Skip to content

fix(Core): trainer rank chains skip ranks the player has outranked - #848

Merged
Xian55 merged 3 commits into
Xian55:devfrom
0x5d0:fix/trainer-rank-chain
Sep 14, 2026
Merged

Xian55 merged 3 commits into
Xian55:devfrom
0x5d0:fix/trainer-rank-chain

Conversation

@0x5d0

@0x5d0 0x5d0 commented Sep 13, 2026 •

Copy link
Copy Markdown

Treats SPELL_ arrays as ordered rank chains: once a rank in the chain is known, every entry below it is settled and no longer offered for training. The Spell Book page reads the same skip point through the same helper, so the table cannot disagree with what the bot will do.

Why lower ranks go missing

Classic has two rank mechanics, and both are live on the same client. Measured by dumping the spellbook, one macro per spell name:

/run for i=1,400 do local nm,rk=GetSpellBookItemName(i,"spell") if nm=="Battle Shout" then local _,id=GetSpellBookItemInfo(i,"spell") print(i,nm,rk,id) end end
/run for i=1,400 do local nm,rk=GetSpellBookItemName(i,"spell") if nm=="Raptor Strike" then local _,id=GetSpellBookItemInfo(i,"spell") print(i,nm,rk,id) end end
25 Battle Shout Rank 4 11549          <- level 32 warrior, ranks 1-3 trained and gone

11 Raptor Strike Rank 1 2973          <- hunter, all three ranks trained and still listed
12 Raptor Strike Rank 2 14260
13 Raptor Strike Rank 3 14261
ability cost spellbook after upgrading ids listed
Battle Shout (warrior, rank 4 known) 10 rage, flat at every rank highest rank only 11549
Raptor Strike (hunter, ranks 1-3 known) 24 mana, scales per rank every rank 2973, 14260, 14261

Mana abilities keep their ranks so they can be downranked. Rage and energy abilities gain nothing from downranking - the cost is identical at every rank - so the client replaces the entry instead, and the lower id is simply gone from the spellbook.

That is the bug, on stock clients, with the profiles this repo ships. Walking Json/class/Warrior_1-10.json's "SPELL_BATTLE_SHOUT": [6673, 5242, 6192, 11549, 11550, 11551, 25289] on a level 32 warrior:

  • 11549 is in the book, so it reads Known
  • 6673, 5242, 6192 are not in the book, and their levels (1, 12, 22) are all met, so GetState reads them Trainable
  • HasTrainableSpell therefore never clears, ClassTrainer fires on every TRAIN_COOLDOWN_SEC, and the bot walks to a trainer that offers none of them - the addon answers TRAINER_NO_MATCH and the whole thing repeats

Every warrior and rogue profile in the repo is exposed: SPELL_BATTLE_SHOUT, SPELL_CHARGE, SPELL_REND, SPELL_THUNDER_CLAP, SPELL_OVERPOWER, SPELL_SUNDER_ARMOR in the warrior profile alone. Hunter and caster chains are unaffected, because every owned rank still answers HasExact and already read Known.

A single id cannot be judged on its own here: 6673 not being in the spellbook is indistinguishable from a rank that was never trained. Only the chain says otherwise - it sits below a rank the character owns, so there is nothing left to learn there. The same reasoning covers ids that are wrong for the running client: ranks deleted on Cata and MoP, profiles carrying ids from another client version, or NPC-only rows such as 9128 Battle Shout that no trainer ever sells.

Changes

  • TrainerSpells.FirstUnsettledRank - one helper, used by Any, Collect and the page, giving the index where a chain starts being interesting
  • TrainableState.Superseded - a rank below one already owned, but not in the spellbook at this exact id. Distinct from Known, which means the player actually holds that rank; rendered as an "Outranked" badge with its own count
  • Collect skips settled ranks outright, so they no longer reach unknownIds either - an id below the owned rank is not a spells.json gap worth reporting

Relies on the ascending order VAR_PREFIX already documents, and answers 0 until AllRanksReceived, the same condition Any and Collect already refuse to answer before.

Ranks cannot be skipped on the way up - the trainer gates rank N behind rank N-1, tooltip "Requires: Level 16, Raptor Strike (Rank 2)" - so a settled prefix is always a contiguous one, which is what makes a single skip index enough.

Verified

Level 12 warrior, live client: with the chain unlearnt 9128 reads Trainable; after learning 6673 it reads Known and 9128 flips to Outranked. Test profile and screenshot in the comments.

The trainer's own gating is visible with:

/run local n=GetNumTrainerServices and GetNumTrainerServices() or 0 for i=1,n do local nm,rk,cat=GetTrainerServiceInfo(i) print(i,nm,rk,cat) end

run at an open trainer - it prints each service as available, unavailable or used, which is the same category the addon buys on.


Original report by @0x5d0:

Fixes trainer rank handling when a higher spell rank is already learned.

Previously, lower ranks could still be treated as trainable if their exact spell ID was no longer present in the spellbook, which could cause repeated trainer visits.

This change makes SPELL_ arrays behave as ordered rank chains and updates the "Spell Book" Web UI to use the same logic.

Tested with Raptor Strike rank upgrades.

0x5d0 and others added 3 commits September 13, 2026 17:27
Keeps the rank-chain skip and reshapes what it reports.

FirstUnsettledRank replaces FirstRankAfterHighest and GetRankState. One public
helper answers where a chain starts being interesting, so both callers ask the
same question instead of the UI going through a second entry point that recomputed
the skip point on every row - a full scan with a set probe per rank, per rank.
RebuildTrainer now computes it once per group and reads each rank with the GetState
it always used.

A rank below the one already owned is not Known: the player does not hold that
exact rank, the spellbook has no such entry, and the Known doc says it does. The
page said "Known" anyway and counted it in that total. TrainableState.Superseded
names the real case, gets its own Outranked badge and its own count, and leaves
Known meaning what it claims. A state with no case in the razor switch renders as
"Not in client", so the badge is required, not cosmetic.

Collect skipping settled ranks also stops them reaching unknownIds. That is the
right call - an id below the owned rank is not a spells.json gap - but it was
silent, so it is written down now.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PbJSLQ8UTBTn1Dw69shnTf
@Xian55 Xian55 changed the title Fix trainer handling of learned higher spell ranks fix(Core): trainer rank chains skip ranks the player has outranked Sep 14, 2026
@Xian55

Xian55 commented Sep 14, 2026 •

Copy link
Copy Markdown
Owner

Good catch on the underlying rule - "a rank below one you already own is not trainable" cannot be expressed in GetState(id, ...), which sees a single id with no chain context, so a chain-aware entry point is the right shape. Builds clean here and the bot-side change is correct as written: GetState already returns Known for owned ranks, so starting the loop at the skip point only changes verdicts for unowned ids below an owned rank, which is exactly the reported case.

Pushed a commit that keeps the mechanism and reshapes what it reports.

One helper instead of two entry points. FirstUnsettledRank replaces FirstRankAfterHighest plus GetRankState, so the bot and the page ask the same question of the same method. GetRankState recomputed the skip point on every row - a full scan with a HasExact probe per rank, once per rank - which makes RebuildTrainer quadratic in chain length. It now computes it once per group and keeps using the GetState it always used.

Known was being claimed for ranks the player does not hold. GetRankState returned TrainableState.Known for everything below the skip point, RebuildTrainer counted it in knownCount, and the badge read "Known" - while the enum's own doc says "Already in the spellbook at this exact rank". For the case this PR is about, that exact id is precisely what is not in the spellbook. Added TrainableState.Superseded with an "Outranked" badge and its own count, so Known keeps meaning what it says. Worth knowing for any future state: the razor switch has a default: arm rendering "Not in client", so a new member without a case silently mislabels itself.

Collect no longer reports skipped ranks through unknownIds. Side effect of starting the loop at the skip point. It is the right call - an id below the rank already owned is not a spells.json gap worth surfacing - but it was silent, so there is now a comment saying so.

Left alone: the ascending-order assumption, which VAR_PREFIX already documents, and the page's behaviour before AllRanksReceived - it already warns there, and the warning text still fits now that the skip point is derived from HasExact too.


Verified in game

Level 12 Warrior
image

Tested with a purpose-built profile rather than by reasoning about it. Result on a live client: with the chain unlearnt, 9128 reads Trainable; after learning 6673 it reads Known and 9128 flips to Outranked.

That is the whole mechanism end to end - the skip point moves to index 1, the UI override fires, and Superseded renders through the new badge case instead of falling into the razor default: arm as "Not in client". Bot side follows from the same helper: Any/Collect start at index 1, so 9128 stops answering HasTrainableSpell and the repeat trainer walk ends.

The trick is the decoy id. On a Classic client every rank you own stays in the spellbook and answers HasExact, so a real learnable rank cannot reproduce this - you need an id inside the chain the character can never hold. 9128 is a Battle Shout row that exists in every era's spells.json (som, tbc, wrath, cata, mop, legacy_cata, legacy_mop) at Level 1 and is NPC-only, so it stands in for a rank the client dropped, with no setup.

Json/class/_/Warrior_trainer_rank_test.json
{
  // Trainer rank-chain test bed. Loads, stands still, and fills the Spell Book page's
  // Class Trainer table with one row per state so the verdicts can be read off directly.
  //
  // WHY A DECOY ID
  // Classic clients keep every rank in the spellbook, so a lower rank of a spell you own
  // normally answers HasExact = true and reads Known on its own. The bug this exercises
  // needs the opposite: an id inside the chain that the player can never hold. 9128 is
  // exactly that - a "Battle Shout" row present in som, tbc, wrath, cata, mop and both
  // legacy DBs, Level 1, never granted to a player. Sitting below real ranks it stands in
  // for a rank the client dropped, with none of the setup.
  //
  // Before the rank-chain fix, 9128 reads Trainable forever: not in the book, level 1, so
  // nothing gates it. HasTrainableSpell stays true, and the bot walks back to the trainer
  // on every pass to learn something no trainer sells. After the fix it is Outranked the
  // moment any later rank in the chain is known.
  //
  // EXPECTED TABLE, level 12 warrior who has just learned Battle Shout rank 1, on
  // tbc/wrath. This is the run in the PR screenshot:
  //
  //   9128   Battle Shout   Outranked     <- the fix; said "Known" in the first draft of
  //                                          the PR and "Trainable" before it
  //   6673   Battle Shout   Known         rank 1
  //   5242   Battle Shout   Trainable     rank 2, level 12 reached and not yet bought
  //   6192   Battle Shout   Level 22      rank 3
  //   11549  Battle Shout   Level 32      rank 4
  //   11550  Battle Shout   Level 42      rank 5
  //   11551  Battle Shout   Level 52      rank 6
  //   25289  Battle Shout   Level 60      rank 7
  //   999999 #999999        Not in client no such row in any spells.json
  //
  // Only the 9128 row changes with the fix. Every rank below the highest one owned is
  // settled, so buying rank 2 moves the skip point up and 6673 stays Known either way -
  // the decoy is the only entry whose verdict the chain logic decides.
  //
  // Turn on "Show all ranks" - the table hides everything but Trainable by default.
  //
  // CROSS-CLIENT: on cata/mop (4.3.4, 5.4.8, 4.4.x, 5.5.x) ranks were deleted, so 5242
  // through 25289 have no spells.json row and the whole middle of the table reads
  // "Not in client" while 6673 survives at a different level. That is the other half of
  // the picture worth eyeballing, and it is why the chain is left un-trimmed here.
  //
  // The trainer goal is wired but starves: HasTrainableSpell is false once every real
  // rank is Known or Level locked, which is the point - the bot should stop going.
  // To make it go, uncomment SPELL_TEST_NEVER_KNOWN below.
  "ClassName": "Warrior",
  "KeyboardOnly": true,

  // Nothing that could pull the character into combat or move it off the spot.
  "Loot": false,
  "Skin": false,
  "TargetNeutral": false,
  "NPCMaxLevels_Above": 0,
  "NPCMaxLevels_Below": 0,

  "IntVariables": {
    // Short, so a trainer visit can be retried without waiting ten minutes.
    "TRAIN_COOLDOWN_SEC": 30,

    // Ascending rank chain with a decoy at the bottom and a dead id at the top.
    "SPELL_TEST_BATTLE_SHOUT": [9128, 6673, 5242, 6192, 11549, 11550, 11551, 25289, 999999]

    // Negative control: a chain that is nothing but the decoy, so no later rank can ever
    // settle it. Stays Trainable, keeps HasTrainableSpell true, and sends the bot to the
    // trainer on every pass - the hole the rank-chain fix cannot close, since an id with
    // no known rank above it is indistinguishable from one that is genuinely trainable.
    // Uncomment to watch the trainer goal fire and the addon answer TRAINER_NO_MATCH.
    //,"SPELL_TEST_NEVER_KNOWN": [9128]
  },

  // Any real path will do - the character is not meant to walk it. Northshire is the
  // smallest starting route in the repo.
  "PathsFilenames": [
    "1-8_Human_Northshire.json"
  ],
  "Paths": [],

  "Pull": {
    "Sequence": []
  },
  "Combat": {
    "Sequence": []
  },
  "NPC": {
    "Sequence": [
      {
        "Name": "ClassTrainer",
        //"TrainAll": true,
        "Requirements": [
          "HasTrainableSpell",
          "Money > 100",
          "SecondsSinceTrained > TRAIN_COOLDOWN_SEC"
        ],
        "Cost": 6.1
      }
    ]
  }
}

State at level 12 with rank 1 just learned - the run in the screenshot above, on tbc/wrath:

id rank before this PR PR as first pushed now
9128 NPC row, never learnable Trainable Known Outranked
6673 1 Known Known Known
5242 2 Trainable Trainable Trainable
6192 3 Level 22 Level 22 Level 22
11549 … 25289 4 - 7 Level locked Level locked Level locked
999999 none, dead id Not in client Not in client Not in client

9128 is the only row the chain logic decides - every real rank answers for itself through GetState, and buying rank 2 just moves the skip point up without changing any verdict but the decoy's.

Flip Show all ranks on to see them - the table hides everything but Trainable by default.

Since measured, and it turned out to be the stronger case. Classic runs two rank mechanics side by side on one client:

/run for i=1,400 do local nm,rk=GetSpellBookItemName(i,"spell") if nm=="Battle Shout" then local _,id=GetSpellBookItemInfo(i,"spell") print(i,nm,rk,id) end end
/run for i=1,400 do local nm,rk=GetSpellBookItemName(i,"spell") if nm=="Raptor Strike" then local _,id=GetSpellBookItemInfo(i,"spell") print(i,nm,rk,id) end end
25 Battle Shout Rank 4 11549          <- level 32 warrior, ranks 1-3 trained and gone

11 Raptor Strike Rank 1 2973          <- hunter, all three ranks trained and still listed
12 Raptor Strike Rank 2 14260
13 Raptor Strike Rank 3 14261

Mana abilities keep every rank so they can be downranked. Rage and energy abilities cost the same at every rank, so downranking buys nothing and the client replaces the entry - the lower id leaves the spellbook entirely.

So the decoy was standing in for something warriors and rogues do on their own, and this is a live bug against the profiles in this repo rather than id-drift insurance. On a level 32 warrior, Json/class/Warrior_1-10.json's SPELL_BATTLE_SHOUT chain reads 11549 Known and 6673 / 5242 / 6192 Trainable - levels 1, 12 and 22 all met, none of them in the book - so HasTrainableSpell never clears and the trainer walk repeats against a trainer selling none of them. SPELL_CHARGE, SPELL_REND, SPELL_THUNDER_CLAP, SPELL_OVERPOWER and SPELL_SUNDER_ARMOR are the same shape. Hunter and caster chains were never affected, which is why the original Raptor Strike test looked clean.

The decoy still earns its place in the test profile: it reproduces this on classes that do keep their ranks, and covers the other half - ids that are wrong for the running client, whether deleted on Cata and MoP, carried over from another client version, or NPC-only rows no trainer sells.

@Xian55 Xian55 added bugfix This pull request fixes an issue. ai Artificial Intelligence tool has been contributed. labels Sep 14, 2026
@Xian55
Xian55 merged commit cdbcdd9 into Xian55:dev Sep 14, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ai Artificial Intelligence tool has been contributed. bugfix This pull request fixes an issue.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants