Lua modding API reference
game
local game = require"game"
Board
An array of rows, top to bottom. Each column is two bits, from left to right going from least to most significant. 00 is empty, and 01, 10, and 11 are different tiles. Note that the indices are from 0 to 19; i.e. they don't start at 1.
type Board = [0...19]integer
CoreOption
A core option. New values for these options can be defined by defining new functions in the table. The parameters passed into the function and when the function is called depends on the specific option.
type CoreOption = table
CoreOption.value
The value of a core option. TODO: allow mutation
CoreOption.value: string | integer
GameState
The state of the game for one player.
type GameState = table
GameState:bclear
Initiates B-type clear sequence. This may invoke other mod functions if they listen to game.events.BCLEAR
.
GameState:bclear() -> boolean
GameState.board
The currently active board. May be mutated.
GameState.board: Board
GameState.completed
Represents which lines, if any, were cleared. Each of the lower 4 bits represents one line, from top to bottom going from least to most significant. If you just want to get a count of how many lines were cleared, see GameState:completedcount
.
GameState.completed: integer
GameState:completedcount
The number of lines that were just cleared.
GameState:completedcount() -> integer
GameState.cur
The currently active tetromino.
GameState.cur: Tetromino
GameState.das
The current DAS charge.
GameState.das: integer
GameState.doubles
The number of doubles cleared.
GameState.doubles: integer
GameState.dropdelay
The amount of time that must pass before the next piece will spawn. If zero, a piece is currently active.
GameState.dropdelay: integer
GameState.drought
The current drought.
GameState.drought: integer
GameState:efficiency
The current efficiency.
GameState:efficiency() -> integer
GameState.fallamt
Counts up to game.gravity(level) before game.events.GRAVITY
is triggered and the current piece is either moved down one or locked into place.
GameState.fallamt: integer
GameState.flip
The direction that the player wants to flip the piece. This is 0 if a rotation wasn't requested, -1 if a counter-clockwise rotation was requested, or 1 if a clockwise rotation was requested.
GameState.flip: integer
GameState.level
The current level.
GameState.level: integer
GameState:lines
The number of lines cleared.
GameState:lines() -> integer
GameState:lock
Locks the currently active piece into place. This may invoke other mod functions if they listen to game.events.PRE_LOCK or game.events.LOCKED
. Returns true if the piece actually locked; this may return false if a mod function cancels the lock.
GameState:lock() -> boolean
GameState.next
The tetromino up next.
GameState.next: Tetromino
GameState.oldrotation
The previous rotation. Only really used by the game to check whether the piece was just rotated, but it may be useful to set this sometimes.
GameState.oldrotation: integer
GameState.oldx
The previous x position. Only really used by the game to check whether the piece was just moved, but it may be useful to set this sometimes.
GameState.oldx: integer
GameState.oldy
The previous y position. Only really used by the game to check whether the piece was just moved, but it may be useful to set this sometimes.
GameState.oldy: integer
GameState.over
Whether the player has topped out.
GameState.over: boolean
GameState.player
The player for this game state: either 0 for player 1 or 1 for player 2.
GameState.player: integer
GameState.pushdownpts
Accumulated push-down points when soft-dropping. This value is mutable.
GameState.pushdownpts: integer
GameState:redraw
Redraws the board. This may invoke other mod functions if they listen to game.events.REDRAW
.
GameState:redraw()
GameState.rotation
The current rotation.
GameState.rotation: integer
GameState.score
The current score.
GameState.score: integer
GameState.singles
The number of singles cleared.
GameState.singles: integer
GameState.softdrop
If negative, this will increase, and GameState.fallamt
will remain frozen until this hits zero. If positive, the piece is being soft-dropped.
GameState.softdrop: integer
GameState.tetrises
The number of tetrises (4-line clears) cleared.
GameState.tetrises: integer
GameState.triples
The number of triples cleared.
GameState.triples: integer
GameState:trtrate
The current tetris rate.
GameState:trtrate() -> integer
GameState.waiting
If positive, this will decrease until it hits zero, and nothing else will happen in the main game loop. This is used when the game first starts (to emulate the delay in NES Tetris), and when B-type is cleared.
GameState.waiting: integer
GameState.x
The current x position.
GameState.x: integer
GameState.y
The current y position. Note that y increases from top to bottom.
GameState.y: integer
Music
Music loaded by game.loadmusic
.
type Music = integer
Option
An option registered by a mod.
type Option = table
Option.value
The current value of an option.
Option.value: string | integer
Screen
A screen, uh not much else to say here lol
type Screen = integer
Sfx
Sound effect loaded by game.loadsfx
.
type Sfx = integer
Tetromino
A tetromino, represented by a single character string: "T", "J", "Z", "O", "S", "L", "I".
type Tetromino = string
Texture
A texture that can be drawn to. Note that not all textures support transparency.
type Texture = table
Texture:clear
Clears a texture.
Texture:clear()
Texture:cleartetromino
Clears the space a tetromino would occupy on a texture.
Texture:cleartetromino(t: Tetromino, rotation: integer, x: integer, y: integer)
Texture:drawrect
Draws a rectangle on a texture. Note that the x and y are in pixels (before the texture is scaled by SDL), not tiles.
Texture:drawrect(x: integer, y: integer, w: integer, h: integer, color: integer)
Texture:drawtetromino
Draws a tetromino on a texture. If 'opacity' is specified, it must be an integer between 0 and 255 (defaults to 255).
Texture:drawtetromino(t: Tetromino, rotation: integer, x: integer, y: integer, level: integer, opacity?: integer)
Texture:drawtetrominobrick
Draws a tetromino brick on a texture. 'id' must be a non-negative number less than 4. If 0, this is a no-op. Otherwise, 'id' represents the tile to draw. If 'opacity' is specified, it must be an integer between 0 and 255 (defaults to 255).
Texture:drawtetrominobrick(id: integer, x: integer, y: integer, level: integer, opacity?: integer)
Texture:fillrect
Draws a rectangle on a texture, and fills it in with the given color. Note that the x and y are in pixels (before the texture is scaled by SDL), not tiles.
Texture:fillrect(x: integer, y: integer, w: integer, h: integer, color: integer)
Texture:write
Writes a string or number to the screen. 'width' must only be supplied if writing a number, but it can always be omitted.
Texture:write(msg: string | integer, x: integer, y: integer, width?: integer, color: integer)
game.TILEHEIGHT
The height of the canvas, in tiles.
game.TILEHEIGHT: integer
game.TILEWIDTH
The width of the canvas, in tiles.
game.TILEWIDTH: integer
game.allempty
Checks whether a piece fits into a board at a given location.
game.allempty(board: Board, t: Tetromino, rotation: integer, x: integer, y: integer) -> boolean
game.bg
The background texture. This is cleared whenever the screen is switched, and is intended to be mostly static and infrequently updated. Transparency is not supported on this texture.
game.bg: Texture
game.color.GREEN
A green color from the NES color palette.
game.color.GREEN: integer
game.color.INVERT
Inverts the background and foreground of a color.
game.color.INVERT(color: integer) -> integer
game.color.PURPLE
A purple color from the NES color palette.
game.color.PURPLE: integer
game.color.RED
A red color from the NES color palette.
game.color.RED: integer
game.color.WHITE
Literally just white. idk why i'm even documenting this
game.color.WHITE: integer
game.color.YELLOW
A yellow color from the NES color palette.
game.color.YELLOW: integer
game.emptyboard
A board which is completely empty; useful when combined with game.allempty
to check if a piece is entirely within the playfield. You shouldn't mutate this board; that would be very impolite to the other mods using it. Don't be impolite.
game.emptyboard: Board
game.events.BCLEAR
Triggers before a B-type clear. Setting GameState.waiting
to 0 will cancel the clear.
game.events.BCLEAR: integer
game.events.END_GAME
Triggers immediately before the game ends.
game.events.END_GAME: integer
game.events.FLIP
Triggers when the player attempts to rotate a piece, immediately before the rotation is attempted. Setting GameState.flip
to 0 will cancel the rotation. This is useful if you'd like to implement your own rotation system.
game.events.FLIP: integer
game.events.FIRST_FRAME
Triggers on the first frame that a piece spawns.
game.events.FIRST_FRAME: integer
game.events.FRAME
Triggers every frame, regardless of whether a game is being played.
game.events.FRAME: integer
game.events.GRAVITY
Triggers before a piece is shifted down or locked due to gravity. Setting GameState.fallamt to a non-zero value or setting GameState.softdrop
to a negative value will cancel this.
game.events.GRAVITY: integer
game.events.LOCKED
Triggers after a piece locks. Data about the piece such as its position and rotation is lost; if you need this, use game.events.PRE_LOCK
.
game.events.LOCKED: integer
game.events.LVLUP
Triggers after the level is incremented.
game.events.LVLUP: integer
game.events.PAUSE
Triggers when the game is paused or unpaused. Read game.pause
to determine which.
game.events.PAUSE: integer
game.events.PRE_LOCK
Triggers before a piece locks. Line clears aren't computed at this point; if you need this, use game.events.LOCKED
.
game.events.PRE_LOCK: integer
game.events.RAW_MOUSEDOWN
Triggers when a button on the mouse is pressed. A third argument is supplied to the mod function for this event: a string of the button that was pressed ("Left", "Middle", "Right", "X1", "X2", or "Invalid"). You shouldn't use this unless you have a very specific use-case which calls for it.
game.events.RAW_MOUSEDOWN: integer
game.events.RAW_MOUSEUP
Triggers when a button on the mouse is released. A third argument is supplied to the mod function for this event: a string of the button that was released ("Left", "Middle", "Right", "X1", "X2", or "Invalid"). You shouldn't use this unless you have a very specific use-case which calls for it.
game.events.RAW_MOUSEUP: integer
game.events.RAW_MOUSEMOVE
Triggers when the mouse is moved. A third argument is supplied to the mod function for this event: a table containing two integer values, containing the x and y position of the cursor. You shouldn't use this unless you have a very specific use-case which calls for it.
game.events.RAW_MOUSEMOVE: integer
game.events.RAW_KEYDOWN
Triggers when a key on the keyboard is pressed. A third argument is supplied to the mod function for this event: a string of the key that was pressed. This differs from game.events.RAW_TEXTINPUT
in that it only sends single key presses, regardless of any modifiers (e.g. shift) being used. You shouldn't use this unless you have a very specific use-case which calls for it.
game.events.RAW_KEYDOWN: integer
game.events.RAW_KEYUP
Triggers when a key on the keyboard is released. A third argument is supplied to the mod function for this event: a string of the key that was released. You shouldn't use this unless you have a very specific use-case which calls for it.
game.events.RAW_KEYUP: integer
game.events.RAW_TEXTINPUT
Triggers when something is typed on the keyboard. A third argument is supplied to the mod function for this event: a string of what was typed. This differs from game.events.RAW_KEYDOWN
in that it sends a string of what was actually typed by the user, taking modifiers (e.g. shift) into account, and supporting composition (e.g. for non-ASCII characters). You shouldn't use this unless you have a very specific use-case which calls for it.
game.events.RAW_TEXTINPUT: integer
game.events.REDRAW
Triggers after the board is redrawn.
game.events.REDRAW: integer
game.events.ROTATE
Triggers after the piece is rotated.
game.events.ROTATE: integer
game.events.SHIFT
Triggers after the piece is shifted in the x direction.
game.events.SHIFT: integer
game.events.START_GAME
Triggers when the game starts, immediately after the current and next piece are first chosen. Note that this isn't the first event that's triggered in a game, since game.events.TICK
triggers even during the initial start delay.
game.events.START_GAME: integer
game.events.SWITCH_SCREEN
Triggers when the active Screen
is switched. Read game.scr
to check which screen is now active. For most use cases you probably don't want to use this event; use a more specific event such as game.events.END_GAME
instead.
game.events.SWITCH_SCREEN: integer
game.events.TICK
Triggers every frame for all players in-game.
game.events.TICK: integer
game.events.TOPOUT
Triggers after the player tops out.
game.events.TOPOUT: integer
game.fg
The foreground texture. This is cleared whenever the screen is switched, and is intended for screen-dependent graphics that are frequently updated. This texture supports transparency.
game.fg: Texture
game.freeze
Completely freezes all game logic. The only event that's triggered when the game is frozen is game.events.FRAME
. This function can be safely called more than once; subsequent calls will have no effect. Call game.unfreeze
to resume game logic.
game.freeze()
game.gravity
Gets the gravity of a level; i.e. the value that GameState.fallamt
must reach before the current piece moves down or locks.
game.gravity(level: integer) -> integer
game.haltmusic
Halts the currently playing music if there is any.
game.haltmusic()
game.height
The B-type height, or nil if not playing on B-type. This value is mutable, but mutating it when not on game.screen.LVLSELECT
when game.type
is "b" won't have any effect. This value will never be greater than 8.
game.height: integer?
game.loadmusic
Loads music from the given path and returns an object that can be played with game.playmusic
. The working directory is set to the directory that mod.lua resides in when the file is first run, so you can use a relative path here.
game.loadmusic(path: string) -> Music
game.loadsfx
Load a sound effect from the given path and returns an object that can be played with game.playsfx
. The working directory is set to the directory that mod.lua resides in when the file is first run, so you can use a relative path here.
game.loadsfx(path: string) -> Sfx
game.multiplayer
Whether or not the game is being played multiplayer, either local or online.
game.multiplayer: boolean
game.newboard
Creates a new board, which can be safely mutated.
game.newboard() -> Board
game.newoption
Registers a new option. The second argument is a table, which must have a 'default' key, whose value is the default value of the option, and an 'events' key, whose value is the bitwise OR of all events that functions for this option will listen to. Register values for the new option by creating functions within the option, i.e. for option foo with value bar: `function foo.bar(ev, player)`. ev is the event that caused this function to be called, and player is the player the event is associated with: either 0 for player 1, or 1 for player 2.
game.newoption(name: string, {default: string | integer, events: integer}) -> Option
game.options.lines_per_level
TODO
game.options.lines_per_level: CoreOption
game.options.rng
TODO
game.options.rng: CoreOption
game.overlay
The overlay texture. This is intended for screen-independent graphics. This texture supports transparency.
game.overlay: Texture
game.pause
Whether the game is currently paused. This value is mutable.
game.pause: boolean
game.pausemusic
Pauses the currently playing music if there is any.
game.pausemusic()
game.players
GameState states for both players. If game.multiplayer
is false, index 1 is invalid here.
game.players: [0...1]GameState
game.playgamemusic
Plays game music according to the value of the "music" core option.
game.playgamemusic()
game.playmusic
Plays music.
game.playmusic(mus: Music)
game.playsfx
Plays a sound effect. If 'pan' is negative, the sound plays moreso to the left, if positive, it plays moreso to the right. If zero, the sound plays equally left and right (i.e. no position changes). The default pan is zero.
game.playsfx(sfx: Sfx, pan?: integer)
game.prompt
Displays a prompt containing one or two choices. When a choice is selected, the respective callback function is called. This should, at minimum, set game.scr
to a different screen.
game.prompt(msg: string, choice1: string, action1: function (), choice2?: string, action2?: function ())
game.rng.misc
A miscellaneous 16-bit unsigned integer used by the selected RNG algorithm. The exact meaning of this number differs based on the active RNG algorithm. This value is mutable; if your mod implements an RNG algorithm that preserves data between games, this should be used so games replay correctly.
game.rng.misc: integer
game.rng.next
Runs the PRNG function to get the next random number and returns the result.
game.rng.next() -> integer
game.rng.value
The most recently generated random number.
game.rng.value: integer
game.scr
The currently active screen. This can be mutated to switch to a different screen, potentially invoking other mod functions that listen to game.events.SWITCH_SCREEN
. game.screen.PROMPT
is NOT a valid argument for this function; use game.prompt
instead.
game.scr: Screen
game.screen.CREDITS
The credits screen.
game.screen.CREDITS: Screen
game.screen.GAME
The game screen.
game.screen.GAME: Screen
game.screen.INPUT
The input mapping screen.
game.screen.INPUT: Screen
game.screen.LEADERBOARD
The leaderboard screen, where the player enters their name to save their score.
game.screen.LEADERBOARD: Screen
game.screen.LVLSELECT
The level select screen.
game.screen.LVLSELECT: Screen
game.screen.ONLINE
The online screen.
game.screen.ONLINE: Screen
game.screen.OPTIONS
The options screen.
game.screen.OPTIONS: Screen
game.screen.PROMPT
The prompt screen, used for user input and error messages.
game.screen.PROMPT: Screen
game.screen.REPLAY
The replay selection screen.
game.screen.REPLAY: Screen
game.screen.ROCKET
The rocket (statistics) screen.
game.screen.ROCKET: Screen
game.screen.TITLE
The title screen.
game.screen.TITLE: Screen
game.startlevel
The level the game was started at, or the level the game will start at if not currently in a game. This value is mutable, but mutating it when not on game.screen.LVLSELECT
won't have any effect.
game.startlevel: integer
game.type
The type of the game, either "a", "b", or nil if inapplicable.
game.type: string?
game.unfreeze
If the game was frozen by game.freeze
, resumes game logic. This function is a no-op if the game isn't frozen.
game.unfreeze()
Undocumented
CoreOption.__name: string
game.__useroptions: table