Scripting (Lua)

A mod has up to two scripts, both Lua 5.4:

• server.lua — the rules. The game server runs it, once for each lobby. It decides: it watches the players, changes HP, rings, speed, the clock, sends messages, ends rounds.
• client.lua — the screen. Each player's game runs it. It draws your HUD and plays sounds, from what the server tells it.

The two talk through game.sync (server → every player), game.event (server → players) and game.send (player → server).

Scripts define functions with known names (hooks) that the game calls. Everything else (game.*, hud.*, mod) is given to them. The standard table, string, math, utf8 and coroutine libraries are there; files, load, os, io and debug are not.

A whole mode in 20 lines

-- server.lua: survivors get a ring every 5 seconds; the one with most rings at the end wins
local timer

function on_round_start(map)
  game.say("`RING RUSH~: most rings at the end wins!")
  timer = game.every(5, function()
    for _, p in ipairs(game.players()) do
      if p.alive and not p.exe then game.give_rings(p, 1) end
    end
  end)
end

function on_round_end(winner)
  game.cancel(timer)
  local best
  for _, p in ipairs(game.players()) do
    if not p.exe and (not best or p.rings > best.rings) then best = p end
  end
  if best then game.say(best.name .. " had the most rings: " .. best.rings) end
end

server.lua

The mod table

mod.id, mod.version, mod.name, and mod.config: the host's settings (the manifest's settings, with the host's values), for example mod.config.fuse.

Players

game.players() returns a list of players; game.player(id) one player (or nil). A player is a table:

Every function that takes a player takes the table or its id.

game.*

What changes a player (kill, set_hp, set_rings, teleport, freeze, launch, set_stat, message, sound) is done by their own game: it works on web and phone players; the server's bots ignore it.

Hooks

Define any of these in server.lua:

Objects (api 2)

The mod's objects (objects/<name>.json, made in the Mod Studio) are placed in its maps or made by a script; the server moves them and runs their events, and every player sees them.

An object is a table (self in its events): x, y, vx, vy (added to x, y every frame), sprite (a sprite's name), frame (nil: animated), visible (false: not drawn, and nothing touches it), solid (false: players go through a solid one), xscale, yscale (-1 mirrors it), alpha (0-1), angle (degrees), id, type, and its own fields. Change them and every player sees it (20 times a second).

Its events, in objects/<name>.lua:

-- objects/coin.lua
function create(self)
  self.vy = 0
end

function touch(self, player)     -- a player came onto its box
  game.give_rings(player, self.value)
  game.sound(player, "snd_ring")
  game.destroy(self)
end

create(self), step(self) (60 a second), touch(self, player), leave(self, player), destroy(self). They see the game rules' globals. At most 256 objects at a time; they are all removed when the round ends. The Studio's Run plays them in your game alone (no server).

A character's own moves (api 2)

A mod character can have characters/<name>.lua beside its .json (the Studio: Give it moves). It runs in the game of whoever plays that character, every frame, after the game's own moves:

function step(me, input)
  if me.ground then
    me.dashes = 1
  elseif input.pressed.c and me.dashes > 0 then   -- a dash in the air
    me.dashes = 0
    me.vx = 9 * me.facing
    me.vy = -1
    me.anim = "spr_tails_fly"                     -- shown to everyone
  end
end

me: x, y, vx, vy, ground, facing (1 / -1), anim (a sprite's name shown instead of the game's animation, nil: the game's), anim_speed, and to read state, character, hp, rings, dead; its own fields stay from frame to frame. input: left, right, up, down, a, b, c (held) and input.pressed.<key> (this frame). It has client.lua's functions: game.send asks the game rules for what the server decides (damage, objects...).

Limits

Each lobby's script has 48 MB of memory and about three million instructions per hook call (and six million for all the calls of one tick): a script stuck in a loop is stopped, not the server, even inside pcall, xpcall or a coroutine. Errors go to the server's console; after 25 errors in a round its hooks rest until the next round.

Also: at most 1000 timers at a time; game.sync keys up to 40 characters (not starting with config.); 200 game.log lines and 20 game.say / game.tell a second; 240 mod messages a second to each player (more are dropped; a synced value always arrives, a moment later); game.send from each player: 30 a second (the web game queues them). setmetatable refuses a __gc field, and patterns (string.find, gsub...) that would take too long stop with "pattern too complex".

client.lua

The mod table

mod.id, mod.version, mod.name, mod.config (the host's settings, as on the server) and mod.synced (what the server shared with game.sync).

hud.* (drawing, in on_draw)

The screen is 480 by 270. Colours are "#rrggbb" or a number 0xRRGGBB; texts take the colour codes.

game.*

Hooks

Limits

32 MB of memory and about two million instructions per hook call, as on the server (pcall can't catch running out of time). After 50 errors in a round the script rests until the next round; a mistake in on_draw runs every frame, so test it with the Studio's Run first.

An example with both: Hot Potato

-- server.lua
local holder, left

local function give(p)
  holder, left = p.id, mod.config.fuse
  game.sync("holder", p.id)
  game.sync("holder_name", p.name)
  game.sync("left", left)
  game.message(0, p.name .. " has the potato!", 2)
end

function on_round_start(map)
  holder = nil
  game.timer(3, function()
    local s = {}
    for _, p in ipairs(game.players()) do
      if p.alive and not p.exe then s[#s + 1] = p end
    end
    if #s > 0 then give(s[game.random(#s)]) end
  end)
end

function on_tick(frame)
  if not holder then return end
  if frame % 60 == 0 then
    left = left - 1
    game.sync("left", left)
    if left <= 0 then
      game.kill(holder)
      game.sound(0, "snd_boom")
      holder = nil
      game.sync("holder", 0)
      return
    end
  end
  for _, p in ipairs(game.players()) do
    if p.alive and not p.exe and p.id ~= holder and game.distance(holder, p) < 32 then
      give(p)
      return
    end
  end
end

-- client.lua
function on_draw()
  local h = mod.synced.holder
  if not h or h == 0 then return end
  if game.me().id == h then
    hud.rect(140, 22, 200, 22, "#000000", 0.6)
    hud.center(240, 26, "`YOU HAVE THE POTATO!~  " .. mod.synced.left, "#ffffff", 0.6)
  else
    hud.center(240, 26, "potato: " .. mod.synced.holder_name, "#ffd040")
  end
end

The full mod (with a passing cooldown and a winner) is on the site as Hot Potato: download it and open it in the Mod Studio (Open a .dmod file) to read it.