healer-man/docs/ROM_HEIRLOOM_REFERENCE.md

# RoM level 1–79 heirloom reference

Status: **source-backed design data, separate from equipped hybrid heirlooms**. `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 source-reference 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 native Priest reference curve uses the well-populated staff series; the active WoW-stat hybrid equips a mace and shield to support the Priest/Knight pairing. A shield 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`.

## Use in the hybrid runtime

The active RoM runtime uses WoW-shaped heirloom stats and WoW combat formulas by design; see `docs/ROM_STATS_AND_GEARING.md`. These native source curves remain references for level progression and class identity. Feeding native values directly into the WoW path would produce meaningless balance. The five active hybrid loadouts use legal weapon layouts, a WoW-stat level budget, and no comparison against WoW boss drops. Tune Knight survival, Priest healing/sustain, and Scout/Rogue/Mage damage 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.