Docs: LANTERN roadmap index + Phase 4/5 design passes + session log B

- Roadmap_Lantern_Slice: Phase-0 status callout + doc index (all Phase-0 artifacts linked).
- Phase 4 (mutations): mostly a re-theme of the shipped boon overhaul (DR-047) + Gloam gating
  + Tallow fixing (persistence) + raw-socketing + culture library; salvage map + gate.
- Phase 5 (death/recovery): the split, stranded suits (deterministic relocation), body-carry,
  flame-share revive, the Tender solo valve, Selkie tariff; builds on the world-model
  in-pocket-death decision (C4); the slice's 2nd falsifiable-test half.
- Session log Part B: the autonomous design pass + the world-model review record.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-07-13 23:58:47 -07:00
parent fc31d066d0
commit d005f140db
5 changed files with 281 additions and 1 deletions
+1 -1
View File
@@ -20,7 +20,7 @@ Multiplayer game on **Unity DOTS** (Entities) + **Netcode for Entities** (server
- **Vision** → [[Pillars]] — design pillars & locked decisions · [[Identity_Lantern]] — the fiction (light-as-territory abyssal co-op) · [[Art_Direction_Lantern]] — style bible & material decision · [[Theme_Direction_Candidates]] — the exploration behind the pivot
- **Game Design** → [[Systems_Index]] — per-system design docs
- **Roadmap** → **[[Roadmap_Lantern_Slice]]** (operative) · [[Lantern_Strip_Mothball_Inventory]] (salvage map) · [[Lantern_World_Model_Spike]] (★review-first) · [[Backlog]] / [[Path_to_Fun]] / [[Milestones]] / [[Iteration_2026-07_CoopHades]] (history).
- **Sessions** → `07_Sessions/2026/` — dated work logs (latest: [[2026-07-13_Lantern_Phase0_Adoption_Pivot]] · [[2026-07-12_Phase17_Boon_Overhaul]])
- **Sessions** → `07_Sessions/2026/` — dated work logs (latest: [[2026-07-13_Lantern_Phase0_Design_Pass_B]] · [[2026-07-13_Lantern_Phase0_Adoption_Pivot]])
- **Decisions** → `07_Sessions/_Decisions/` — decision records DR-001 … DR-049 · [[DR-001_Netcode_Test_Harness]] · latest [[DR-049_Lantern_World_Model_Design]] (world-model, review-hardened) · [[DR-048_Lantern_Adoption_Full_Pivot]] (the pivot)
- **Meta** → [[Documentation_Protocol]] · [[Tags]]
- **Templates** → [[Session_Log_Template]] · [[Decision_Record_Template]]
@@ -0,0 +1,95 @@
---
title: LANTERN — Phase 4 Mutations & Homecoming Economy (design pass, pre-review)
date: 2026-07-13
tags: [roadmap, lantern, mutations, sparks, phase-4, design]
status: design-pre-review
permalink: gamevault/06-roadmap/lantern-phase4-mutations-design
---
# LANTERN — Phase 4: Sparks, Mutations & the Homecoming Economy
> Phase 4 of [[Roadmap_Lantern_Slice]] — a **design pass** (not a code contract; it deepens + gets its ★review
> when the phase is reached). The happy discovery from the combat/boon salvage: **the just-shipped boon
> overhaul ([[DR-047_Phase17_Boon_Overhaul_Mechanic_Changers]]) already IS ~70% of the mutation layer.** The
> `BoonEffects` substrate, pocket-clear offers, and the strip-on-return are the mutation loop; LANTERN adds
> **Gloam gating, Tallow fixing (persistence), raw-socketing, and the culture library.**
## The mapping: boons → wild mutations (mostly a re-theme)
| LANTERN design ([[Identity_Lantern]]) | Current system (salvage) | Gap |
|---|---|---|
| Sparks **drink Gloam** — kills/vents/blooms feed the mutation offer | `KillRewardSystem` already fires on-kill; offers already generate | Gate the offer on a **Gloam threshold** (a per-descent counter), not on room-clear alone |
| **2 paced thresholds per descent, at pocket-clear beats** (never mid-combat) | `BoonOfferSystem` offers once per `RoomEpoch` on `RoomReward` entry | Re-cadence to **2 Gloam-thresholds/descent** at PocketClear; keep the "never mid-combat" rule (it's already there) |
| **23 warps offered** (your decoy bursts / taunts / splits) | `BoonMath.PickBoons` draws 3, dedup + dominated-protection + family-bias | Re-theme the catalog entries as Spark-warps; keep the picker verbatim |
| Mutations are gloam-things: **evaporate at homecoming** | `RunDirectorSystem` **already strips the boon band + resets `BoonEffects`** on `Returning` | ✅ *already exactly this* — homecoming = the existing return-strip |
| **Tallow fixing: 1 fix slot per Spark** (a mutation survives homecoming) | (new) | NEW: a per-Spark fix slot that exempts one mutation from the return-strip + persists it |
| **Raw-socketing** a fresh organ wild (over-tuned, gone at homecoming) | (new; the socket kit is Phase 1) | NEW: socket a Spark mid-descent in an over-tuned wild state; strips on return unless cultured |
| **Culture library** — first organ home = permanently cultured; grafts regrow cheaply | (new; the ability catalog + `EquipmentSlot`-swap pattern is the seed) | NEW: a persistent per-station unlocked-Spark set; death-proof knowledge floor |
| **Scripted first-evaporation** (Keeper gifts one Tallow) | (new; onboarding pattern exists) | NEW: a one-shot scripted beat on the first homecoming-with-a-mutation |
## The four genuinely-new pieces
### 1. Gloam gating (the mutation feed)
A **per-descent server counter** `Gloam` (see [[Lantern_Currency_ReMean]] — a counter, not a ledger row) fills
from kills/vents/blooms (hook the existing `KillRewardSystem` + hazard events). At **2 paced thresholds** per
descent, at a **PocketClear** beat, the offer fires. This replaces "offer every room-clear" with "offer when
the descent has drunk enough Gloam" — a paced, earned cadence. The thresholds are live-tunable knobs.
### 2. Tallow fixing (the persistence + the scarcity gate)
- **1 fix slot per Spark** (a possible 2nd very late) — **slots, not materials, are the scarcity** (so the meta
can't ossify; in-run variety survives the best players — the review-hardened identity decision).
- Fixing = render a wild mutation in **Tallow** → that mutation is **exempted from the return-strip** and
persisted (a new additive save field: per-Spark fixed-mutation id). Mechanically: the fixed mutation's
`BoonEffects` contribution / `StatModifier` band is re-applied born-correct at the next descent's launch
(reuse the `ClassSwapUtil`/prep-band replay pattern — a proven "re-apply a modifier band" idiom).
- **The return-strip stays the default** (`RunDirectorSystem` Returning strip); fixing is the *exception list*.
### 3. Raw-socketing (the recurring temptation)
Socket a **fresh organ wild** mid-descent (Phase-1 socket kit): over-tuned stats, temporary, **gone at
homecoming unless cultured**. Mechanically = a socket write + a wild `StatModifier` band in a distinct source-id
range that the return-strip clears (unless the Spark was cultured — then the base graft persists, the wild
over-tune doesn't). The tension: wield it wild now vs. bag it to culture.
### 4. The culture library (the death-proof knowledge floor)
- First time an organ (Spark) comes home = **permanently cultured** (a persistent per-station unlocked-Spark
set; a new additive save array). Grafts **regrow cheaply from culture** → your kit is functional within
minutes of dying (non-negotiable in a skillshot game — the death-split's whole premise).
- Mechanically = the ability catalog (`AbilityDatabase`) + a persisted "cultured" bitset; socketing a cultured
Spark is free/cheap; the death-split (Phase 5) strands *cargo + raw organs*, never the cultured base.
## Catalog: fill the Spark set to 810
The current default catalog is 12 boon entries (8 mechanic-changers + 4 stat). Re-theme + extend into 810
**Sparks** (abilities-as-organs from named myths) with their warp-mutations. Each Spark = an `AbilityDefBlob`
row (Phase 1) + its mutation warps as `BoonCatalog` entries tagged to that Spark's `Family`. Reuse the
`Family` tag system for build-bias + dominated-protection verbatim.
## Salvage map
| Piece | Verdict |
|---|---|
| `BoonEffects` (Pierce/Fork/Chain/Flags, `SendToOwner`, `ProjectileEffectState`/`KillRewardSystem` hooks) | **KEEP** — the mutation substrate; add flag bits / count bytes for new warps (each new `[GhostField]` re-bakes the player ghost — batch them) |
| `BoonMath.PickBoons` (dedup / dominated / family-bias, pure integer-hash) | **KEEP verbatim** — the offer picker |
| `BoonOfferSystem` (once-per-RoomEpoch offer) | **REWORK** — re-cadence to 2 Gloam-thresholds/descent at PocketClear |
| `BoonApplySystem` (Kind==1 mutates `BoonEffects`; Kind==0 appends `StatModifier`) | **KEEP** — the apply substrate |
| `RunDirectorSystem` Returning strip | **KEEP + extend** — the homecoming evaporation; add the Tallow-fix exception list |
| `ClassSwapUtil` / prep-band replay | **KEEP as pattern** — the born-correct "re-apply a modifier band" idiom for fixed mutations |
| Culture bitset + fixed-mutation save fields | **NEW** — additive save schema (with the Phase-2/3 v7 bump) |
## The gate ([[Roadmap_Lantern_Slice]])
Two consecutive descents produce **visibly different builds from the same kit**; the **evaporation beat reads
as a gift, not a theft** (the scripted first-evaporation + the Tallow gift). Feel/balance knobs: Gloam
thresholds, warps-per-offer, Tallow slot count, raw-socket over-tune magnitude.
## Open forks (parked in [[Lantern_Operator_Questions]])
- Gloam as a stored ledger byte vs a per-descent counter (recommend: counter).
- The exact Spark set (810) + each Spark's 23 warps — a content-design pass with the operator.
- Whether raw-socketing shares the Phase-1 socket slots or a separate "wild slot."
## Related
- [[DR-047_Phase17_Boon_Overhaul_Mechanic_Changers]] — the substrate this evolves · [[Lantern_Phase1_Combat_Gym_Build_Spec]] — the socket kit + Sparks
- [[Identity_Lantern]] — the mutation economy (fix slots, culture, raw-socketing, the scripted gift)
- [[Lantern_Currency_ReMean]] — Gloam + Tallow · [[Roadmap_Lantern_Slice]] Phase 4
@@ -0,0 +1,104 @@
---
title: LANTERN — Phase 5 Death, Recovery & the Solo Valve (design pass, pre-review)
date: 2026-07-13
tags: [roadmap, lantern, death, recovery, phase-5, design]
status: design-pre-review
permalink: gamevault/06-roadmap/lantern-phase5-death-recovery-design
---
# LANTERN — Phase 5: Death, Recovery & the Solo Valve
> Phase 5 of [[Roadmap_Lantern_Slice]] — a **design pass** (deepens + gets its ★review when reached; this is
> netcode-heavy — stranded-suit persistence, body-carry, the Tender companion). It owns the **second half of
> the slice's falsifiable test:** *does a stranded suit feel worth a second descent?* The world-model review
> already locked the load-bearing constraint (NR-2/C4 in [[World_Model_Build_Spec]]): **in-pocket death, warp-
> to-station gated behind party-wipe, revive is new code.** This phase builds the rest on that.
## The one rule, applied to the body
> *What the light holds, stays; what the dark holds, changes* — applied to death: **your flame (the person)
> returns to the light; your cargo (what the dark held) strands with the suit in the dark.**
## The split (the core design — [[Identity_Lantern]])
- **Flame returns cheap.** Snuffed, the flame goes home; re-kindle in a rack-spare. **Base grafts regrow
cheaply/immediately from the culture library** (Phase 4) → kit functional within minutes. *Non-negotiable in
a skillshot game* — recovery is an optional value-run with a WORKING build, never mandatory kit-repair.
- **What strands with the suit (dark in the deep):** cargo (unbanked Lumen + organs), **fixed mutations**, and
any **raw-socketed** wild organ. This is exactly the Phase-4 return-strip set — death = a *localized,
recoverable* version of homecoming-evaporation, dropped at the death site instead of evaporated.
- **Salvage:** `PlayerDeathStateSystem` (derives `Dead` from `Health<=0`, gates move/aim/fire) + `RespawnState`/
`PlayerRespawnSystem` are the base — but per C4 the respawn is **rewritten to in-pocket** (the guttering
suit stays put; full-wipe warps everyone home together).
## Stranded suits (recovery — deterministic, never RNG)
- A death spawns a **stranded-suit entity** at the death site (a server ghost carrying the stranded cargo/
mutation manifest). **Persists across descents** — deterministic **server relocation, never RNG theft** (the
doppelganger that "wears your build" is the marquee *deferred* post-slice encounter; until then the dark just
relocates the container by a server rule).
- **Ally body-carry:** a teammate hauls the suit home. **Carried suits stay LOUD** (count fully toward party
Loudness — no dead-mule stealth logistics). A carried suit = an attachment/parent on the carrier + a Loudness
contribution.
- **One-suit debt cap:** die on the recovery run → the older suit is **dark-claimed** (resurfaces later as a
partial salvage lot at the Selkie's counter). Cap = 1 outstanding stranded suit; this bounds the state +
prevents a soft-lock spiral.
- **Party wipe:** all stranded suits **drift one pocket shallower** (the dark spits out what it plays with) — a
deep wipe never soft-locks the save. This composes with the world-model loss-floor invariant (DP-5/C2 —
muster keyed on graph-reachability-from-station; drifting-shallower keeps recovery reachable).
## Guttering & flame-share revive (co-op — NEW code per C4)
- A downed Wick's flame **gutters** (a telegraphed countdown; the lamp-morse revive-plea, per the
[[Lantern_Tone_Bible]]). An ally re-lights it **from their own flame** — it **costs the giver** (a Flame/
Health price). Reachable *because* the downed suit stays in-pocket (C4).
- Mechanically: a `Guttering` state (server-only timer) on the downed player; a revive RPC/proximity-interact
that transfers a Flame cost from giver → downed and clears `Dead`/`Guttering` in place (at the pocket origin,
`PocketTag = active`, never the station). Full gutter (no revive in time) = the flame goes home, suit strands.
## The solo valve (the Tender dive-companion)
Converts the co-op-only verbs (revive, carry, hold-the-line) into **degraded-but-present solo verbs,
diegetically** — a solo Wick may take **one Tender** down:
- **No combat power.** It drags your guttering suit toward light, hauls cargo, and can hold a lantern's feed
during a tide.
- Mechanically: a server-only companion entity with simple follow/drag AI (reuse the `EnemyAISystem` seek/
move-util chassis, no attack; the collide-and-slide mover). **Not** a ghost the party competes over — a
solo-only support. Its "drag guttering suit toward light" = a body-carry variant driven by AI.
## The Selkie tariff (menu-level for the slice)
- The Selkie **retrieves a lost suit for a steep tariff** — for the slice, a **menu-level** transaction (spend
banked Lumen at the station to recover a dark-claimed suit), not a full questline (that's v1.0). Reuse the
storage/deposit RPC + a station vendor panel.
## Salvage map
| Piece | Verdict |
|---|---|
| `PlayerDeathStateSystem` (Dead-derive, gate move/aim/fire) | **KEEP** |
| `PlayerRespawnSystem` | **REWRITE to in-pocket** (C4; warp-to-station only on party-wipe) |
| `RespawnState` / respawn timer | **REWORK** → guttering timer + in-place resolve |
| Stranded-suit ghost + manifest | **NEW** (server ghost; persists via the Phase-2/3 save schema — additive) |
| Body-carry (parent + Loudness) | **NEW** (attachment + the Loudness meter from currency re-mean) |
| Flame-share revive RPC | **NEW** (co-op verb; the receiver-sets-command / proximity-interact idiom) |
| Tender companion AI | **NEW** (reuse the `EnemyAISystem` seek/move-util chassis, no combat) |
| Selkie vendor | **NEW-lite** (reuse storage/deposit RPC + a station panel) |
## The gate ([[Roadmap_Lantern_Slice]])
**a stranded suit feels worth a second descent** — solo death is a story, not a rage-quit. Feel knobs: gutter
window, flame-share cost, carried-suit Loudness weight, party-wipe drift distance, Selkie tariff.
## Dependencies & sequencing
Depends on: the world-model (in-pocket death, loss-floor, muster — [[World_Model_Build_Spec]]), the currency
re-mean (Flame = Health, Loudness meter, cargo-vs-banked — [[Lantern_Currency_ReMean]]), and the Phase-4
culture library (cheap regrow is what makes the split fair). Netcode-heavy → **its own ★ design review before
code** (stranded-suit persistence + relevancy, body-carry replication, the companion).
## Related
- [[World_Model_Build_Spec]] C4 — the in-pocket death constraint this builds on
- [[Identity_Lantern]] — the split, recovery, the Tender, the Selkie · [[Lantern_Phase4_Mutations_Design]] — the culture floor
- [[Lantern_Tone_Bible]] — the revive-plea lamp-morse · [[Roadmap_Lantern_Slice]] Phase 5
@@ -30,6 +30,13 @@ permalink: gamevault/06-roadmap/roadmap-lantern-slice
**Gate:** DR merged; world-model design review passed; **A0 style-proof scene approved**.
> **Phase 0 status (2026-07-13):** ✅ 0.1 adoption ([[DR-048_Lantern_Adoption_Full_Pivot]]) · ✅ 0.2 strip/
> mothball ([[Lantern_Strip_Mothball_Inventory]]) · ✅ 0.3 world-model **design review passed** →
> [[World_Model_Build_Spec]] + [[DR-049_Lantern_World_Model_Design]] · ◻ 0.4 A0 material spec written
> ([[Art_Direction_Lantern]] + [[Lantern_Art_Pipeline_Recipes]]) but the **in-engine style-proof scene gate is
> OPEN** (needs a focused editor + operator eyes). **Open gate items = the A0 scene only.** Phase-1 design is
> ready ([[Lantern_Phase1_Combat_Gym_Build_Spec]]); operator decisions parked in [[Lantern_Operator_Questions]].
## Phase 1 — Combat core: two frames that feel like Shape of Dreams
The primary verb first. No world, no lanterns — a gym.
@@ -181,6 +188,9 @@ The deeper technical pass (next sessions) takes each phase in turn: context7-ver
## Related
- [[Identity_Lantern]] — the design this implements (scope ladder = this roadmap's contract; readability law = A-track law)
- **Phase 0 artifacts:** [[DR-048_Lantern_Adoption_Full_Pivot]] · [[Lantern_Strip_Mothball_Inventory]] · [[World_Model_Build_Spec]] + [[DR-049_Lantern_World_Model_Design]] (+ [[Lantern_World_Model_Spike]] / [[Lantern_World_Model_Design_Proposal]]) · [[Art_Direction_Lantern]] + [[Lantern_Art_Pipeline_Recipes]]
- **Phase 1+ design:** [[Lantern_Phase1_Combat_Gym_Build_Spec]] · [[Lantern_Currency_ReMean]] · [[Lantern_Tone_Bible]] (Phase 7)
- **Running:** [[Lantern_Operator_Questions]] — decisions parked for the operator
- [[Theme_Direction_Candidates]] — research underneath the direction
- [[Synty_Asset_Inventory]] — placeholder quarry during the transition
- [[Iteration_2026-07_CoopHades]] — superseded on adoption
@@ -0,0 +1,71 @@
---
date: 2026-07-13
type: session
tags: [session, lantern, phase-0, phase-1, world-model, design, autonomous]
permalink: gamevault/07-sessions/2026/2026-07-13-lantern-phase0-design-pass-b
---
# Session 2026-07-13 (Part B) — LANTERN Phase 0.3 review + autonomous design pass
> Continuation of [[2026-07-13_Lantern_Phase0_Adoption_Pivot]] (Part A = the pivot). Operator directed:
> *"continue with everything you can in the roadmap — commit as you go, don't stop; create a doc of operator
> questions as needed; only stop at a hard blocker with nothing else to work on"* then stepped away. This is
> an autonomous **design/documentation** run — no Unity code (all LANTERN code is greenfield netcode-touching →
> needs plan-approval + a focused editor + the ★review-first ritual; parked in [[Lantern_Operator_Questions]]).
## Goal
Advance the LANTERN roadmap as far as possible without a focused editor or operator input: run the Phase-0.3
world-model design review, then produce the "deeper technical pass" design/build-spec scaffolding.
## Done
**Phase 0.3 — world-model design review (the ★ gate):**
- Grounded the real code (3 read-only Explore passes: relevancy/region · run-room lifecycle · save/procgen) +
ctx7 on `GhostRelevancy`/`GhostImportance`. Locked two operator forks (co-located party; party light-union).
- Wrote the design proposal ([[Lantern_World_Model_Design_Proposal]]), then ran the **adversarial design-review
Workflow** (`wf_aa6fb661-e25`; 22 agents, **0 failures** — checked the failures list per the standing rule;
findings are real, not the masquerading-empty trap). **18 findings, 12 CONFIRMED + 6 PARTIAL, 0 refuted.**
- The review caught real design-breakers before any code: seed-model self-contradiction (DP-1/RS-1),
wrong persistence-lifecycle (DP-2), invariant-breaking respawn-to-base (NR-2/RS-3), phantom-kill VFX (NR-1),
undodgeable dark hits (NR-3), the ~23-site `RegionTag→PocketTag` semantic rewrite (RS-2).
- Synthesized → [[World_Model_Build_Spec]] (review-hardened contract, all 18 folded + findings ledger + build
order + open risks). Recorded [[DR-049_Lantern_World_Model_Design]]. **Design half of Phase 0.3 passed.**
**Deeper technical pass (design scaffolding):**
- [[Lantern_Phase1_Combat_Gym_Build_Spec]] — two frames, 4-socket manual-aim kit, 5 Sparks, on the salvaged
ability/boon pipeline (grounded in a combat/ability/boon Explore pass).
- [[Lantern_Art_Pipeline_Recipes]] — the material foundation (palette atlas + 3 master shaders) + statics/
skinned recipes + 3 rig families + CreatureKit (Workstream A0/A1/A2).
- [[Lantern_Currency_ReMean]] — Ore/Aether/Biomass/Charge → the 7 light currencies + byte ids.
- [[Lantern_Tone_Bible]] — Phase-7 register bounds per voice (before any bark generation).
- [[Lantern_Phase4_Mutations_Design]] — mutations = the DR-047 boon layer re-themed + Gloam/Tallow/culture.
- [[Lantern_Phase5_Death_Recovery_Design]] — the split, stranded suits, flame-share, the Tender, the Selkie.
- [[Lantern_Operator_Questions]] — running parking lot (code impl, extra reviews, A0 art, design forks).
- Roadmap index updated ([[Roadmap_Lantern_Slice]] Phase-0 status + doc links).
## Decisions
- [[DR-049_Lantern_World_Model_Design]] — the review-hardened world-model design accepted (Build Spec is the contract).
## Open / deferred (hard blockers for autonomous work — see [[Lantern_Operator_Questions]])
- **Code implementation** — all LANTERN code is greenfield netcode-touching; needs plan-approval + a focused
editor (unfocused throttles MCP + breaks Burst) + the per-slice ★review. NOT started autonomously.
- **A0 in-engine style-proof scene** — the one open Phase-0 gate; needs a focused editor + operator eyes.
- **Additional ★ design reviews** (Phase-1 light-relevancy, Phase 2 world code, etc.) — did not fire more heavy
Workflows unprompted beyond the one greenlit.
- New design forks surfaced by the review (dark-contact policy, lantern placement granularity, END-1/EB-1
mothball timing) + the Phase-1 forks — all parked with recommendations.
## Next
Operator on return: (1) answer the parked questions (one pass); (2) focus Unity + greenlight Phase-1
implementation from the build spec (or the world-model Phase-2 code from the Build Spec's build order); (3)
judge the A0 style-proof scene when the art track produces it. Everything is designed + reviewed so code can
move fast.
## Related
- [[World_Model_Build_Spec]] · [[DR-049_Lantern_World_Model_Design]] · [[Roadmap_Lantern_Slice]] ·
[[Lantern_Operator_Questions]] · [[2026-07-13_Lantern_Phase0_Adoption_Pivot]] (Part A)