Document the Script API surface and update the glossary (#87) #99

Merged

crowmaki merged 2 commits from script-api-docs-87 into main

2026-09-06 06:56:29 +00:00

crowmaki commented

2026-09-06 06:53:38 +00:00

Owner

Closes #87. Closes #75.

docs/script-api.md documents every name a Script can reach: cinnabar.script/1, the globals, Component.define and field Kinds, Component instances, lifecycle timing, update ordering, GameObject, transform, reference fields, hot reload, and what is out of scope. Every stated behaviour maps to a tests/luau test, and the page ends with that map.

The glossary gains Script API, Script Component and the cinnabar.script Interface, revises Script, and carries the Plugin List Order note about luau and physics.

ADR-0029 records the one decision the parent spec did not state: a reloaded Script's added fields take the new define's default rather than ADR-0020's zero.

Tests are added for the error behaviours the page states that the suite did not yet pin: define outside a load, a duplicate define, an Odin-registered name, non-string names, keys and defaults, unload leaving Components running, refused GameObject names, destroyed parents, non-boolean activation, unknown property writes, a destroyed reference target, the shared lookups on an Odin Component, and gameObject on a destroyed Component.

The page lives in the repo rather than the Forgejo wiki so it is reviewed here first. The wiki repo is empty; after merge, copy docs/script-api.md to it as Script-API.md.

Closes #87. Closes #75. `docs/script-api.md` documents every name a Script can reach: `cinnabar.script/1`, the globals, `Component.define` and field Kinds, Component instances, lifecycle timing, update ordering, `GameObject`, `transform`, reference fields, hot reload, and what is out of scope. Every stated behaviour maps to a `tests/luau` test, and the page ends with that map. The glossary gains Script API, Script Component and the `cinnabar.script` Interface, revises Script, and carries the Plugin List Order note about `luau` and physics. ADR-0029 records the one decision the parent spec did not state: a reloaded Script's added fields take the new define's default rather than ADR-0020's zero. Tests are added for the error behaviours the page states that the suite did not yet pin: define outside a load, a duplicate define, an Odin-registered name, non-string names, keys and defaults, `unload` leaving Components running, refused GameObject names, destroyed parents, non-boolean activation, unknown property writes, a destroyed reference target, the shared lookups on an Odin Component, and `gameObject` on a destroyed Component. The page lives in the repo rather than the Forgejo wiki so it is reviewed here first. The wiki repo is empty; after merge, copy `docs/script-api.md` to it as `Script-API.md`.

crowmaki added 2 commits

2026-09-06 06:53:38 +00:00

Document the Script API surface and update the glossary (#87 ) 454c5e224e

Closes #87. Completes #75.

`docs/script-api.md` documents every name a Script can reach: `cinnabar.script/1`, the globals, `Component.define` and field Kinds, Component instances, lifecycle timing, update ordering, `GameObject`, `transform`, reference fields, hot reload, and what is out of scope. Every stated behaviour maps to a `tests/luau` test, and the page ends with that map.

The glossary gains Script API, Script Component and the `cinnabar.script` Interface, revises Script, and carries the Plugin List Order note about `luau` and physics.

ADR-0029 records the one decision the parent spec did not state: a reloaded Script's added fields take the new define's default rather than ADR-0020's zero.

Tests are added for the error behaviours the page states that the suite did not yet pin: define outside a load, a duplicate define, an Odin-registered name, non-string names and keys, `unload` leaving Components running, refused GameObject names, non-boolean activation, unknown property writes, a destroyed reference target, the shared lookups on an Odin Component, and `gameObject` on a destroyed Component.

Pin the review's untested claims and fix the reference-field error wording (#87 ) 3a5a8829aa

crowmaki merged commit cf3bc26235 into main

2026-09-06 06:56:29 +00:00

crowmaki deleted branch script-api-docs-87

2026-09-06 06:56:29 +00:00

crowmaki referenced this pull request from a commit

2026-09-06 06:56:31 +00:00

Document the Script API surface and update the glossary (#87) (#99)