Content engine + Studio Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Ship an app-resident content engine (blocks + document runtime + logic graph + tiny formulas), an agent-first Studio (headless CLI + Mac UI), a gated publish pipeline (sbapi registry, content.stickbash.com, signed packs, staged rollout) and an exact-match proof set. All new skins, maps, kill films and taunts then ship from our server with no app update.

Build order (the user, 6 Nov: "u build one by one, first map engine, then animation engine, like that"): the engines are built one after another, each finished end to end before the next starts:

1. Stage 1: the shared core, only what maps need.
2. Stage 2: the MAP engine.
3. Stage 3: the ANIMATION (kill film) engine.
4. Stage 4: the SKIN engine.
5. Stage 5: the TAUNT / EMOTE engine.
6. Stage 6: the shared catalogue, Studio polish and launch readiness.

Within an engine, tasks marked [par] can split between two lanes.

Architecture:

• Game. A Unity-free core (Scripts/Engine/Core/) holds the document model, the compiler, quantisation, the logic graph, fixed-point formulas and the pack format, and is unit-tested headless in seconds. On top of it, Unity-side block families wrap today's tested code paths: the page-film engine, ArenaDef / MapScript, cosmetics recipes and the taunt rig. The Studio is the internal player build with -scenario studio:*.
• Server. sbapi gains a content module, and Caddy behind Cloudflare serves immutable content-addressed files.

Tech Stack:

• Unity 6000.3.26f1 (C#, IL2CPP), Newtonsoft JSON (com.unity.nuget.newtonsoft-json 3.2.2), Unity's bundled Roslyn + NetCoreRuntime for headless core tests.
• Go (sbapi), Caddy, Cloudflare.
• zsh tooling (unity.sh, build_test.sh, cap.sh, net_test.sh, tools/csc_check.sh, tools/locked.sh).

Spec: docs/superpowers/specs/2026-11-06-content-engine-design.md (APPROVED 6 Nov; all 15 decisions made). Section numbers below (§x) refer to it. Executors read both.

Global Constraints

• No downloaded executable code. Packs are declarative data, strings, audio and images. There is no scripting language. The only expression type is the tiny formula set of §5.5a: ops add sub mul div(÷0 = 0) min max clamp abs lerp step, ≤ 32 nodes, no loops, recursion, variables, functions or strings, and a server kill switch to each slot's mandatory fallback constant.
• Bundles hold only AudioClip, Texture2D (and Font). No MonoScript, shader, custom-shader material or component prefab. Same Unity version 6000.3.26f1.
• Logic graph bounds per document:
  • ≤ 256 nodes, ≤ 1024 wires, ≤ 32 state nodes;
  • ≤ 64 sinks firing per tick, logic state ≤ 64 B;
  • one evaluation pass per tick, actions visible to triggers on the next tick;
  • counters i16, saturating.
• Formula budgets: ≤ 64 formulas per document. Per LOW frame ≤ 2,048 look formula nodes; per fixed step ≤ 1,024 sim formula nodes. sim formulas use Q16.16 int32, saturating, division rounding toward zero.
• Determinism:
  • Content numbers are quantised once at compile: ticks, mm, 1/65536 turn, 1e-4 for dimensionless numbers.
  • Engine wire messages use EngineWriter: ContentRef (u8 room-table index + u16 local index), Tick, Seed, small ints, enums and Pos (int16 mm). It has no F32 / Half.
  • Random draws use seeded streams with an FNV-1a seed. Never string.GetHashCode (except the proof maps' director-compat stream).
• Do not touch legacy content paths. FilmStart, PageKillWire (append-only), emote ids 0-33 and cosmetic u8 slot indexes stay byte-for-byte as they are. Existing content stays as it is.
• Protocol:
  • 144 → 145 in Stage 2 (the map engine: room table, pack-set hash, arena ContentRef, the generic snapshot block, the relay), with NfOldRoomProtocol-style refusal.
  • Each later engine adds its messages with one more bump: EngineFilmStart → 146 (Stage 3), the loadout extension → 147 (Stage 4), the taunt ContentRef → 148 (Stage 5).
  • This is allowed only because no player builds exist before launch. The launch build carries the last number.
• Performance:
  • Frame p95 ≤ 16.7 ms, max ≤ 33 ms, begin ≤ 16.7 ms, 0 B GC per frame in steady state, on LOW / MED / HIGH and with -perfslow 6.
  • GPU numbers come from the Mac / M2 only; the VM reports CPU ms only.
  • The budget meter never drops or changes a sim part.
• Gore LOW 0 / MEDIUM 2 / EXTREME 5. Every new film authors all three levels (D11). New films must be the same tick length and have the same online state at every level. Imported legacy takes use the legacy ladder mode.
• Packs:
  • ≤ 5 MB per pack per platform and ≤ 150 MB cache, with LRU eviction; owned items' current and previous live packs are pinned (D6).
  • Content identity = sha256 of the content only. The envelope (.sbe: gate report, Unity version, texture formats, approval, Ed25519 signature) sits beside it.
• Approval: only a human dashboard account can move a pack to live (D2). Rollout is internal → test → 10 % for a day → everyone, with a one-tap pull-back (D9).
• Phone download: the splash downloads required / new packs before the menu with "Downloading new content… X / Y MB". Offline, it retries 3 times over ~10 s, then continues with the cache plus a "new content waiting" note; it never blocks forever. Rooms download a missing playable pack with a progress bar before joining (D4, D5).
• Exact match (proof set): identical, zero difference per frame in shapes, sounds and positions, same machine, same gore level, same seed (D7).
• Proof set:
  • Maps: Backyard, Belt Line, Wrecking Yard.
  • Films: SIX-SHOOTER, THE X, DRIP, HIGH NOON, COLD-BLOODED, THE OFFERED HAND.
  • Cosmetics: ICE revolver, one PLAIN skin, HOODIE, CROWN, FIRE aura, RAINBOW trail.
  • Taunts: LOSER, CHAI BREAK, DAB, BHANGRA (D8).
• Repos:
  • Game code: branches off live-v4train7 in StickFight-online-train7.
  • Server: branches off main in stickbash-online.
  • Content: new private repo farisbasha/stickbash-content (D15).
  • Commit by path, never commit -a, no stash.
  • Game builds rewrite ProjectSettings.asset: restore it after builds.
• Lab code sits under #if !SB_STORE. The Studio never ships in a store build.
• Mac load rules: heavy steps go to the M2 / VM first, under the load bands (< 20 normal, 20-35 no new heavy local steps, > 35 hold). One Unity editor at a time through tools/locked.sh.

Review Focus

1. A phone that is offline or slow at app open. The splash must give up after ~10 s and enter the menu with cached packs. A half-downloaded pack must never register. Pinned packs must survive an LRU sweep. Test: Task C.3 partial_download_never_registers, lru_keeps_pinned; Task C.10 splash_offline_continues.
2. A joiner whose app is older (ENGINE_SIM differs) or outside the rollout bucket. The room must still form, with engine maps not offered and nobody refused. Test: Task M.8 older_engine_sim_room_plays_builtins, rollout_bucket_outsider_can_fetch_room_pack.
3. A document that is valid but pathological. Examples: a logic graph at every cap at once, a formula dividing by a signal that is 0, a counter at i16 max that keeps adding. It must run within budget with no exception and give deterministic output. Test: Task C.4 logic_caps_all_at_once, counter_i16_saturates; Task C.5 formula_div_zero_is_zero.
4. A pack pulled while a room is playing its map, or while players own its items. The match finishes unchanged, dependents cascade, and nothing crashes on the next fetch. Owned items fall back or hide. Test: Task C.9 kill_list_cascades_dependents; Task M.8 pulled_map_finishes_round; Task K.6 pulled_owned_item_falls_back.
5. The same document on ARM (phones, M1 Mac) and x64 (VM). Replicated state bytes, the gore-independent film hash and Q16.16 formula bits must be identical. Test: Task 2 detspike_cross_arch_digest_equal; Task C.5 fixed_golden_vectors.

Stages, sizes and lanes

Sizes are lane-days of build. "Effective" adds ~15 % for review rounds. Each stage ends with its engine's done definition passing.

Building one engine at a time costs a little more than the old interleaved plan, about +10 %. Each engine gets its own Studio editing and its own end-to-end done pass, and some core work comes back when a later engine first needs it. In return, each engine is usable as soon as it is finished.

Calendar (honest; agents run daily, review latency included)

• 2 lanes is the sweet spot under the coordinator's cap of 4 shared subagents. That leaves room for a reviewer and other work.
• A third lane helps less than it did in the interleaved plan, because one engine at a time leaves fewer independent tasks. The third lane mostly takes the Studio UI and server work of each stage.
• Each "done" definition is a hard gate: the next engine starts only after it passes.

Lanes inside each stage

• Lane B (core / maps / net) and Lane C (agent CLI / server / Studio) run Stages 1-2.
• In Stages 3-5, Lane A (films / cosmetics) replaces B as the content lane, and C stays on the CLI, Studio and server side.
• Tasks are tagged [seq] (waits for the listed deps) or [par] (can run beside the stage's other [par] tasks once its deps are met).

Writing the detail. The first 3 tasks are written to full step detail below. Every other task carries its files, interfaces, tests and acceptance. The lane that starts a stage first runs a short writing-plans pass to expand that stage's tasks into numbered steps in the same style. No stage starts without its expanded steps committed to this file.

File map (the game repo, StickBrawl/Assets/_Game/Scripts/)

Server (stickbash-online): server/sbapi/content/ (new), server/sbapi/admin/ + dash/ (approval), server/relay/ (pack-set hash), deploy/stack/content-site.caddy.tmpl (new). Content repo (stickbash-content, new): the layout of spec §6.4.

Stage 1: the shared core, only what maps need

What Stage 1 builds and what it defers

Task 1: Map document + loader spike: Backyard rebuilt from a document, identical [par] (Lane B, 4-5 days)

Retires: can a map document reproduce a code-built arena exactly, with the same ArenaDef, the same bot navigation and the same frames (D7)? The map export is lossy (MapExportLab.cs:29), so this proves the exact-geometry path.

Files:

• Create: Engine/Lab/EngineProbe.cs, Engine/Lab/MapSpikeLab.cs, Engine/Map/SpikeMapDoc.cs (a throw-away JSON → ArenaDef adapter for map.frame, map.solid floor / one-way, map.spawns incl. extra spawns, the theme id), tools/engine/spike_docs/backyard.json
• Modify: Core/Game.cs (case "engine:mapspike"), Render/ShapeBatch.cs (a #if !SB_STORE static Probe callback once per batch upload: batch name, vertex count, the verts span; null in normal runs), Level/Arenas.cs (register the doc's arena only in lab runs, appended after every built-in so no index shifts, hidden = true)
• Test: the lab (./cap.sh "engine:mapspike"), output lines [ENGMAP]

Interfaces:

• Produces: EngineProbe.Begin(string runId), EngineProbe.FrameDigest() -> ulong (FNV-1a over every ShapeBatch vertex quantised to 1e-4 in batch order, every fighter's root + 13 joints ×1e2, every MapPlat pose in mm), EngineProbe.End() -> ProbeReport { int frames; ulong[] digests; int firstDiff; }. This is the exact-match harness of every later proof task.
• Produces: SpikeMapDoc.Build(string jsonPath) -> ArenaDef (id eng.spike.backyard).

• Step 1: Write the lab's PASS / FAIL contract. MapSpikeLab compares the built-in backyard with eng.spike.backyard and prints a line for each of these checks:

  • (a) ArenaDef field by field: every PlatDef (rect, kind, ice, conveyor, look, rot, a, b), spawns, extra spawns, bounds, camArea, killArea, focusArea, fitSize, middle, skyY, dropRange, theme. Printed as [ENGMAP] def <field> equal|DIFF <a> <b>.
  • (b) NavGraph: the same spans and links (kind, take / land x, cost, air). Printed as [ENGMAP] nav spans=<n> links=<m> equal|DIFF.
  • (c) A frame-by-frame run: a seeded 3-bot deathmatch, 20 s, seed 11, on each arena, at -devicetier low|medium|high. Printed as [ENGMAP] run q=<tier> frames=<n> firstDiff=<i|-1>.

  It ends with [ENGMAP] PASS only when all are equal.

• Step 2: Build and run it to see it fail. ./build_test.sh && ./cap.sh "engine:mapspike" 0 0 (on the M2 when the Mac load ≥ 20). Expected: [ENGMAP] FAIL (no doc).

• Step 3: Implement EngineProbe and the ShapeBatch probe callback.

• Step 4: Write backyard.json. Write it by hand from Arenas.cs:214-216, in metres with units (convert the prototype px through the same Px.R / Px.P maths the DSL uses, printed by a one-off lab helper so no number is retyped by hand). Then implement SpikeMapDoc.Build. Run. Expected: (a) and (b) equal. When (c) differs, the lab dumps both frames' batch lists to captures/engmap/<case>/ for a side-by-side.

• Step 5: Fix differences until [ENGMAP] PASS. If a difference comes from float rounding of px → m, the doc keeps the exact value the DSL produces (the compiler grid is 1 mm, and Px values land on it). Record any value that doesn't.

• Step 6: Write the findings to stickbash-online/docs/superpowers/results/2026-11-xx-engine-map-spike.md: the grid question, the probe cost per frame, and what Wrecking Yard / Belt Line will need beyond Backyard. Commit by path:

git add StickBrawl/Assets/_Game/Scripts/Engine StickBrawl/Assets/_Game/Scripts/Core/Game.cs StickBrawl/Assets/_Game/Scripts/Render/ShapeBatch.cs StickBrawl/Assets/_Game/Scripts/Level/Arenas.cs tools/engine/spike_docs/backyard.json
git commit -m "engine spike M1: Backyard from a map document, identical ArenaDef / NavGraph / frames; EngineProbe"

Acceptance: [ENGMAP] PASS at all three tiers, and the results note committed.

Task 2: Logic-graph determinism spike: fixed point, the graph, the float-free writer, across ARM and x64 [par] (Lane B or a second lane, 4-5 days)

Retires: can replicated state and formulas be bit-identical across the Mac (ARM64), the VM (x64) and phones, and can a generic payload replace hand-written Write / Read (spec §5.7, MapWreck.cs:341-352)?

Files:

• Create: Engine/Core/Fixed.cs, Engine/Core/Logic.cs (spike subset: sources tick, zone; logic AND, NOT, toggle, delay, timer; sink door.open), Engine/Core/Streams.cs (FNV-1a seed + xorshift128+), Engine/Runtime/EngineWriter.cs, Engine/Lab/DetSpikeLab.cs, tools/engine/coretest.sh, tools/engine/tests/Run.cs, FixedTests.cs, LogicTests.cs, StreamsTests.cs, tools/engine/spike_docs/det-door.json (two zones → AND → a sliding door piece, plus a formula-driven mover speed)
• Modify: Core/Game.cs (case "engine:detspike")

Interfaces:

• Produces:
  • struct Fx: Q16.16, Fx.FromRaw(int), Fx.Of(int milli), + - * / saturating, / by 0 = 0, Min Max Clamp Abs Lerp Step.
  • static class Fnv { ulong Hash(ReadOnlySpan<byte>) }.
  • sealed class Stream { Stream(ulong seed); uint Next(); int Range(int lo, int hi); int Draws { get; } }.
  • sealed class LogicGraph { static LogicGraph Compile(LogicDoc d, out List<Error> errs); void Tick(ISignals inputs, ISinks outputs); int StateBytes { get; } void Write(EngineWriter w); void Read(EngineReader r); }.
  • sealed class EngineWriter { U8 U16 U32 I16 Tick(uint) Seed(uint) Ref(ContentRef) Pos(int mmX, int mmY) } and EngineReader mirroring it. No float methods.
• Consumed by: Tasks C.4-C.6 (they harden these into the full core).

• Step 1: Write tools/engine/coretest.sh. It compiles StickBrawl/Assets/_Game/Scripts/Engine/Core/**/*.cs + tools/engine/tests/*.cs with Unity's Roslyn and runs the result on Unity's NetCoreRuntime/dotnet (the paths of tools/csc_check.sh:19-32), without UnityEngine.dll, so any using UnityEngine in Core fails. Run.cs calls every static method marked [T] and prints ok <name> / FAIL <name>: <msg>, then exits non-zero on any failure. With --digest it prints one FNV digest over every golden output. Run with no tests. Expected: 0 tests, exit 0.

• Step 2: Write the failing tests.

  • fixed_golden_vectors: 64 (a, b, op) → raw results written in the test file, covering saturation at ±32767.99998, /0 = 0, negative rounding toward zero, Lerp clamping t.
  • fixed_saturates.
  • formula_div_zero_is_zero (through a 3-node AST).
  • streams_fnv_seed_stable: Fnv.Hash(utf8("wreck")) equals the constant printed by an independent FNV-1a 64 implementation (Python one-liner in the test comment).
  • streams_draw_count.
  • logic_one_pass: a toggle wired to itself through delay 1 flips once per tick.
  • logic_caps_all_at_once: 256 nodes, 1024 wires, 32 state nodes, 64 sinks per tick. It runs, StateBytes ≤ 64, no exception.
  • writer_has_no_float: reflection finds no EngineWriter method taking float, double or Half.

  Run tools/engine/coretest.sh. Expected: FAIL (types missing).

• Step 3: Implement Fx, Fnv, Stream, the spike LogicGraph, and EngineWriter / EngineReader until coretest passes.

• Step 4: Cross-arch. Run tools/engine/coretest.sh --digest on the Mac (ARM64) and the VM (x64, through the VM lane rules; never touch live services). It also runs 10,000 ticks of det-door.json with seeded inputs. Expected: identical digests; record both.

• Step 5: Write DetSpikeLab. It loads det-door.json on a hidden lab arena (appended, hidden = true, like travlab) with a minimal EngineMapScript stub that writes the graph's state through EngineWriter into the level snapshot. Run host + 1 client: net_test.sh detspike 1 "-scenario engine:detspike" "-scenario engine:detspike". Bots walk on and off the zones. Each side prints [ENGDET] tick=<t> state=<hex> every 60 ticks, and [ENGDET] PASS when the client's state equals the host's at every sample and the door poses are equal in mm.

• Step 6: Run on the phone. Run the digest inside a player lab (engine:detspike:digest) on the reference iPhone (HOWIN team route; never the Fayiz phone). Expected: the Step 4 digest.

• Step 7: Write the findings to .../results/2026-11-xx-engine-det-spike.md (digests, payload bytes per tick, surprises). Commit by path.

Acceptance: coretest green on Mac + VM with equal digests, the phone digest equal, [ENGDET] PASS host + client, and writer_has_no_float green.

Task 3: Agent CLI skeleton: studio.sh serve, validate, preview of a map, < 30 s edit → still [par] (Lane C, 3-4 days)

Retires: can agents iterate on maps without Unity builds (spec §6.5), and do the RPC + capture paths work on Mac, M2 and VM?

Files:

• Create: tools/studio.sh, Engine/Lab/StudioServe.cs (scenario studio:serve: TcpListener on 127.0.0.1:<port>, newline-delimited JSON-RPC 2.0, FileSystemWatcher on --content <dir>), Engine/Lab/StudioCommands.cs (ping, validate, preview), Engine/Core/Validate.cs (spike subset: Error { string path; string rule; string found; string allowed; string hint; }), tools/engine/studio_smoke.sh, tools/engine/spike_docs/tiny-arena.json (a one-screen arena: a floor, two ledges, four spawns, one ladder)
• Modify: Core/Game.cs (case "studio:serve", "studio:validate", "studio:preview")

Interfaces:

• Produces the CLI contract every later command follows:
  • studio.sh <cmd> [args] prints exactly one JSON object on stdout: { "ok": bool, "cmd": str, "errors": [Error], "warnings": [Error], "outputs": [path], "ms": int, "seed": int|null }.
  • Exit codes: 0 ok, 1 errors, 2 warnings only, 3 tool failure.
  • When serve runs (port file ~/.stickbash-studio/<worktree>.port), the CLI forwards over RPC. Otherwise it launches a one-shot batchmode player, as cap.sh does.
• Produces: StudioCommands.Preview(DocRef doc, PreviewOpts o) -> List<string> pngPaths (o.at in s or ticks, o.cam fit|follow, o.seed, o.w / o.h).
• Task 1's SpikeMapDoc.Build is reused for the tiny arena (coordinate on the file if both run at once; Task 3 may copy the adapter and merge later).

• Step 1: Write the smoke test. tools/engine/studio_smoke.sh:

  1. Start studio.sh serve --content tools/engine/spike_docs in the background.
  2. ping → ok:true.
  3. validate tiny-arena.json → ok:true.
  4. A copy with the ladder's top below its bottom → ok:false, exit 1, an error at path /blocks/3/p/y1 with a non-empty hint.
  5. preview tiny-arena.json --at 1s --cam fit --seed 3 → one PNG listed, and the file exists.
  6. Move a ledge in the doc and time the file write → the new PNG on disk; assert < 30000 ms.
  7. Stop the server.

  Run. Expected: FAIL (no studio.sh).

• Step 2: Implement tools/studio.sh (zsh): forwarding, the port file, the one-shot fallback (-batchmode -scenario studio:<cmd> ...), JSON passthrough.

• Step 3: Implement StudioServe + Validate (the spike checks the tiny arena's params against declared ranges and orderings) and Preview (build the arena, load it in a world with no fighters, render through the capture Shot path in Core/Game.cs:327).

• Step 4: Implement hot reload. On a file change: re-read, re-validate, rebuild the arena in the warm world (no scene reload when the theme is unchanged), and re-render a pending preview. Run the smoke test on the Mac. Expected: PASS, with the timing printed.

• Step 5: Run it on the M2 and the VM (the Linux player via build_test.sh's Linux path, under Xvfb). Record the three timings.

• Step 6: Write the findings to .../results/2026-11-xx-studio-cli-spike.md (timings, the RPC contract as built, what Task C.7 must change). Commit by path.

Acceptance: the smoke test passes on Mac, M2 and VM, edit → still < 30 s on the Mac and M2, and the contract documented.

Stage 1 core tasks (after the spikes)

Stage 1 done when coretest is green on Mac + VM + phone, every C task's tests pass, and an agent can publish --channel test a tiny static map pack that a test phone downloads at the splash and plays offline. Online play comes in Stage 2.

Stage 2: the MAP engine, complete

Done definition (the coordinator, 6 Nov): an agent makes a brand-new map from the CLI, previews it, bot-tests it, passes the gates, publishes it to the test phones, and it plays online. In addition, the proof maps Backyard / Belt Line / Wrecking Yard are identical (D7), and the map Studio editing works agent-first, then visual.

Stage 3: the ANIMATION (kill film) engine

Done definition: an agent makes a brand-new film from a kill-page take plus Studio blocks at all three gore levels, previews it, gates it on every fitting arena, publishes it to test phones, and it plays online (host + client hash equal). The 6 proof films are identical.

Stage 4: the SKIN engine (+ attachments)

Done definition: an agent makes a brand-new premium weapon skin (look + an attached engine film + ammo + sparks + burst + feed icon) and a new body cosmetic. They gate, publish to test, show in matches, films and previews, travel online in the loadout, and a pulled pack falls back correctly. The 6 proof cosmetics are identical.

Stage 5: the TAUNT / EMOTE engine

Done definition: an agent makes a brand-new taunt with a prop and a gloat variant, and a new emote. They gate, publish to test and play online for everyone in the room. The 4 proof performances are identical.

Stage 6: the shared catalogue, Studio polish, launch readiness

Self-review (done)

• Spec coverage:
  • §5.1-5.4 → C.* / M.* / F.* / K.* / T.*;
  • §5.5 / 5.5a → C.4 / C.5 (+ K.2 for look formulas);
  • §5.6 → F.5; §5.7 → Task 2, C.6, M.8, F.5;
  • §5.8 → C.0, M.8, F.5, K.4, T.3; §5.9 → M.9;
  • §5.10 → M.13, F.10, K.7, T.5, X.2; §5.11 / §6 → Task 3, C.8, C.11, M.14;
  • §5.12 → C.8, M.12, F.9; §5.13 → C.9, C.10, K.6; §5.14 → M.10, X.1; §5.15 → X.4;
  • §7 → M.4-M.7, F.6, K.1 / K.3, T.2; §8 → M.11, F.8, K.5, T.4; §11 → X.5.
• Types: EngineProbe, Fx, LogicGraph, EngineWriter / EngineReader, ContentRef, Error and the CLI JSON result are defined once (Tasks 1-3, C.0) and only referenced later.
• Review Focus: each of the 5 lines names its test in its owning task.
• Proportion: full steps only for the three map de-risk spikes; each stage is expanded by its lane before it starts.