Iron's Spellbooks ↔ Pufferfish's Skills Compat
Bridge Iron's Spells 'n Spellbooks and Pufferfish's Skills. Gate casts and inscribing spells behind unlocked skill nodes or hand out innate spells castable from a keybind with no spellbook needed.
Features
There are 2 main features: blocking the casting and inscribing of spells behind a pufferfish skill node, and allowing players to gain innate spells they can cast without any spellbook.
Spell Casting and Inscribing Restrictions
Skill-gated casting & inscribing. Block a spell at every cast source (spellbook, sword, scroll) and at the inscription table when the player hasn't unlocked the configured skill(s). One data-driven rule format groups spells with the skills they require (AND semantics). Once they unlock the spell they will be able to use the spell again.
Innate Spells
Innate spells. A Pufferfish skill node can grant a spell directly to the player. Castable from a keybind with no spellbook, sword, or scroll required. Casts still consume mana and respect cooldown; they also still flow through the gate above, so the two systems compose. This includes a new spell wheel and cast keybind just for innate spells:
Here is what it looks like on the player HUD. This is a pretty powerful feature, especially if you're willing to make some custom spells. You can configure Iron's to not drop the spell or allow its crafting, and then add it to the skill tree. Easily create custom skill tree only abilities, or just allow players access to existing spells.
Default Keybinds
Chosen specifically to avoid Iron's Spellbooks' defaults (R/V/L-Alt). All rebindable in vanilla controls.
- Hold
C to open the innate spell wheel. Release to commit the highlighted spell as the new selection.
X to cast the currently selected innate spell.- Hold
Z + scroll wheel to cycle through innate spells without opening the wheel.
- Toggle wheel, registered but unbound by default; bind it yourself if you prefer a toggle over hold-to-open.
Getting Started — Skill-Gated Casting
Drop a file at data/your_pack/spell_skill_requirements/anything.json. A rule lists the spells it covers and the skills each of those spells requires:
{
"spells": [
"irons_spellbooks:fireball",
"irons_spellbooks:fire_arrow",
"irons_spellbooks:fire_breath"
],
"requires": [
{ "category": "your_pack:apprentice_mage", "skill": "pyromancy_gate" }
]
}
Semantics: every spell in spells requires every skill in requires (AND). The player can't cast or inscribe any of those spells until they've unlocked all the listed skills. The filename is organizational only, the spell IDs live inside the JSON.
This one shape covers both directions you might think about it:
- One skill gates many spells — list many
spells, one entry in requires (the example above).
- One spell needs many skills — list one spell, multiple
requires:
{
"spells": ["irons_spellbooks:fireball"],
"requires": [
{ "category": "your_pack:apprentice_mage", "skill": "pyromancy_gate" },
{ "category": "your_pack:apprentice_mage", "skill": "fire_mastery" }
]
}
If you have multiple rules that name the same spell, it requires you unlock all of those nodes to unlock the spell. This allows you to make a multi skill unlock if you'd like. It might make more sense to just make the node cost more skill points though, but there it is.
Getting Started — Innate Spells
Drop a file at data/your_pack/innate_spells/anything.json with this shape:
{
"category": "your_pack:apprentice_mage",
"skill": "innate_firebolt",
"spell": "irons_spellbooks:firebolt",
"level": 1
}
When the player unlocks the innate_firebolt node, they get Firebolt in their innate pool at level 1, castable from the keybind. Mana cost and cooldown still apply.
level defaults to 1 if omitted and must be at least 1. If you set a level higher than the spell actually supports, it's clamped down to that spell's maximum (and a warning is logged) so a typo can't cast a spell at an impossible level.
Upgrade chains
Pufferfish nodes are binary (taken / not taken), there's no per-node "rank up" concept. To let a player level up an innate spell, add multiple skill nodes each granting the same spell at progressively higher level, chained via connections.json:
[innate_firebolt level 1] → [innate_firebolt_2 level 2] → [innate_firebolt_3 level 3]
The mod deduplicates by spell ID and keeps the highest level grant. A player who's unlocked all three nodes sees only one Firebolt entry in their wheel at level 3. The lower-level definitions are still useful: they fence the chain (you have to take level 1 before you can take level 2) and they specify the unlock cost per rank.
Client Config
Located at config/irons_spellbooks_pufferfish_compat-client.toml after first launch:
[SelectedInnateSpell] — the always-on badge to the left of the hotbar showing the currently selected innate spell.
display — Always, Contextual (fades in on selection-change/cast), or Never.xOffset / yOffset — pixel offset from the default position (just left of the hotbar).
[InnateWheel] — the hold-to-open radial menu.
ignoreGuiScale — if true, the wheel keeps its size regardless of the GUI scale option.ignoreGuiScaleSizeMultiplier — when ignoreGuiScale is on, multiply the wheel's size by this.
FAQ
Q: Does this work without Iron's Spellbooks installed?
A: No. Both Iron's Spells 'n Spellbooks and Pufferfish's Skills are hard dependencies. This is a compat layer, not a standalone mod. Q: Will you port to Fabric / Forge / older Minecraft versions?
A: This targets NeoForge 1.21.1. No plans to backport or port to other loaders.
Q: Can I use this in my modpack or on my server?
A: Yes, of course.
