Skip to main content
Darkness Falls

Act I (Survive) + Class Signatures Design Pass

Act I (Survive) + Class Signatures Design Pass

Status: VISION LOCKED 2026-07-26 for Act I + signature tables (D1–D5 locked to recommended defaults); Phase A not yet code-authoritative until local_proved

Last updated: October 28, 2026

Darkness Falls — Act I (Survive) + Class Signatures Design Pass

Status: VISION LOCKED 2026-07-26 for Act I + signature tables (D1–D5 locked to recommended defaults); Phase A not yet code-authoritative until local_proved
Parent vision: north-star.md Phase 1
Proof system: design-proof-contract.md
Companion: class-identity.md (problem + lever toolbox; this doc is the implementation contract for Act I)

Goal of this pass: lock a journey players can feel by level 10 without rewriting the explore → fight → loot → hideout loop people already enjoy, and without shipping anything we cannot hermetically validate on target:'local'.

1. Non-negotiable preservation contract

These are already enjoyed or hard-won. Act I / signature work must not remove or re-key them.

Keep Why players care Regression guard
After-action combat + auto-attack on contact Core DF feel — fight by walking Existing combat scenario suite + “move into enemy auto-attacks”
Optional auto-loot (default OFF for new players) Learning then convenience auto-loot.md scenarios
STARTER_ZONE weapon gate to leave Clear first goal Scenario: leave without weapon fails; with weapon succeeds
Early XP bonuses L1–15 Fast into action progression.md / level-up scenarios
L10 gold milestone (1,000 gold) Retention pulse Existing milestone scenario
objective + real main menu Orientation on demand Scenarios from
Tip sparsity after ~L10 / city-only portal tips Not hand-holding veterans design-decisions-rejected.md tip policy
Hideout as always-safe home Recovery + shops + Star Map Teleport hideout scenarios
Existing zone graph (Starter → L1 wild → Trevmarch chain) Content already built No zone deletes/reparents in Phase A–B

Additive rule: new systems attach beside the loop. A player who never uses a class signature must still complete Act I with the same auto-attack path they use today. Signatures make play better and more distinct, not mandatory for survival of the starter path.

1b. Capability Contracts (HAVE vs SHOULD + proof)

Canonical pattern: design-proof-contract.md. Nothing in this doc is "shipped for players" until its claim is at least local_proved and, after deploy, prod_proved. Documentation alone is never proof.

Status key: gap → spec → building → local_proved → prod_proved → stable | drift | wont_fix

Scenario descriptions MUST start with claim:{claim_id} | when authored.

claim_id title have_now should_have status proof_local proof_prod preserves
df.act1.pres.auto-attack Auto-attack on contact Live — move into enemy runs combat round Unchanged when player never uses a signature local_proved scenario:845,2126 (claim-tagged 2026-07-25) metric:combat_metrics; error_absent NO_OPTIONS spike Y
df.act1.pres.starter-weapon-gate Starter weapon / early move gate Live — class confirm auto-equips weapon (1386); east blocked until starter loot in pickup path (772) Player can clear first squares with a weapon local_proved scenario:772,1386 error_absent starter dead-end Y
df.act1.pres.early-xp L1–15 flat XP bonuses Live — earlyGameFlatXpBonus L1-5=+50, L6-10=+30, L11-15=+15 Unchanged local_proved junit:DarknessFallsEarlyGameXpBonusTest (scenario 2936 skipped COVERED_BY_JUNIT — combat path non-hermetic) milestone:LEVEL_UP Y
df.act1.pres.l10-gold Level 10 gold milestone 1000 Live Unchanged local_proved scenario:2279 milestone:df_level_milestone Y
df.act1.pres.objective-menu objective + main menu Live Unchanged orientation surfaces local_proved scenario:2062,2063 metric:OBJECTIVE/MAIN_MENU call health Y
df.act1.pres.tip-sparsity No tip spam past ~L10 Policy live; starter + L12 wild proved Unchanged tip policy local_proved scenario:1775,2937 none-yet Y
df.act1.onboarding.first-fight First-session path to a fight Live nudge east/south Keep first-fight discoverability local_proved scenario:2508 none-yet Y
df.act1.obj.stages Staged objective copy (3 stages) Live — level proxies L1-5/L6-8/L9+ 3 short stages by Act I progress local_proved scenario:2938,2939,2941 + junit:DarknessFallsAct1ClarityUtilitiesTest metric:OBJECTIVE calls still succeed N
df.act1.return.briefing Return briefing law 1 Live on launch for named returners + whereAmI Location + objective + one next step on return local_proved scenario:2940 (R1); orientation 2299–2302 none-yet N
df.act1.sig.teach Signature teach tip ≤2 lifetime Live — playstyle tip ≤2 (hold ground / move / auto swing) Automatic identity tip; no cast chip local_proved scenario:2949 none-yet N
df.act1.sig.fighter Fighter Guard Live — auto stationary Guard every 4 hold rounds Hold ground to brace next hit; no cast local_proved scenario:2946,2951 + junit playstyle error_absent post-ship N
df.act1.sig.rogue Rogue Strike Live — auto every 3 attacks Rotation Strike + mobile momentum local_proved scenario:2948 + junit playstyle error_absent post-ship N
df.act1.sig.sorcerer Sorcerer Blast Live — auto every 4 attacks Rotation Blast; no cast local_proved scenario:2947 + junit playstyle error_absent post-ship N
df.act1.sig.cleric Cleric Mend Live — auto stationary Mend every 3 hold rounds Hold ground while hurt to heal; no cast local_proved scenario:2950,2779 + junit playstyle error_absent post-ship N
df.act1.sig.ignore-path Never-use-signature still clears Act I fight Live auto-attack path Explicitly still true after signatures ship local_proved scenario:845 (walk-and-clear without special verbs) metric:combat completes Y
df.act1.npc.watch-seed Recurring Watch NPC memory line Live — Watch-Sergeant first-meet + return on Rourke talk / seed One NPC remembers return (B5) local_proved scenario:2960,2962 + junit Act1Clarity none-yet N
df.act1.threat.teaser Named threat teaser B6 Live — Thinning Shadow in objective L9+ and one-time teaser after Watch L8+; the main menu and objective record the teaser as heard without speaking it, because their objective line already names the threat Objective/rumor names threat + leave-starter reason local_proved scenario:2963,2964 + junit Act1Clarity none-yet N
df.act1.close.coda L10 Act I coda once Live — L10 gold + one-time Act I coda Gold + one-time coda; no spam for veterans local_proved scenario:2961 (+2279 gold) + junit Act1Clarity milestone:L10 N
df.act1.sig.twins Twin class signatures Live — auto Rage/Mark/Drain/Smite Barb/Ranger/Necro/Paladin distinct auto signatures local_proved scenario:2952,2953,2954,2955 + junit playstyle error_absent post-ship N

Phase exit gates (claim status)

Phase Required claim statuses before calling the phase done
A Clarity df.act1.obj.stages, df.act1.return.briefing ≥ local_proved; all preserves=Y still local_proved/stable (not drift); early-xp + tip-sparsity written or still openly spec
B Pilot signatures Four df.act1.sig.{fighter,rogue,sorcerer,cleric} + df.act1.sig.teach + df.act1.sig.ignore-path ≥ local_proved; then after deploy ≥ prod_proved
C Twins df.act1.sig.twins ≥ local_proved (and per-twin rows split when implemented)
D Narrative glue df.act1.npc.watch-seed, df.act1.threat.teaser, df.act1.close.coda ≥ local_proved
Act I product complete All rows above except explicit wont_fix ≥ prod_proved; preserves not in drift

Preserve-claim audit log (2026-07-25)

Ran against prod game_test.scenario_tests (DARKNESS_FALLS, is_active=1, skip_test=0). Scenario descriptions claim-tagged in DB.

claim_id Bound scenario ids Outcome
df.act1.pres.auto-attack 845, 2126 Bound + claim-tagged; false-stable → local_proved
df.act1.pres.starter-weapon-gate 772, 1386 Bound; HAVE note (auto-equip vs pick-up) → local_proved
df.act1.pres.early-xp junit:DarknessFallsEarlyGameXpBonusTest (2936 COVERED_BY_JUNIT) local_proved 2026-07-26 — pure formula; combat scenario non-hermetic
df.act1.pres.l10-gold 2279 Bound + claim-tagged → local_proved
df.act1.pres.objective-menu 2062, 2063 Bound + claim-tagged → local_proved
df.act1.pres.tip-sparsity 1775, 2937 Starter + L12 TREVMARCH_OUTSKIRTS no Navigation tip → local_proved
df.act1.sig.ignore-path 845 Bound (shared with auto-attack walk-clear) → local_proved
df.act1.onboarding.first-fight 2508 Bound + claim-tagged → local_proved

Phase 0 preserve proofs closed 2026-07-26. Phase A local_proved 2026-07-26 (obj.stages 2938/2939/2941, return.briefing 2940). Phase B+C local_proved 2026-07-27 (pilot 2946-2951 + twins 2952-2955). Next: USER /code-checkin + /deploy for prod_proved; then Wave 1 Phase D narrative (Watch / threat / coda) per design-code-alignment.md.

2. Act I “Survive” (levels 1–10) — locked spine

Player belief (from north-star)

“I can stay alive here.”

Required outcomes by level 10

  1. Movement, combat, loot, and hideout are understood in play (not only in help text).
  2. One unmistakable class mechanic has been taught and used (see §3).
  3. There is a named threat and a reason to leave the starter region (teaser is enough; full antagonist chain is Act II content).
  4. Return sessions restate location + objective + one next step (north-star law 1).

Beats using **existing** geography (no new regions)

Map to live content from world.md L1–L10 band and city/onboarding flags.

Beat Levels Place (reuse) Player does Experience check
B0 Create 1 Character create Name + class; hears one-line class fantasy Class select copy differs per class
B1 Wake 1 STARTER_ZONE Orient, find/equip weapon, learn scan/move Cannot leave without weapon; intro once per character
B2 First wild 1–3 First portal to L1 band (Forest Path / Farmstead Ruins / equivalent live exit) First fight via move-into-enemy; pick up loot Auto-attack works; death is recoverable via hideout
B3 Signature teach 3–5 Any early combat First successful use of class signature verb Distinct text/state vs “just attack”; optional chip offered in combat
B4 Home 3–7 Hideout Teleport hideout; see facilities; optional Star Map point Briefing: where you are + what to do next
B5 Belonging seed 6–9 Trevmarch Market / City (existing hub) Meet one recurring NPC voice (the Watch / town authority — final names open) NPC recognizes return if met before (even one line of memory)
B6 Threat teaser 8–10 Edge of starter band or Trevmarch rumor Hear the named threat and a push into Act II region Objective text upgrades from generic survival to “the Watch needs help with X”
B7 Act I close 10 Anywhere Level-10 gold milestone + Act I completion line Milestone gold still 1,000; one-time Act I coda spoken once

What we deliberately do **not** put in Act I

  • Promotion / Paragon systems (40 / 50).
  • Rifts, Sieges, Mastery.
  • Full quest graph or multi-region campaign map (Act II).
  • New primary stats (no Wisdom rewrite in Act I).
  • Mandatory multiplayer or party play.
  • ISP pressure after death.

Objective copy evolution (voice budget)

Keep a single short objective that can upgrade at most twice in Act I (law 7 — voice time):

Stage Objective shape (example — final copy TBD)
Fresh “Survive the wilds: equip a weapon, fight, loot, and grow strong enough to leave the starter lands.”
After B5 “The Watch in Trevmarch knows your name. Push the surrounding threats so the roads stay open.”
After B6 “A darker force is thinning the Watch. Follow the trail beyond the starter lands.”

DARKNESS_FALLS_OBJECTIVE and main menu share the same constant source so answers never diverge ( pattern).

3. Class signatures — additive, voice-first, testable

Hard rule — automatic power, playstyle variance (owner 2026-07-27)

Default combat power is automatic. Skill gems, Star Map, and class signatures fire on rotation (howOftenSwings) or on playstyle streaks (stationary vs mobile). Players customize builds off-combat (gear, paths, class); in combat they move and hold ground.

Layer Trigger
Attack rotation specials Every N attacks (e.g. Strike 3, Blast 4)
Stationary Guard Every 4 consecutive combat rounds without moving
Stationary Mend Every 3 consecutive combat rounds without moving while hurt
Mobile momentum +15% damage when the player moved this combat turn

The class resource — what mana, stamina and energy buy

A signature always fires on its trigger. When the class resource covers its cost, it spends the cost and lands harder; when it does not, it fires at its base effect, so an empty bar never makes a player weaker than the signature alone. The spend is spoken with the new readout ("Your Blast draws 43 mana and hits harder. Mana: 132 of 175."), and the abilities readout says what the resource is for. The resource comes back each combat turn outside the hideout and is full in it, and a stats refresh (an equip, a craft) keeps what was spent. The cost, the boost and the regeneration are the constants on ; where this section and that class differ, the class is right.

Signature Empowered effect
Rotation signatures (Strike, Blast, Rage, Mark, Drain, Smite) Half again as much damage
Mend Half again as much healing
Guard Turns away a further share of the blow

Proof: scenario-df-sorcerer-blast-spends-mana, scenario-df-rogue-strike-spends-energy; JUnit , .

At most 0 cast verbs for class identity in Act I pilot. Leftover cast … NLU soft-redirects. Future gear may still use rare manual utilities only if design reopens the cast layer deliberately.

Design constraints

Constraint Rule
Primary loop intact Auto-attack remains the default win path in Act I.
One signature verb One player-facing name per class (chip + NLU synonyms).
Felt by L5, reliable by L10 North-star identity law.
Distinct decision Using it vs not using it changes something the player can hear or measure.
Fail soft Wrong timing / empty resource → short refusal + still in combat with options; never dead-end.
No menu tree Signature is a combat/field option, not a nested build UI.
Hermetic Every signature has a scenario_test that forces the state and asserts the effect.

Signature table (target fantasies)

Thin v1 effects — enough to feel different, not a full ability tree.

Class Fantasy Signature verb v1 effect (Act I) Resource / limit Distinct check
Fighter Reliable frontline Guard Next hit taken reduced (or block once); short spoken “you brace” Cooldown 3 fights or short stamina Damage taken lower on next hit vs unguarded baseline
Barbarian Reckless berserker Rage +damage for N rounds; slight self-risk or no heal while raging Cooldown; ends on combat end Damage dealt higher while raging
Rogue Precision assassin Strike (opener) Bonus damage if first action of fight or from stealth-flag Once per fight Opening burst > follow-up auto-attack
Ranger Hunter Mark Target takes +damage from you for the fight One mark at a time Marked target text + higher damage
Sorcerer Elemental artillery Blast Spend mana for a heavier hit (single target) Mana cost Blast costs mana; bigger damage spike
Necromancer Attrition Drain Damage + small self heal Mana / cooldown HP up when drain lands
Cleric Support healer Mend Self (or later ally) heal Mana cost HP up without potion
Paladin Holy bruiser Smite Melee hit + small self sustain Cooldown Damage + heal hybrid in one verb

Caster split without a new stat (Act I): Cleric Mend is heal-primary; Sorcerer Blast is damage-primary. Same INT sheet for now; different verbs and outcomes. Wisdom/Faith stays deferred per class-identity.md Option B.

Archetype de-collapse: Barbarian Rage vs Fighter Guard; Ranger Mark vs Rogue Strike; Necromancer Drain vs Sorcerer Blast; Paladin Smite vs Cleric Mend. Twins must not share the same verb.

Teach path (so identity is not hidden)

  1. Class select: one-clause fantasy already partially shipped — extend to name the signature verb (“Cleric — heal and support with Mend”).
  2. First combat (B2–B3): if signature never used, offer the chip once with a short tip (max SIGNATURE_HINT_MAX_SHOWS = 2 lifetime, mirror distance-hint pattern).
  3. Status / help combat: one line “Your class can say {verb}.”
  4. Never block auto-attack if they ignore the tip.
  5. A tutorial for each class: class help speaks the player's own class's tutorial (what the class is, the stat it grows with, its signature and how it fires, how to play it), and help followed by a class name speaks that class's. DarknessFallsClassTutorial is the text; the abilities readout keeps the signature's numbers, read from the character.

What we are *not* doing in signature v1

  • Full skill trees or promotion skills pulled to L1.
  • Reworking Star Map paths (Phase later; clarity copy only).
  • Account-wide class mastery meta (multi-character carrot) — design later; not Act I blocker.
  • Party-only signatures (Cleric heal-other can wait until shared combat is real).

4. Ship phases (safe order)

Phase Scope Risk Exit proof
A — Clarity Class-select + objective stage strings; return briefing skeleton; no new combat math Low Copy scenarios; no combat suite reds
B — Signature pilot 4 base classes only: Fighter, Rogue, Sorcerer, Cleric (one of each pair) Medium 4 signature scenario_tests green 2× local; DF suite green
C — Twin signatures Barbarian, Ranger, Necromancer, Paladin Medium 4 more scenarios; paired twin vs original produce different useful choices
D — Act I narrative glue B5 NPC memory line + B6 threat teaser + objective upgrade + Act I coda at L10 Medium-low (content) Path scenario STARTER→threat teaser; objective text stages
E — Full Act I polish Hint caps, voice length audit, optional second NPC line Low Play_sequence first-hour transcript review

Do not start D content that depends on unfinished B mechanics. Narrative can be written in parallel, but ship order stays A → B → C → D.

Pilot choice rationale: four bases prove the system (option, resource, teach, test harness) before investing in twin fantasy. If pilot feels bad in play, twins do not multiply the mistake.

5. Local validation contract (mandatory for every ship item)

5.1 Principles

  1. Hermetic first — setup_json alone seeds class, level, zone, HP, cooldowns; no relic state (hermetic-scenario-tests).
  2. Prove twice from clean — green twice on local before release.
  3. Play path + unit path — scenario_tests for player-facing; JUnit only for pure formula helpers.
  4. Regression shield — any DF handler change runs DARKNESS_FALLS scenario suite local before handoff (scenario-regression-discipline).
  5. Experience, not only correctness — for Act I, also capture a play_sequence transcript and check: no dead-ends, no option floods, signature optional, auto-attack still works.

5.2 Scenario matrix (minimum)

ID Purpose Setup sketch Assert (structural preferred)
A1 Leave starter without weapon blocked STARTER, no weapon contains block reason; options remain
A2 Leave starter with weapon STARTER, weapon equipped zone change / enter succeeds
A3 Auto-attack still works without signature wild zone, enemy contact, never use verb combat resolves; enemy HP down
S-{CLASS} Signature fires setClass, combat seeded, fire verb effect-specific: HP delta / damage flag / cooldown set
S-{CLASS}-softfail Empty resource / cooldown fire verb twice short refusal; options ≥1; still in fight
P-pair Same encounter, two classes two scenarios or dual setup different useful option_key or effect
O1–O3 Objective stages flags for beat progress objective text matches stage
R1 Return briefing mid-Act I relaunch location + next step present
REG Full DF suite — no new reds from this change

Canonical authoring: MCP add_scenario_test only.

5.3 Local play recipes (agent / human)

# Fresh Act I smoke (any class)
play_sequence game:darkness_falls target:local
  setup: bypassCharacterCreation, setClass:{C}, setLevel:1, setZone:STARTER_ZONE
  inputs: [look, scan, inventory, objective, menu, … equip path …, enter / portal …]

# Signature smoke
  setup: setClass:{C}, setLevel:5, setZone:{combat zone}, setHealth, enemies as needed
  inputs: [status, {signature verb}, attack, {signature verb again for cooldown}]

Experience checklist on the transcript:

  • Never zero options after a signature or blocked move
  • Signature tip ≤ 2 lifetime shows
  • Spoken response not a novel when auto-attacking
  • Player who only says directions + attack still progresses

5.4 What “experience is correct” means for this pass

Dimension Pass Fail
Clarity Player can name class verb and current objective “What do I do?” after first session
Agency Signature is a real choice in at least one fight Verb is flavor text with no state change
Compatibility Ignore-signature path still fun Forced mini-game or soft-lock
Distinctness Twin classes feel different in a paired fight Barbarian ≈ Fighter in decisions
Voice Short combat lines; detail on status/look Every hit narrates a paragraph

6. Compatibility with “what people already enjoy”

Enjoyed behavior How we protect it
“I just walk and fight” Signature optional; auto-attack unchanged
Fast early levels Keep XP bonuses; no Act I grind gates
Hideout as hub Briefing enhances hideout; does not replace facilities
Discovery / sparse tips No new spam tips past L10; signature teach capped
Build power fantasy later Signatures are seed identity; Promotion/Paragon still the deep build layer
Existing characters Signatures unlock by class at current level; no wipe; cooldowns default ready

Migration: live characters receive the signature for their class at next load. No respec forced. No retroactive Act I coda spam for L10+ — coda is first-time flag only for characters crossing L10 after ship, or a one-time “the roads darken…” rumor for L10+ who never heard the threat (opt-in via objective, not forced dump).

# Decision Locked answer Blocks
D1 Pilot 4 bases first vs all 8 thin at once Pilot 4 (Fighter, Rogue, Sorcerer, Cleric) Phase B
D2 Signature power level: strong identity vs mild bonus Mild but audible — must change a number player can feel, not trivial Phase B balance
D3 Named Watch NPC + threat codenames Watch-Sergeant + the Thinning Shadow until campaign cast pass Phase D
D4 Objective upgrades: 2 stages vs 3 3 stages as in §2 (still short) Phase A/D
D5 Cleric Mend: self-only in Act I vs party Self-only until shared combat is real Phase B Cleric

Locked by session default per handoff recommendations (owner may reverse before Phase B combat). North-star P0 class-signatures open decision should point here as resolved.

8. Implementation sketch (for later agents — not a commit plan)

  1. Content/constants: signature verb enum + per-class copy; objective stage resolver.
  2. Combat hook: after-action-safe signature command in existing combat generator path.
  3. NLU: one-shot + option chips; Tier 2 when chip visible; never Tier 1 global steal.
  4. Teach: lifetime hint counter on character (mirror distanceHintsShown).
  5. Scenarios: matrix §5.2 before claiming done.
  6. No new regions in this pass.

Code paths will be found via IntelliJ (DarknessFallsCombat*, , ) at implement time — this doc stays design-authoritative.

9. Success for the *design pass* (this document)

  • Act I beats mapped to existing zones without new region dependency
  • Preservation contract listed with regression intent
  • All 8 signatures named with soft-fail and test hooks
  • Pilot vs full-rollout order defined
  • Capability Contracts table (HAVE/SHOULD/proof/status) bound to design-proof-contract.md
  • Preserve claims bound to real scenario ids (audit 2026-07-25)
  • Owner locks D1–D5
  • Phase A claims at least local_proved
  • Local validation matrix defined
  • Phase A clarity ships with scenarios (deploy pending USER /deploy)
  • Phase B pilot green on local suite (2026-07-27: 2946-2951, 2779, 845)
  • Phase C twins green on local suite (2026-07-27: 2952-2955)
  • Phase D narrative (Watch / threat / coda) local_proved (2026-07-27: 2960-2964)

Refs