Aller au contenu principal

Bitsy System



These APIs are the base layer on which the bitsy engine is built. When combined with a JavaScript intepreter, they define the system requirements for bitsy.

The web implementation of these APIs is found in editor/script/system/system.js (source). I've also written a standalone desktop implementation called bitsybox (source).

NOTE: Currently these are experimental and likely to change significantly from version to version - at least until they reach v1.0.


System Object


All of the functions and constants of the bitsy system are members of the bitsy global object. This object represents the bitsy system and must be provided by the host system for the engine to run.


These constants are special values used by bitsy system functions.

Memory Blocks

Memory blocks are virtual locations in system memory used by certain functions to specify what memory they are changing. Currently the exact meaning of "memory block location" is not defined, so these constants should essentially be treated as arbitrary IDs.


Location of the main display memory for bitsy when accessing pixels individually (see Graphics Modes).


Location of the text display memory for bitsy (where the textbox is drawn). Seperate memory is required since it may not share the same internal resolution as the main display.


Location of the background tilemap.


Location of the foreground tilemap.


Location of sound channel 1.


Location of sound channel 2.

Graphics Modes

There are two graphics modes for the main display.


In video mode, every pixel on the main display can be written to individually. This is used for screen transition effects.


In tilemap mode, instead of directly writing to pixels you write tile IDs into tilemap memory. This is used for normal gameplay.

Text Modes

There are two text display modes as well.


The internal resolution of the textbox display is 2x the main display. This is the default mode.


The internal resolution of the textbox display is the same as the main display. Games can request this display mode via settings.


Constant size values.


The size of tiles in pixels.


The size of tilemaps in tiles.


The size of the main display in pixels.

Button Codes

Bitsy has six gamepad buttons for input.


Up arrow or W on keyboard, swipe up on touch screen, d-pad up on gamepad.


Down arrow or S on keyboard, swipe down on touch screen, d-pad down on gamepad.


Left arrow or A on keyboard, swipe left on touch screen, d-pad left on gamepad.


Right arrow or D on keyboard, swipe right on touch screen, d-pad right on gamepad.


"Any key" on keyboard, tap on touch screen, face buttons on gamepad. (Used to advance dialog.)


Ctrl+R on keyboard, no touch control yet, start button on gamepad. (Restarts the game.)

Pulse Waves

Bitsy's virtual soundchip supports three different pulse waves for audio output.


Pulse wave with 1/8 duty.


Pulse wave with 1/4 duty.


Pulse wave with 1/2 duty (aka square wave).

IO (Input / Output)


Writes the string message to the debug console.


Returns true if the button referred to by code is held down (see Button Codes). Otherwise it returns false.


Returns the game data as a string.


Returns the default font data as a string.



Sets the current graphics display mode (see Graphics Modes), and also returns the current graphics mode. If no mode input is given, just returns the current mode without changing it.


Sets the current text display mode (see Text Modes), and also returns the current text mode. If no mode input is given, just returns the current mode without changing it.

bitsy.color(color, r, g, b)

Sets the color in the system palette at index color to a color defined by the color parameters r (red), g (green), and b (blue). These values must be between 0 and 255. (For example, bitsy.color(2, 0, 0, 0) sets the color at index 2 to black and bitsy.color(2, 255, 255, 255) set the color at the same index to white.)


Allocates a new tile and returns its memory block location.


Deletes the tile at the specified memory block location.

bitsy.fill(block, value)

Fills an entire memory block with a number value. Can be used to clear blocks such as video memory, tilemap memory, and tile memory.

bitsy.set(block, index, value)

Sets the value at index within a memory block with a number value.

bitsy.textbox(visible, x, y, w, h)

Updates the textbox display settings. If visible is true the textbox is rendered, otherwise it's hidden. The textbox's position (relative the main display's coordinate space) is defined by x and y. And the size of the textbox (in its internal resolution) is defined by w (width) and h (height). Omitted parameters are unchanged (For example, you can just reveal the textbox without changing its position and size using bitsy.textbox(true)).


bitsy.sound(channel, duration, frequency, volume, pulse)

Updates all audio settings for one sound channel (either bitsy.SOUND1 or bitsy.SOUND2). The duration is in milliseconds, frequency is in decihertz (dHz), volume must be between 0 and 15, and pulse is one of the pulse wave constants (see Pulse Waves).

bitsy.frequency(channel, frequency)

Sets the frequency for one sound channel. Units are decihertz (dHz).

bitsy.volume(channel, volume)

Sets the volume for one sound channel. Volume must be between 0 and 15 (inclusive).



The system will call function fn on every update loop. It will attempt to run at 60fps, but fn will also receive an input parameter dt with the delta time since the previous loop (in milliseconds).