# Gear upgrades (Polestar)

**For:** players curious about the gear advice, and contributors. **At the end:** you know how upgrades are scored, where the data comes from, and where it differs from Polestar.

The equipment panel says, per slot, what to wear instead and where to get it:
"Belt of Arugal, +13.6 (6% of your gear), drops from Archmage Arugal in Shadowfang Keep". The
items, where they come from and how much each one is worth to your class and
spec all come from [Polestar](https://github.com/fitzforge/polestar)'s gear
advice. `data/gear-reference.json` ships in the image and `wowstats/gear.py`
scores with Polestar's own formulas, checked item by item against Polestar's
Lua (below).

A drop names its boss and, for a dungeon, the level range
(`data/forever-reference.json`, `docs/forever-reference.md`).

Polestar is required: without its SavedVariables a character has no level
the server trusts, so the panel says Polestar is missing instead.

## Credit and licences

[Polestar](https://github.com/fitzforge/polestar) is the leveling guide addon
for WoW Forever, by fitzforge and its contributors, GPL-3.0-only. Its gear
advice (`addon/Polestar/Gear/`, `addon/Polestar_ItemDB/`) is built from:

| Part | From | Licence |
| --- | --- | --- |
| Polestar's scoring (`Gear.lua`, `Weights.lua`, `Adjust.lua`), ported to `wowstats/gear.py` | Polestar | GPL-3.0-only |
| Forever's item stats and where leveling gear comes from: quest rewards and choices, dungeon drops, crafts (`Polestar_ItemDB/Forever.lua`); racial gear traits (`SpecData.lua`) | [ForeverLevelingBiS](https://www.curseforge.com/wow/addons/forever-leveling-bis) **v0.12.0-beta** by Thunder, generated by Polestar | MIT, Copyright (c) 2026 Thunder |
| Stat weights per level band (`SpecData.lua`) | Polestar's own, blended with simulated weights from [wowsims](https://github.com/wowsims) | MIT, Copyright (c) 2024 wowsims team |
| Classic Era item stats (`Polestar_ItemDB/Items.lua`), the Forever client's rating and health tables in `Weights.lua` | Blizzard client tables, via wago.tools | Game data © Blizzard Entertainment, used as facts |
| Creature armor by level, behind the armor penetration weight | ForeverTDB | GPL-2.0, used as facts |

wow-stats is GPL-3.0-only (`LICENSE`), so the GPL parts fit as they are. The
MIT notices for ForeverLevelingBiS and wowsims are in
[`THIRD_PARTY.md`](https://github.com/sam-dumont/wow-mcp/blob/main/THIRD_PARTY.md), as Polestar keeps them in its own
`THIRD_PARTY.md` and `LICENSE-DATA.txt` files.

Only ForeverLevelingBiS **v0.12.0-beta** is in here, a version released
under MIT, and only through what Polestar generated from it. Later versions
(1.x, All Rights Reserved) are never read: not their data, not their weights,
not their scores. The one thing the shipper takes from a newer install is the
spec the player picked in it (a setting in its SavedVariables, below).

The file records where it came from: `polestar.tag` and `polestar.commit`,
`leveling` (source, author, version, generation date, licence) and
`item_stats.build`.

## How the file is made

`tools/gear_reference/export.mjs` runs Polestar's own files, nothing built:

1. A shallow clone of Polestar at the release tag, the same tag as the route
   times (`POLESTAR_TAG` in `.github/workflows/route-reference.yml`, moved by
   hand when kb-refresh's watcher reports a new Polestar release).
2. `tools/gear_reference/dump.lua` loads `Gear/ItemDB.lua`, then the data
   addon's `Items.lua` and `Forever.lua` in the order of its `.toc`, then
   `Weights.lua` and `SpecData.lua`, each in an empty environment (no `io`,
   `os` or `load`). Items are parsed by `ItemDB.Get`, sources by
   `ItemDB.Sources`, quests by `ItemDB.Quest`, so the file reads the data the
   way the addon does.
3. The export keeps the items gear advice scores (no shirts, tabards, bags or
   ammo), their sources, the quests behind them and the class rules and
   weights.

Under 3 seconds, the same file byte for byte on every run:

```sh
git clone --depth 1 --branch v0.4.1 https://github.com/fitzforge/polestar /tmp/polestar
node tools/gear_reference/export.mjs --polestar /tmp/polestar
```

CI reruns both exports on every change to them, the data files or the
scoring, and fails when a result differs from the committed file. A Polestar
bump means: change `POLESTAR_TAG`, rerun both exports, commit the three files.

## What the file holds

| Key | What |
| --- | --- |
| `items.<id>` | `inv` (inventory type), `ilvl`, `req` (required level), `quality`, `class`, `subclass`, `speed` (weapons), `allow` (class mask), `unique`, `stats` (Polestar's stat keys: `sp`, `spi`, `sta`, `dps`...) |
| `names.<id>` | Item names, for the items with a source |
| `sources.<id>[]` | `{kind: "quest", quest}`, `{kind: "drop", npc, npc_name, pct, zone, zone_name}` (npc 0 is trash) or `{kind: "craft", spell, profession, skill}` |
| `quests.<id>` | `name`, `level`, `req`, `side` (1 Alliance, 2 Horde, 3 both), `zone_name`, `race` and `class` masks, `dungeon`, `choices[]` and `items[]` |
| `gear` | Polestar's `CLASSES`, `WEIGHTS`, `WEIGHT_BANDS`, `PROFICIENCY`, `RACIALS`, `STAT_KEYS`, health per Stamina, mana per Intellect, Intellect per 1% spell crit per class and level, the armor share per level |

10,621 items, 3,529 of them with a source, 1,088 quests; 1.7 MB (about
220 KB gzipped on the wire). `GEAR_REFERENCE_FILE` points at another file,
`off` turns gear advice off.

## How a character is scored

`wowstats/gear.py`, per character, at the level Polestar last saw:

- **Weights.** Polestar's level band for the class and spec
  (`Weights.lua` `Gear.WeightsFor`), with its formula stats (health and mana
  from Stamina and Intellect at that level) and the melee DPS tiebreaker.
  The player's own edits from Polestar's Adjust weights window
  (`PolestarDB.gearAdjust`, shipped in `wow-gear` as `gear_adjust`) apply on
  top, as `Adjust.lua` does.
- **Score.** Stats times weights, the racial multipliers, the cap on
  spell school bonuses, the off-hand and two-hander rules of `Gear.lua`
  (`Score`, `CompareToEquipped`): same numbers as the addon.
- **Usable.** Armor and weapon types the class learns, and at what level
  (Shamans wear mail from 40), the class mask, the required level.
- **Where.** Quests of your side, race and class only, minus the ones you
  handed in (Polestar Recorder's `turnin` records). A quest that offers a
  choice shows its best reward only (`Rewards.lua` `RankChoices`). Crafts
  say whether you make it at your rank; crafts with no required level
  (Engineering goggles, which need the skill to wear) only show to those
  who have it.

Per slot: the best item you can wear now and the next one within 3 levels,
when it beats both.

**Gains are in Polestar's points**, the number that compares across slots,
with their share of everything the character wears ("+13.6, 6% of your
gear"). The percent over the replaced item is Polestar's tooltip number, but
against a weak item it reads +427% for a modest gain, so the page keeps it
for the tooltip and sorts by points.

**Weapons are whole setups.** A two-hander is weighed against main hand + off
hand (`Gear.lua` `compare`). A one-hander against a worn two-hander is never
weighed alone: in game Polestar pairs it with the best off-hand piece in your
bags (`refreshBags`, `bagBest`); the server pairs it with the best off hand
you can get by then (held ones included), or the one you wear, and says which
("with Raptor's Gaze, drop: Shadetooth"). A setup is listed once.

**Repeated sources** read once: the data has some quests twice (one copy
without a zone), and the copy that says the most stays. The page lists them by where you get them (a group
per dungeon, zone's quests, profession or the auction house; a dungeon ranked
by its expected gain per clear, the chance-weighted best per slot) or by
slot; either way a slot shows its best and at most 2 alternatives that add
something (another source, available now, another gate), a group at most 3,
and the rest folds under "N more". An upgrade under 2% of your gear is
"small". **Gates** (`gates` on each upgrade): the level to wear it, and for
an item only a craft gives, the profession's skill when you have the
profession, or "buy" when you don't (a crafter or the auction house; the
data has no recipe price or reputation gate, so none is shown).

**The spec**, first match wins:

1. The selector on the page (kept in the browser).
1b. The site's `WEIGHTS` setting for that character (docs/deploy.md): the
   player's choice, kept where the site runs.
2. Polestar's Stat weights setting for the class, when it isn't Automatic
   (`PolestarDB.settings.gear.spec`, shipped as `polestar_spec`).
3. The talent tree with the most points, as Polestar's Automatic picks it
   (`Gear.lua` `DetectSpec`, `mostPoints`). The game keeps talents to
   itself; [Vulcan SimBench](https://addons.wago.io/addons/E6gzVqN1)
   saves them per character when you run `/simx` (its last export string,
   `VulcanSimBenchCharDB.last`). The shipper checks the string's Adler-32
   and keeps only the points and tree names (`talents` in `wow-gear`).
4. The spec the player picked in a gear addon: ForeverLevelingBiS or
   GearQuestForever's SavedVariables (`spec` in `wow-gear`). In game,
   Polestar puts Forever Leveling BiS's pick before the talents, but only
   through that addon's 1.x API, which this kit keeps out; a saved pick can
   also be months old.
5. The class's leveling default in Polestar (Shadow for a Priest).

The page and the `gear` tool say which one won, in words: "Scored for Shadow
because you picked Shadow in ForeverLevelingBiS. No talents saved yet: run
/simx once". The shipper sends which addon the pick came from (`spec_from`).

Run `/simx` again after a respec: the talents are as of the last export.

The character card keeps two things apart (owner, 2026-11-18): the talents
as the game has them, named by points ("Discipline 16/0/7", from Battle.net
daily, else the last `/simx`), and what the gear is scored for, from the
list above. Battle.net's talents don't feed step 3: they would move the
weights every time a point goes in, and a player leveling as Discipline on
the way to Shadowform scores for Shadow on purpose. From level 30 the full
view adds one line when the weights' tree can't reach its 31-point talent
by 40 without a respec ("Shadowform at 40 = full respec into Shadow").

## Where it differs from the addon

- **No vendor items.** Polestar's data has quests, drops and crafts only.
- **Bags as of the last logout.** Like the game, items in your bags (and,
  unlike it, your bank) count, from Syndicator's save: the shipper's
  `wow-bags`. Such an upgrade has one source, the bag or the bank ("equip
  it"), and stays listed past the three-a-slot cap. Something picked up
  since the last logout isn't there yet.
- **Random-suffix items** ("of the Owl") keep their stats in the item link,
  which Syndicator saves without them. A worn one scores on the stats
  Battle.net's armory shows for it (the exporter's
  `wow_character_equipped_stat`, when the character is on Battle.net and
  wears the same item as at the daily refresh). Otherwise, and for a
  random-suffix drop or bag item, it scores on its *likely* suffix: the
  median, by your weights, of what the fixed-stat items of the same slot,
  quality and item level (±2) carry beyond armor and damage. Blizzard gives
  a suffix the same stat budget, so half the suffixes it could roll are
  worth less to you and half more. Against a guessed worn item the gain
  shows in points, not percent, and those rows sort after the others. The
  Auction House never offers a random-suffix item: its price is the
  cheapest suffix listed, whatever the stats.
- **Talent ranks.** Polestar reads ranks that change weights (Mental
  Dexterity); the server only has points per tree, and only as of the last
  `/simx`.
- **Weapon skills.** The addon checks what you've trained; the server allows
  every weapon type the class can learn.
- **Handed-in quests** count only from when Polestar Recorder ran: a quest
  done before that still shows.
- With ForeverLevelingBiS 1.x installed, Polestar's Automatic weights may use
  its scores in game. The page never does.

## Checked against Polestar's Lua

`tools/gear_reference/parity.lua` runs the release's `Gear.lua` (with its
`ItemDB.lua`, `Weights.lua`, `SpecData.lua` and `Adjust.lua`) in Lua 5.4 with
a stub client and answers `Gear.CompareToEquipped` for every item.
`tests/test_gear_parity.py` compares weights, usability, score, gain,
percent and slot for all 10,621 items in 11 cases: 9 classes, 7 races,
levels 12 to 60, dual wield, two-handers, player weight edits. No difference
at v0.4.1. CI runs it with the export; locally:

```sh
POLESTAR_CHECKOUT=/tmp/polestar LUA=lua5.4 uv run pytest tests/test_gear_parity.py
```
