healer-man/README.md

# Healer Man

A standalone React Three Fiber dungeon game using the exact Wailing Caverns
layout extracted from the local 3.3.5a client. The runtime includes the textured
WMO, all 3,381 active default-set doodad placements, reconstructed WMO water,
separate collision, authoritative entrance/encounter anchors, and a responsive
exploration HUD modeled after the architecture of `i-want-to-heal-mmo`.

## Run

```powershell
npm install
npm run dev
```

For online-account testing, run `npm start` in a second terminal so Vite can
proxy `/api` to the local Node/SQLite server on port `4173`. Then open the local
URL printed by Vite. Offline roster play does not require the second process.

The game starts at the Healer Man account gate. Online accounts authenticate
through the combined Node server and synchronize character rosters to its
persistent SQLite database. A separate device-local offline roster remains
available when the server cannot be reached. Server passwords are stored as
salted scrypt verifiers rather than plaintext.

For a production-style local run after building:

```powershell
npm run db:init
npm start
```

The TrueNAS checkout, persistent-data mount, reverse-proxy cutover, update,
backup, and Gitea APK release procedures are documented in
[`DEPLOYMENT.md`](DEPLOYMENT.md).

Verification:

```powershell
npm run test:ready-five
npm run build
```

Boss and party balance simulations, including exact, random, and automatic
multi-party sweeps with complete per-boss/member/ability reports, are documented in
[`docs/BALANCE_LAB.md`](docs/BALANCE_LAB.md). Start the guided tool with
`npm run balance:lab`, or use the server-powered **Balance Lab** beneath GM
Tools. The GM screen keeps previous runs across server restarts and provides
filterable in-app boss, class/spec, party, pressure, damage, and kill-time
graphs/tables. The Abilities tab retains every learned/available ability,
including zero-use rows, so missing rotations can be compared with casts, hits,
damage share, healing, and absorbs.

Automatic balance certification is Ready-only: Protection Warrior, Discipline
Priest, Marksmanship Hunter, Fire Mage, and Assassination Rogue. Every other
WoW spec plus every CoA and RoM entry is Needs Testing and excluded from broad
bracket, regression, and NPC seat-audit runs.

Authenticated GMs can open **Ability & Talent Tuning** from the main-menu GM
Menu. The local sandbox supplies searchable ability and talent catalogs plus
per-device runtime overrides for cooldowns, cast times, costs, damage, healing,
durations, area reach, and supported passive talent modifiers. See
[`docs/BALANCE_TUNING.md`](docs/BALANCE_TUNING.md).

Manastorms, Arenas/PvP, and their GM tools are shelved in normal browser and
Android builds. Their source and saved data remain intact. Use
`npm run dev:shelved` or `npm run build:shelved` for maintenance builds, and
set `HEALER_MAN_ENABLE_SHELVED_MODES=1` on the matching development server.

Boss-mechanic and dungeon-event extension points, telegraph rules, checkpoint
behavior, test workflow, and the explicit source-gap ledger are documented in
[`ENCOUNTER_AUTHORING.md`](ENCOUNTER_AUTHORING.md).

## Content downloads

Production browser and Android builds ship a compact required set: the game
runtime, interface, starter equipment, Wailing Caverns starter content, and a
basic male/female Human character model with its default appearance. Large
character and skin libraries, additional dungeons, and the original
spell-effects and sound pack are optional downloads. Manastorm environment
packs remain internal dungeon dependencies and are installed automatically
when a regular dungeon needs one; they are not shown as standalone downloads.

Open **Downloads** from the main menu to download, update, or remove optional
packs on either platform. Browser downloads live in an app-managed verified
cache; Android downloads live in app-private storage. Removing a pack never
removes a roster or save. If a character's model/skin pack is unavailable, the
shared character renderer displays the matching-gender basic Human while
preserving that character's identity and progress for a later reinstall.

Original spell effects and authentic sounds are enabled by default; their
optional media pack downloads automatically. All ten WoW classes use packaged
source visuals, including animated meshes, particles, ribbon trails, and
particle model dependencies. Generated visuals cover unavailable phases;
missing sounds stay silent. The pack can be removed to reclaim storage. See
[`scripts/combat-effects/README.md`](scripts/combat-effects/README.md) for coverage,
regeneration, and the local effect preview. See
[`CONTENT_UPDATES.md`](CONTENT_UPDATES.md) for the content lifecycle and release
contract.

## Conquest of Azeroth classes

All 21 CoA classes use a checked-in live Vol'Jin catalog generated from
Ascension's builder API and class database, then joined to the extracted
realm-specific `area-52/patch-D` `Spell.dbc` and `SkillLineAbility.dbc` files,
plus the spell support tables from `patch-S`. The snapshot includes 91 trees,
3,612 selectable nodes, all 3,929 node-rank spell IDs and descriptions, 5,444
class-page spell rows, 556 skill-line-specific spell chains, and 8,034 unique
spell records with complete DBC matches. Runtime spell ranks are selected from
character level; tree abilities remain locked until their exact node and rank
are purchased.

CoA progression starts at level 10 and alternates class-tree Ability Essence
and specialization-tree Talent Essence, reaching the live 26/25 split at level
60. Node costs, level locks, tree-investment gates, prerequisites, connections,
coordinates, passives, and rank tooltips come directly from the live payload.

Refresh the snapshot and locally extracted icons with:

```powershell
npm run coa:sync:live
npm run coa:icons
```

`coa:sync:live` maintains a resumable tooltip cache because the public database
occasionally returns transient gateway errors. `npm run coa:sync` refreshes the
builder/class data and reuses that cache without crawling every spell-detail
page. Icon export includes all ability, talent, and class-selection icons; the
current extraction completes without question-mark fallbacks.

## Boss loot

Boss loot is authored in SQLite-compatible SQL under
[`data/loot/`](data/loot/README.md), not in combat or scene code. Run
`npm run loot:generate` after changing the schema or seed data. The generator
validates the relational data and ships both a browser-safe JSON catalog and
`public/data/healer-man-loot.sqlite`, whose `boss_loot_browser` view is ready
for a future loot-browser screen.

Every Wailing Caverns boss rolls one item when it dies. The item instance
captures its item level at the killing blow, remains on the corpse until
looted, and is then saved in that character's inventory. Drops use character
level through 79; level-80 drops begin the first endgame tier at item level 85.
The SQL loot source contains the original 3.3.5a attributes, ratings, armor,
block, weapon damage, weapon speed, regeneration, and spell-power values for
each item. A scaled drop preserves that original stat distribution instead of
replacing it with a generic item-power budget.

Every WoW and Conquest of Azeroth character has a saved specialization that
locks its activity role and selects a complete specialization-aware heirloom
loadout. Runes of Magic derives the same profile from its active primary class
and selected role. Virtual heirlooms fill every applicable unoccupied slot,
rescale through item level 79 for players and 80 for AI party members, never
enter inventory, and automatically return when earned equipment is removed.
During leveling their score is normalized above compatible same-level catalog
drops. At level 80 the item-level-85 boss tier contains real upgrades, which
the equipment and loot interfaces highlight without equipping automatically.

The equipment runtime uses the Wrath primary attributes and itemizable combat
stats. Strength, Agility, Stamina, Intellect, Spirit, Attack Power, Spell
Power, weapon damage, Hit, Critical Strike, Haste, Expertise, Armor
Penetration, defensive ratings, block, regeneration, resilience, and magical
resistances feed the player and AI-party combat calculations. Combat ratings
use the level- and class-specific conversion data from the local 3.3.5a client.
The Inventory & Equipment screen exposes the resulting Attributes, Offense,
and Defense sheets for the player and every current party member.

The reusable dungeon pipeline (global WMO and ADT/hybrid) is documented in
[`dungeon-pipeline/README.md`](dungeon-pipeline/README.md). Its entry points are:

```powershell
npm run dungeon:discover -- <slug>
npm run dungeon:extract -- <slug>
npm run dungeon:convert -- <slug>
npm run dungeon:optimize -- <slug>
npm run dungeon:creatures -- <slug>
npm run dungeon:navmesh -- <slug>
npm run dungeon:build -- <slug>
npm run dungeon:validate -- <slug>
npm run dungeon:enable -- <slug>
```

World and creature GLBs ship with KTX2/Basis GPU textures. On Windows, install
the pinned Khronos encoder into the project-local `.tools` directory and audit
the checked-in visual assets with:

```powershell
powershell -ExecutionPolicy Bypass -File scripts/asset-pipeline/bootstrap-ktx.ps1
npm run assets:ktx2:visuals
npm run assets:ktx2:audit
```

The dungeon, Manastorm, and Runewaker environment optimizers apply the same
KTX2 step to future visual outputs. The production build also runs the audit so
an accidentally reintroduced PNG/JPEG world texture fails before deployment.

## Controls

- Move: WASD, arrow keys, or left stick
- Jump: Space or L3
- Look: hold the right mouse button for mouse look, or use right stick
- Base abilities: keyboard 1–8; controller Cross, Square, Triangle, Circle,
  R1, R2, D-pad Left, and D-pad Right
- Secondary abilities: hold Shift or L1 while pressing an ability control
- Tertiary abilities: hold Alt or L2 while pressing an ability control
- Hostile target: Tab or R3
- Friendly target: click a party/player frame or use D-pad Up/Down to cycle
  living allies and yourself
- Party orders: F1 Attack, F2 Defend, F3 Stop
- Companion screen on a one-screen PC: C or gamepad Back/Select
- Map: M; Spellbook: P; Talents: N
- Pause: Escape or gamepad Start

Menus support keyboard, mouse/touch, and controller navigation. Use the D-pad
or left stick to move, Cross to select, and Circle to go back. Open
**Ability controls** from the pause menu to customize all 24 Base/L1/L2
bindings. Bindings save independently for each character and may be empty or
reuse the same class ability.

## Displays

Healer Man uses one authoritative game runtime and one WebGL canvas:

- AYN Thor top display: dungeon renderer and primary menus (`960 x 540` CSS).
- AYN Thor bottom display: roster, character details, and tactical UI
  (`620 x 540` CSS). It never creates a second dungeon renderer.
- PC: the same lower-screen UI opens as an overlay with C or Select; normal
  Tab navigation remains available throughout the menus.

Preview both Thor surfaces in a desktop browser at:

```text
http://localhost:5173/?layout=thor-preview
```

The Android host uses two Capacitor WebViews, Android `DisplayManager`, and a
secondary `Presentation`; state and semantic commands cross screens through a
rate-limited `BroadcastChannel`.

## Android / AYN Thor

Install JDK 21 and Android SDK Platform 36, set `JAVA_HOME` and
`ANDROID_SDK_ROOT`, then run:

```powershell
npm run android:apk
```

The debug APK is written under `android/app/build/outputs/apk/debug/`. To build
and install directly onto a connected device, use `npm run android:install`.

Android uses a compact `dist-android` build with the same required-content
boundary as the production browser build. Optional dungeons, character/skin
packs, internal environment dependencies, and original spell media are
downloaded into app-private storage. Installed content and local saves remain playable without
a server connection and survive APK updates. See `CONTENT_UPDATES.md` for the
update contract and `DEPLOYMENT.md` for TrueNAS publishing and signed Gitea
releases.

## Runtime details

- The player is a dynamic capsule against a separate static Rapier trimesh.
- Physics uses a fixed 60 Hz timestep.
- The real entrance is `[163.49, -73.66, 132.9]` in Three.js coordinates.
- Source coordinates convert one-to-one as
  `Three(x,y,z) = (-WoW.x, WoW.z, WoW.y)`.
- Repeated props use `EXT_mesh_gpu_instancing`: 3,348 placements are grouped
  into 71 batches.
- The population uses 16 locally extracted, skinned creature GLBs with native
  Stand, locomotion, attack, wound, cast, and death libraries; distant static
  mobs and roaming packs are unmounted beyond the proximity gate. Background
  animation runs at 30 Hz or 15 Hz by distance and freezes safely behind the
  camera, while bosses, targets, combatants, and nearby actors stay full-rate.
- Production world and creature textures use KTX2/Basis transcoding to remain
  compressed in GPU memory instead of expanding to uncompressed RGBA textures.
- Missing production GLBs activate a small cave proxy; malformed assets activate
  the recoverable scene-error screen.
- Missing optional character or skin packs render the built-in basic Human
  model instead of hiding the player, party member, or roster preview.
- The controller action HUD displays only the active eight-slot layer. Its
  face-button diamond, shoulders, and D-pad keep the physical controller layout
  visible without showing all 24 bindings over the playfield.

The navigation GLB is generated offline with pinned Recast settings. Party
leaders project onto its route graph, including separately-authored off-mesh
links, while collision/floor checks reject wall shortcuts. Followers replay the
leader's breadcrumb trail to avoid cutting corners. A disconnected route makes
the party hold safely and reports `Route blocked`; player movement continues to
use the collision GLB directly.

## Structure

- `src/game/`: serializable state, combat/loot simulation, input mapping, coordinates, and area math
- `data/loot/`: authoritative SQL loot schema and dungeon seed data
- `src/app/`: local accounts, character rosters, creation catalog, and shell state
- `src/platform/`: single/dual display routing and Thor synchronization
- `src/scene/`: R3F Canvas, Rapier bridge, camera, player, and dungeon loaders
- `src/ui/`: responsive HUD, encounter map, loading, pause, and error surfaces
- `src/assets/game/dungeons/wailing-caverns/`: shipping GLBs and anchor metadata

Wailing Caverns remains the global-WMO regression fixture. Deadmines is the
gated ADT/hybrid pilot and cannot be enabled without authoritative server data
and green automated/visual reports.