M1 design: the player and the Tideline slice

Status: accepted for building, 2026-09-30. Read with ARCHITECTURE §3–§8, ADRs 0002–0007 and 0010, and research/unspent-ortho-study.md §4 (the slice and its acceptance).

M1 makes one generic Godot player that runs any bundle, a first set of kits for the action_survival template, and Tideline, a small unspent-style game written by hand as a Game Pack. No AI. This document fixes the contracts, so several builders can work in parallel without guessing: the bundle, the kit interface, the simulation API, expressions, input, events, saves, tours, traces and the engine CLI.

1. Contracts first (landed before fan-out)

A builder that needs a contract changed proposes the change in its report. It doesn't edit another track's contract silently.

2. The bundle

gamewright bake <pack> writes <pack>/.gamewright/build/<hash12>/, where hash12 comes from the whole manifest (so a change to kit versions or media also makes a new folder):

bundle.json    manifest: game id, engine range, schema version, template pin, kits, content hash,
               media list, entry, the world stamp inputs
content.json   one canonical JSON array of every resolved document (template + packs + game),
               sorted by id
exprs.json     compiled expressions: [{src, type, code}], one per distinct source text
media/<sha256>.<ext>

• Resolved means: template and pack documents merged with the game's, overrides by id applied, id-addressed edits applied, defaults filled from the schemas. The engine never resolves anything.
• Expression fields keep their source text in content.json. The engine looks the compiled program up in exprs.json by source text. Compilation is context-free; typechecking, which depends on context, already happened in the core.
• The world stamp is SHA-256 over the RFC 8785 bytes of {sim, kits, worldgen, biomes, rootSeed}: the simulation version, the kit versions, the generator documents and the seed.
• The player verifies sha256(content.json) and sha256(exprs.json) against the manifest, every media file against its name, and the engine range against its own version. A failure stops with a named reason.
• content.json is one fetch on the web. Media are fetched lazily by hash.

3. Kits

A kit is a folder engine/addons/gamewright/kits/<name>/ with a kit.json and typed GDScript.

{
  "kind": "Kit", "schemaVersion": "1.0", "id": "kit.melee", "name": "Melee", "version": "1.0.0",
  "description": "Blows with windup, active and recovery windows; dodges with invulnerable frames; plate that rings and a working part that takes damage. Use for close combat where tactics beat trading hits.",
  "requires": ["kit.core", "kit.move"],
  "systems": [
    {"id": "melee", "script": "melee_system.gd", "after": ["move"], "provides": ["hits"], "consumes": ["intent"]}
  ],
  "views": [{"id": "melee_fx", "script": "melee_view.gd"}],
  "components": [
    {"id": "melee", "description": "…", "params": { "type": "object", "additionalProperties": false, "properties": { … } }}
  ],
  "actions": [{"id": "damage", "description": "…", "params": { … }}],
  "events": [{"id": "melee.hit", "description": "…", "fields": [{"name": "attacker", "type": "entity"}, …]}],
  "functions": [{"id": "in_windup", "description": "…", "args": [{"name": "e", "type": "entity"}], "returns": "bool"}],
  "passes": [], "tasks": [], "tourVerbs": [], "saveKeys": ["melee"]
}

• The core reads every kit.json and generates schemas/v1/vocab.schema.json: a discriminated union of components ("component": "<id>"), of actions ("action": "<id>"), of passes ("pass": "<id>"), plus enums of event, function and task ids. Document schemas reference these unions. The Expr typechecker reads function signatures from the same files.
• Parameter schemas follow ADR-0005 (closed, no recursion, units in names, Expr where a number is tunable: {"anyOf": [{"type": "number"}, {"$ref": "common.schema.json#/$defs/Expr"}]}).
• kit.core is the always-on kit: entities, stats, tags, variables, rules, the Expr VM, the event bus, timers, and the basic actions (spawn, despawn, set_var, add_var, set_stat, add_stat, emit, give, take, play_cue, show_message, end_game). Vocabulary ids are lowercase with dots and underscores (kit.schema.json DottedId), so action ids are snake_case.

4. Expressions (L1)

Syntax: a Python/GDScript expression subset. Literals (numbers, true, false, strings in single quotes); + - * / %; < <= > >= == !=; and or not; a if cond else b; parentheses; member access on roots; calls to registered functions. No assignment, loops, lambdas or indexing.

Roots: self, target, source, other (entities, where the context provides them), event (the triggering event's fields), game (tick, hour, minute, day, seed), var (game variables), tune (tuning knobs), stat (not a root; stats are read as self.health). Entity members: stat names, alive, x, y, z, level, and component state fields as self.<component>.<field>.

Types: number, bool, string (ids and tags), entity, vec3. The core typechecks each field against the type its schema declares, with the roots the document's context allows.

Bytecode: an array of instructions, each an array. The engine VM (GwExprVm) runs it with a step budget of 256 and returns the value or an error.

testdata/expr-vectors.json holds source → bytecode → value cases, run by both the core (compiler) and the engine (VM) tests.

5. The simulation API

All in engine/addons/gamewright/runtime/sim/. Pure RefCounted classes; no node access.

class_name GwSim            # one per running game
var content: GwContent      # documents indexed by id and by kind
var tick: int               # ticks since start
var hz: int                 # ticks per second (template sim.tickHz, default 60)
var root_seed: int
var entities: GwEntities    # spawn(arch_id, at, stable_id) / despawn / get / by_tag / all
var vars: Dictionary        # game variables (JSON values)
var events: GwEvents        # emit(id, fields) / on(id, callable) / this_tick()
var vocab: GwVocab          # actions, functions, passes, tasks, tour verbs by id
func rng(path: String) -> GwPcg32        # a named stream: deriveSeed(root_seed, path)
func expr(src_or_value: Variant) -> GwValue  # a constant or a compiled Expr
func step(frame: GwInputFrame) -> void   # one tick: systems in order, then rules
func state() -> Dictionary               # every system's save_state() plus core state
func state_hash() -> String              # sha256 of JSON.stringify(state(), "", true, true)
func system(id: StringName) -> GwSystem  # only for ids this system declared in `consumes`

class_name GwSystem         # base class for every kit system
var sim: GwSim
func setup() -> void        # read documents, register vocabulary, build initial state
func start() -> void        # after every system's setup
func step(frame: GwInputFrame) -> void
func save_state() -> Dictionary
func load_state(d: Dictionary) -> void

class_name GwEntity         # plain data
var id: StringName          # stable: "player", "sentry.0", "region.r0/prop.pine.17"
var arch: StringName
var tags: PackedStringArray
var stats: Dictionary       # name -> float
var comp: Dictionary        # component id -> Dictionary of that component's state
var pos: Vector3            # world units; +Y up
var facing: float           # radians, 0 = +X
var alive: bool

• Order. GwKitRegistry reads the kits the template and packs name, sorts systems by after/provides/consumes (a cycle is an error naming the systems), and calls setup then start. Rules run after all systems each tick.
• Props are not entities. Thousands of world props live in the world kit's packed tables (unspent's design). They get stable ids from their stream and index, so saves and tours can name them.
• No floats in decisions where a generator decides; quantize first (ADR-0004).

6. Input

GwInputFrame: move: Vector2 (world-space intent, length ≤ 1), aim: Vector2, down: PackedStringArray (held actions), pressed: PackedStringArray (pressed this tick). Actions are the ids in the game's InputMap document. The pointer (2026-10-09, pointer-input.md) adds point (where it is on the ground, world x and z on a 1/64 m grid), clicked and, on a click, target (what the view picked under it: an entity id or prop: and a prop's id): world terms only, never pixels, so a replay needs no camera.

Sources: GwDeviceInput (Godot InputMap built from the document at boot, camera-relative movement turned into world intent), GwTourInput, GwReplayInput, bots. The player polls exactly one source per tick. The devices latch each button press from its event until the next tick, so a tap that goes down and up between two ticks (one browser frame) still presses once. While a view holds the keys (a slate app), the game gets an empty frame, and the first frame after the view lets them go presses nothing: the key that closed the app went down for the app. A replay file is a header (bundle hash, seed, engine version) plus one frame per tick (run-length encoded) and a state hash every 60 ticks. It covers the run since the last boot, load or staging (--at, --hour, a tour's hour: changes no input frame repeats), and keeps a start save whenever the game it starts from is not a fresh boot.

7. Presentation

GwView extends Node (2D or 3D subclasses): bind(sim: GwSim, stage: GwStage) once, then present(alpha: float) every rendered frame, reading simulation state and interpolating. Views never write to the simulation. GwStage holds the world root node, the camera rig, the light pool, the render profile and the builder cache. What a view carries from one tick to the next it takes in in ticked(), called after every step; what it spreads over frames (a camera's easing, chunks streamed in) it finishes in settle(), called before a shot. A tool run draws no frame between its shots (fast-runs.md), so a shot must not depend on frames drawn.

Builders (runtime/present/builders/): pure functions from a recipe document (plus seed and palette) to a Mesh, Image, or AudioStreamWAV, cached by the recipe's content hash. Each builder has a version; golden-hash tests pin its output.

8. Tours

Line-oriented, one command per line, # comments. Everything is staged by name.

seed 3
boot title
press confirm                   # start a new game from the title
await control 10                # fails if the player has no control within 10 s of game time
goto prop:driftwood             # path to the nearest driftwood prop (world kit's nav)
use until taken:driftwood 5
repeat 2 { goto prop:driftwood; use until taken:driftwood 5 }
make rcp.campfire
await made:rcp.campfire 3
hour 19.5                       # set the clock (only between shots; logged)
toggle lamp
shot night-lamp with player,light:lamp
goto near arch.sentry 12
await noticed:player 20
await tell:sentry.0 5
press dodge
...
save slot1
quit title
load slot1
assert same-state

• The pointer is staged by name too: point at WHAT (an entity id, prop:<kind>, place:<name>; followed as it moves) and point off, aim DEG (round the player, as facings go), click [WHAT] (once, then the pointer stays there); a click game walks there, await arrived 20 (pointer-input.md §4).
• Verbs come from kit.core (seed, boot, press, hold, release, point, aim, click, wait, await, until, assert, shot, screen, save, load, quit, hour, repeat) and from kits' tourVerbs (goto, use, make, toggle).
• screen ID holds the game's Screen ID open over the game for the shots after it, as a person reaches it (an app on the slate, the title); screen alone goes back to what the game shows. It gives no input and steps nothing (2026-10-02, m3-verification.md decision 13). The player's --screen ID is the same from the start.
• await WHAT SECS fails on timeout; until WHAT SECS never fails. Waits are in game seconds (ticks), never wall time. On the desktop a tour steps as fast as the machine allows, drawing only at its shots (fast-runs.md); in a browser it keeps the game's rate.
• shot NAME with SUBJECTS waits for the subjects to be in frame and unoccluded, captures at that tick, and fails if they aren't there at the shutter.
• A tour passes only if it prints tour <name> done and the log has no script, shader or parse error.

9. Traces and results

• Trace (trace.jsonl): one JSON object per line, each with a type. header (bundle hash, seed, engine version, input source) comes first; boot marks a boot or a load, and staged a change outside the input (a tour's hour), where a recording restarts; tick lines appear for ticks that had events, with t, the input frame, the player's state and the events; hash lines carry the state hash every 60 ticks; footer ends it with the outcome and counters.
• Engine result (result.json, and the last stdout line): {ok, command, bundle, seed, ticks, stateHash, worldDigest, outcome, diagnostics[], files[]}.

10. The engine CLI

godot --path engine res://cli/cli.tscn -- <command> [options], wrapped by tools/engine-cli.sh.

The player app itself (res://player/player.tscn) takes the same boot options for people: --bundle, --seed, --level, --at, --hour, --tour.

11. Tideline

examples/tideline/ pins tpl.action_survival@1 from library/templates/action_survival/. Scope, acceptance and exclusions: research/unspent-ortho-study.md §4, restated as ROADMAP M1.

12. Tracks

Builders work in worktrees on branches, and merge in this order. Each track ends green on tools/check-all.sh with its own tests.

13. Document shapes for M1

As built (T2): only template is required in a GameManifest, and bake fills theme, style, world, input and camera with the only document of each kind; a template pin may be "1", "1.2" or "1.2.0" and the bundle records the exact version; Model and Sound params are checked against the builder's generated parameter schema by the core (JSON Schema can't select a shape from a sibling field); GameBrief stays out of bundles. The table below is the original contract.

Envelope on every pack document: kind, schemaVersion, id, name, meta. Fields ending in Expr accept a number or bool, or an expression string. <Union> means a discriminated union generated from kit registrations. T2 writes the JSON Schemas to match this table; a track that needs a change proposes it.

Test fixtures: until T2's bake exists, each track builds GwContent in its tests from dictionaries of these shapes, kept under engine/tests/fixtures/<track>/.