Release Healer Man 0.1.21

ENCOUNTER_AUTHORING.md

@@ -0,0 +1,110 @@
+# Encounter authoring and fidelity
+
+Healer Man keeps boss abilities, dungeon orchestration, presentation, and source
+evidence separate. Boss abilities are modular `EnemyAttackDefinition` records;
+dungeon-wide doors, waves, checkpoints, and transitions are modular
+`DungeonEncounterDefinition` records. Neither runtime stores Three.js or React
+objects, so the same definitions can later be selected or randomized without
+rewriting a boss component.
+
+## Adding or editing a boss mechanic
+
+1. Add or edit the attack in the boss entity's `combat.attacks` list. Imported
+   RuneWaker lists are generated under `src/game/generated`; authored WoW
+   exceptions live with their dungeon content.
+2. Give the mechanic a stable `id`, timing, condition, target, effect, and source
+   record. Health mechanics use `self-health-percent`; timed mechanics use
+   `initialCooldownMs` and `repeatCooldownMs`.
+3. Author a `telegraph` when the source supplies geometry. Harmful area attacks
+   without explicit geometry receive a conservative circle/cone/line inference,
+   but inferred geometry is not described as source-exact.
+4. Add a guide override only when the generated explanation needs encounter
+   context that cannot be derived from the mechanic. The Boss Guide otherwise
+   reads the runtime definition directly, including its trigger, timer, effect,
+   telegraph, counterplay, fidelity, and test procedure.
+5. Run the focused mechanic, telegraph-geometry, campaign, timeline, and guide
+   tests, then perform the browser playtest described in `PLAYTEST_NOTES.md`.
+
+Telegraph geometry is shared by presentation and hit resolution. A circle,
+frontal cone, or line shown on the floor is therefore the area the resolver
+tests when the cast completes. `warningMs` is also enforced as a minimum cast
+time, so a telegraph cannot appear after its damage resolves.
+
+## Adding a dungeon encounter rule
+
+Attach a `DungeonEncounterDefinition` to `DungeonDefinition.encounters`. Rules
+combine a trigger, optional guards, and reusable actions. Available primitives
+cover tick/elapsed time, signals, interactions, entity engagement/death/health,
+all-members-dead checks, phases, flags, counters, timers, spawn groups, dynamic
+world-object state, objective completion, checkpoints, party teleports, loot,
+and signal chaining.
+
+Definitions and snapshots are JSON-safe and stable-ID based. Actions are
+idempotent by default. Loot actions must use `persistence: "run"`; this prevents
+a wipe or checkpoint reload from duplicating a reward. Declare encounter-owned
+mob waves in `DungeonDefinition.encounterSpawnGroups`. Declare doors, switches,
+chests, keys, bridges, NPC prompts, and quest objects in
+`DungeonDefinition.serverGameObjects`; their collision, sight blocking, visual,
+prompt, and allowed interaction states follow the current encounter snapshot.
+
+Online groups use party-leader authority. A follower interaction is sent as a
+request, then revalidated by the leader against the follower's synchronized
+position, range, line of sight, object state, and object ID before any rule is
+dispatched. The leader publishes serializable encounter snapshots to followers.
+
+## Save behavior
+
+Character profiles store a versioned safe dungeon checkpoint. The checkpoint
+projection retains only actions marked `checkpoint` or `run`; active timers,
+temporary waves, and a half-finished pull are reset. Entering the same dungeon
+hydrates that safe projection and its spawn after definitions are registered.
+Loading a different dungeon starts at its normal entrance.
+
+## Source fidelity and remaining review
+
+The deterministic ledgers are:
+
+- `scripts/runewaker-pipeline/RUNEWAKER_ENCOUNTER_IMPLEMENTATION_REPORT.md`
+- `scripts/runewaker-pipeline/RUNEWAKER_GAMEPLAY_CONTENT_REPORT.md`
+- `scripts/runewaker-pipeline/RUNEWAKER_ENVIRONMENT_ASSEMBLY_REPORT.md`
+- `scripts/runewaker-pipeline/RUNEWAKER_NAVIGATION_GAP_REPORT.md`
+
+Current encounter evidence covers 30 RuneWaker packages, 4,113 deferred source
+rows, and 1,524 unique direct evidence records. Of those evidence records, 388
+have exact executable spell mappings and 1,136 still need source review. Four
+bosses have clearly labeled, playable Healer Man fallback kits because the
+preserved data does not expose their original executable behavior. Eight
+non-empty packages do not contain source-confirmed boss membership; two
+authoritative variants are intentionally empty.
+
+The upgraded WDB environment builder can assemble all referenced ROS resources
+with full placement translation, quaternion, and nonuniform scale, source-hash
+caching, shared meshes, collision chunking, and a separate dynamic-placement
+manifest. The integration pass regenerated Raksha Temple and The Origin through
+that full-WDB path; remaining shipping packages retain their last validated
+build until they are individually regenerated. The current audit finds 107
+filename-only dynamic candidates; they remain static and review-required
+because filenames alone do not prove door/switch behavior.
+
+Treasure Trove's 908-placement full-WDB staging export is reproducible and its
+487,380-triangle visual/collision assembly, meshopt pass, and KTX2 compression
+all succeed. Its 0.3-metre, 512-cell full-resolution Recast navigation bake did
+not complete: the watershed run was stopped after nearly two CPU-hours when it
+showed the smaller-tile retry signature, and the explicit monotone run was
+stopped after more than four CPU-hours on its first pass. The fail-closed
+pipeline therefore did not publish that staged package. The last validated
+shipping package remains active. The recipe retains the monotone tiled policy
+for a future offline bake or a reviewed spatial-partitioning optimization;
+lowering navigation resolution was not silently substituted.
+
+The route report contains 19 unreachable legs across eight dungeons, all from a
+distance-from-entrance objective-order heuristic. Those legs are evidence that
+objective order needs review, not proof that an off-mesh link should exist.
+Links are added only when source geometry or a reviewed traversal justifies
+them.
+
+Run `npm run runewaker:audit:gameplay`, `npm run
+runewaker:audit:environment-assembly`, and `npm run runewaker:audit:navigation`
+after importing new source data. A report can be structurally green while its
+content status remains `review-required`; this is intentional and prevents an
+incomplete source inference from being presented as an original mechanic.