healer-man/docs/WOW_HUNTER_PET_FAMILIES.md

# WoW Hunter Pet Family Source Data

## Source and extraction

`src/game/generated/wow335PetFamilyData.json` is generated from the local 3.3.5a client archive `../wow335a/Data/enUS/patch-enUS.MPQ`. The generator reads `CreatureFamily.dbc`, `SkillLineAbility.dbc`, `Spell.dbc`, and `SpellDuration.dbc`:

- `scripts/generate-wow335-pet-families.mjs` owns the extraction and writes the generated JSON.
- `src/game/wow335HunterPetFamilyData.ts` exposes the family rows, their unique and common pet skill lines, and rank/effect fields—including `AttributesEx1`, `procFlags`, `procChance`, and `procCharges`—without marking source rows playable.
- `src/game/wow335HunterPetFamilyData.test.ts` checks family classification and representative Wolf, Turtle, and Cat rank/effect rows.

The DBC has 40 named families. The local core classifies a family as a Hunter pet when `petTalentType` is non-negative (`Player.cpp`, pet talent validation); 32 rows satisfy that condition. Each family row includes its source ID/name, pet talent type, food mask, scaling fields, family skill line, and common pet skill line. Skill-line associations are corroborated by `Pet.cpp`: `LearnPetPassives()` looks up the creature family's skill lines, and `InitLevelupSpellsForLevel()` loads a family's level-up spells.

Regenerate with `node scripts/generate-wow335-pet-families.mjs`. The default archive is the local client path above; optional command-line arguments can supply another MPQ path and output path.

## Runtime boundary

The extracted family rows are source data, not a claim that every family is playable. The current selectable profiles are Wolf, Turtle, and Cat, defined in `src/game/wow335HunterPetFamilySelection.ts` and `src/game/wow335HunterPetRuntime.ts`. The player profile saves the choice as `CharacterProfile.hunterPetFamily`; legacy, invalid, and unsupported values normalize to Wolf. Selection is player-only, available from the active pet frame, and locked while an encounter is active. The player call and revive paths use that saved choice. Generated Hunter companions continue to use Wolf.

Turtle uses the same 11 Bite spell IDs as Wolf (17253, 17255-17261, 27050, 52473-52474), so the existing Bite rank damage and source-listed coefficients apply to either family. Turtle family skill line 251 also supplies Shell Shield spell 26064 at required pet level 1: 0 Focus, 60-second cooldown, 12-second duration, and AuraType 87 with a -50% damage-taken amount. The simulator autocasts Shell Shield while the Turtle has a combat target; that trigger is the simulator's pet-AI policy, while the timing and reduction values come from the local source row. Wolf alone receives Furious Howl.

Cat family skill line 209 supplies Claw (25 Focus, no recovery cooldown, 1.5-second GCD), Rake, and Prowl. The level-80 Rake rank (59886) costs 20 Focus, has a 10-second cooldown and 1.5-second GCD, and applies three ticks at three-second intervals over nine seconds. Cat Claw ranks use the local AzerothCore `spell_bonus_data` coefficients (.07 AP and .119658 spell damage); Rake's direct and periodic components each use .0175 AP and .0299 spell damage. The DBC damage ranges are resolved to their midpoint by the simulator.

Rake has separate armor rules for its components. The local Spell.dbc row has no spell-wide mechanic; effect 0 is direct school damage with mechanic 0, while effect 1 is periodic damage with mechanic 15 (bleed). Core `Unit::IsDamageReducedByArmor` applies physical armor to direct attacks and skips it for the bleed tick. The simulator applies armor to Cat's physical auto attacks and direct Claw/Rake specials, then carries Rake's `ignoreArmor` source mechanic on its periodic event. Target damage modifiers and absorbs still run once through the normal target-damage path for each component. Rake ticks remain owned by the pet and continue on their application target after pet death, dismissal, or family swap, consistent with the target-owned aura and null-caster periodic handler in the local core.

Prowl rank 1/2/3 are learned at pet levels 1/30/50. Their DBC rows cost no Focus, have no GCD, use a 10-second category cooldown, and grant stealth with -50%/-45%/-40% movement speed plus +20%/+35%/+50% damage for school mask 65 (`0x41`, physical and arcane). The runtime keeps the aura pet-owned, applies the rank movement reduction to modeled follow/chase movement, and applies the sourced modifier to the next ready auto swing. Prowl's source rows have `procFlags=332116` (`0x51154`, including `PROC_FLAG_DONE_MELEE_AUTO_ATTACK` bit `0x4`), one proc charge, and proc chance 100/101. The spell's `auraInterruptFlags` are 140291 (`0x22403`) for ranks 1/3 and 139267 (`0x22003`) for rank 2; none includes `MELEE_ATTACK` (`0x1000`). The local core therefore consumes Prowl through its successful-auto-attack proc after damage calculation, rather than through the melee interrupt mask. The runtime models that post-auto consumption for a recorded hit, including a fully absorbed hit. The pet-special damage path has no miss/dodge combat-result channel today, so the simulator treats a ready swing against a valid target as a hit and cannot model source miss exclusion. Claw/Rake have no `ALLOW_WHILE_STEALTHED` exception, and PetAI casts them as non-triggered spells; `Spell::prepare` removes their `SPELL_ATTACK` interrupt aura before effect resolution, so Prowl does not increase their direct or periodic damage. PetAI handles a ready melee swing before spell autocasting; the Cat runtime follows that order when both are ready. Autocasting Prowl without a target and incoming-damage break are simulator policies. Stealth visibility/detection remains unsupported. Kill Command is consumed once per executed Claw or Rake cast, and its matching `SPELLMOD_DAMAGE` and `SPELLMOD_DOT` modifiers are both snapshotted by Rake's direct and periodic components before that cast consumes one charge; subsequent ticks do not consume more charges.

Hunter pets currently have no dynamic model renderer in `src/scene/CombatSummonPopulation.tsx`; the summon frame shows the selected family name. Turtle's family/profile and name change with the saved selection, while `creatureId` remains legacy summon metadata and does not select Wolf-only mechanics.

No other extracted Hunter family is selectable yet. The extracted identities do not imply that all 32 Hunter families are playable.

## Remaining pet mechanics

- **Stable:** the simulator has no persistent pet roster or stable slots. The local core reference stores pets by `character_pet` rows and stable-slot modes (`PetDefines.h`, `Pet.cpp`); choosing among families alone does not model those saved pets.
- **Feed and happiness:** the generated family source now retains each `PetFoodMask`, but the simulator has no pet-owned food inventory or persistent happiness value. `wow335HunterPetHappinessRuntime.ts` only maps a supplied happiness value to a state and auto-attack multiplier.
- **Training:** the DBC source exposes family skill lines, rank requirements, and spell effects, but the simulator has no pet learned-spell book, training-point budget, or trainer purchase flow. Selecting a highest rank from owner level remains a runtime rule for the supported family profiles.
- **Stealth detection:** Prowl's source stealth level is retained, but the world has no stealth-visibility or detection-resolution model; the current runtime marks the pet as stealthed and applies its movement, auto-swing damage, and break behavior.
- **Pet critical inheritance:** unresolved. The local critical audit found no stock owner-crit inheritance formula; do not add the unmerged issue's owner-melee-crit proposal. See `docs/ACTIVE_CLASS_AUDIT.md` for the source boundary.