Lua API Cheatsheet
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.
Lifecycle
| Name | Arguments | Description |
|---|---|---|
| Draw | Draw() is called once per frame after the Update() has completed. | |
| Reset | Reset() is called when a game is restarted. | |
| Shutdown | Shutdown() is called when quitting a game or shutting down the Runner/Game Creator. |
Color
| Name | Arguments | Description |
|---|---|---|
| BackgroundColor | id |
The background color is used to fill the screen when clearing the display. This method returns the current background color ID. |
| Color | id value |
The Color() method allows you to read and update color values in the ColorChip. This method returns a hex string for the supplied color ID. |
| 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. | |
| 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. |
| TotalColors | ignoreEmpty |
The TotalColors() method simply returns the total number of colors in the ColorChip. This method returns the total number of colors in the color chip based on the ignoreEmpty argument's value. |
Display
| Name | Arguments | Description |
|---|---|---|
| Clear | x y width height |
Clearing the display removed all of the existing pixel data, replacing it with the default background color. |
| Display | visible |
The display's size defines the visible area where pixel data exists on the screen. |
| DrawPixel | x y colorRef drawMode |
This method allows you to draw a single pixel to the Tilemap Cache. |
| DrawPixels | pixelData x y width height drawMode flipH flipV 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 |
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. |
| DrawTile | id c r drawMode colorOffset |
The DrawTile method makes it easier to update the visuals of a tile on any of the map layers. |
| DrawTilemap | x y columns rows offsetX offsetY drawMode |
By default, the tilemap renders to the display by simply calling DrawTilemap(). |
| DrawTiles | ids c r width drawMode colorOffset |
The DrawTiles method makes it easier to update the visuals of multiple tiles at once by leveraging the DrawTile method. |
| RedrawDisplay | You can use RedrawDisplay to make clearing and drawing the tilemap easier. | |
| ScrollPosition | x y |
You can scroll the tilemap by calling the ScrollPosition() method and supplying a new scroll X and Y position. By default, this method returns a vector with the current scroll X and Y position. |
File IO
| Name | Arguments | Description |
|---|---|---|
| ReadSaveData | key defaultValue |
Allows you to read saved data by supplying a key. Returns string data associated with the supplied key. |
| WriteSaveData | key value |
Allows you to save string data to the game file itself. |
Input
| Name | Arguments | Description |
|---|---|---|
| Button | button state controllerID |
The main form of input for Pixel Vision 8 is the controller's buttons. Returns a bool based on the state of the button. |
| InputString | The InputString() method returns the keyboard input entered this frame. | |
| 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. This method returns a bool based on the state of the button. |
| MouseButton | button state |
Pixel Vision 8 supports mouse input. Returns a bool based on the state of the button. |
| MousePosition | The MousePosition() method returns a vector for the current cursor's X and Y position. |
Sound
| Name | Arguments | Description |
|---|---|---|
| PauseSong | Toggles the current playback state of the sequencer. | |
| PlaySong | loopIDs loop |
This helper method allows you to automatically load a set of loops as a complete song and plays them back. |
| PlaySound | id channel |
This method plays back a sound on a specific channel. |
| RewindSong | position loopID |
Rewinds the sequencer to the beginning of the currently loaded song. |
| Sound | id data |
This method allows your read and write raw sound data on the SoundChip. |
| StopSong | Stops the sequencer. | |
| StopSound | channel |
Use StopSound() to stop any sound playing on a specific channel. |
Sprite
| Name | Arguments | Description |
|---|---|---|
| MaxSpriteCount | total |
This method returns the maximum number of sprites the Display Chip can render in a single frame. Returns an int representing the total number of sprites on the screen at once. |
| Sprite | id data |
This allows you to return the pixel data of a sprite or overwrite it with new data. Returns an array of int data which points to color ids. |
| SpriteSize | width height |
Returns the size of the sprite as a Vector where X and Y represent the width and height. Returns a vector where the X and Y for the sprite's width and height. |
| Sprites | ids width |
This allows you to get the pixel data of multiple sprites. |
| TotalSprites | ignoreEmpty |
Returns the total number of sprites in the system. This method returns the total number of sprites in the color chip based on the ignoreEmpty argument's value. |
Tilemap
| Name | Arguments | Description |
|---|---|---|
| Flag | column row value |
This allows you to quickly access just the flag value of a tile. |
| RebuildTilemap | columns rows spriteIDs colorOffsets flags |
This forces the map to redraw its cached pixel data. |
| Tile | column row spriteID colorOffset flag |
This allows you to get the current sprite id, color offset and flag values associated with a given tile. Returns a dictionary containing the spriteID, colorOffset, and flag for an individual tile. |
| TilemapSize | width height |
This will return a vector representing the size of the tilemap in columns (x) and rows (y). Returns a vector of the tile maps size in tiles where x and y are the columns and rows of the tilemap. |
| UpdateTiles | column row columns ids colorOffset flag |
A helper method which allows you to update several tiles at once. |
Lua Game Chip API
The following APIs are specific to the Lua Game Chip found in the Game Creator. These methods are also available in the runner but are not part of the core C# API. These are helper functions that are available globally from any Lua script to bridge missing functionality not found in the core Game Chip itself.
Lifecycle
| Name | Arguments | Description |
|---|---|---|
| Init | Init() is called when a game is loaded into memory and is ready to be played. |
Math
| Name | Arguments | Description |
|---|---|---|
| CalculateIndex | x y width |
Converts an X and Y position into an index. Returns an int value representing the X and Y position in a 1D array. |
| CalculatePosition | index width |
Converts an index into an X and Y position to help when working with 1D arrays that represent 2D data. Returns a vector representing the X and Y position of an index in a 1D array. |
| Clamp | val min max |
Limits a value between a minimum and maximum. Returns an int within the min and max range. |
| Repeat | val max |
Repeats a value based on the max. Returns an int that is never less than 0 or greater than the max. |
Utils
| Name | Arguments | Description |
|---|---|---|
| SplitLines | str |
This calls the TextUtil's SplitLines() helper to convert text with line breaks (\n) into a collection of lines. Returns an array of strings representing each line of text. |
| WordWrap | text width |
This allows you to call the TextUtil's WordWrap helper to wrap a string of text to a specified character width. |
Scripts
| Name | Arguments | Description |
|---|---|---|
| AddScript | name script |
This allows you to add your Lua scripts at runtime to a game from a string. |
| LoadScript | name |
This allows you to load a script into memory. |
Sound
| Name | Arguments | Description |
|---|---|---|
| PlayRawSound | data channel frequency |
This helper method allows you to pass raw SFXR string data to the sound chip for playback. |
Geometry
| Name | Arguments | Description |
|---|---|---|
| NewRect | x y w h |
A Rect is a Pixel Vision 8 primitive used for defining the bounds of an object on the display. Returns a new instance of a Rect to be used as a Lua object. |
| NewVector | x y |
A Vector is a Pixel Vision 8 primitive used for defining a position on the display as an x,y value. Returns a new instance of a Vector to be used as a Lua object. |
Enums
Pixel Vision 8’s APIs leverage several Enums. You can find a full listing of the enums referenced in the API docs below.
Buttons
The Button enum contains all of the valid buttons on the controller.
| Enum | Value |
| Buttons.Up | 0 |
| Buttons.Down | 1 |
| Buttons.Left | 2 |
| Buttons.Right | 3 |
| Buttons.A | 4 |
| Buttons.B | 5 |
| Buttons.Select | 6 |
| Buttons.Start | 7 |
InputState
The InputState enum contains the vaid states of a button.
| Enum | Value |
| InputState.Down | 0 |
| InputState.Released | 1 |
DrawMode
The DrawMode enum contains all of the valid render layers and modes available to the DisplayChip.
| Enum | Value | Description |
| DrawMode.Background | 0 | This is the clear layer and is usually reserved for filling the screen with a background color. |
| DrawMode.SpriteBelow | 1 | This is a layer dedicated to sprites just above the background. |
| DrawMode.Tile | 2 | This is the tilemap layer and is drawn above the SpriteBelow layer allowing sprites to appear behind the background. |
| DrawMode.Sprite | 3 | This is the default layer for sprites to be rendered at. It is above the background. |
| DrawMode.UI | 4 | This is a special layer which can be used to draw raw pixel data above the background and sprites. It's designed for HUDs in your game and other graphics that do not scroll with the tilemap. |
| DrawMode.SpriteAbove | 5 | This layer allows sprites to render above the UI layer. It is useful for mouse cursors or other graphics that need to be on top of all other layers. |
SaveFlags
The SaveFlags enum is used when loading or saving a game’s state. It helps define each of the pieces of data used to make a complete game when loading it into memory. This is used specifically for the GameEditor.
| Enum | Value |
| SaveFlags.System | 1 |
| SaveFlags.Code | 2 |
| SaveFlags.Colors | 4 |
| SaveFlags.ColorMap | 8 |
| SaveFlags.Sprites | 16 |
| SaveFlags.Tilemap | 32 |
| SaveFlags.TilemapFlags | 64 |
| SaveFlags.Fonts | 128 |
| SaveFlags.Meta | 256 |
| SaveFlags.Music | 512 |
| SaveFlags.Sounds | 1024 |
| SaveFlags.SpriteCache | 2048 |
| SaveFlags.TilemapCache | 4096 |
| SaveFlags.SaveData | 8192 |
Keys
The Keys enum is used to detect keyboard button presses when calling Key(). Simply pass in the enum for the key you want to test and the input state.
| Enum | Value |
| Keys.None | 0 |
| Keys.Backspace | 8 |
| Keys.Tab | 9 |
| Keys.Clear | 12 |
| Keys.Return | 13 |
| Keys.Pause | 19 |
| Keys.Escape | 27 |
| Keys.Space | 32 |
| Keys.Exclaim | 33 |
| Keys.DoubleQuote | 34 |
| Keys.Hash | 35 |
| Keys.Dollar | 36 |
| Keys.Ampersand | 38 |
| Keys.Quote | 39 |
| Keys.LeftParen | 40 |
| Keys.RightParen | 41 |
| Keys.Asterisk | 42 |
| Keys.Plus | 43 |
| Keys.Comma | 44 |
| Keys.Minus | 45 |
| Keys.Period | 46 |
| Keys.Slash | 47 |
| Keys.Alpha0 | 48 |
| Keys.Alpha1 | 49 |
| Keys.Alpha2 | 50 |
| Keys.Alpha3 | 51 |
| Keys.Alpha4 | 52 |
| Keys.Alpha5 | 53 |
| Keys.Alpha6 | 54 |
| Keys.Alpha7 | 55 |
| Keys.Alpha8 | 56 |
| Keys.Alpha9 | 57 |
| Keys.Colon | 58 |
| Keys.Semicolon | 59 |
| Keys.Less | 60 |
| Keys.Equals | 61 |
| Keys.Greater | 62 |
| Keys.Question | 63 |
| Keys.Alt | 64 |
| Keys.LeftBracket | 91 |
| Keys.Backslash | 92 |
| Keys.RightBracket | 93 |
| Keys.Caret | 94 |
| Keys.Underscore | 95 |
| Keys.BackQuote | 96 |
| Keys.A | 97 |
| Keys.B | 98 |
| Keys.C | 99 |
| Keys.D | 100 |
| Keys.E | 101 |
| Keys.F | 102 |
| Keys.G | 103 |
| Keys.H | 104 |
| Keys.I | 105 |
| Keys.J | 106 |
| Keys.K | 107 |
| Keys.L | 108 |
| Keys.M | 109 |
| Keys.N | 110 |
| Keys.O | 111 |
| Keys.P | 112 |
| Keys.Q | 113 |
| Keys.R | 114 |
| Keys.S | 115 |
| Keys.T | 116 |
| Keys.U | 117 |
| Keys.V | 118 |
| Keys.W | 119 |
| Keys.X | 120 |
| Keys.Y | 121 |
| Keys.Z | 122 |
| Keys.Delete | 127 |
| Keys.Keypad0 | 256 |
| Keys.Keypad1 | 257 |
| Keys.Keypad2 | 258 |
| Keys.Keypad3 | 259 |
| Keys.Keypad4 | 260 |
| Keys.Keypad5 | 261 |
| Keys.Keypad6 | 262 |
| Keys.Keypad7 | 263 |
| Keys.Keypad8 | 264 |
| Keys.Keypad9 | 265 |
| Keys.KeypadPeriod | 266 |
| Keys.KeypadDivide | 267 |
| Keys.KeypadMultiply | 268 |
| Keys.KeypadMinus | 269 |
| Keys.KeypadPlus | 270 |
| Keys.KeypadEnter | 271 |
| Keys.KeypadEquals | 272 |
| Keys.UpArrow | 273 |
| Keys.DownArrow | 274 |
| Keys.RightArrow | 275 |
| Keys.LeftArrow | 276 |
| Keys.Insert | 277 |
| Keys.Home | 278 |
| Keys.End | 279 |
| Keys.PageUp | 280 |
| Keys.PageDown | 281 |