Winefox's Spellbooks

中文说明 · Minecraft 1.21.1 · NeoForge · MIT

Bridges Touhou Little Maid and Iron's Spells 'n Spellbooks: maids read spellbooks, manage mana and pick their own spells, and players can summon maids onto the battlefield in return.

Mod Overview

Winefox's Spellbooks turns the maids of Touhou Little Maid into real spellcasters: put a spellbook in her accessory slot and she picks spells to suit the situation, budgets her mana, respects cooldowns, strafes and repositions — and plays a casting animation if she uses a GeckoLib model.

Beyond that main line, the mod also provides:

• Winefox Hex — a standalone school with its own damage type and attributes, built around player–maid teamwork: the player opens, the maid follows up, and fighting together pays far better than fighting apart;
• Addon compatibility — behaviour classifications for several hundred spells across 15 Iron's Spells addons. Installed addons take effect automatically; missing ones cause no errors.

About the name: casting animations only play on GeckoLib maid models, and "Winefox" is one such model.

Quick Start

1. Install the dependencies: Touhou Little Maid and Iron's Spells 'n Spellbooks, plus their own dependencies (Curios, GeckoLib).
2. Install this mod.
3. Give the maid a spellbook with spells inscribed and put it in her accessory slot, or give her an imbued weapon / armour piece.
4. Open the maid GUI and switch her task to Magic Attack or Magic Support.
5. With Show spell names in spell battle enabled (the default), the spell she is casting appears above her head.

Maid Spellcasting

Casting Media

Her main hand, armour slots, maid accessory slots and Curios slots are all scanned; spells in any "spell container" (spellbook, imbued weapon, imbued armour) enter her spell list.

• Only one spellbook takes effect at a time, same as for players; imbued gear is not subject to that limit and stacks.
• Spell level = the spell's own level + the Affinity bonus from gear.
• A spell that belongs to no behaviour category is ignored — the most common reason for "she just won't cast that spell". See Seven Behaviour Categories.
• Any change of equipment recalculates the spell list immediately; after /reload updates the spell tags, loaded maids rescan as well.

The Two Tasks

Magic Attack is the regular combat role: seek targets, reposition, cast, and optionally finish with a melee weapon.

Magic Support never starts a fight. It heals, buffs and cleanses the owner and same-team creatures (including other maids of the same owner), and debuffs enemies along the way.

Both tasks share the same unlock condition: an imbued weapon in the main hand or armour slots, or a spellbook with inscribed spells in an accessory slot.

Seven Behaviour Categories

A maid's spell list is split into seven behaviour categories; the in-game config screen uses these same names. Each category also has an English field name in the spell tags and the loadout datapack:

Two further marker tags take no part in classification: summon_spells (summons) and maid_should_recast_spells (needs several casts). They only mark a spell; they do not decide whether a maid may cast it.

Mana

• A maid has her own mana bar, independent of the player's; point at her with Jade to see it.
• The cap uses the same formula as for players: "Max Mana" affixes on staves and mage gear apply, and the Maximum mana multiplier option scales the whole thing.
• Natural regeneration defaults to roughly 2% per second, modified by mana regen affixes.
• Having been struck by lightning is a permanent flag saved on the maid — one strike and it never wears off. With Lightning-struck maids regenerate mana 100x faster enabled, such maids refill the entire bar every 0.5 seconds, which is effectively unlimited mana. That option is off by default.

How a Maid Picks a Spell

She makes a decision every short interval (upper bound set by Max combo delay tick, 10 ticks by default):

1. Drop what cannot be cast right now: anything short on mana or still on cooldown. If a multi-cast spell is unfinished, she finishes it first.
2. Weight every behaviour category, pick one category by weighted random, then pick a spell within it with equal probability.

Rules of thumb for the weights:

• The lower an ally's health, the higher the Ally Heal weight; a dying ally outranks everything else;
• With allies nearby, support categories dominate the round and combat categories sit it out;
• The lower her own health, the higher the Defense and Movement weights;
• With no line of sight to the target she rarely picks attack spells, and repositions instead;
• If an ally lacks a buff, or carries a debuff that can be cleansed, the matching spell's weight rises sharply;
• If Defense / Negative Effect was picked last round, both weights drop, so she does not spam the same category.

The search radius comes from Maximum spell attack search range (64 blocks by default), and enemies carrying a Crescent Brand are preferred. She has to close to Start spell casting range (15 blocks by default), or the spell's own casting distance, before she starts.

Other combat behaviour:

• Positioning: backs off inside half her range, circles in place while in range and in sight, moves slower while casting, and stops repositioning when told to sit.
• Melee finisher: controlled by Allow maids to use melee weapons during spell attacks, on by default.

Casting Animations

The mod wires Iron's Spells' casting animations into Touhou Little Maid's animation system; maids on GeckoLib models play the matching animation when they cast.

Model pack authors can define animation clips prefixed with iss: in their own animation files; for the key names see Touhou Little Maid's iss.animation.json.

The animation assets are converted from Iron's Spells' originals. A few poses may have bone misalignment; these will keep being fixed in later versions.

Winefox Hex School

Winefox Hex is the standalone school added by this mod, with its own damage type and two attributes (Winefox Hex Spell Power / Winefox Hex Magic Resist), stackable with mage gear affixes from Iron's Spells itself.

It is designed for "player + maid": its spells pass value back and forth between the two — the player brands, the maid follows up and detonates, and the mantle and cleanse the player casts also cover nearby maids. Solo play works, but a squad of maids is its complete form.

The school is still growing; later versions will keep adding new directions.

School Items

The school's scrolls also appear by chance in stronghold libraries, nether fortresses and Iron's Spells' Pyromancer Tower, Catacombs and Citadel library chests. The mod ships a creative tab holding both items and every level of every school scroll.

Spell List

Brand Detonation and Brewsurge

Currently the clearest expression of "player + maid" teamwork in the school:

1. Brand an enemy with Crescent Brand (12s base, +1s per level).
2. Deal any Winefox Hex damage to it — Foxshade Wisps, the Foxshade Ambush bite and a direct Vintner's Bomb hit all qualify.
3. The brand detonates at once: damage = 10 base + the spell power at the time it was applied.
   • Detonated by the player: 3-block radius, no chaining;
   • Detonated by your own maid: ×1.5 damage, 4-block radius (5 blocks at full player Brewsurge), and it can chain-detonate the next branded target.
4. Every detonation gives the player one stack of Brewsurge: rolling 10-second refresh, up to 3 stacks, each granting +10% school spell power. Maid detonations count for the player as well.

A brand that simply expires does a small self-detonation within 2 blocks (3 points of vanilla magic damage, no Brewsurge stack, no chaining).

In short: the player brands, the maid detonates — keep the detonations flowing and Brewsurge never lapses.

Tipsy

Tipsy is a neutral effect. It deals no damage, but a creature under it:

• moves 30% slower (scaled by effect level);
• staggers while walking and has its facing jitter randomly (players are exempt from the jitter, since their view is client-side);
• fires arrows and other projectiles far off target.

Your own maids are immune to Tipsy Mist and wine pools.

Summon Maid

One of the school's spells: summons a squad of temporary maids to help finish the current fight.

• The count grows with level (2 at level 1, 7 at level 6, and higher still with spell power gear) and they last 10 minutes. Casting the spell again during that time does not add another squad — it dismisses the existing one early.
• Each maid rolls a model at random and rolls gear and spells by summon level; some ride a broom into the air and cast while circling above the summoner.
• They cannot be interacted with, take no orders and never sit; they simply fight alongside the summoner. They drop no gear on death and vanish when their time runs out. By default creepers also actively avoid them.

Three built-in loadouts (replaceable or extendable by datapack):

Each loadout has three tiers by summon level — 1–2, 3–4 and 5–6. Higher tiers mean more complete armour, more spells and a higher spell level cap.

Summoned maids are currently on the strong side, and later versions will keep adding balance limits (count, duration, permitted spells may all change). To rein them in now, adjust the caps under Summoned Maid in the config — the defaults already limit them to level 3, Epic rarity and no learned-only school (i.e. Eldritch) spells. You can also swap the loadouts out with a datapack.

Addon Support

The mod ships behaviour classifications for the Iron's Spells addons below. Installed addons take effect automatically; missing ones cause no errors (the first row is Iron's Spells itself):

Spells that need several casts (Cataclysm, Requiem, Fire's Ender Expansion and others) have dedicated handling, so maids finish the remaining casts just like players do.

Spells that are not covered cause no errors; maids simply never pick them. Add a classification under Spell Compatibles in the config, or classify them yourself with datapack tags.

Configuration

Everything is server config (in multiplayer the server's settings win). Edit it from the config screen in the mod list, or in <world>/serverconfig/winefoxs_spellbooks-server.toml. The second column below is the key in that file.

Combat & AI

Flying Maids

Summoned Maid

Vulpine Anima Morning Gift

Spell Compatibles

Used to add spells from addons or datapacks to the behaviour categories. Each of the seven categories has an "Extra … spell ids" list; for the screen names and keys see Seven Behaviour Categories. Four more entries live here:

⚠️ This section can only add, never remove, and changes need a game restart. To stop a maid casting a spell, see the next section.

Datapack Customisation

Excluding Spells

Which spells a maid may cast is decided by spell tags. To ban one (a friendly-fire heavy AoE, say), remove it from its tag with a datapack.

Create <world>/datapacks/<your-pack>/pack.mcmeta:

{ "pack": { "pack_format": 48, "description": "Maid spell blacklist" } }

Then <your-pack>/data/winefoxs_spellbooks/tags/irons_spellbooks/spells/attack_spells.json:

{
  "values": [],
  "remove": [
    { "id": "irons_spellbooks:fireball" }
  ]
}

Run /reload and it takes effect: the spell catalog rebuilds at once and loaded maids rescan their spell lists.

Behaviour tags (a spell belongs to exactly one; removing it from that one is enough — see Seven Behaviour Categories for the tag name of each category).

To find out which tag holds a given spell, open this mod's jar with any archiver and look in data/winefoxs_spellbooks/tags/irons_spellbooks/spells/ — the seven behaviour tags and the two marker tags are all there as json, holding the mod's default classification. Copy one as the starting point for your own pack.

Marker tags — removing an entry from summon_spells or maid_should_recast_spells only drops the summon / multi-cast marker; the maid still casts the spell.

⚠️ Config extras are merged after tags, so do not list the same spell id in extraAttackSpells and friends — it would be added straight back.

Casting Range and Applied Effects

Under data/<namespace>/magic_maid_spell_data/:

• default_casting_range.json — the distance at which a maid starts casting each spell;
• default_caused_effect.json — declares which mob effect a spell applies, so a maid can tell whether to re-apply a buff or cleanse a debuff on a target.

Both take effect on /reload; matching entries in the config file take priority over the datapack.

Summoned Maid Loadouts

Under data/<namespace>/summoned_maid_loadouts/<name>.json; minimal skeleton:

{
  "weight": 40,
  "broom_mode": "default",
  "tiers": [
    {
      "conditions": [
        { "condition": "winefoxs_spellbooks:summon_level", "min": 1, "max": 2 }
      ],
      "spell_level_cap": 3,
      "weapon": {
        "rolls": 1,
        "entries": [ { "type": "tag", "expand": true, "name": "modid:weapon_tag" } ]
      },
      "armor": {
        "helmet": {
          "chance": 0.3,
          "pools": [ { "rolls": 1, "entries": [ { "type": "tag", "expand": true, "name": "modid:helmet_tag" } ] } ]
        }
      },
      "spells": {
        "attack": {
          "rolls": { "min": 1, "max": 2 },
          "entries": [ { "type": "tag", "expand": true, "name": "modid:attack_spells" } ]
        }
      }
    }
  ]
}

Fields:

• weight — selection weight; 0 disables the loadout;
• broom_mode — always / never / default (roll the chance);
• model_filter (optional) — { "mode": "all" | "allowlist" | "denylist", "models": [...] };
• tiers[].conditions — currently supports the min / max range of winefoxs_spellbooks:summon_level;
• tiers[].spell_level_cap — the tier's spell level cap, combined with the config option by taking the lower;
• tiers[].weapon / armor / spells — item and spell pools; rolls accepts an integer or { "min": n, "max": m }, and entries reference item tags / spell tags;
• the keys under spells are the seven behaviour categories: attack, defense, movement, support, positive_effect, negative_effect, support_other (see Seven Behaviour Categories).

The built-in warrior.json, mage.json and support.json work as templates.

Morning Gift Drops

The morning gift's contents come from the loot table winefoxs_spellbooks:gameplay/maid_morning_gift (95% for one Vulpine Anima by default); modpacks can override it to hand out something else.

Commands

Both require permission level 2:

/wsb cast <targets> <spell> [level]
/wsb summon [target] [count] [summonLevel] [loadout] [duration] [airForce]

• /wsb cast — makes the given entities cast a spell, level 1–10. It only skips the pre-cast availability checks and still consumes mana, so raise the target's mana cap before testing.
• /wsb summon — with no arguments, summons for yourself. count 1–10, summonLevel 1–10, loadout takes a loadout id (random if left out), duration is in seconds (-1 for permanent), and airForce forces broom riding on or off.

Compatibility & Integration

• Curios — spellbooks occupy the spellbook slot defined by Iron's Spells; a maid wears at most one. Accessories is supported as an alternative.
• Jade — point at a maid to see her mana; point at a summoned maid to also see her spell count, and hold Shift for the full list.
• JEI — every item from this mod has an info page (the "i" in the top right).
• Advanced Loot Info — the loot this mod injects into chests, and the maid morning gift, both show their odds in JEI / EMI / REI.
• Patchouli — 12 guide entries under the "Winefox's Spellbooks" category of Touhou Little Maid's Memorizable Gensokyo, covering mana, casting media, tasks, animations, mod integration, troubleshooting, the school with its items and spells (summoned maids included), datapacks, commands and config.

FAQ

She does not cast at all. Check in order:

1. Is her task set to Magic Attack / Magic Support?
2. Is the spellbook in an accessory slot, and are its spell slots inscribed?
3. Does the spell belong to a behaviour tag? Spells outside every behaviour category are ignored.
4. Is there enough mana, and is the cooldown over? A "Spell reloading" bubble means one of the two.
5. Is the enemy beyond Maximum spell attack search range, or has she not yet closed to Start spell casting range?

Her AoE spells keep hitting allies. Remove that spell from its behaviour tag with a datapack and run /reload.

My config change did nothing. Changes under Spell Compatibles need a game restart; datapack-side changes only need /reload.

Why won't maids cast Summon Maid? By design — that spell is reserved for players (and /wsb summon); a maid will not use it to summon another squad of maids.

My support maid never heals anyone. Magic Support only acts on same-team targets, and she also needs spells in the matching categories (Ally Heal / Ally Buff) before she switches to support behaviour.

Requirements & Versions

Casting animations only work on maids using a GeckoLib model; other models cast normally but play no animation.

License

Released under the MIT License. You are free to use, modify and distribute it, provided you retain the original copyright notice.