worldbox-observer-mod/docs/story-planner.md

Story Planner

IdleSpectator commits to short multi-beat stories instead of channel-surfing ranked tips.

Feeds, sticky ensembles, presentability, and InterestDirector stay in place. StoryScheduler owns which durable character thread and episode purpose the next sequence belongs to. StoryPlanner retains short-arc aftermath/crisis lifecycle and visual completion.

Short-arc board (not the dossier rail)

Hard storylines (notable duel / mass / war / plot / love / grief) still form a small watching + parked board (cap 4) for short-chapter resume. Cutting away parks a hard arc; soft anonymous scraps still end. There is no rail Commit / hard pin anymore.

• Lore browse uses browsePause - freezes idle without StoryPlanner.Clear().
• StoryPlanner.Clear does not wipe the life-saga roster.
• Combat spine Kind comes from sticky/live ensemble scale + StoryArcKind, not tip Label prefixes.

Dossier life-saga rail is owned by LifeSagaRoster / LifeSagaRail (up to 10 MCs). Click toggles Prefer (soft favorite). AFK caption is Identity + Beat + Context via CaptionComposer (see life-saga.md). Cast/Legacy depth is rail hover only (LifeSagaViewController + LifeSagaPanel). Durable observations live in NarrativeEventStore/NarrativeStoryStore and are persisted by NarrativePersistence (independent of ChronicleEnabled). Hover temporarily pauses camera switching without disabling Idle Spectator. See life-saga.md.

Crisis camera hold: WarFront always blocks Mass/Battle cut-ins (war_theater_hold). Disaster / outbreak signals use the same class rule while their chapter is live (crisis_theater_hold), classified via live AssetManager.disasters + catalog categories (not tip-string IndexOf).

InterestDirector is a partial class: session orchestrator + StickyMaintain + SwitchPolicy.

Harness: story_lore_pause_keeps, story_board_park_resume (short-arc park/resume via story_resume_parked), story_crisis_war, story_crisis_disaster, war_front_sticky, plus saga_* scenarios.

See also: life-saga.md, scoring-model.md, event-reason.md.

Pipeline

Feeds → InterestRegistry → StoryScheduler (thread + episode grammar)
       → StoryPlanner (short-arc/crisis policy) → EpisodeShotSelector
       → InterestDirector → CameraDirector

Director still owns camera, sticky maintain, and switch margins. Planner never calls MoveCamera.

Episodes track Establish, Development, Pressure, TurningPoint, Payoff, Consequence, Reintroduction, and WorldContext roles. A shot must advance an uncovered role or be a permitted critical interrupt; character texture never counts as fake progress. Meaningful-cut exposure debt helps under-covered MCs without forcing weak footage, while repeated subject/action families cool.

Arc model

Kind	Climax	Hard hold
CombatDuel	sticky pair	only notable pairs (2+ notables)
CombatMass	Skirmish+	yes
WarFront / Plot / Love / Grief	existing sticky / life	yes

Phases: Climax → Aftermath → Epilogue → Done.

• Aftermath injects on climax cold (quiet grace / follow_lost), or claims natural death_* grief.
• Only grief / love-outcome pending tips block synthesis - cast hatch/food noise does not.
• Injected story beats bypass FixedDwell beat hard-skip and PreferOver cast life tips while the arc is live.
• Soft duel Mass↔Duel key flips still cold-hook once per theater anchor.
• Epilogue once after aftermath if a living lover/friend resolves.
• Soft anonymous duels still get aftermath tips; they do not use raised arcHoldMargin.
• Aftermath follow, cast recovery, and epilogue pick Prefer/MC among living theater/cast candidates via LifeSagaRoster.PreferRosterUnit (never MCs outside the cast).
• Parked-board trim drops anonymous scraps before Prefer/MC/cast arcs when over cap.

Dossier spine

While the current watch tip is the active arc's climax or story aftermath/epilogue beat, ContextLine shows a muted Kind · Phase (e.g. Duel · Aftermath, War front · Climax) via StoryPlanner.FormatSpineLabel → CaptionComposer (wins over stake hitch).

Hidden when idle is off, the dossier is hidden, or the camera has left the story for an unrelated tip (cast membership alone is not enough). A status banner owns only the Beat row; Identity and Context continue updating beneath it. Also hidden when the orange beat already leads with the same Kind at Climax (WatchCaption.FilterRedundantStorySpine filters against the presentable beat before clause enrichment).

Love climax is outcome-only (set_lover / fallen-in-love). find_lover seeking stays camera-worthy but does not open a Love arc. Leaving a climax without aftermath ends the arc (Done).

Sticky combat reframes (Battle ↔ Duel) sync climax Kind in place via SyncActiveClimax so the spine cannot say Mass · Climax on a Duel tip.

arcHoldMargin applies only while the watch tip is the aftermath/epilogue beat. Cast life tips (parenthood, sleep) no longer keep the raised cut-in wall.

Family life chapters (just_had_child, pregnancy, …) share arc:life:family, use a longer beat cool (including world-wide happiness cool), and bleed ledger heat so the village cast cannot monopolize the next picks.

Intimacy chapters (just_kissed / shares intimacy) use arc:life:intimacy with the same soft-life cool class (pair + world) so one couple cannot keep cutting between combat tips.

Settlement finds (just_found_house / finds a home) use arc:life:home with the same soft cool (world + subject) so house crumbs cannot keep cutting between combat beats.

Kill crumbs (milestone_kill / Killed X (species) / just_killed) use arc:life:kill with the same soft cool (subject + world) so hunter kill tips cannot keep cutting between mass beats.

Courtship crumbs (fallen_in_love / smitten / find_lover seeking) use arc:life:love soft cool (subject + world + pair). Bond outcomes (set_lover) stay hotter.

Life-intent decisions (sexual_reproduction_*, decision find_lover, …) share arc:decision:intent soft cool (subject + world). Outcomes (pregnancy, child, seeking) stay hotter.

Ordinary civ construction finishes (building:complete / tents / houses) share arc:construction soft cool. Spectacle wonders stay hotter.

Soft personal status FX (taking_roots, singing, moods, …) share arc:status:fx soft cool. Danger / combat statuses stay hotter. Hatch crumbs use arc:life:hatch.

Sleep / wake / dream cycle (sleeping, just_slept, had_*dream, had_nightmare, …) share arc:life:rest soft cool so rest crumbs cannot monopolize between richer beats.

WorldLog politics meta (king_dead, city_destroyed, favorite fell, …) share arc:worldlog:meta soft cool so sticky death crumbs cannot re-monopolize.

Interrupted resume: already-cooled moment beats are not parked / not resumed after a cut-in (hatch/reproduce cannot bounce back after combat).

Story spine: aftermath tips must match the active arc CorrelationKey (no stale duel aftermath under a Mass spine). Combat Kind word follows tip Label (Battle / Skirmish / Mass / Duel).

Wiped opposing combat camps collapse to a living-side pack label at live scale (never Mass - A (n) vs B (0)).

Combat aftermath names only a dead theater partner (stands over X), else stands over the fallen. Living lover/friend fallbacks are never the fallen.

Spine Kind follows the live tip Label for combat (Duel vs Mass/Skirmish/Battle), not sticky scale-hold alone. Cold climax tips do not show · Aftermath - only the aftermath tip does. Aftermath Follow loss promotes another living cast member before follow_lost.

Harness: story_spine / story_hold_margin / story_family_variety / story_intimacy_cool / story_settlement_cool / story_kill_cool / story_courtship_cool / story_decision_intent_cool / story_decision_intent_live / story_construction_cool / story_status_fx_cool / story_rest_cool / story_resume_cooled / story_worldlog_meta_cool / combat_wiped_side / reason_life_principal (story_arc_combat, story_spine_scoped, story_aftermath_combat, story_family_variety).

Crisis chapters (Phase 4)

Parallel overlay beside short StoryArc - war / disaster / outbreak thresholds open a multi-minute chapter without thrashing when unrelated tips cut in.

Signal	Enter when
WarFront	live participants ≥ crisisWarParticipantMin (default 8), both sides present (peak lock alone does not enter)
EarthquakeActive / Disaster category	live or EventStrength ≥ crisisDisasterStrengthMin (95)
StatusOutbreak	EventStrength ≥ disaster floor

While live:

• crisisOwnershipBoost + crisisHoldMargin on matching tips
• Character-fill ambient is suppressed (SuppressAmbientFill)
• Epic peers (≥ disaster floor) may still cut

On exit (signal linger / max duration / harness interest_crisis_end): inject epilogue_crisis ({a} surveys the aftermath of the crisis), then cooldown.

Disaster / outbreak chapters use a shared family anchor (disaster / outbreak), a longer linger after the last WorldLog pulse, and crisisDisasterCooldownSeconds (default 120) armed when the closer injects so stacked tornado tips cannot double-close.

War chapters stamp a kingdom theater pair. Local Mass/Battle on that pair keeps the chapter warm and cannot steal the War tip (war_theater_hold). Crisis closers clear short-arc spine and suppress combat task detail crumbs under the orange reason.

Short-arc related epilogue is skipped when a crisis closer owns the exit. When a short-arc war linger injects while a war crisis is live, the crisis quiet-closes (no second epilogue_crisis). Harness batch end and interest_story_purge_leftovers drop leftover crisis closers so free AFK does not inherit a fake ending. After hard story/crisis ends, softFillQuietSeconds suppresses soft-life crumbs, short interrupt FX (stunned / invincible), and character-fill ambient briefly. FamilyPack does not break that quiet window (see life-saga.md).

Selection discipline

• InterestVariety.Pick takes #1 when score gap ≥ story.nearTieEpsilon (default 8).
• Prefer / MC / MC-cast tips may still win when the gap is below story.sagaNearTieEpsilon (default 28).
• Near-ties among peers still Prefer > MC > cast, else roll among top-3.
• Causal heat + life-saga Prefer/MC/cast soft bias + cross-MC bonus add into RecalcTotal.
• See life-saga.md for camera / rival / dual-rail contracts.

Knobs

scoring-model.json → story block (loaded by InterestScoringConfig.Story).

Catalog policy ids live under event-catalog.json → story (aftermath_survivor, aftermath_mourner, aftermath_war_linger, epilogue_crisis, …).

Harness

Scenario	Proves
story_crisis_war	WarFront → crisis active → epilogue_crisis
story_crisis_disaster	EarthquakeActive → crisis → epilogue_crisis; cool blocks reopen
story_aftermath_combat	duel cold → aftermath tip
story_aftermath_partner_truth	aftermath never names living lover as fallen
story_aftermath_cast_noise	hatch noise pending still gets aftermath
story_aftermath_prefers_mc	aftermath follow prefers roster MC
story_recover_follow_mc	cast recovery prefers living MC
story_park_trim_keeps_mc	parked trim keeps Prefer/MC arcs over scraps
story_crisis_beats_mc_aftermath	war crisis cuts MC aftermath; hot peer cannot reclaim
story_pick_opens_stranger_arc	empty Prefer roster still opens Duel climax (non-goal)
reason_duel_principal	bystander Follow cannot own duel reason
reason_life_principal	Follow hijack cannot keep intimacy Label
story_intimacy_cool	just_kissed cools; peer wins next pick
story_settlement_cool	finds-a-home cools; peer wins next pick
story_kill_cool	kill crumbs cool; peer wins next pick
story_courtship_cool	smitten/seeking cool; peer wins next pick
story_decision_intent_cool	reproduce/find-lover decisions cool as a class
story_decision_intent_live	live EmitDecision path cools intent class
story_construction_cool	tent/house finishes cool; peer wins
story_status_fx_cool	taking_roots FX cool; peer wins
story_rest_cool	sleep/wake rest cycle cools; peer wins
story_resume_cooled	cooled soft tip does not resume after cut-in
story_worldlog_meta_cool	king_dead cools; peer wins next pick
combat_wiped_side	wiped camp never prints vs (0)
story_aftermath_war	war sticky cold → aftermath; no dual crisis closer
story_crisis_hygiene	auto-opened war crisis + short-arc linger; purge leaves no epilogue leak
story_near_tie	large gap always picks #1
story_arc_combat	climax → aftermath ownership
story_arc_preempt_resume	epic cut then fresh scrap aftermath
story_ledger_revisit	featured unit wins near-tie

./scripts/harness-run.sh --repeat 3 story_crisis_war
./scripts/harness-run.sh --repeat 3 story_crisis_disaster
./scripts/harness-run.sh --repeat 3 story_aftermath_war
./scripts/harness-run.sh --repeat 3 war_front_sticky
./scripts/harness-run.sh --repeat 3 story_aftermath_combat
./scripts/harness-run.sh --repeat 3 story_aftermath_partner_truth
./scripts/harness-run.sh --repeat 3 story_aftermath_cast_noise
./scripts/harness-run.sh --repeat 3 story_crisis_beats_mc_aftermath
./scripts/harness-run.sh --repeat 3 story_pick_opens_stranger_arc
./scripts/harness-run.sh --repeat 3 reason_duel_principal
./scripts/harness-run.sh --repeat 3 story_near_tie
./scripts/harness-run.sh --repeat 3 story_arc_combat
./scripts/harness-run.sh --repeat 3 story_ledger_revisit
./scripts/harness-run.sh --repeat 3 story_kill_cool
./scripts/harness-run.sh --repeat 3 story_courtship_cool
./scripts/harness-run.sh --repeat 3 story_decision_intent_cool
./scripts/harness-run.sh --repeat 3 story_decision_intent_live
./scripts/harness-run.sh --repeat 3 story_construction_cool
./scripts/harness-run.sh --repeat 3 story_status_fx_cool
./scripts/harness-run.sh --repeat 3 story_rest_cool
./scripts/harness-run.sh --repeat 3 story_resume_cooled
./scripts/harness-run.sh --repeat 3 story_worldlog_meta_cool
./scripts/harness-run.sh --repeat 3 combat_wiped_side

Files

• IdleSpectator/Narrative/StoryScheduler.cs - narrative episode and camera-story ownership
• IdleSpectator/Story/StoryPlanner.cs - visual completion, cold-hook, spine, and crisis lifecycle
• IdleSpectator/Story/LifeSagaRoster.cs - durable MC cast + Prefer + emerging-story admission
• IdleSpectator/Story/SagaProse.cs - player-facing relation/stake/title English
• IdleSpectator/Story/CaptionComposer.cs - Identity + Beat + Context
• IdleSpectator/Story/LifeSagaOverview.cs / LifeSagaRail.cs - rail Prefer + hover
• IdleSpectator/Story/CrisisChapter.cs - parallel crisis chapter state
• IdleSpectator/Story/StoryReason.cs - presentable aftermath Labels
• IdleSpectator/WatchCaption.cs - character beat caption + ContextLine