All Pixel Vision 8 games have access to a set of common set of APIs. These are exposed via the
GameChip. These APIs allow you to access the underlying system chips. Below is a list of the most common APIs.
These APIs manage system colors and the background color used to clear the display.
BackgroundColor ( id )
The background color is used to fill the screen when clearing the display. You can use this method to read or update the background color at runtime. When calling
BackgroundColor() without an argument, it returns the current background color as an int. You can pass in an optional int to update the background color by calling
0 is any valid system color ID.
Color ( id, value )
Color() API allows you to read and update color values in the
ColorChip. This API has two modes that require a color ID to work. By calling the method with just an ID, like
Color(0), it returns a HEX string for that color. If you supply an additional HEX string value, like
Color(0, "#FFFF00"), you can change the color with the given ID.
These APIs are in charge of copying pixel data to the display.
DrawRect ( x, y, width, height, color, drawMode )
DrawRect() API allows you to display a rectangle with a fill color on the screen. Since this API uses
DrawPixels(), rectangles can be drawn to the tilemap cache or sprite layers.
DrawSprite ( id, x, y, flipH, flipV, drawMode, colorOffset )
DrawSprite() API allows you to draw a single sprite to the display. Sprites represent individual collections of 8 x 8 blocks of pixel data. The display also has a limitation on how many sprites that can be on the screen at the same time. Each time you call
DrawSprite(), the sprite counts against the total amount the display can render.
DrawSpriteBlock ( id, x, y, width, height, flipH, flipV, drawMode, colorOffset, onScreen, useScrollPos, bounds )
DrawSpriteBlock() is similar to DrawSprites except you define the first sprite (upper left corner) and the width x height (in sprites) to sample from sprite ram.
DrawSprites ( ids, x, y, width, flipH, flipV, drawMode, colorOffset, onScreen, useScrollPos, bounds )
DrawSprites() API makes it easier to draw a group of sprites to the display. Unlike the DrawSpriteBlock() API, you define the exact sprites you want to be drawn. While there is no limit on the size of the sprite group which can be rendered, it is important to note that each ID in the array still counts as an individual sprite.
DrawText ( text, x, y, drawMode, font, colorOffset, spacing )
DrawText() API allows you to render text to the display. Files ending with the
.font.png extension are loaded by the
FontChipand converted into character sprites. The
FontChipstores these characters separately from
SpriteChip’s own sprites.
These APIs allow you to read and write save data to handle persistent game data.
ReadSaveData ( key, defaultValue )
ReadSaveData() API allows you to read saved data by supplying a key. If no matching key exists, "
undefined" is returned.
WriteSaveData ( key, value )
WriteSaveData() API allows you to write saved data by supplying a key and value. Once saved, this data persists even after restarting a game.
These APIs handle input from the system’s controllers, keyboard, and mouse.
Button ( Buttons button, InputState state, int controllerID )
The main form of input for Pixel Vision 8 is the controller's buttons. You can get the current state of any button by calling the
Button() method and supplying a button ID. There are optional parameters for specifying an
InputState and the controller ID.
Key ( key, state )
While the main forms of input for Pixel Vision 8 are the controllers, you can test for keyboard input by calling the
Key() API. When this API is called, it returns the current state of that specific key.
MouseButton ( int button, InputState state )
Pixel Vision 8 supports mouse input. You can get the current state of the mouse's left (
0) and right (
1) buttons by calling
MouseButton()API. In addition to supplying a button ID, you can also provide an option
MousePosition ( )
MousePosition() API returns a Point for the mouse cursor's
Y position. The mouse's
0 position is in the upper left-hand corner of the display and when the mouse is off-screen it will return
-1. This value is read-only.
The following functions are automatically called when your game is running.
This is called when a game first loads up.
Draw() is called once per frame after the Update() has been completed. This is where all of your game's draw calls should take place such as clearing the display, drawing sprites, and pushing raw pixel data into the display.
Update( timeDelta )
Update() is called once per frame at the beginning of the game loop. This is where you should put all non-visual game logic such as character position calculations, detecting input and performing updates to your animation system. The
timeDelta is provided on each frame so you can calculate the difference in milliseconds since the last render took place.
These APIs allow you to manage music in your game.
PauseSong ( )
PauseSong() API toggles the current playback state of the sequencer. If the song is playing, it will pause. If the song is paused, it will play.
PlaySong ( id, loop, startAt )
PlaySong() API allows you to activate the
MusicChip’s tracker to playback any of the songs stored in memory. A song is simply a collection of patterns. You can supply an optional parameter called
startAt to tell the
MusicChip which pattern to start the song at.
RewindSong ( position, patternID)
RewindSong() API allows you rewind the currently playing song to a specific position and pattern ID. Calling this API without any arguments will simply rewind the song to the beginning of the first pattern.
StopSong ( )
StopSong() API will stop the currently playing song.
These APIs are in charge of managing what renders to the display.
Display ( visible )
Display() method allows you to get the resolution of the display at run time. By default, this will return the visible screen area based on the overscan value set on the
RedrawDisplay ( )
RedrawAPI() allows you to execute both the
DrawTilemap() APIs in a single call. This is a simple helper function to make redrawing the display easier. If you need to supply additional arguments to either the
DrawTilemap() APIs, then you’ll need to call each one independently without using
ScrollPosition ( x, y )
You can scroll the tilemap by calling the
ScrollPosition() API and supplying a new scroll
Y position. By default, calling
ScrollPosition() with no arguments returns a
Point with the current scroll
Y values. If you supply an
Y value, it updates the tilemap's scroll position the next time you call the
These APIs allow you to play sound effects on specific audio channels.
PlaySound ( id, channel )
PlaySound() API allows playing a single sound effect on a specific channel. The
SoundChiphas a limited number of active channels, so playing a sound effect on a channel where a sound is already playing will override it.
Sound ( int id, string data )
Sound() API allows you to read raw sound data from the
SoundChip. You need to provide a sound effect ID. If you supply the optional data argument, which is a comma-delimited string of sound effect property values, you’ll be able to update the sound effect.
StopSound ( channel )
StopSound() to stop any sound playing on a specific channel.
These APIs allow you to manage sprite pixel data and get the total amount of sprites in memory.
Sprite ( id, data )
Sprite() API allows you to read and write pixel data directly to the
SpriteChip’s memory. Sprite pixel data is simply an array of color IDs. When calling the
Sprite() with only an ID argument, you will get the sprite's pixel data. If you supply data, it will overwrite the sprite.
TotalSprites ( bool ignoreEmpty )
TotalSprites() API returns the total number of sprites in the
SpriteChip. By supplying
ignoreEmptyparameter, it will only return sprites that contain pixel data.
These APIs allow you work with tilemap data.
Flag ( column, row, value )
Flag() API allows you to quickly access just the flag value of a tile. This is useful when trying to calculate collision on the tilemap. By default, you can call this method with just a
rowposition to return the flag value at that tile. If you supply a new value, it will be overridden on the tile.
RebuildTilemap ( )
RebuildTilemap() API forces the tilemap to redraw the tilemap cache layer. Use this to clear any pixel data drawn on top of tiles in the tilemap cache layer.
Tile ( column, row, spriteID, colorOffset, flag, flipH, flipV )
Tile() API allows you to get the current sprite, color offset and flag values associated with a given tile ID. You can optionally supply your own values if you want to update the tile.
TilemapSize ( width, height, clear )
TilemapSize() API returns a
Pointrepresenting the size of the tilemap in
Y). To find the size in pixels, you will need to multiply the returned
Y values by the sprite size's
Y. This method also allows you to resize the tilemap by passing in an optional new
UpdateTiles ( ids, column, row, width, colorOffset, flag )
UpdateTiles() API allows you to update the color offset and flag values of multiple tiles at once. Simply supply an array of tile IDs and the new tile’s color offset and a flag value. This helper method uses the
Tile() API under the hood to update each tile, so any changes to a tile’s color offset will automatically force it to be redrawn to the tilemap cache layer.