Lua API Cheat Sheet

All Lua games have access to a set of APIs that communicate directly with the Pixel Vision 8 engine. These are exposed via the Game Chip. This bridge allows you to access the native properties and methods of the core framework.

Life Cycle APIs

These functions can be added to your game and will be called based on specific point of the game's lifecycle.

  • Init() - is called when a game loads up.
  • Draw() - called once per frame after the Update() has completed.
  • Reset() - called when a game is restarted.
  • Update (timeDelta) - is called once per frame at the beginning of the game loop.

GameChip APIs

These APIs represent the core functions available to your game at runtime. These include options for displaying graphics, playing audio, and saving a game's state.

  • AddTextFile (name, file) - This allows you to add your Lua scripts at runtime to a game from a string.
  • BackgroundColor (id) - The background color is used to fill the screen when clearing the display.
  • BreakLine (text, pos, max) - Locates position to break the given line so as to avoid breaking words.
  • Button (button, state, controllerID) - The main form of input for Pixel Vision 8 is the controller's buttons.
  • CalculateDistance (x0, y0, x1, y1) - Fast calculation to get the distance between two points .
  • CalculateIndex (x, y, width) - Converts an X and Y position into an index.
  • CalculatePosition (index, width) - Converts an index into an X and Y position to help when working with 1D arrays that represent 2D data.
  • Clamp (val, min, max) - Limits a value between a minimum and maximum.
  • Clear (x, y, width, height) - Clearing the display removed all of the existing pixel data, replacing it with the default background color.
  • Color (id, value) - The Color() method allows you to read and update color values in the ColorChip.
  • ColorsPerSprite () - Pixel Vision 8 sprites have limits around how many colors they can display at once which is called the Colors Per Sprite or CPS.
  • Configure () - .
  • ConvertCharacterToPixelData (character, fontName) - A helper method that converts a single character into pixel data.
  • ConvertTextToSprites (text, fontName) - A helper method to convert a string of characters into an array of sprite IDs.
  • Display (visible) - The display's size defines the visible area where pixel data exists on the screen.
  • DrawPixels (pixelData, x, y, width, height, flipH, flipV, drawMode, colorOffset) - This method allows you to draw raw pixel data directly to the display.
  • DrawRect (x, y, width, height, color, drawMode) - This method allows you to draw a rectangle with a fill color.
  • DrawSprite (id, x, y, flipH, flipV, drawMode, colorOffset) - Sprites represent individual collections of pixel data at a fixed size.
  • 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) - The DrawSprites method makes it easier to combine and draw groups of sprites to the display in a grid.
  • DrawText (text, x, y, drawMode, font, colorOffset, spacing) - The DrawText() method allows you to render text to the display.
  • DrawTilemap (x, y, columns, rows, offsetX, offsetY, drawMode) - By default, the tilemap renders to the display by simply calling DrawTilemap().
  • Flag (column, row, value) - This allows you to quickly access just the flag value of a tile.
  • InputString () - The InputString() method returns the keyboard input entered this frame.
  • IsChannelPlaying (channel) - Returns a bool if the channel is playing a sound.
  • Key (key, state) - While the main form of input in Pixel Vision 8 comes from the controllers, you can test for keyboard input by calling the Key() method.
  • MaxSpriteCount (total) - This method returns the maximum number of sprites the Display Chip can render in a single frame.
  • MouseButton (button, state) - Pixel Vision 8 supports mouse input.
  • MousePosition () - The MousePosition() method returns a vector for the current cursor's X and Y position.
  • NewPoint (x, y) - A Vector is a Pixel Vision 8 primitive used for defining a position on the display as an x,y value.
  • NewRect (x, y, w, h) - A Rect is a Pixel Vision 8 primitive used for defining the bounds of an object on the display.
  • PaletteOffset (value) - This method will automatically calculate the start color offset for palettes in the color chip.
  • PauseSong () - Toggles the current playback state of the sequencer.
  • PlayPattern (id, loop) - This helper method allows you to automatically load a set of patterns as a complete song and plays them back.
  • PlayPatterns (loopIDs, loop) - This helper method allows you to automatically load a set of patterns as a complete song and plays them back.
  • PlaySong (id, loop, startAt) - Plays a sing by it's ID.
  • PlaySound (id, channel) - This method plays back a sound on a specific channel.
  • ReadMetaData (key, defaultValue) - Reads the meta data that was passed into the game when it was loaded.
  • ReadSaveData (key, defaultValue) - Allows you to read saved data by supplying a key.
  • RebuildCache (targetTextureData) - This method converts the tile map into pixel data that can be rendered by the engine.
  • RebuildTilemap () - This forces the map to redraw its cached pixel data.
  • RedrawDisplay () - You can use RedrawDisplay to make clearing and drawing the tilemap easier.
  • Repeat (val, max) - Repeats a value based on the max.
  • ReplaceColor (index, id) - The ReplaceColor() method allows you to quickly change a color to an existing color without triggering the DisplayChip to parse and cache a new hex value.
  • RewindSong (position, loopID) - Rewinds the sequencer to the beginning of the currently loaded song.
  • ScrollPosition (x, y) - You can scroll the tilemap by calling the ScrollPosition() method and supplying a new scroll X and Y position.
  • SongData () - Returns a dictionary with information about the current state of the music chip.
  • Sound (id, data) - This method allows your read and write raw sound data on the SoundChip.
  • SplitLines (str) - This calls the TextUtil's SplitLines() helper to convert text with line breaks (\n) into a collection of lines.
  • Sprite (id, data) - This allows you to return the pixel data of a sprite or overwrite it with new data.
  • SpriteSize (width, height) - Returns the size of the sprite as a Vector where X and Y represent the width and height.
  • Sprites (ids, width) - This allows you to get the pixel data of multiple sprites.
  • StopSong () - Stops the sequencer.
  • StopSound (channel) - Use StopSound() to stop any sound playing on a specific channel.
  • Tile (column, row, spriteID, colorOffset, flag, flipH, flipV) - This allows you to get the current sprite id, color offset and flag values associated with a given tile.
  • TilemapSize (width, height, clear) - This will return a vector representing the size of the tilemap in columns (x) and rows (y).
  • TotalColors (ignoreEmpty) - The TotalColors() method simply returns the total number of colors in the ColorChip.
  • TotalSprites (ignoreEmpty) - Returns the total number of sprites in the system.
  • Update (timeDelta) - Update() is called once per frame at the beginning of the game loop.
  • UpdateTiles (column, row, columns, ids, colorOffset, flag) - A helper method which allows you to update several tiles at once.
  • VisibleBounds () - Returns the visible bounds of the display as a Rectangle.
  • WordWrap (text, width) - This allows you to call the TextUtil's WordWrap helper to wrap a string of text to a specified character width.
  • WriteSaveData (key, value) - Allows you to save string data to the game file itself.

Controller Input

There are two controllers for player one and two. The first controller ID is 0 and the second is 1. You can get the state of a given controller by calling the Button() method:

bool Button( button, state, controllerID)

The Button() method returns a boolean and needs to supply a Button ID, an input state, and the controller id. By default, the input state is set to InputState.Down, and the controller is the first player. There is an enum for each of the controller's buttons:

  • Buttons.Up
  • Buttons.Down
  • Buttons.Left
  • Buttons.Right
  • Buttons.A
  • Buttons.B
  • Buttons.Select
  • Buttons.Start

You can supply a different input state when calling the Button() method. Here are the two options in the InputState enum:

  • InputState.Down
  • InputState.Released

When calling the Button() method and supplying InputState.Released, it returns true if the button was down in the previous frame but is not down in the current frame. It is important to note that both controllers are always "connected." You can get their value at any time in your game's code, and you do not need to worry about them being connected or disconnected from the system. If for some reason there is no controller, it will return false.

Get Pixel Vision 8 Today

Join the Fantasy Console Club for free to get your copy of Pixel Vision 8. Indie memberships also include Pixel Vision OS,  exclusive tutorials, and demos. Those looking for access to more tools can join the pro membership for just $1 each month and help support the project.
Become A Member Today

Help Support Pixel Vision 8

Pixel Vision 8 is still in development. Currently, it is offered as "early access" and may contain bugs, unexpectedly crash, or be missing features. You can cancel your membership at any time. These early access builds help get feedback, identify bugs, and stress test the toolchain. Join the dedicated Discord server for support and chatting with the community.
Join The Discord Server