Skip to content

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’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.

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 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 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, 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.

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:

Terminal window
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.

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.

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 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”).

  • 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.

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:

Terminal window
POLESTAR_CHECKOUT=/tmp/polestar LUA=lua5.4 uv run pytest tests/test_gear_parity.py