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.
Credit and licences
Section titled “Credit and licences”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.
How the file is made
Section titled “How the file is made”tools/gear_reference/export.mjs runs Polestar’s own files, nothing built:
- A shallow clone of Polestar at the release tag, the same tag as the route
times (
POLESTAR_TAGin.github/workflows/route-reference.yml, moved by hand when kb-refresh’s watcher reports a new Polestar release). tools/gear_reference/dump.lualoadsGear/ItemDB.lua, then the data addon’sItems.luaandForever.luain the order of its.toc, thenWeights.luaandSpecData.lua, each in an empty environment (noio,osorload). Items are parsed byItemDB.Get, sources byItemDB.Sources, quests byItemDB.Quest, so the file reads the data the way the addon does.- 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:
git clone --depth 1 --branch v0.4.1 https://github.com/fitzforge/polestar /tmp/polestarnode tools/gear_reference/export.mjs --polestar /tmp/polestarCI 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
Section titled “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
Section titled “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.luaGear.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 inwow-gearasgear_adjust) apply on top, asAdjust.luadoes. - 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
turninrecords). A quest that offers a choice shows its best reward only (Rewards.luaRankChoices). 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:
- The selector on the page (kept in the browser).
1b. The site’s
WEIGHTSsetting for that character (docs/deploy.md): the player’s choice, kept where the site runs. - Polestar’s Stat weights setting for the class, when it isn’t Automatic
(
PolestarDB.settings.gear.spec, shipped aspolestar_spec). - The talent tree with the most points, as Polestar’s Automatic picks it
(
Gear.luaDetectSpec,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 (talentsinwow-gear). - The spec the player picked in a gear addon: ForeverLevelingBiS or
GearQuestForever’s SavedVariables (
specinwow-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. - 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
Section titled “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
Section titled “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:
POLESTAR_CHECKOUT=/tmp/polestar LUA=lua5.4 uv run pytest tests/test_gear_parity.py