Global variables

These variables are always there to use.

game_manager

GameManager?source

if game_manager.game_props.game_has_focus == false then
    message("Come back soon!")
end

The GameManager gives access to a couple of Screens as well as the pause and journal UI elements

meta

tablesource

meta.name = "Awesome Mod"
meta.version = "1.0"
meta.author = "You"
meta.description = [[
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut at nulla porttitor, lobortis magna at, tempus dolor. Cras non ligula tellus. Duis tincidunt sodales velit et ornare. Mauris eu sapien finibus dolor dictum malesuada in non elit.

    Aenean luctus leo ut diam ornare viverra. Nunc condimentum interdum elit, quis porttitor quam finibus ac. Nam mattis, lectus commodo placerat tristique, justo justo congue dui, sed sodales nunc sem ut neque.
]]
-- set this to enable unsafe mode
--meta.unsafe = true

-- rest of your mod goes here

Table of strings where you should set some script metadata shown in the UI and used by other scripts to find your script.

online

Online?source

message = "Currently playing: "
for _, p in pairs(online.online_players) do
    if p.ready_state ~= 0 then
        message = message .. p.player_name .. " "
    end
end
print(message)

The Online object has information about the online lobby and its players

options

anysource

register_option_bool("bomb_bag", "BombBag", "Spawn bomb bag at the start of every level", false)

set_callback(function()
    if options.bomb_bag then
        -- Spawn the bomb bag at player location thanks to the LAYER.PLAYER1
        spawn_entity_snapped_to_floor(ENT_TYPE.ITEM_PICKUP_BOMBBAG, 0, 0, LAYER.PLAYER1)
    end
end, ON.LEVEL)

Table of options set in the UI, added with the register_option_functions, but nil before any options are registered. You can also write your own options in here or override values defined in the register functions/UI before or after they are registered. Check the examples for many different use cases and saving options to disk.

pause

anysource

Access the PauseAPI, or directly call pause(true) to enable current pause.pause_type

players

anysource

-- Make the player invisible, use only in single player only mods

players[1].flags = set_flag(players[1].flags, 1)

An array of Player of the current players. This is just a list of existing Player entities in order, i.e., players[1] is not guaranteed to be P1 if they have been gibbed for example. See get_player.

prng

PRNG?source

--Make it so there is 50% chance that the Ankh will be destroyed

set_callback(function ()
    -- more or less 50% chance
    if prng:random(2) == 1 then
        -- get all Ankh's in a level
        ankhs = get_entities_by(ENT_TYPE.ITEM_PICKUP_ANKH, MASK.ITEM, LAYER.BOTH)
        for _, uid in pairs(ankhs) do
            get_entity(uid):destroy()
        end
    end
end, ON.LEVEL)

The global prng state, calling any function on it will advance the prng state, thus desynchronizing clients if it does not happen on both clients.

savegame

SaveData?source

Print best time from savegame

prinspect(savegame.time_best)

Provides access to the save data, updated as soon as something changes (i.e. before it's written to savegame.sav.) Use save_progress to save to savegame.sav.

state

StateMemory?source

if state.time_level > 300 and state.theme == THEME.DWELLING then
    toast("Congratulations for lasting 5 seconds in Dwelling")
end

A bunch of game state variables. Your ticket to almost anything that is not an Entity.