neon-sprawl/docs/decomposition/modules/E7_M1_QuestStateMachine.md

E7.M1 — QuestStateMachine

Summary

Field	Value
Module ID	E7.M1
Epic	Epic 7 — Quest / Faction
Stage target	Prototype
Status	Planned (see dependency register)

Purpose

Data-driven quest lifecycle: start, step progression, branching, failure/reset, and completion with durable persistence. Integrates crafting and combat outcomes so guided content ties together gather–craft–combat loops without duplicate rewards.

Scope / party: Per-character state by default; optional party credit and turn-in rules via QuestDef and E8.M1.

Responsibilities

• Load and interpret QuestDef; track QuestStepState per character; synchronize party-credit advances per quest_scope_and_party.md.
• Apply QuestStateTransition rules for advance, abandon, fail, and complete.
• Invoke or subscribe to E3.M2 and E5.M1 (or their events) for step completion predicates.

Key contracts

Contract	Role
QuestDef	Steps, prerequisites, objectives, and branching metadata.
QuestStepState	Current step progress and internal flags.
QuestStateTransition	Valid transitions and side effects (before E7.M2 reward routing).

Module dependencies

• E3.M2 — RefinementAndRecipeExecution: craft completion, item hand-ins, refine steps.
• E5.M1 — CombatRulesEngine: defeat objectives, encounter-linked steps.

Dependents (by design)

• E7.M2 — RewardAndUnlockRouter: idempotent delivery after completion.
• E7.M3 — FactionReputationLedger: reputation-gated content (pre-production).
• E5.M3 — EncounterAndRewardTables: encounter completion and quest credit.
• E6.M4 — RewardParityEnforcer: quest/PvP reward alignment.

Related implementation slices

See Epic 7 Slice 1 — Quest core and persistence: 3–5 onboarding quests plus one chain across gather/craft/combat; telemetry quest_start, quest_step_complete, quest_complete, funnel times.

Risks and telemetry

• Scripting weight: keep QuestDef data-first; templates in decomposition/tooling path per epic.
• Double-claim: design for idempotency before E7.M2; lint bundles vs E6.M4 / E3.M5.

Source anchors

• Master plan: neon_sprawl_vision.plan.md — Core Epic Map, Epic 7.
• Module dependency register