games/

Declarative game simulations for the janet-brand runtime.

pong.yml is the canonical reference implementation — the most complete and executable example in the defs hierarchy.

Canonical format

Games use the flat YAML simulation format loaded by load_brand_object_any_file.

Required sections

apiVersion: net.plantange/v1
kind: simulation

meta:
  name: <name>
  version: <semver>
  genome: "<hex>"

schedule:
  fps: <integer>

roles: [<role>, ...]

state: { ... }    # pure data — initial values for all paths
inputs: { ... }   # input schema only — no logic here
defs: { ... }     # physics and structural definitions

Optional sections

control: { ... }        # input → drive wiring
interactions: { ... }   # body collision and discrete write handlers
triggers:               # event-driven state mutations
  event:
    - on: $/defs/<name>.<event>
      do: [...]

Path conventions

All cross-section references use $/ prefix:

Path	Meaning
`$/state/<key>`	State value access
`$/defs/<name>`	Reference to a def body by id
`$/defs/<name>.<event>`	Emitted event channel on a def
`$/defs/roles`	Enum reference to declared roles

Def types

`type:`	Section	Purpose
`kinematic_body`	`defs`	Moving body with position, velocity, constraints
`constrained_axis`	`defs`	1D axis for paddle/slider motion
`clipping_plane`	`defs`	Boundary with reflect/exit behaviour
`matcher`	`defs`	Pattern detection against body state or lattice
`lattice`	`defs`	Discrete 2D grid (used by naughts)
`axis_drive`	`control`	Wires input value to a constrained axis
`collider`	`interactions`	Two-body collision handler
`discrete_write`	`interactions`	Guarded write to a lattice cell

Why pong works checklist

Use this checklist when authoring a new canonical simulation:

State first: all runtime paths used by defs/triggers exist under state.
Def references are absolute: all cross-links use $/defs/<name> and point to existing defs.
Body bindings are valid: kinematic/constrained defs point to real $/state/... paths.
Triggers are event-shaped: on points at an emitted channel and match keys exist in payload.
Control is one-way: input drives defs, then defs mutate state via interactions/triggers.
Minimal executable loop exists: at least one body can tick and write back to state.

File inventory

File	Kind	State
`pong.yml`	simulation	canonical
`pong_minimal.yml`	simulation	canonical-minimal
`naughts.yml`	game	canonical