Add source-backed RoM heirloom reference curves

docs/ROM_HEIRLOOM_REFERENCE.md

@@ -0,0 +1,41 @@
+# RoM level 1–79 heirloom reference
+
+Status: **source-backed design data, not equipped game items**. `scripts/runewaker-pipeline/export-rom-heirloom-reference.mjs` generates `src/game/generated/romHeirloomReference.json` from the sibling RuneWaker client snapshot, or from `RUNEWAKER_ROOT`. Run `node scripts/runewaker-pipeline/export-rom-heirloom-reference.mjs` after refreshing `src/game/generated/romLevelingGearPackages.json`. `src/game/romHeirloomReference.ts` provides typed level and item lookups. The 5 × 79 curves cover the five selected primary classes; their secondary class always shares the primary level.
+
+## Evidence and scope
+
+The [RoM Item Sets index](https://runesofmagic.fandom.com/wiki/Category:Item_Sets) and [Leveling Packages index](https://runesofmagic.fandom.com/wiki/Category:Leveling_Packages) identify leveling families. The [Issac](https://runesofmagic.fandom.com/wiki/Issac%27s_%28Item_Set%29), [Savage Lands](https://runesofmagic.fandom.com/wiki/Savage_Lands_%28Item_Set%29), [Lance's Support](https://runesofmagic.fandom.com/wiki/Lance%27s_Support), and [Cloth Armor Package (Multi)](https://runesofmagic.fandom.com/wiki/Cloth_Armor_Package_%28Multi%29) pages connect sets with the level-50, 55, 60, and 65 rewards. `docs/ROM_LEVELING_GEAR_PACKAGES.md` records the quest/package IDs and distinguishes wiki claims from the client package links that remain undecoded.
+
+The local client provides **3,026 Good-quality (blue) armor and weapon records** with required level 1–79. Their IDs, names, levels, armor/weapon types, positions, suit IDs, base effects, deterministic fixed attributes, and decoded native stats are retained as source references. Of those, 727 have attribute IDs absent from this snapshot's `addpowerobject.db`, and 98 have effects outside the mapped core stat model; they remain visible but are excluded from curve candidates. Source file SHA-256 values are embedded for reproducibility. The generated output is design evidence, not a claim that all 3,026 items are normally obtainable at their required level.
+
+The parser uses the local `ObjectStruct.h` `GameObjectWeaponENUM`, `GameObjectArmorENUM`, and `WearEqTypeENUM`, and fixed record layouts from `armorobject.db`, `weaponobject.db`, and `addpowerobject.db`. Numeric quality 2 is the client's Good/blue tier, consistent with the [wiki quality legend](https://runesofmagic.fandom.com/wiki/Category:Items). An effect with type 7 adds its value to all five primary attributes. Only 100% fixed item attributes are summed; random attribute rolls are listed by ID without being assumed.
+
+## Design rules
+
+| Primary class | Armor reference | Main weapon reference | Other weapon reference |
+| --- | --- | --- | --- |
+| Knight/Scout | Plate | One-hand mace | Shield |
+| Priest/Knight | Cloth | Two-hand staff | None in this curve |
+| Scout/Rogue | Leather | Dagger | Bow |
+| Rogue/Warrior | Leather | Dagger | Off-hand dagger |
+| Mage/Warlock | Cloth | Two-hand staff | None |
+
+These choices follow the [official class equipment guide](https://archive.runesofmagic.gameforge.com/en/classes.html). Scout is **leather**, not chain. Priest can also legally use a wand or mace with a shield, but this client has only one complete blue wand record at level 57. The current Priest curve uses the well-populated staff series; the shield reference belongs to a separate future one-hand build and must not be combined with a two-hand staff. The Mage/Warlock remains dwarf; race has no effect on the equipment reference table itself.
+
+The generator chooses a median item at each observed required level using role-oriented native-stat scores, then substitutes matching 50/55/60/65 package-suit armor pieces at those milestone levels. For levels between source points it interpolates each stat; below the first point or above the last it scales from the nearest source point. It rounds positive values to at least one and retains the prior level's value when the next candidate would lower a stat. `referenceItemIds` are the points behind that level, while `packageId` identifies a matched package-suit milestone. A curve row can therefore combine retained prior stats with current source values and **is not an exact copy of its listed item**. These scoring coefficients are selection heuristics, not certified combat stat weights.
+
+All five profiles cover head, hands, feet, chest, legs, back, waist, shoulder, neck, finger, trinket, and main hand. Off hand exists for Knight and Rogue; Scout has ranged. Source earrings are represented by the game's `trinket` reference slot. The source catalog has no matching wrist slot for this export. The game must resolve its final slot design before equipping the sets.
+
+## Numeric cross-checks
+
+| Source item | Required level | Confirmed decoded effects |
+| --- | ---: | --- |
+| Magic Robe of the Lake, ID 229164 | 65 | 1,029 DEF, 1,655 MDEF, 273 HP, 290 MATK, 100 Stamina, 67 Intelligence |
+| Gale Staff, ID 213416 | 60 | 903 weapon damage, 1,094 magical weapon damage, 172 MATK, 20 Stamina, 56 Intelligence, 56 Wisdom |
+| Rescuer's Blessing, ID 212999 | 50 | 440 Heal Point, 660 MATK, 1,717 magical weapon damage, 50 Wisdom; a useful healing reference but an unusually strong source item, so it is not a median staff anchor |
+
+The [Gale Staff wiki entry](https://runesofmagic.fandom.com/wiki/Gale_Staff) provides an independent level-60 cross-check. More source IDs, including each 65 package chest, are queryable through `romSourceReferenceItem` and each curve's `referenceItemIds`.
+
+## Before activating heirlooms
+
+The current RoM runtime still generates WoW-shaped heirloom stats and converts RoM attributes with WoW formulas; see `docs/ROM_STATS_AND_GEARING.md`. Feeding these native RoM values directly into that path would produce meaningless balance. Implement the RoM equipment slots, class permissions, item-instance bonus layer, and native combat conversion first. Then tune one native-stat heirloom set by targeted Knight survival, Priest healing/sustain, and Scout/Rogue/Mage damage checks across levels 1–79. Keep dungeon bosses on the existing cards-only leveling policy; heirlooms and package gear should come from progression, not dungeon equipment drops. Elite skills remain out of scope.

docs/ROM_LEVELING_GEAR_PACKAGES.md

@@ -1,10 +1,10 @@
 # RoM leveling gear package catalog
 
-Status: **quest choices verified; package contents and equipment stats unverified**. This is source evidence for a RoM leveling route, not a runtime gear grant. The generated inventory is `src/game/generated/romLevelingGearPackages.json`, owned by `scripts/runewaker-pipeline/export-leveling-gear-packages.mjs`. Refresh it with `node scripts/runewaker-pipeline/export-leveling-gear-packages.mjs` against the sibling RuneWaker client snapshot, or set `RUNEWAKER_ROOT` to another snapshot.
+Status: **quest choices and several armor-set families verified; exact client package expansion unverified**. This is source evidence for a RoM leveling route, not a runtime gear grant. The generated inventory is `src/game/generated/romLevelingGearPackages.json`, owned by `scripts/runewaker-pipeline/export-leveling-gear-packages.mjs`. Refresh it with `node scripts/runewaker-pipeline/export-leveling-gear-packages.mjs` against the sibling RuneWaker client snapshot, or set `RUNEWAKER_ROOT` to another snapshot. Native item-stat references and 1–79 heirloom curves are in `docs/ROM_HEIRLOOM_REFERENCE.md`.
 
 ## Confirmed quest milestones
 
-The client `Resource/data/questdetailobject.db` links each quest to the armor-category reward packages in the order below. `itemobject.db` confirms that the later parent packages and their similarly named weapons and armor subpackages exist. The client strings describe each later parent choice as giving one weapons package and one armor package; their exact item links have not been decoded. The inner package expansion into individual items is also unverified, so the seven-piece suits listed for levels 50–65 are **matching source sets**, not proven package contents. Their member IDs and required levels are recorded in the generated JSON from `suitobject.db` and `armorobject.db`.
+The client `Resource/data/questdetailobject.db` links each quest to the armor-category reward packages in the order below. `itemobject.db` confirms that the later parent packages and their similarly named weapons and armor subpackages exist. The client strings describe each later parent choice as giving one weapons package and one armor package; their exact item links have not been decoded. The generated catalog records matching seven-piece source suits from `suitobject.db` and `armorobject.db`; wiki pages independently identify several as package contents, but do not establish every weapon, accessory, quantity, or version in this client snapshot.
 
 | Quest level and name | Quest ID | Plate package | Chain package | Leather package | Cloth package |
 | --- | ---: | ---: | ---: | ---: | ---: |
@@ -17,15 +17,28 @@ The client `Resource/data/questdetailobject.db` links each quest to the armor-ca
 
 *The level-30 source name is **World Battlefield Bonus Armor Package**, without the word “Plate.” Its plate classification is only a likely reading of its position beside chain, leather, and cloth; the generated catalog uses `armor` until verified. This is a battlefield reward, so it is an optional source candidate rather than a guaranteed leveling grant. The level-5 quest has only three choices, and its chain choice is named **Chainmail Armor Box**. Neither early tier has confirmed individual package contents. The level-65 rewards are the Redhill Mountains Pioneer packages. The source-linked subpackage IDs, source names, matching suit IDs, seven armor member IDs, and their actual required levels for levels 50–65 are in the JSON catalog. Some level-50 suit members have required levels below 50; the quest reward level is the milestone, not an assertion that every item requires that level.
 
+## Wiki cross-checks
+
+The [Item Sets index](https://runesofmagic.fandom.com/wiki/Category:Item_Sets) and [Leveling Packages index](https://runesofmagic.fandom.com/wiki/Category:Leveling_Packages) give additional reference families beyond the client quests. Their set pages support these specific connections:
+
+| Milestone | Package or set evidence | Confidence for armor pieces |
+| --- | --- | --- |
+| 50 | [Issac's sets](https://runesofmagic.fandom.com/wiki/Issac%27s_%28Item_Set%29) identify four seven-piece sets in the level-50 armor packages. | Wiki-confirmed family; source suit member IDs in catalog. |
+| 55 | [Savage Lands sets](https://runesofmagic.fandom.com/wiki/Savage_Lands_%28Item_Set%29) identify Haz, Eduth, Luzan, and Rufa with Bodo Treasure rewards. | Wiki-confirmed family; source suit member IDs in catalog. |
+| 60 | [Lance's Support](https://runesofmagic.fandom.com/wiki/Lance%27s_Support) identifies Rh'anka, Sley, Tempest, and Croso package choices; the [Tempest set](https://runesofmagic.fandom.com/wiki/Tempest_Set_%28Item_Set%29) supplies a piece-level cross-check. | Wiki-confirmed family; source suit member IDs in catalog. |
+| 65 | [Cloth Armor Package (Multi)](https://runesofmagic.fandom.com/wiki/Cloth_Armor_Package_%28Multi%29) names the Lake Energy cloth set at 65; the other armor categories currently have matching source suits but need their package pages checked. | Cloth wiki-confirmed; other categories matched by source name/type/level. |
+
+The wiki is a reference for the RoM item families, while the local RuneWaker records are the authority for item IDs and numeric stats in this snapshot. Page descriptions alone do not prove that this snapshot's package-opening script grants the same items.
+
 ## Applying these to the five classes
 
-The current game marks Knight as plate, Priest and Mage as cloth, and Rogue and Scout as leather in `src/app/characterCatalog.ts`. This suggests one plate, one leather, and one cloth choice for the five-class cohort; chain remains in the catalog because it is one of the source quest choices. Before grants are enabled, confirm native RoM class permissions and individual weapon choices, especially the Scout. A secondary class shares the primary's level and does not require a second package progression.
+The current game marks Knight as plate, Priest and Mage as cloth, and Rogue and Scout as leather in `src/app/characterCatalog.ts`. The [official class guide](https://archive.runesofmagic.gameforge.com/en/classes.html) confirms that Scout wears cloth or leather, while Knight can wear plate and Priest/Mage cloth. This suggests one plate, two leather, and two cloth choices for the five-class cohort; chain remains in the source catalog but is not a default choice for these primary classes. A secondary class shares the primary's level and does not require a second package progression.
 
 During leveling, `src/game/lootPolicy.ts` suppresses all boss item drops. Boss cards are awarded separately. Package gear should come from a level or quest milestone, never from a dungeon boss loot table. A fallback starter kit can cover levels for which no verified source package exists.
 
 ## Gaps before playable package gear
 
 1. Locate and verify package expansion records or scripts for every parent and subpackage, including weapon selections, accessories, exact armor items, and quantities. Matching a suit by name, category, and required level is not enough to grant its pieces as historical package contents.
-2. Decode native equipment slots, weapon and armor type, base stats, and item-instance bonuses. The current RoM gear path uses WoW-shaped synthetic heirlooms and cannot represent the source items faithfully.
+2. The source-backed 1–79 reference now decodes native equipment slots, weapon/armor type, base stats, and deterministic fixed attributes. Implement the separate item-instance and native-combat adapter before these become equippable heirlooms; the current RoM gear path still uses WoW-shaped synthetic heirlooms.
 3. Find a complete, generally available source-backed route from 1–49 and above level 65. Level 5 has only cloth, leather, and chain choices; level 30 has four battlefield choices. Logar/Hope package names exist in the item table, but their acquisition route and contents are not confirmed. Avoid inventing missing plate or weapon contents.
 4. Make the milestone grant idempotent and persistent, then verify class eligibility, package selection, leveling through each milestone, and native-stat combat outcomes for all five builds.

docs/ROM_STATS_AND_GEARING.md

@@ -1,6 +1,6 @@
 # RoM stat weights and gearing audit
 
-Status: **source model identified; runtime conversion and equipment import pending**. This audit covers the Priest/Knight healer, Knight/Scout tank, Scout/Rogue DPS, Rogue/Warrior DPS, and Mage/Warlock DPS. It does not assign balance weights to unimplemented RoM gear.
+Status: **source model and level 1–79 gear references identified; runtime conversion and equipment import pending**. This audit covers the Priest/Knight healer, Knight/Scout tank, Scout/Rogue DPS, Rogue/Warrior DPS, and Mage/Warlock DPS. It does not assign balance weights to unimplemented RoM gear. See `docs/ROM_HEIRLOOM_REFERENCE.md` for the client-derived blue-item atlas and proposed per-level native-stat curves.
 
 ## Current runtime
 
@@ -42,10 +42,10 @@ Priest healing cannot be scored by MATK alone: the source healing path also uses
 
 RoM equipment has base item properties plus additional attribute sources. [Gameforge's class guide](https://archive.runesofmagic.gameforge.com/en/classes.html) lists native class weapon/armor permissions. Its [rune guide](https://archive.runesofmagic.gameforge.com/us/runes.html) describes socketed runes and up to four rune slots; its [Arcane Transmutor guide](https://archive.runesofmagic.gameforge.com/en/arcanetransmutor.html) describes transferring attributes through Fusion and Mana Stones. These changes must be represented as item-instance bonuses rather than a WoW item-level budget. Source `RoleAttr.cpp` already distinguishes flat equipment contributions, attribute contributions, and multiplicative rates.
 
-1. Decode `armorobject.db` and `weaponobject.db` into native slot, armor/weapon type, base defense/damage, attribute, and level fields. Preserve source object IDs and validate the binary layout against source structures and known items before allowing package equipment to equip.
+1. Use `scripts/runewaker-pipeline/export-rom-heirloom-reference.mjs` and `src/game/generated/romHeirloomReference.json` as the decoded source references for native slot, armor/weapon type, base effects, deterministic fixed attributes, and required level. Preserve item IDs and investigate the 727 records with unresolved attribute IDs and any special effects before turning a source item into equippable gear. The `src/game/romHeirloomReference.ts` lookup is design data and is not read by combat equipment yet.
 2. Add a RoM item-instance bonus layer for native flat stats, transferred attributes, rune sockets, and later enhancement/tier data. Sum those bonuses into a native stat block. Keep WoW `ItemStats` and heirloom scoring unchanged for WoW characters.
 3. Extend the generated class data with race and sex arguments and the vocation conversion coefficients. Keep secondary growth tied to the primary's level, including after the level-10 secondary unlock. Convert the complete RoM stat block to combat inputs through a RoM-specific adapter, including ATK, MATK, DEF, MDEF, and separate healing inputs.
-4. Use legal starter equipment as a temporary bridge, then source-backed quest or item-shop equipment packages for leveling. The client snapshot confirms four armor-choice quest reward families at levels 50, 55, 60, and 65, a three-choice quest at level 5, and a battlefield reward at level 30; see `docs/ROM_LEVELING_GEAR_PACKAGES.md`. Resolve the package expansion data and missing general-route tiers before granting source items. Dungeon bosses award cards during leveling, not equipment or miscellaneous items. Do not tune a RoM heirloom to a WoW drop score or apply WoW rating conversions to it.
+4. Use legal starter equipment as a temporary bridge, then source-backed quest or item-shop equipment packages for leveling. The client snapshot confirms four armor-choice quest reward families at levels 50, 55, 60, and 65, a three-choice quest at level 5, and a battlefield reward at level 30; see `docs/ROM_LEVELING_GEAR_PACKAGES.md`. The native-stat reference curves fill the design gaps at every level 1–79 but are interpolated from source items and must be tuned in native combat. Resolve exact package expansion before granting historical items. Dungeon bosses award cards during leveling, not equipment or miscellaneous items. Do not tune a RoM heirloom to a WoW drop score or apply WoW rating conversions to it.
 5. Derive role-specific *upgrade scores* from the marginal combat effect of each native stat at the current level and gear state. Measure Knight survival/threat, Priest effective HPS and sustain, and each DPS build's damage on the same targeted encounter set. Source coefficients seed that model; targeted combat measurements establish practical weights and catch caps or nonlinear effects.
 
 ## Online and validation boundary