Pixelbox takes inspiration from fantasy consoles like PICO8 and game creation frameworks like Unity3D.

From version 2, Pixelbox package no longer includes the editor. Instead, the editor is now a standalone application that can be downloaded on Itch.io.

A Pixelbox project have the following structure:

assets/
 ├── tilesheet.png
 ├── palette.png
 └── maps.json
audio/
build/
src/
 └── main.js
tools/
node_modules/
project.pixelbox
package.json
index.html

• assets/ is where game assets go (images, text files, JSON)
• audio/ is where sounds and music go
• src/ is the source code folder, and main.js is the entry file of the game.

The game entry point is the src/main.js file. If you provide a exports.update function, Pixelbox will call it every frame.

Build is made using browserify which give you access to require (or import) and exports to easily modularize your project.

Pixebox automatically load all assets at startup, before executing the game code. All supported files added inside the assets/ directory will be available in the assets global object. The structure follow the structure of the directory. For instance, the file file located in assets/sprites/player.png will be accessible with assets.sprites.player.

Supported files includes:

• images (.png, .jpg)
• JSON formatted data (.json)
• plain text files (.txt, .css, .vert, .frag)

You directly have access to JSON content.

Because files are loaded inside assets object and refered wthout their extension, you cannot have a file and a directory with the same name inside the same directory.

Pixelbox expose the following methods directly on the global scope:

• cls() clear screen with paper color
• sprite(n, x, y [,flipH [,flipV [, flipR]]]) draw sprite number n on screen at pixel position (x, y). flipH and flipV can be used to flip sprite horizontally or vertically, flipR adds a 90 degree clockwize rotation.
• draw(image, x, y [,flipH [,flipV [, flipR]]]) draw an Image, Texture or TileMap on screen at pixel position (x, y)
• tilesheet(image) change image used as default tilesheet
• rect(x, y, w, h) stroke a rectangle with pen color
• rectf(x, y, w, h) fill a rectangle with paper color
• camera(x, y) scroll add further drawing by provided position

Pixelbox has a predefined "minitext" bitmap font that you can use to print text on screen or in textures. Minitext is available by default, but can be disabled in the project settings.

• print(text, [x, y]) if x, y is provided, print text at pixel position (x, y). else print text at cursor current position.
• println(text) print text and feed new line. When cursor reach the bottom of the screen, a vertical scroll is applied (just like it would happend in a terminal.)
• locate(i, j) set cursor position at column i line j
• pen(colorId) set text color to colorId in color palette
• paper(colorId) set paper color to colorId in color palette.

• btn state of the buttons. By default, available buttons are: up, down, left, right, A, B (buttons names and binding can be configured in the project settings)
• btnp if button has been pressed during current frame
• btnr if button has been released during current frame

• sfx('sound'); play the sound.mp3 file in audio/ folder
• music('bgm'); play the bgm.mp3 file in loop. If another music is already playing, it will cross fade to the new music. If no soundId is provided, the music stops.

AudioManager is the module that handle audio loading and playback. You have access to its instance on audioManager.

• clamp(value, min, max) clip a value between min and max
• chr$(n) return a character from code n.
• random(n) return a random integer between 0 and n
• inherits(Child, Parent) make class Child inherits from class Parent

Texture is a canvas that can be drawn and inside which things can be drawn. In Canvas2D mode, it is implemented with a HTML canvas. In WebGL mode, it is implemented with a GLTexture2D.

The main screen (accessible by the global variable $screen) is an instance of Texture and most of its methods are accessible from the global scope.

To create new texture, you need to require the Texture module:

var Texture = require('Texture');
var texture = new Texture(128, 128); // create a new texture of 128 by 128 pixels

texture.resize(width, height);
texture.setPalette(palette);
texture.pen(colorIndex); // set PEN color index from palette (pen is used for text and stroke)
texture.paper(colorIndex); // set PAPER color index from palette (paper is used for fill)
texture.setTilesheet(tilesheet); // set tilesheet used for this texture

A tilesheet is an Image containing 256 sprites organized in a 16 x 16 grid (the size of the tilesheet depend of the sprite size you set for your game).

texture.clear(); // clear texture (it become transparent)
texture.cls(); // clear screen (the whole texture is filled with the PAPER color)
texture.sprite(sprite, x, y, flipH, flipV, flipR); // draw a sprite from current tilesheet in the texture
texture.draw((img, x, y, flipH, flipV, flipR); // draw an image (or Texture or Map) in texture.
texture.rect(x, y, width, height); // stroke a rectangle
texture.rectfill(x, y, width, height); // fill a rectangle

texture.locate(i, j); // set text cursor to specified location
texture.print(text, x, y); // print some text
texture.println(text); // print some text and feed a new line

Pixelbox has a built-in TileMap component. A TileMap consist of:

• A name
• A tilesheet. When the tilesheet is changed, the whole map will be redrawn with the new tilesheet.
• A grid of sprites from the tilesheet plus few flags to flip or rotate sprites.

Once created, a tile map is rendered in one draw call only.

TileMap can be used to reder a level made of sprites, or just to store game data.

You can create tile maps from your game code; But usually, you will be using Pixelbox's tools (see the Tools section bellow) to create and manage your maps as game assets. A map can then be retrived by its name with Pixelbox's getMap function. The tile map can then be drawn on screen (or in another Texture), modified, copied, pasted, resized, etc.

When stored in assets, the map is compressed to Pixelbox format to reduce file size.

var map = getMap('mapName'); // get a tile map by its name

To create new maps, you need to require the Map module:

var TileMap = require('TileMap');
var map = new TileMap(16, 16); // create a new tile map of 16 by 16 tiles

map.draw(x, y);  // draw map on screen at [x, y] position
draw(map, x, y); // idem, using the global draw function
texture.draw(map, x, y); // draw a map in another texture
map.setTilesheet(tilesheet); // set tilesheet to use for this map.
                             // The whole map is redrawn when calling this function.

map.get(x, y); // returns the Tile at position [x, y]. null if empty
map.set(x, y, tile, flipH, flipV, flipR, flagA, flagB); // add a tile
map.remove(x, y); // remove tile at position [x, y]. (set it to null)
map.find(tile, flagA, flagB); // find all tiles with specified properties

map.resize(width, height); // resize the map (size unit is tiles)
map.clear(); // Reset the whole map content by setting all its tiles to null
var mapCopy = map.copy(x, y, width, height); // copy this map to a new one.
               // x, y, width, height can be specified to copy only a rectangular part of the map.
map.paste(mapCopy, x, y, merge); // paste map data in the map at position offset [x, y].
               // if 'merge' flag is set, then null tiles will not overwrite current map tile.

The gamepad module allow easy access to gamepads if the browser supports it.

getGamepads(); // get all gamepads state
getGamepad(id); // get gamepad state
getAnyGamepad(); // Merge states of all gamepads and return a global gamepad state.

the gamepad state returned by these function works like keyboard controls: You get the state of each buttons, button presses and button release, plus the values of analog controls.

var gamepad = require('gamepad'); // require the gamepad module
var state = gamepad.getGamepad(0); // get state of gamepad id 0

// buttons:
state.btn.A; // state of A button
state.btn.B; // state of B button
state.btn.X; // state of X button
state.btn.Y; // state of Y button
state.btn.start; // state of 'start' button
state.btn.back;  // state of 'back' button
state.btn.up;    // directionnal pad's up button
state.btn.down;  // directionnal pad's down button
state.btn.left;  // directionnal pad's left button
state.btn.right; // directionnal pad's right button
state.btn.lb; // left bumper button
state.btn.rb; // right bumper button
state.btn.lt; // left trigger button
state.btn.rt; // right trigger button

// button press and release.
// the structure is the same as state.btn but the values are true only
// on button press or release.
state.btnp; // button press
state.btnr; // button release

// analog values
state.x  // x axe value (first stick horizontal)
state.y  // y axe value (first stick vertical)
state.z  // z axe value (second stick horizontal)
state.w  // w axe value (second stick vertical)
state.lt // left trigger analog value
state.rt // right trigger analog value

Pixelbox editor is bundled with a music tracker called PataTracker. The tracker player must be enabled in the project settings. Player allows to directly plays the songs in the json formatted tracker files.

PataTracker player is exposed as a patatracker global variable.

patatracker.playSong(songNumber);
patatracker.stop();

Pata-Tracker automatically loads project album data (assets/patatracker.json). If you need to load a different album, you can do it with the following API:

patatracker.loadData(data);

Bleeper is the sound effect editor of Pixelbox. Like for PataTracker, it must be enabled in the project settings. Note that Bleeper depends on the AudioManager component.

There are several ways to play Bleeper sounds:

If the sound is named, it is accessible on the assets global, and automatically added to AudioManager.

// from assets global
assets.bleeper.mySound.play(volume, panoramic, pitch); // all parameters optionnals

// using audioManager
sfx('mySound', volume, panoramic, pitch); // using default channel
audioManager.playSound('sfx', 'mySound', volume, panoramic, pitch);

Bleeper module exposes an array of all sounds defined in the program.

var bleeper = require('pixelbox/bleeper');
bleeper.sounds[3].play(volume, panoramic, pitch);