@origingame/engine 0.0.0-stage → 0.1.1

package/knowledge/wiki/commands.md

@@ -0,0 +1,357 @@
+<!-- Generated from crates/og-api/api.ogt by `og api gen`. Do not edit: `og api check` fails on any difference; change api.ogt and regenerate. -->
+
+# The `commands` module
+
+The command channel: actions scheduled on simulation time, from `og run --commands "t:action[:args];..."` or the probe's commands().
+
+Core actions ship with the engine; a module or a game registers more. Unknown actions warn and continue. Not in publish builds.
+
+Outputs are relative to the output directory: an absolute path, a `..` component or a name starting with `.` (kept for the harness, such as a playtest's kept store) is refused. A file an earlier step of the script wrote is never overwritten: the later step's is written as `<stem>-2.<ext>` with a warning naming both steps.
+
+- **TypeScript**: functions are the namespace `og.commands`; components, resources and events are tokens on `og`.
+- **Publish builds**: dropped (members may override).
+- **Skill**: `og-build`, which teaches the module (how much of it to use, and how to prove it).
+- **Index**: [every module and name](index.md).
+
+```ogt
+module commands {
+  # declarations follow, each quoted below
+```
+
+<sub>`api.ogt` line 10355</sub>
+
+## Contents
+
+| Name | Kind | Summary |
+|---|---|---|
+| [`CoreAction`](#type-CoreAction) | enum | The actions the engine ships. Arguments follow the action, separated by `:`. |
+| [`CommandHandler`](#type-CommandHandler) | callback | A registered action. It runs at the start of the tick it was scheduled for. |
+| [`CommandDesc`](#type-CommandDesc) | desc struct | How a registered action describes itself in `og run --help` and the wiki. |
+| [`CommandStep`](#type-CommandStep) | struct | One parsed step of a command script. |
+| [`CommandInfo`](#type-CommandInfo) | struct | One action as help lists it. |
+| [`CommandsReport`](#type-CommandsReport) | struct | What scheduling a script did. |
+| [`og.commands.register`](#fn-register) | function | Register an action into the command channel. GameDesc.commands does this for a game's own actions. |
+| [`og.commands.parse`](#fn-parse) | function | Parse a script without scheduling it. |
+| [`og.commands.help`](#fn-help) | function | Every action the channel knows: core actions in CoreAction order, then registered ones by name. |
+| [`og.commands.schedule`](#fn-schedule) | function | Schedule a script on simulation time, from the current tick. |
+
+## Functions
+
+<a id="fn-register"></a>
+
+### `og.commands.register`
+
+Register an action into the command channel. GameDesc.commands does this for a game's own actions.
+
+```ts
+og.commands.register(name: string, handler: CommandHandler, desc?: CommandDesc): Result<void>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `name` | `string` | no | The action name, snake_case, such as `spawn_wave`. |
+| `handler` | `CommandHandler` | no | What it does. |
+| `desc` | `CommandDesc` | yes | Its usage line and doc. |
+
+**Returns** `Result<void>`: Refused for a name a core action or another registration already uses.
+
+Binding symbol `og_commands_register` · publish builds: dropped
+
+```ogt
+fn register {
+  doc "Register an action into the command channel. GameDesc.commands does this for a game's own actions."
+  param name String "The action name, snake_case, such as `spawn_wave`."
+  param handler CommandHandler "What it does."
+  param desc CommandDesc "Its usage line and doc."
+  returns Result.Void "Refused for a name a core action or another registration already uses."
+}
+```
+
+<sub>`api.ogt` line 10431</sub>
+
+<a id="fn-parse"></a>
+
+### `og.commands.parse`
+
+Parse a script without scheduling it.
+
+```ts
+og.commands.parse(script: string): Result<readonly CommandStep[]>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `script` | `string` | no | `t:action[:args];...` with t in simulation seconds. |
+
+**Returns** `Result<readonly CommandStep[]>`: The steps, or the first malformed step.
+
+Binding symbol `og_commands_parse` · publish builds: dropped
+
+```ogt
+fn parse {
+  doc "Parse a script without scheduling it."
+  param script String "`t:action[:args];...` with t in simulation seconds."
+  returns Result.List.CommandStep "The steps, or the first malformed step."
+}
+```
+
+<sub>`api.ogt` line 10439</sub>
+
+<a id="fn-help"></a>
+
+### `og.commands.help`
+
+Every action the channel knows: core actions in CoreAction order, then registered ones by name.
+
+```ts
+og.commands.help(world: World): readonly CommandInfo[]
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world whose channel is asked. |
+
+**Returns** `readonly CommandInfo[]`.
+
+Binding symbol `og_commands_help` · publish builds: dropped
+
+```ogt
+fn help {
+  doc "Every action the channel knows: core actions in CoreAction order, then registered ones by name."
+  param world World "The world whose channel is asked."
+  returns List.CommandInfo
+}
+```
+
+<sub>`api.ogt` line 10445</sub>
+
+<a id="fn-schedule"></a>
+
+### `og.commands.schedule`
+
+Schedule a script on simulation time, from the current tick.
+
+```ts
+og.commands.schedule(world: World, script: string): Result<CommandsReport>
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world. |
+| `script` | `string` | no | `t:action[:args];...` with t in simulation seconds. |
+
+**Returns** `Result<CommandsReport>`: The report, or the first malformed step.
+
+Binding symbol `og_commands_schedule` · publish builds: dropped
+
+```ogt
+fn schedule {
+  doc "Schedule a script on simulation time, from the current tick."
+  param world World "The world."
+  param script String "`t:action[:args];...` with t in simulation seconds."
+  returns Result.CommandsReport "The report, or the first malformed step."
+}
+```
+
+<sub>`api.ogt` line 10451</sub>
+
+## Types
+
+<a id="type-CoreAction"></a>
+
+### `CoreAction` (enum)
+
+The actions the engine ships. Arguments follow the action, separated by `:`.
+
+A string: one of the variants below. The zero value is `"screenshot"`.
+
+| Variant | Doc |
+|---|---|
+| `"screenshot"` | `screenshot[:path][:full\|:N]`: capture the next frame. Without a renderer it writes nothing and logs, not as a warning, that the frame is unchecked. |
+| `"listen"` | `listen[:path][:seconds]`: write the last seconds of rendered audio as a WAV. |
+| `"touch_move_to"` | `touch_move_to:<ui id>`: move the pointer to a UI element. |
+| `"touch_move"` | `touch_move:x,y`: move the pointer to CSS pixel coordinates. |
+| `"touch_start"` | `touch_start`: press the pointer where it is. |
+| `"touch_end"` | `touch_end`: release the pointer. |
+| `"scroll"` | `scroll:dx,dy`: scroll at the pointer. |
+| `"touch"` | `touch:<id>:<down\|move\|up>:<x,y \| ui id>`: a further touch (pointer 1 to 4) held while the pointer is busy elsewhere. |
+| `"gamepad"` | `gamepad:<a+b+...\|->[@pad][:lx,ly[,rx,ry]][:lt,rt]`: set a pad's whole state (pad 0 unless `@1` to `@3` follows the buttons); `gamepad:off` disconnects it. |
+| `"key_down"` | `key_down:[Mod+]<Key>`: hold a key by its code, with the modifiers named before it (`Shift+ArrowLeft`, `Meta+ArrowLeft` for Command, apart from Ctrl). |
+| `"key_up"` | `key_up:[Mod+]<Key>`: release a key, then the modifiers named before it. |
+| `"type"` | `type:<text>`: type text, two ticks per character: its key press and the character as typed text (input.TextInput); a character no key types is typed text alone. The text runs to the `;` exactly, a trailing space included; after it a text field takes typed text only, so a bare key_down types nothing. |
+| `"compose"` | `compose:<text>`: an input method's composition so far (input.TextInput composing); a focused text field shows it underlined at the caret, `compose:` with nothing ends it. |
+| `"commit"` | `commit:<text>`: an input method commits text; a focused text field inserts it and the composition ends. |
+| `"move_to_text"` | `move_to_text:[=]text[@N]`: move the pointer to the UI element showing the text (exactly with `=`, the Nth with `@N`). |
+| `"teleport"` | `teleport:<entity>:x,y,z`: set an entity's position. |
+| `"frame_entity"` | `frame_entity:<entity>`: point the camera at an entity. |
+| `"dump_world"` | `dump_world[:path]`: tables, systems and their matched counts. |
+| `"dump_entity"` | `dump_entity:<name>[:path]`: one entity's components and transform. |
+| `"dump_ui"` | `dump_ui[:path]`: the UI tree with bounds. |
+| `"set"` | `set:<entity>.<component>.<field>=<value>` or `set:<Resource>.<field>=<value>`: a Tune write through the schema: a number, `true` or `false` for a bool, `x,y,z` for a vector, an enum's variant name or its index; refused outside the field's FieldOptions min/max, never clamped. |
+| `"get"` | `get:<Resource>[.<field>]` or `get:<entity>[.<component>[.<field>]][:path]`: read through the schema as game code sees it (an enum as its variant's name, `"music"`; og.Time whole, with rate and the time scale; the DirectionalLight og.DayNight drives with the colour, intensity and direction it is drawn with), logged and written as JSON to `get-<tick>.json` (more unnamed ones on one tick: `get-<tick>-2.json`, ...). |
+| `"seed"` | `seed:<n>`: reseed the Rng resource. |
+| `"pause"` | `pause`: hold the clock; advance still steps. |
+| `"resume"` | `resume`: release the clock. |
+| `"advance"` | `advance:<ticks>`: take fixed steps. |
+| `"quit"` | `quit`: exit. |
+| `"help"` | `help`: list every action the channel knows, core and registered. |
+
+```ogt
+enum CoreAction {
+  doc "The actions the engine ships. Arguments follow the action, separated by `:`."
+  variant screenshot "`screenshot[:path][:full|:N]`: capture the next frame. Without a renderer it writes nothing and logs, not as a warning, that the frame is unchecked."
+  variant listen "`listen[:path][:seconds]`: write the last seconds of rendered audio as a WAV."
+  variant touch_move_to "`touch_move_to:<ui id>`: move the pointer to a UI element."
+  variant touch_move "`touch_move:x,y`: move the pointer to CSS pixel coordinates."
+  variant touch_start "`touch_start`: press the pointer where it is."
+  variant touch_end "`touch_end`: release the pointer."
+  variant scroll "`scroll:dx,dy`: scroll at the pointer."
+  variant touch "`touch:<id>:<down|move|up>:<x,y | ui id>`: a further touch (pointer 1 to 4) held while the pointer is busy elsewhere."
+  variant gamepad "`gamepad:<a+b+...|->[@pad][:lx,ly[,rx,ry]][:lt,rt]`: set a pad's whole state (pad 0 unless `@1` to `@3` follows the buttons); `gamepad:off` disconnects it."
+  variant key_down "`key_down:[Mod+]<Key>`: hold a key by its code, with the modifiers named before it (`Shift+ArrowLeft`, `Meta+ArrowLeft` for Command, apart from Ctrl)."
+  variant key_up "`key_up:[Mod+]<Key>`: release a key, then the modifiers named before it."
+  variant type "`type:<text>`: type text, two ticks per character: its key press and the character as typed text (input.TextInput); a character no key types is typed text alone. The text runs to the `;` exactly, a trailing space included; after it a text field takes typed text only, so a bare key_down types nothing."
+  variant compose "`compose:<text>`: an input method's composition so far (input.TextInput composing); a focused text field shows it underlined at the caret, `compose:` with nothing ends it."
+  variant commit "`commit:<text>`: an input method commits text; a focused text field inserts it and the composition ends."
+  variant move_to_text "`move_to_text:[=]text[@N]`: move the pointer to the UI element showing the text (exactly with `=`, the Nth with `@N`)."
+  variant teleport "`teleport:<entity>:x,y,z`: set an entity's position."
+  variant frame_entity "`frame_entity:<entity>`: point the camera at an entity."
+  variant dump_world "`dump_world[:path]`: tables, systems and their matched counts."
+  variant dump_entity "`dump_entity:<name>[:path]`: one entity's components and transform."
+  variant dump_ui "`dump_ui[:path]`: the UI tree with bounds."
+  variant set "`set:<entity>.<component>.<field>=<value>` or `set:<Resource>.<field>=<value>`: a Tune write through the schema: a number, `true` or `false` for a bool, `x,y,z` for a vector, an enum's variant name or its index; refused outside the field's FieldOptions min/max, never clamped."
+  variant get "`get:<Resource>[.<field>]` or `get:<entity>[.<component>[.<field>]][:path]`: read through the schema as game code sees it (an enum as its variant's name, `\"music\"`; og.Time whole, with rate and the time scale; the DirectionalLight og.DayNight drives with the colour, intensity and direction it is drawn with), logged and written as JSON to `get-<tick>.json` (more unnamed ones on one tick: `get-<tick>-2.json`, ...)."
+  variant seed "`seed:<n>`: reseed the Rng resource."
+  variant pause "`pause`: hold the clock; advance still steps."
+  variant resume "`resume`: release the clock."
+  variant advance "`advance:<ticks>`: take fixed steps."
+  variant quit "`quit`: exit."
+  variant help "`help`: list every action the channel knows, core and registered."
+}
+```
+
+<sub>`api.ogt` line 10362</sub>
+
+<a id="type-CommandHandler"></a>
+
+### `CommandHandler` (callback)
+
+A registered action. It runs at the start of the tick it was scheduled for.
+
+Game code supplies this function.
+
+```ts
+type CommandHandler = (world: World, args: readonly string[]) => void
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world. |
+| `args` | `readonly string[]` | no | The `:`-separated arguments after the action name. |
+
+```ogt
+callback CommandHandler {
+  doc "A registered action. It runs at the start of the tick it was scheduled for."
+  param world World "The world."
+  param args List.String "The `:`-separated arguments after the action name."
+}
+```
+
+<sub>`api.ogt` line 10394</sub>
+
+<a id="type-CommandDesc"></a>
+
+### `CommandDesc` (desc struct)
+
+How a registered action describes itself in `og run --help` and the wiki.
+
+A desc: every field may be omitted and takes its default; `{}` is valid.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `usage` | `string` | `""` | — | — | — | The argument form, such as `<count>`. |
+| `doc` | `string` | `""` | — | — | — | One sentence on what it does. |
+
+```ogt
+struct CommandDesc {
+  doc "How a registered action describes itself in `og run --help` and the wiki."
+  desc true
+  field usage String "The argument form, such as `<count>`."
+  field doc String "One sentence on what it does."
+}
+```
+
+<sub>`api.ogt` line 10400</sub>
+
+<a id="type-CommandStep"></a>
+
+### `CommandStep` (struct)
+
+One parsed step of a command script.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `at` | `number` | `0` | — | `s` | — | When it runs, in simulation seconds from the start of the script. |
+| `action` | `string` | `""` | — | — | — | The action name. |
+| `args` | `readonly string[]` | `[]` | — | — | — | The arguments. |
+
+```ogt
+struct CommandStep {
+  doc "One parsed step of a command script."
+  field at f32 "When it runs, in simulation seconds from the start of the script." {
+    unit s
+  }
+  field action String "The action name."
+  field args List.String "The arguments."
+}
+```
+
+<sub>`api.ogt` line 10407</sub>
+
+<a id="type-CommandInfo"></a>
+
+### `CommandInfo` (struct)
+
+One action as help lists it.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `name` | `string` | `""` | — | — | — | The action name. |
+| `usage` | `string` | `""` | — | — | — | Its argument form, such as `screenshot[:path][:full\|:N]`. |
+| `doc` | `string` | `""` | — | — | — | One sentence on what it does. |
+| `core` | `boolean` | `false` | — | — | — | Shipped with the engine (true) or registered by a module or a game. |
+
+```ogt
+struct CommandInfo {
+  doc "One action as help lists it."
+  field name String "The action name."
+  field usage String "Its argument form, such as `screenshot[:path][:full|:N]`."
+  field doc String "One sentence on what it does."
+  field core bool "Shipped with the engine (true) or registered by a module or a game."
+}
+```
+
+<sub>`api.ogt` line 10416</sub>
+
+<a id="type-CommandsReport"></a>
+
+### `CommandsReport` (struct)
+
+What scheduling a script did.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `scheduled` | `number` | `0` | — | — | — | Steps scheduled. |
+| `untilTick` | `number` | `0` | — | — | — | The tick of the last step. |
+| `warnings` | `readonly string[]` | `[]` | — | — | — | Unknown actions and other skipped steps, each naming the fix. |
+
+```ogt
+struct CommandsReport {
+  doc "What scheduling a script did."
+  field scheduled u32 "Steps scheduled."
+  field untilTick u32 "The tick of the last step."
+  field warnings List.String "Unknown actions and other skipped steps, each naming the fix."
+}
+```
+
+<sub>`api.ogt` line 10424</sub>

package/knowledge/wiki/game.md

@@ -0,0 +1,220 @@
+<!-- Generated from crates/og-api/api.ogt by `og api gen`. Do not edit: `og api check` fails on any difference; change api.ogt and regenerate. -->
+
+# The `game` module
+
+The game entry: what the bundle's default export declares.
+
+- **TypeScript**: functions are members of the root object `og` (`og.<fn>`); components, resources and events are tokens on `og`.
+- **Publish builds**: kept (members may override).
+- **Skill**: `og-game`, which teaches the module (how much of it to use, and how to prove it).
+- **Index**: [every module and name](index.md).
+
+```ogt
+module game {
+  # declarations follow, each quoted below
+```
+
+<sub>`api.ogt` line 460</sub>
+
+## Contents
+
+| Name | Kind | Summary |
+|---|---|---|
+| [`FactsFn`](#type-FactsFn) | callback | The game's own facts for the probe's state(): a small JSON object, computed from the world without changing it. |
+| [`StartFn`](#type-StartFn) | callback | The game's setup: called once before the first tick, after GameDesc.scene has spawned. Spawn, insert, load and set resources here; systems then only read and write their views. |
+| [`GameDesc`](#type-GameDesc) | desc struct | A game: its tick, scenes, systems and commands. |
+| [`Game`](#type-Game) | interface | A declared game, the bundle's default export. |
+| [`og.game`](#fn-game) | function | Declare the game. The bundle's default export is its result. |
+
+## Functions
+
+<a id="fn-game"></a>
+
+### `og.game`
+
+Declare the game. The bundle's default export is its result.
+
+```ts
+og.game(desc?: GameDesc): Game
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `desc` | `GameDesc` | yes | Tick, scenes, systems and commands. |
+
+**Returns** `Game`.
+
+Binding symbol `og_game_game` · publish builds: kept
+
+```ogt
+fn game {
+  doc "Declare the game. The bundle's default export is its result."
+  param desc GameDesc "Tick, scenes, systems and commands."
+  returns Game
+}
+```
+
+<sub>`api.ogt` line 512</sub>
+
+## Interfaces
+
+<a id="type-Game"></a>
+
+### `Game` (interface)
+
+A declared game, the bundle's default export.
+
+```ogt
+interface Game {
+  doc "A declared game, the bundle's default export."
+  # members follow, each quoted below
+```
+
+<sub>`api.ogt` line 506</sub>
+
+<a id="member-Game-tick"></a>
+
+#### `Game.tick` (property)
+
+GameDesc.tick, or 60 when it is unset (the engine then runs at project.ogt's `tick` when the host passes the project, as og run and og build do).
+
+```ts
+readonly tick: number
+```
+
+Binding symbol `og_game_get_tick` · publish builds: kept
+
+```ogt
+prop tick u32 "GameDesc.tick, or 60 when it is unset (the engine then runs at project.ogt's `tick` when the host passes the project, as og run and og build do)."
+```
+
+<sub>`api.ogt` line 508</sub>
+
+<a id="member-Game-systems"></a>
+
+#### `Game.systems` (property)
+
+The systems in declaration order.
+
+```ts
+readonly systems: readonly System[]
+```
+
+Binding symbol `og_game_get_systems` · publish builds: kept
+
+```ogt
+prop systems List.System "The systems in declaration order."
+```
+
+<sub>`api.ogt` line 509</sub>
+
+## Types
+
+<a id="type-FactsFn"></a>
+
+### `FactsFn` (callback)
+
+The game's own facts for the probe's state(): a small JSON object, computed from the world without changing it.
+
+Game code supplies this function.
+
+```ts
+type FactsFn = (world: World) => unknown
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world, read only. |
+
+```ogt
+callback FactsFn {
+  doc "The game's own facts for the probe's state(): a small JSON object, computed from the world without changing it."
+  param world World "The world, read only."
+  returns Json
+}
+```
+
+<sub>`api.ogt` line 465</sub>
+
+<a id="type-StartFn"></a>
+
+### `StartFn` (callback)
+
+The game's setup: called once before the first tick, after GameDesc.scene has spawned. Spawn, insert, load and set resources here; systems then only read and write their views.
+
+Game code supplies this function.
+
+```ts
+type StartFn = (world: World) => void
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `world` | `World` | no | The world. |
+
+```ogt
+callback StartFn {
+  doc "The game's setup: called once before the first tick, after GameDesc.scene has spawned. Spawn, insert, load and set resources here; systems then only read and write their views."
+  param world World "The world."
+}
+```
+
+<sub>`api.ogt` line 471</sub>
+
+<a id="type-GameDesc"></a>
+
+### `GameDesc` (desc struct)
+
+A game: its tick, scenes, systems and commands.
+
+A desc: every field may be omitted and takes its default; `{}` is valid.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `tick` | `number` | `60` | 1 … 240 | `hz` | — | The fixed tick rate. Left unset, project.ogt's `tick` applies (else 60); tick, seed, scenes and scene set both here and in project.ogt to different values refuse the engine, naming both. |
+| `seed` | `number` | `0` | — | — | — | The project seed every Rng stream derives from; left unset, project.ogt's `seed` (else 0). A replay overrides it. |
+| `scenes` | `Readonly<Record<string, string>>` | `{}` | — | — | — | Scene names to `.ogt` paths, as `{ main: "scenes/main.ogt" }`; left unset, project.ogt's `scenes` block. |
+| `scene` | `string` | `"main"` | — | — | — | The scene loaded first; left unset, project.ogt's `scene` (else main). |
+| `systems` | `readonly System[]` | `[]` | — | — | — | The systems, in declaration order before `after`/`before` constraints apply. |
+| `resources` | `readonly AnyResource[]` | `[]` | — | — | — | The game's own resources, created at their defaults. |
+| `commands` | `Readonly<Record<string, CommandHandler>>` | `{}` | — | — | — | Game actions registered into the command channel, by action name. |
+| `commandHelp` | `Readonly<Record<string, CommandDesc>>` | `{}` | — | — | — | Each game action's argument form and one sentence, by its name in commands, for `help`: `{ place: { usage: "<x>:<y>", doc: "Move the hero there." } }`. An action without an entry is listed by name alone. |
+| `maxCatchUp` | `number` | `4` | 1 … 60 | `ticks` | — | The most ticks one frame may run to catch up with the clock; the accumulator drops the rest. |
+| `facts` | `FactsFn \| null` | `null` | — | — | — | The game's own facts for the probe's state(). |
+| `start` | `StartFn \| null` | `null` | — | — | — | Called once before the first tick, after the first scene spawned. A throw fails the run: no tick runs on the half-built world, `og run`, `og test` and `og dev` exit non-zero naming the error with its stack, and the web shell shows it. |
+| `render` | `RenderOptions` | `{}` | — | — | — | How the renderer is created: antialiasing and shadow map size. Read once, when the host attaches the renderer. |
+| `look` | `string` | `""` | — | — | — | A look (`looks/<name>.ogt`, og.load.look) applied after the first scene spawned and before start runs, so start may still change any of it; its antialias is the renderer's when render leaves antialias out. Empty applies none. |
+
+```ogt
+struct GameDesc {
+  doc "A game: its tick, scenes, systems and commands."
+  desc true
+  field tick u32 "The fixed tick rate. Left unset, project.ogt's `tick` applies (else 60); tick, seed, scenes and scene set both here and in project.ogt to different values refuse the engine, naming both." {
+    default 60
+    min 1
+    max 240
+    unit hz
+  }
+  field seed u32 "The project seed every Rng stream derives from; left unset, project.ogt's `seed` (else 0). A replay overrides it."
+  field scenes Map.String "Scene names to `.ogt` paths, as `{ main: \"scenes/main.ogt\" }`; left unset, project.ogt's `scenes` block."
+  field scene String "The scene loaded first; left unset, project.ogt's `scene` (else main)." {
+    default "main"
+  }
+  field systems List.System "The systems, in declaration order before `after`/`before` constraints apply."
+  field resources List.AnyResource "The game's own resources, created at their defaults."
+  field commands Map.CommandHandler "Game actions registered into the command channel, by action name."
+  field commandHelp Map.CommandDesc "Each game action's argument form and one sentence, by its name in commands, for `help`: `{ place: { usage: \"<x>:<y>\", doc: \"Move the hero there.\" } }`. An action without an entry is listed by name alone."
+  field maxCatchUp u32 "The most ticks one frame may run to catch up with the clock; the accumulator drops the rest." {
+    default 4
+    min 1
+    max 60
+    unit ticks
+  }
+  field facts Option.FactsFn "The game's own facts for the probe's state()."
+  field start Option.StartFn "Called once before the first tick, after the first scene spawned. A throw fails the run: no tick runs on the half-built world, `og run`, `og test` and `og dev` exit non-zero naming the error with its stack, and the web shell shows it."
+  field render RenderOptions "How the renderer is created: antialiasing and shadow map size. Read once, when the host attaches the renderer."
+  field look String "A look (`looks/<name>.ogt`, og.load.look) applied after the first scene spawned and before start runs, so start may still change any of it; its antialias is the renderer's when render leaves antialias out. Empty applies none."
+}
+```
+
+<sub>`api.ogt` line 476</sub>