Introductory modding tutorial

This guide will walk you step by step through writing your first mod. More specifically, this guide will walk through creating a mod that lets you change the next piece by using the directional buttons.

generic tetromino game mods are written in Lua. This guide isn't a tutorial for Lua itself, though if you already have some rudimentary programming experience you may be able to just follow along and learn as you go. You may prefer to first go through a proper Lua tutorial though.

Anatomy of a mod

(Almost) every mod will register an option, which will listens for a set of events and call a function when an event is triggered. Examples of events are PAUSE, ROTATE, and TICK. The specific function called depends on the value of the option, which can be set by the player on the options screen. Typically, you'll want the default value of an option to be something like "off", with a no-op function. This allows the player to conditionally enable the mods they want, even if many are installed.

If that all sounds complicated, don't worry: it sounds a lot more complicated than it actually is. Here's an example of a simple "hello world" mod:


-- every mod will begin by first importing the "game" package, which is provided
-- by generic tetromino game.
local game = require"game"

-- register a new option named "hello".
local hello = game.newoption("hello", {
    -- by default, the value is set to "off", disabling the mod.
    default = "off",
    -- this mod only listens to one event: STARTUP, which triggers exactly once
    -- when the game first launches.
    events = game.events.STARTUP,
})

-- a function is provided for every possible value the "hello" option can have.
-- the game will recognize which functions are defined here, and only allow
-- these values to be cycled through on the options screen. it will also display
-- an error message if the config file sets the option to an invalid value.

-- the default function doesn't do anything, so the mod is disabled.
function hello.off(ev, player, flags)
    -- no-op
end

-- the option may have one other value: "world". this function will run when the
-- STARTUP event is triggered. this is where all the actual mod logic is
-- implemented.
function hello.world(ev, player, flags)
    -- the game.prompt function shows a prompt to the player. here, we make it
    -- so when the game launches, a prompt saying "HELLO WORLD" is displayed.
    -- when the player selects "CONTINUE", the supplied function is called,
    -- which sends the player to the title screen.
    game.prompt("HELLO WORLD", "CONTINUE", function ()
        game.scr = game.screen.TITLE
    end)
end