Changelog

2.2 — The Big Fix Release (June 23, 2026)

This is the release players were waiting for.

After the 1.21.1 port, most of the real pain points from CurseForge reports and in-game testing were still there — mages that forgot who they were, spellbooks vanishing into racks, recruitment UI breaking, and channel spells that fizzled out in half a second. 2.2 tackles those head-on.

We rebuilt the mage guard from the ground up instead of patching around the Druid job. The result: a proper JobMage with its own AI, spellbook equipment type, and casting logic that follows Iron's Spellbooks' own mob cast cycle — the same rules Fire Breath and other continuous spells use in the base mod.

Spellbook request system — refactored (heavily reported)

If you ever had a mage stuck asking for the same thing over and over, or a clipboard full of duplicate guard requests — this is the fix.

We replaced the old Druid-style Tool request path (equipment levels, Wood/Gold ore icons, repeated checkIfRequestForItemExistOrCreateAsync calls) with a dedicated MageSpellbookRequestHelper built on MineColonies StackList requests.

What changed:

• Request spam stopped — pending-request tracking, dedup of open/completed requests, and cancellation of stale Tool-type spellbook requests so the mage does not open a new ticket every few seconds
• Player-facing message fixed — "I need a spellbook with at least one spell to continue working." instead of nonsense tier text (Wood/Gold) that never matched Iron's Spellbooks
• UI icons fixed — cycling sprites are grimórios only (SpellBook class + path filter), not every Iron's item (scrolls, staffs, crossbows, etc.)
• EntityAIMage owns the flow — spellbook checks bypass the generic guard Tool request and go through one shared helper used by both guard AI and combat handler
• Player takeaway: one mage = one spellbook request until you fulfill or cancel it. No more request avalanche on the clipboard.

Fixed (critical — most reported issues)

• Profession loss on world reload — custom JobMage replaces the Druid runtime clone; citizens deserialize with the correct job instead of needing re-hire
• Spellbook deposited in guard rack — dedicated spellbook equipment type + EntityAIMage no longer inherits Druid rack behaviour
• Missing recruitment module (minecoloniesmages_mage_work) — robust registry injection on both dedicated server and client; errors logged if registration fails
• Continuous / long Iron's Spells not completing — casting now mirrors AbstractSpellCastingMob: correct initiateCast duration, per-tick handleCastDuration, periodic onCast for CONTINUOUS spells (e.g. Fire Breath cone), proper onServerCastComplete cleanup
• Legacy save migration — citizens that still had JobDruid + mage marker are one-shot migrated to JobMage on reconciliation
• Reconciliation giving up too early — extended retries (up to 720 attempts) when persisted mage IDs are present; persistence marked on hire, not only on world unload
• Spellbook request spam & broken request UI — refactored to MageSpellbookRequestHelper + StackList: single deduplicated request per mage, correct message, grimório-only display icons; legacy Tool requests auto-cancelled (REQUEST-SPAM-FIX)

Changed

• New architecture: JobMage → EntityAIMage → MageCombatAI → MageCastingController (Gunner-style MineColonies pattern)
• Visual: mage guards use the Druid model (fits spellcaster fantasy better than archer)
• Mixin surface reduced — job registration mixin uses JobMage::new producer; research hook mixin kept only where no public MC 1.21.1 API exists (documented in README)
• Spellbook requests — centralized in MageSpellbookRequestHelper; EntityAIMage.checkForToolOrWeapon routes spellbook needs away from MineColonies generic Tool/equipment-level requests

Technical notes for pack makers

• Requires Minecraft 1.21.1, NeoForge 21.1+, MineColonies 1.1.1319-1.21.1+, Iron's Spellbooks 1.21.1-3.16.0+
• Not compatible with 1.20.1 / Forge builds
• Existing colonies: mages should auto-migrate on first load after update; if a citizen was stuck jobless before, give reconciliation a few seconds after login

Recommended quick test after updating

1. Recruit 2+ mages → save / quit / rejoin → professions intact

2. Equip spellbook → open Guard Tower → no missing-module error

3. Fire Breath (or any channel spell) in combat → full duration cone

4. Send mage back to post → spellbook not in rack

5. Mage without grimório → one spellbook request on clipboard (correct text + grimório icon); cancel → no duplicate flood

Thank you to everyone who reported issues on CurseForge and helped reproduce these — this release is directly shaped by that feedback.