Project-M/Docs/Vault/06_Roadmap/Lantern_Phase4_Mutations_Design.md

title, date, tags, status, permalink

title	date	tags	status	permalink
LANTERN — Phase 4 Mutations & Homecoming Economy (design pass, pre-review)	2026-07-13	roadmap lantern mutations sparks phase-4 design	design-pre-review	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)
2–3 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 8–10

The current default catalog is 12 boon entries (8 mechanic-changers + 4 stat). Re-theme + extend into 8–10 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 (8–10) + each Spark's 2–3 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