docs/language: a page for every keyword and attribute the vocabulary has

Keywords: module uses friend export internal numbers unsafe mut port bind action
reducer registry of as from def open alias component prop view (structure),
shows lasts then loads (scenes), system (ecs), dispatch (control), true false
null (operators). Attributes: @Ref @OneOf @Range @Unit @Asset @Color, @Node /
@Clip / @Material, @Tint @Derived, @Text / @Multiline, @Key, @AppendOnly /
@ByKey, @PerMap / @Chunked, @frame @max, @owns / @creates / @releases,
@deterministic @alloc_ok. Each is in tools/docgen/inventory.json; every fence
that is not marked skip parses (ludicc --fmt). annot-clearcolor's token loses its
quotes, which no reader strips.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/language/annotations/annot-alloc_ok.md

@@ -0,0 +1,12 @@
+---
+id: annot-alloc_ok
+name: @alloc_ok
+category: annotations
+kind: annotation
+tokens: @alloc_ok
+sig: @alloc_ok("why") function f()  /  @alloc_ok("why") statement
+tip: Allocates in a frame on purpose; the reason is required.
+order: 80
+---
+
+<code>@alloc_ok("a memo miss, bounded by MM_CAP")</code> on a function or a single statement marks an allocation reachable from a frame as deliberate: the fence lets it through and <code>ludic deps</code> does not count it. The reason is required and greppable.

docs/language/annotations/annot-appendonly.md

@@ -0,0 +1,18 @@
+---
+id: annot-appendonly
+name: @AppendOnly
+category: annotations
+kind: annotation
+tokens: @AppendOnly @ByKey
+sig: @AppendOnly @ByKey registry Name of Record ...
+tip: How a registry's entries may change: only appended (their index is saved), or saved by key.
+order: 74
+---
+
+<code>@AppendOnly</code> on a registry says an entry's index is stored somewhere that outlives the build, so entries are only ever appended; <code>@ByKey</code> says entries are saved by key, so their order is free. Editors keep to what each says.
+
+```ludic
+# doc-check: skip — the file it names is beside the example
+@AppendOnly @ByKey
+registry Tools of Tool as TL from "data/tools.lres"
+```

docs/language/annotations/annot-asset.md

@@ -0,0 +1,12 @@
+---
+id: annot-asset
+name: @Asset
+category: annotations
+kind: annotation
+tokens: @Asset
+sig: @Asset("kind"[, map[, optional]]) field: string = ""
+tip: A path to a file of that kind; with map, under each map's directory.
+order: 67
+---
+
+<code>@Asset("gltf")</code> says a string field names a file of that kind. With <code>map</code> the path is under each map's directory and <code>ludicc --check</code> looks for it in every map, refusing one that lacks it unless the field says <code>optional</code>.

docs/language/annotations/annot-clearcolor.md

@@ -3,7 +3,7 @@ id: annot-clearcolor
 name: "@ClearColor"
 category: annotations
 kind: annotation
-tokens: "@ClearColor"
+tokens: @ClearColor
 sig: "@ClearColor(0xRRGGBB) handler Draw phase Render { … }"
 tip: Declare a clear colour so the Render phase auto-clears + auto-presents for you.
 order: 62

docs/language/annotations/annot-color.md

@@ -0,0 +1,12 @@
+---
+id: annot-color
+name: @Color
+category: annotations
+kind: annotation
+tokens: @Color
+sig: @Color field: int = 0
+tip: The field is a colour.
+order: 68
+---
+
+<code>@Color</code> marks an <code>int</code> field as a colour so an editor shows a swatch and a picker; with <code>@Tint(SLOT)</code> beside it the colour is for that tint slot.

docs/language/annotations/annot-derived.md

@@ -0,0 +1,12 @@
+---
+id: annot-derived
+name: @Derived
+category: annotations
+kind: annotation
+tokens: @Derived
+sig: @Derived field: float = 0.0
+tip: Worked out at boot: anything written in the data is overwritten.
+order: 71
+---
+
+<code>@Derived</code> tells an editor a field is computed when the game starts, so a value typed into the data would be overwritten and is not offered for editing.

docs/language/annotations/annot-deterministic.md

@@ -0,0 +1,12 @@
+---
+id: annot-deterministic
+name: @deterministic
+category: annotations
+kind: annotation
+tokens: @deterministic
+sig: @deterministic function f() { }
+tip: No floating point inside: it must replay the same everywhere.
+order: 79
+---
+
+<code>@deterministic</code> on a function or a handler refuses floating point inside it, so it computes the same bits on every machine - what lockstep and replays need.

docs/language/annotations/annot-frame.md

@@ -0,0 +1,12 @@
+---
+id: annot-frame
+name: @frame
+category: annotations
+kind: annotation
+tokens: @frame
+sig: @frame field: fn() -> void
+tip: A fn stored here runs every frame.
+order: 76
+---
+
+<code>@frame</code> on a function-typed field says whatever function it holds runs every frame, so <code>ludic deps</code> counts what it can allocate among the frame's allocations.

docs/language/annotations/annot-key.md

@@ -0,0 +1,12 @@
+---
+id: annot-key
+name: @Key
+category: annotations
+kind: annotation
+tokens: @Key
+sig: @Key field: int = 0
+tip: The field is a key code.
+order: 73
+---
+
+<code>@Key</code> marks an <code>int</code> field as a key code, so an editor offers a key to press rather than a number.

docs/language/annotations/annot-max.md

@@ -0,0 +1,18 @@
+---
+id: annot-max
+name: @max
+category: annotations
+kind: annotation
+tokens: @max
+sig: @max(64) rows: []Row
+tip: The most a list may hold; growing past it fails the run.
+order: 77
+---
+
+<code>@max(n)</code> bounds a list field: it never holds more than <code>n</code>, and a push past it fails the run (exit 87) rather than growing a list that should not grow.
+
+```ludic
+property Log {
+  @max(64) lines: []int
+}
+```

docs/language/annotations/annot-node.md

@@ -0,0 +1,12 @@
+---
+id: annot-node
+name: @Node
+category: annotations
+kind: annotation
+tokens: @Node @Clip @Material
+sig: @Node(model) / @Clip(model) / @Material(model) field: string = ""
+tip: A node, an animation clip or a material inside the glTF another field names.
+order: 69
+---
+
+<code>@Node(model)</code>, <code>@Clip(model)</code> and <code>@Material(model)</code> say a string field names a node, a clip or a material inside the glTF that field <code>model</code> of the same record names (an <code>@Asset("gltf")</code> field, or an <code>@Ref</code> to a registry whose record has exactly one). Naming anything else is an error.

docs/language/annotations/annot-oneof.md

@@ -0,0 +1,12 @@
+---
+id: annot-oneof
+name: @OneOf
+category: annotations
+kind: annotation
+tokens: @OneOf
+sig: @OneOf(PREFIX_) / @OneOf(A, B) / @OneOf("word", ...)
+tip: The field holds one of these constants or words.
+order: 64
+---
+
+<code>@OneOf(GR_)</code> says a field holds one of the constants whose names start <code>GR_</code>; <code>@OneOf(GR_GOLD, GR_SILVER)</code> one of those (each must exist); on a <code>string</code> field, <code>@OneOf("box", "hull")</code> one of those words, and every registry row is checked against them.

docs/language/annotations/annot-owns.md

@@ -0,0 +1,12 @@
+---
+id: annot-owns
+name: @owns
+category: annotations
+kind: annotation
+tokens: @owns @creates @releases
+sig: @owns(Kind) field  /  @creates(Kind) function  /  @releases(Kind) function
+tip: Resource handles: a field that owns one, a function that makes one, a function that lets one go.
+order: 78
+---
+
+<code>@creates(PhysShape)</code> on a function says it returns a handle the caller must release, <code>@releases(PhysShape)</code> that it releases one, and <code>@owns(PhysShape)</code> on a field that its record owns the handle it holds. <code>ludic deps --resources</code> counts a created handle never released, and an owned one lost when its record is released.

docs/language/annotations/annot-permap.md

@@ -0,0 +1,12 @@
+---
+id: annot-permap
+name: @PerMap
+category: annotations
+kind: annotation
+tokens: @PerMap @Chunked
+sig: @PerMap registry Name of Row from "rows.lres"  /  @PerMap @Chunked(n) registry ...
+tip: A table whose rows are read per map from that map's directory; @Chunked(n) reads it a chunk at a time.
+order: 75
+---
+
+A <code>@PerMap</code> registry holds what is on a map rather than in the game: its rows are read when a map loads, from that map's directory, into a state the compiler writes with its verbs (<code>_load</code>, <code>_find</code>, ...). <code>@Chunked(n)</code> reads it in n-by-n-metre chunks from files named by <code>{cx}</code> and <code>{cz}</code>.

docs/language/annotations/annot-range.md

@@ -0,0 +1,12 @@
+---
+id: annot-range
+name: @Range
+category: annotations
+kind: annotation
+tokens: @Range
+sig: @Range(lo, hi) field: float = 0.0
+tip: The least and the most the value may be.
+order: 65
+---
+
+<code>@Range(0, 20.5)</code> gives an editor the bounds of a number field, and <code>ludicc --check</code> holds every map row's value to them. Both arguments are numbers.

docs/language/annotations/annot-ref.md

@@ -0,0 +1,19 @@
+---
+id: annot-ref
+name: @Ref
+category: annotations
+kind: annotation
+tokens: @Ref
+sig: @Ref(Registry) field: int = 0
+tip: The field is an entry of that registry: an index, or a key for a @PerMap one.
+order: 63
+---
+
+<code>@Ref(Items)</code> on a field says its value is an entry of the registry <code>Items</code> - its index on an <code>int</code> field, its key on a <code>string</code> field of a <code>@PerMap</code> table - so an editor offers the entries. It changes nothing the program does; a registry the program does not declare is a warning and <code>"unresolved"</code> in the schema, anything else of that name is an error.
+
+```ludic
+# doc-check: skip — the registry is declared elsewhere
+property Tool {
+  @Ref(Vendors) seller: int = 0
+}
+```

docs/language/annotations/annot-text.md

@@ -0,0 +1,12 @@
+---
+id: annot-text
+name: @Text
+category: annotations
+kind: annotation
+tokens: @Text @Multiline
+sig: @Text @Multiline field: string = ""
+tip: Read by the player, so translated; and prose, edited over several lines.
+order: 72
+---
+
+<code>@Text</code> marks a string the player reads, so it is translated; <code>@Multiline</code> says it is prose, edited as several lines rather than one.

docs/language/annotations/annot-tint.md

@@ -0,0 +1,12 @@
+---
+id: annot-tint
+name: @Tint
+category: annotations
+kind: annotation
+tokens: @Tint
+sig: @Color @Tint(SLOT) field: int = 0
+tip: A colour for that tint slot.
+order: 70
+---
+
+<code>@Tint(TSLOT_HAIR)</code> names the tint slot a colour field paints - a constant, which must exist (or, when the program lacks it, is a warning and unresolved).

docs/language/annotations/annot-unit.md

@@ -0,0 +1,12 @@
+---
+id: annot-unit
+name: @Unit
+category: annotations
+kind: annotation
+tokens: @Unit
+sig: @Unit("m/s") field: float = 0.0
+tip: The value's unit, in one canonical ASCII spelling.
+order: 66
+---
+
+<code>@Unit</code> takes one of <code>m</code>, <code>m/s</code>, <code>m/s2</code>, <code>s</code>, <code>min</code>, <code>h</code>, <code>d</code>, <code>deg</code>, <code>rad</code>, <code>rad/s</code>, <code>kg</code>, <code>N</code>, <code>N.m</code>, <code>%</code>, <code>px</code>, so one word means one unit to an editor; another spelling is a warning naming the canonical one.