Repository navigation
Tier-2 runtime script host: piccolo + game_script + curated host API #99
Description
Spec: the packages-devx design, §Runtime scripts (public proposal: #1; the full design doc lives in the private working origin); engine research: the Lua-scripting research notes (private working origin — piccolo decision, Eluna-shaped API, notify-hooks-first).
The Tier-2 runtime script host, per the recorded design — sequencing prerequisites (registry generalization, packages, hook catalog) are all shipped; this is the remaining step:
- piccolo (pinned, behind a thin
scriptmodule so an engine swap stays contained) compiled into the module with the getrandom workaround from the research notes; fuel budget per script run — a runaway script errors out, never stalls the tick. game_scripttable (name, event binding, source, enabled, priority for same-event ordering); compiled-script cache in module-instance globals (cache only, lazily rebuilt).- Curated host API, Eluna-shaped (read entity fields, deal damage, heal, grant item/XP/rep, send chat/emote, spawn creature, schedule follow-up) — never raw table access. Notify-only event bindings against the existing HOOK_EVENTS catalog; mutating hooks remain explicitly OUT pending separate green-light.
- Scripts ship in packages (
scripts/) and upload togame_scripton publish — the publish fan-out is what keeps all shards consistent. Any raw upload reducer must fan out too (operator tooling), or it recreates the partial-publish trap. - Authoring is TS→Lua per the spec (TSTL at
lyracore packages buildtime, hand-written Lua accepted — the runtime contract is Lua). Known day-one tax: runtime errors reference generated Lua; source-map threading is a follow-up. Fuel budgets calibrated against TSTL output, not artisanal Lua.
Blocked by #96
Done when: a package-shipped script bound to on_kill runs on every shard after a plain publish (verified server-side via its host-API effects); a deliberately infinite-loop script is killed by the fuel budget with the tick unaffected; a hand-written Lua script works through the same path.
Migrated 2026-08-11 from the private tracker (spacetime-core#511).
Activity
Mathih13 commentedon Aug 24, 2026
Human Brief
Category: enhancement
Summary: Coordinate the Runtime Script host, Package reconciliation, first host API, and TypeScript authoring path.
Why this needs a human:
The parent spans four implementation units and defines a durable gameplay execution boundary. Agents can implement the formal children once their dependencies are met; a maintainer owns their integration and final live behavior.
Current behavior:
The piccolo feasibility spike is complete, but the Module has no Runtime Script host or persisted Package script lifecycle.
Desired behavior:
#317 supplies a fuel-bounded host with fresh invocation state and staged effects. #318 reconciles Package-only scripts on every Shard using numeric
script_ididentity. #319 adds only event reads, actor and target reads, healing, and chat. #320 compiles TypeScript to deterministic Lua while accepting hand-written Lua through the same artifact.Runtime Scripts have no raw upload path and no raw data access. Lower priority runs first, then
script_id. One failure discards that invocation's effects but does not stop core or later scripts.Acceptance criteria:
Out of scope:
Mathih13 commentedon Aug 28, 2026
Closing in favor of the Runtime Scripts breakdown: #317 (piccolo, fuel budget, staged effects), #318 (Package script reconciliation across Shards), #319 (first curated host API), #320 (TypeScript-to-Lua authoring). #317 and #319 are done; #318 is implemented and merged, pending a live check on a real Shard; #320 has not started. Tracking moves to those four.