Lua games

A script game is written in Lua 5.4. veduta.json names its main script, and the tool runs it itself: no Go code, no build, the same commands (build checks the scripts, test, simulate, render, bench, fuzz, run) and the same MCP tools.

{ "veduta": "project/1", "name": "mygame", "engine": "v2.0.0", "script": "main.lua" }

Every .lua file of the project is read when a run starts (the directories out, bin, the cooked assets and hidden ones are skipped). The main script runs once per run, before the scene is loaded; it fills the game and kinds tables. A run is deterministic: the same seed and the same inputs give the same trace on every machine.

Playing it

veduta sim (Windows) plays the game in the simulator: the console's panel at a whole scale, in its 16-bit colors, with the keyboard pressing the buttons (arrows or W A S D, Space or Z for A, X or Shift for B, Enter or Tab for Select, Escape or Backspace for Cancel; Ctrl+Q leaves) or any pad. Three keys work the player itself:

Editing while it plays

The simulator watches the scripts and the asset sources. When one is saved it reads everything again (a changed scene, texture or material is compiled on the spot) and restarts in place: in the scene the game was in, or in its world around the cell the player stands in, with the same seed. So a level is laid out with the scene file open next to the simulator, and a hud is written in game.draw while it shows: every save shows the result a second later, without playing back to it. The run starts again at tick 0 there; game.init runs again, so a game whose init loads its title scene comes back to the title.

veduta sim --scene level3 (or --world land --at 4,-2, and --seed N) opens the simulator in that scene rather than the project's default; the debugger's "scene" does the same in VS Code (the snippet "Veduta: Play a scene"). F5 records from there, and the scenario it writes names that scene.

An error stops the run but not the simulator: the last frame stays, the error (a script's file, line and traceback; an asset that does not compile; a scene that does not load) is written over it, and the next save that fixes it reloads. F9 does the same from the start.

Debugging

veduta dap is a debug adapter (the Debug Adapter Protocol, on stdin and stdout), which VS Code's Veduta extension starts on F5. It plays the game ("mode": "play", the simulator on Windows) or runs a scenario headless ("mode": "scenario", "scenario": "collect") with a debugger on the scripts: breakpoints, pause, stepping over, into and out of calls (into a module require runs too), the call stack, each call's locals and upvalues and the globals, tables and entities opened field by field, and a name with its fields (e.state.score) evaluated on hover or as a watch. "stopOnEntry": true stops before the first statement. Ctrl+F5 runs without it. While the game is stopped the simulator's window does not redraw. A run under the debugger gives the same trace as one without.

Editing

veduta init sets an editor up, and veduta upgrade brings it to the tool's version: .veduta/lua/veduta.d.lua describes this API for the Lua Language Server (VS Code's sumneko.lua, which .vscode/extensions.json recommends; .luarc.json points it there and turns off io, os, debug and package), and .veduta/schema/ holds a JSON Schema of every source format, which .vscode/settings.json maps to veduta.json, *.vscene, *.vscenario and the other asset files. The editor then completes the API and the fields of every file, shows their descriptions, and marks a misspelt function, a button that does not exist or a field the format does not have. upgrade sets only its own keys in .vscode/settings.json, .vscode/extensions.json and .luarc.json, and leaves one with comments in it as it is.

The game

function game.init()        -- once, after the first scene is loaded
end

function game.update()      -- once per tick (20 per second), before the entities
end

function game.draw()        -- once per rendered frame, after the scene: the hud
end

All three are optional. A Lua error in any of them, or in a kind, stops the run with the script's file, line and traceback.

Kinds

An entity whose kind names an entry of kinds gets its behaviour from it:

kinds.coin = {
  init = function(e)         -- when the entity is loaded or spawned
    e.state.value = 1
  end,
  update = function(e)       -- once per tick, in entity id order, after game.update
    e:set_rotation(0, engine.tick * 4.5, 0)
  end,
}

static, camera and light are built-in kinds. A scene that names a kind no script defines fails to load.

Two more callbacks, both optional:

kinds.coin = {
  on_touch = function(e, other)   -- e and other started to overlap (end of the tick)
    if other:has_tag("hero") then e:despawn() end
  end,
  on_despawn = function(e)        -- e:despawn() is removing it
    particles.burst{x = e.x, y = e.y, color = "#ffd84a"}
  end,
}

on_touch runs once when two entities start to overlap, for each of them whose kind has it, as the trace's collision event; on_despawn runs inside e:despawn(), before the entity goes.

Entities

An entity is a value with fields and methods. The same entity is always the same value, so a == b compares entities.

Setting any other field is an error: keep your own values in state.

scene

The scene does not exist while the main script runs: call these from game.init on.

input

The console has eight buttons: up, down, left, right, a, b, select (the game's menu) and cancel (back). Home leaves the game and never reaches it.

While a dialog is open or a scene fades, and on the tick a dialog closes, these read as nothing (false, 0): the dialog has the buttons.

camera

world

map

The scene's tile map (docs/map.md): a grid of cells painted with terrains, in layers, and objects. Cell (x, y) counts columns right and rows down from the top-left cell, from 0. A layer argument is a layer's name.

A scene without a map raises an error from every function but map.name and map.load.

hud

Only inside game.draw, except hud.text_width and hud.wrap, which measure. Coordinates are pixels from the top left of the frame.

A color is "#rrggbb", "#rrggbbaa" or an integer 0xrrggbb; the default is white. A texture drawn in the hud is a texture asset like any other (assets/textures/<name>.vtex, often a PNG image layer): an icon sheet is one texture and src picks each icon.

engine

engine.tick (0 in game.init), engine.dt (seconds per tick), engine.width, engine.height (the frame: the project resolution, or in game.draw the frame being drawn), engine.headless, the project's engine.name and engine.title, and engine.api, the API level of the runtime (1 in v2.0.0). A game that needs a later level says so with "api" in veduta.json, and an older console refuses it with a message.

mesh and volume

Models built while the game runs: the terrain of a block world, a shape that changes. The loops run in the engine, not in Lua, so a whole chunk of blocks is one call.

local world = volume.new(16, 8, 16)
world:fill(0, 0, 0, 15, 2, 15, 1)       -- three layers of stone
world:fill(0, 3, 0, 15, 3, 15, 2)       -- grass on top
mesh.set("game:chunk", mesh.voxels(world, {[1] = "stone", [2] = "grass"}))
scene.spawn{name = "chunk", model = "game:chunk"}

save

Saves outlive a run: progress, settings, high scores. A save is a table of numbers, strings, booleans and tables of them, stored under a name (a valid asset name: slot1, settings). Integers and floats come back as they went in, and tables in the order of their keys, sorted.

Where saves live depends on the run. The simulator and the console keep them in files, one per save: the console on its card (saves/<game>/), the simulator in out/saves of the project, or wherever VEDUTA_SAVE_DIR says. Tests never touch those: a run starts with the saves its scenario lists ("saves" in the scenario topic) and keeps its writes in memory, recording save_write and save_remove events a scenario can count.

function game.init()
  local data = save.read("slot1")
  if data then
    gold, level = data.gold, data.level
  end
end

local function on_checkpoint()
  local ok, err = save.write("slot1", {gold = gold, level = level, party = {"mira", "tobi"}})
  if not ok then
    message = "COULD NOT SAVE"   -- the card is full or missing; the game goes on
    print(err)
  end
end

Time: timer, tween, task

Timers, tweens and tasks count ticks, so they replay exactly. Each belongs to the screen that made it (it waits while another screen is pushed over, and is cancelled when that screen leaves) and to an owner entity when it has one (cancelled when the entity is despawned). game.pause stops those of the game. A scene or world load cancels all but those made with keep. They run after the kinds, in the order they were made.

task.start(function()
  ui.dialog("Mira", "The bridge is out.")
  tween(scene.find("boat"), {x = 12}, 2, "in_out_sine")
  wait(2)
  if ui.dialog("Mira", "Get in?", {choices = {"Yes", "No"}}) == 1 then scene.load("river", {fade = 0.4}) end
end)

Flow: screen, signal

A game made of screens gives each one a table of callbacks and moves between them. The screens on the stack are drawn bottom first, after game.draw; only the top one updates. game.update and the kinds run only while there is at most one screen: a screen pushed over the game (a pause menu, an inventory) stops it until it is popped.

screen.add("title", {update = function() if input.pressed("a") then screen.go("play") end end,
                     draw = function() hud.text(160, 100, "PRESS A", {align = "center"}) end})
screen.add("play", {enter = function() scene.load("level1") end,
                    update = function() if input.pressed("select") then screen.push("pause") end end})
screen.add("pause", {update = function()
                       local i = pause_menu:update()
                       if i == 1 or input.pressed("select") then screen.pop() end
                     end,
                     draw = function() pause_menu:draw() end})
function game.init() pause_menu = ui.menu{"Resume", "Quit"}; screen.go("title") end

ui

Menus, dialogs and toasts drawn in the look of ui.style (back, border, text, accent, dim colors, or panel, a texture drawn as a nine-slice with panel_border).

particles

Small squares that fly, fall and fade, drawn over the scene and under the hud, 512 at most (a burst past it makes fewer). They move after the kinds and wait while the game is paused.

settings, lang and T

settings is a table that saves itself: settings.volume = 3 writes the save settings at once, and the next run reads it back. settings.defaults{volume = 5} gives the values of keys never set; settings.reset() forgets them all, settings.all() is a copy of every value.

Texts in several languages live in lang/<code>.lua beside the main script, each returning a table (nested tables give dotted keys):

-- lang/it.lua
return {menu = {play = "Gioca"}, hello = "Ciao, {name}!"}

trace, invariant, require

The standard library

string, table, math and utf8 behave as in Lua 5.4, with the additions below.

math.random draws from the run's seeded generator, so it is deterministic. print writes to the tool's error output. coroutine works as in Lua 5.4, and a coroutine may even yield from inside a function the engine calls back (a table.sort comparison). Differences from Lua 5.4: pairs visits keys in the order they were first set; there is no goto, no io, os, debug or load, and no string.pack, string.unpack, string.packsize or string.dump. A callback that runs for 20 million steps without returning is stopped as an endless loop.

Full example

main.lua of a game where the D-pad moves a hero that collects coins:

local SPEED = 4
local score = 0

function game.init()
  invariant("score_non_negative", function() return score >= 0 end)
end

function game.draw()
  hud.text(4, 4, "SCORE " .. score)
end

kinds.hero = {
  update = function(e)
    local dx, dy = input.dpad()
    e:move(dx * SPEED * engine.dt, dy * SPEED * engine.dt, 0)
    for _, coin in ipairs(e:overlapping("coin")) do
      score = score + 1
      trace("coin_collected", {coin = coin.name, score = score})
      coin:despawn()
    end
    e.state.score = score
  end,
}