Veduta game API

A Veduta game is a Go program whose main calls veduta.Run(&game.Game{}). The same binary plays on the console (a linux/arm64 board drawing on its panel's framebuffer and reading a gamepad) and, with -headless, renders, simulates and answers queries for the veduta tool on any machine, including a server with no display. Game logic lives only in the game binary; the tool never contains game code.

package main

import (
	"github.com/riftbane/veduta-engine"
	"mygame/game"
)

func main() { veduta.Run(&game.Game{}) }

Interfaces

type Game interface {
	Init(ctx *veduta.Context) error              // once, after the first scene is loaded
	Update(ctx *veduta.Context, in veduta.Input) // exactly once per tick, before behaviours
	Draw(ctx *veduta.Context, dl *gfx.DrawList)  // once per rendered frame, after the scene
}

type Behaviour interface {
	Update(ctx *veduta.Context, e *scene.Entity, in veduta.Input)
}

func RegisterKind(name string, ctor func(*scene.Entity) veduta.Behaviour)

• RegisterKind binds a scene entity kind to the constructor of its behaviour. Call it from an init function. Names are lowercase [a-z0-9_-]; static, camera and light are built-in kinds without behaviour. Loading a scene with an unregistered kind fails.
• The constructor runs when an entity of that kind is loaded or spawned; it may set e.State. veduta.BehaviourFunc adapts a plain function.
• Behaviour values must be stateless: keep per-entity state in e.State (a pointer to a struct with exported fields). The trace records it as state.<json field> and snapshots save it with encoding/gob.

Context

type StateCodec interface {
	SaveState(enc *gob.Encoder) error
	LoadState(dec *gob.Decoder) error
}

Input

veduta.Input is a value type, identical whether it comes from the console or a script.

A button pressed and released within one tick appears in Pressed and Released but not in Held.

The console's controls

The console has a D-pad, A, B, Select, Cancel and Home. A game sees eight buttons; Home is the console's, and no game can see or swallow it: pressed, it opens the console's overlay over the game (the game keeps running, with no button held); held for a second, it leaves the game, even one that has stopped answering.

A USB pad has no Home button, so Select and Start pressed together are its Home; alone, its Start is the game's menu and its Select is Cancel. A pad's other buttons (X, Y, shoulders) and sticks beside a four-button D-pad are ignored. A program that plays games without an overlay (veduta run) leaves on a press of Home.

Cameras

ctx.Scene.Camera is the camera the player and render --camera scene draw with; a game may replace it during Update.

• scene.Camera2D(center gmath.Vec2, height float32) scene.Camera is the camera of a 2D game played in the XY plane: orthographic, looking down −Z at (center.X, center.Y, 0) from z = scene.Camera2DDistance (100), +X to the right and +Y up on screen, height world units visible vertically (the width follows from the aspect ratio), near 0.1 and far 200, so z from −100 to 99.9 is visible and a larger z is nearer the camera. Follow a hero with p := hero.WorldPosition(); ctx.Scene.Camera = scene.Camera2D(gmath.V2(p.X, p.Y), 12). It is the same camera as a scene file's "type": "orthographic", "size": 12, "position": [x, y, 100], "look_at": [x, y, 0]. The 2d docs topic is the recipe for a 2D game: camera, sprites, layers, hitboxes, HUD, pad input and the traps.
• Camera.LookFrom(eye, yawDeg, pitchDeg) places a camera at eye looking along yaw and pitch, keeping the projection.

Entities

scene.Entity fields: ID, Name, Kind, Transform (Position, Rotation quaternion, Scale, relative to Parent), Model, Material, Tags, AABB (world bounds of the hitbox, else of the model, recomputed after every tick), Visible, State, Parent, Hitbox *gmath.AABB (the scene file's hitbox: a local-space box that replaces the model bounds as the source of AABB, so collisions, Overlapping, no_overlap and the trace's aabb use it; nil for none; Spawn copies it), Layer int (the scene file's layer: the first key of the draw order, lower layers drawn first; within a layer opaque parts in id order, then blended parts back to front by depth along the view axis; opaque and cutout parts write depth, so among them the nearest is in front whatever the layer, while blended parts write none, so an opaque part on a higher layer is drawn over a blended part on a lower one whatever their depth). Useful methods: WorldPosition(), World(), HasTag(t), Alive(). Use gmath for math: its Sin/Cos/Atan2 are deterministic on every platform; never use math.Sin in game logic.

Coordinates: right-handed, Y up, −Z forward, meters. Angles are degrees in files and radians in code. rotation_deg: [x, y, z] means R = Ry·Rx·Rz.

Tick timeline

1. Tick 0: the scene is loaded (ids 1…n in scene-file order), Init runs, then the engine records tick 0 (events scene_load and any spawns from Init).
2. Each tick t = 1, 2, …: Game.Update(ctx, in), then every live entity's behaviour in id order (entities spawned during the tick start next tick), then despawns are applied, transforms and AABBs are recomputed, collisions and invariants are checked, and tick t is recorded.

Input events of a script at tick t are part of the Input of tick t; events at tick 0 apply before the first update and appear in tick 1. The simulation runs at tick_rate (20 Hz by default); there is no interpolation and the player renders once per tick. With VEDUTA_PERF=<seconds> the player writes its frame times (below). The player collects garbage less often than a Go program does by default, at a heap five times what is live (GOGC=400; GOGC in the environment overrides it), and right after a scene or world loads, where the load already stalls a frame.

Frame times on a console

With VEDUTA_PERF=<seconds> (a console's dashboard sets 10 for every game) the player writes, that often, one line like this one to stderr, which a console copies to its kernel log:

veduta: perf: gpu (VC4 V3D 2.1), 200 frames in 10.0 s, update 2.10 ms, render 18.40 ms, present 6.20 ms, worst 41.00 ms, 0 over 50 ms, stepped 200, rendered 200, build 3.10 ms, submit 4.00 ms, readpixels 9.00 ms, convert 2.30 ms, keep 0.20 ms, overlay 0.01 ms, pack 2.00 ms, write 3.99 ms, commands 42.0, gl calls 812.0, gc 3, alloc 7.5 KB, self user 55.0%, self system 10.0%, cpu user 56.0%, cpu system 20.0%, cpu softirq 3.0%, cpu idle 20.0%

Fields are separated by ,, each a name and a value; the first ones, up to over, are the line as it has always been, and keep their order. Times are means per frame over the period, in milliseconds.

Measuring a draw

internal/drawcost in the engine's repository is a Lua game that draws N small textured quads, each an entity and so one draw command of two triangles: 25, then 100, then 200, 400 ticks (20 s) each, and again. Its scenes n25, n100 and n200 draw one count only, for bench, which checks the counts but not a console's times. On a console:

1. Put the folder on the card as games/drawcost (veduta deploy from the folder, the card plugged in, or a plain copy).
2. Start Draw cost from the dashboard, let it run a few minutes, leave it and power off.
3. Take its veduta: perf: lines from the card's vedutaos/kernel.log. Keep those whose commands is a count plus the hud's one command (26, 101, 201): a period across two counts has a mean between them.
4. Fit a straight line through render against commands: its slope is the milliseconds a draw costs, its intercept what a frame costs with nothing in it. The parts (submit, readpixels) tell where the draws' cost lands.

Determinism rules

• Randomness only through ctx.RNG; no time.Now, no environment or file access after Init.
• Never let map iteration order affect state or trace: sort keys first.
• Round every float product that feeds an addition or subtraction with a conversion to its own type: y += float32(v * ctx.DT), float32(a*b) + float32(c*d). On linux/arm64, the console, the compiler may fuse a*b + c into one instruction that rounds once, where amd64 rounds twice; about a quarter of all inputs then differ in the last bit and the trace drifts from goldens recorded on a PC. A conversion is a rounding point the compiler may not fuse across, and it costs nothing on amd64. This holds across statements and through inlined calls, so p := a * b followed by q := p + c needs it too. gmath already rounds inside its own operations (Vec3.Scale, Mul, Dot, Cross, Lerp, matrix and quaternion products), so pos.Add(vel.Scale(ctx.DT)) is safe as written. veduta doctor builds the game for linux/arm64 and lists every line of the game's code where a fusion happened, and every line of another package that fused after it was inlined into a function of the game, such as gmath/vec.go:105 inlined in demo/game.updatePlayer: there the product to round is the one that function passes in, pos.Add(gmath.V3(float32(a*b), 0, 0)). The text names the first ten places; veduta doctor --json lists all of them in the check's sites.
• Use gmath's trigonometry, never math.Sin, math.Exp, math.Pow or math.Log: those are not the same on every architecture. math.Sqrt, Abs, Floor, Ceil, Trunc and Mod are exact everywhere.
• Same seed + same input ⇒ same trace hash and identical frames on linux/amd64, linux/arm64 and windows/amd64 (the engine's CI runs its goldens on all three).

Trace

One canonical JSON object per tick in trace.jsonl:

{"entities":[{"aabb":{"max":[0.5,1,-0.75],"min":[-0.5,0,-1.75]},"id":2,"kind":"player","material":"hero","model":"hero","name":"player","parent":"","position":[0,0,-1.25],"rotation_deg":[0,180,0],"scale":[1,1,1],"state":{"score":1},"tags":["player"],"visible":true}],"events":[{"event":"gem_collected","gem":"gem_1","score":1}],"tick":75}

Keys are sorted, no whitespace, floats use the shortest form that round-trips (float32 values as float32), non-finite numbers are the strings "NaN", "+Inf", "-Inf". Entity summaries hold: id, name, kind, position (world), rotation_deg (local Euler angles, R = Ry·Rx·Rz, pitch in [-90, 90]), scale (local), visible, tags, model, material, parent (name, "" for none), aabb ({min, max}, world; only entities with a model or a hitbox, and the hitbox's bounds when one is set) and state (only when set). Scenario expectation paths address these keys (position.z, aabb.max.y, state.score). The trace hash is the SHA-256 of the file's bytes.

Built-in events: scene_load (scene, entities), spawn and despawn (id, name, kind), collision (a, b, a_id, b_id: two AABBs started overlapping this tick; touching does not count; two static entities never collide), invariant_violation (name, detail: an invariant started failing this tick). Game events come from ctx.Trace.

Invariants

Checked after every tick (including tick 0). A scenario's invariants list is used when present, else the project's. Built-ins: finite_positions, within_bounds (project bounds), entity_count_max:N, no_overlap:tagA,tagB. Any other name must be registered by the game with ctx.Invariant(name, pred). A violation is reported when an invariant starts failing, not again while it keeps failing.

Headless subcommands

Every game binary accepts -project DIR (default .), -version, and:

game -headless render   --scene S --tick T --seed N --camera P --mode M --width W --height H --out F [--bundle] [--input F]
game -headless simulate --scenario F | --scene S --ticks N --seed N [--input F] [--screenshots 0,60] [--invariants a,b] --out DIR
game -headless query    --frame F --at x,y | --coverage
game -headless snapshot --scene S --tick T --out F [--input F]
game -headless snapshot --restore F --ticks N [--input F] [--out trace.jsonl]
game -headless describe
game -headless bench    --scenario F | --scene S --ticks N --seed N [--input F] [--width W --height H] [--cpus N]

• Each prints one JSON report on stdout. Errors print {"ok":false,"error":...,"errors":[{file,line,col,msg}]}.
• Exit codes: 0 success, 1 error, 2 bad command line, 3 simulate ran and the verdict is fail.
• Camera presets: scene, top, front, back, left, right, iso, orbit:<deg>, or the name of a camera entity. Render modes: color, wireframe, normals, depth, ids, silhouette, overdraw, uv_checker, collision.
• simulate writes trace.jsonl, result.json and one sheet.png (screenshots at the requested ticks plus a trajectory tile: seen from the top, or in the XY plane when the scene camera is orthographic and looks along −Z, as a 2D game's does) into the output directory. The verdict is fail when an expectation fails or an invariant is violated.
• An input file (--input) is a JSON array of input events or an object with an inputs array (a scenario file works).
• bench runs a scenario (or a scene with an input script) the way the player does, without recording a trace, and times each tick's update and its frame rendered with the scene camera at the project's resolution (or --width×--height), the renderer limited to --cpus processors. It reports update_ms, render_ms and frame_ms (mean, p50, p95, max), budget_ms (1000 / tick_rate), over_budget ticks, slowest_tick, and per frame commands (draw commands), triangles and drawn (submitted and rasterized) and culled and reduced entities (mean, max). The times are the machine's that runs it, not the console's; VEDUTA_PERF gives those (see Frame times on a console).
• snapshot saves the state at --tick and --restore continues from it. A script game's state lives in its interpreter, which no file can hold, so its snapshot is the run itself (scene or world, seed, every tick's input) and restoring plays that run again; the replay must reach the snapshot's trace hash, so a snapshot of a game that has changed since is refused.
• describe lists registered kinds with their state fields, game invariants, whether a state codec is registered, scenes, render modes and camera presets.