Magic NPCs

Magic NPCs lets mobs and NPCs cast real spells from Iron's Spells 'n Spellbooks.

Credit to TheWiggleDuck for the awesome Curseforge project icon!

You can check out example datapacks here to better understand how customization works: Click Here to Visit on GitHub

Turn skeletons into battlemages, give guards healing magic, build elemental NPCs, create custom bosses, or add spellcasting to creatures from other mods. Magic NPCs is a datapack-driven framework designed to work with almost any mob without requiring custom code for each one.

For players, it adds much more varied magical combat and NPC behavior. For modpack authors, it provides detailed control over who can cast, what they cast, how often they cast it, and under what conditions.

Features

Make almost any mob a spellcaster

Spellcasters are defined through datapack loadouts. A loadout can target any registered mob and give it:

• Attack and support spells
• Custom spell levels
• Mana and mana regeneration
• Weighted spell selection
• Minimum and maximum casting ranges
• Individual cooldowns
• Cast chances
• Friendly-fire safety radiuses
• Cast wind-up times
• Native Iron's cast-time overrides
• Starting equipment
• A chance for only some mobs of that type to become casters
• Reactive conditions based on health, nearby enemies, recent damage, and more

Loadouts can also be restricted by biome, dimension, difficulty, height, time of day, moon phase, weather, raids, and other world conditions.

A simple skeleton caster can be created with:

{
  "entity_type": "minecraft:skeleton",
  "max_mana": 100,
  "mana_regen": 10,
  "spells": [
    {
      "spell": "irons_spellbooks:magic_missile",
      "level": 1,
      "weight": 3,
      "max_range": 16.0,
      "role": "attack"
    },
    {
      "spell": "irons_spellbooks:heal",
      "level": 1,
      "role": "support"
    }
  ]
}

Run /reload and existing matching mobs are updated too. You do not need to respawn them.

Real Iron's spellcasting

Magic NPCs does not imitate Iron's spells with simplified effects.

NPCs use the actual Iron's casting lifecycle, including initiation, casting ticks, channeled spells, completion, cancellation, projectiles, particles, sounds, mana costs, and cooldowns.

This means continuous and channeled spells behave like actual spells instead of being reduced to a single instant effect.

Magic NPCs also maintains a reviewed compatibility table for Iron's spells. Unknown or unverified add-on spells are skipped by default rather than consuming mana and silently failing.

Modpack authors can add support for spells from Iron's add-ons through datapack spell manifests, trusted namespaces, or individual capability overrides.

Magic schools

NPCs can be assigned one of Iron's magical schools:

• Fire
• Ice
• Lightning
• Holy
• Ender
• Blood
• Evocation
• Nature
• Eldritch

School casters build their available spells dynamically from the registered spells in that school, allowing them to make use of compatible add-on spells as well.

Schools can be assigned automatically or controlled per NPC with commands and the craftable School Tome.

Use the School Tome on an NPC to inspect its current assignment, or sneak-use it to cycle through available schools.

Smarter caster AI

Magic NPCs is designed to coexist with the mob's normal combat AI.

Each loadout can choose how spellcasting interacts with existing attacks:

• coexist lets the NPC use its normal attacks and spells together
• yield lets spellcasting give way to the NPC's normal attack behavior
• suppress converts the NPC into a dedicated caster by temporarily suppressing compatible attack goals

Suppressed casters also know how to position themselves for their spells. They can approach distant targets, back away when enemies get too close, maintain an appropriate casting range, and stop moving while channeling.

The original attack AI is restored if suppression is later removed.

Support magic outside combat

Support NPCs do not need to enter combat before helping themselves.

A wounded caster can use healing and other support behavior while idle, with a separate configurable decision interval to keep the behavior natural and inexpensive.

Adjustable cast times

Pack authors can speed up or slow down the native casting time of individual spells.

For example:

{
  "spell": "irons_spellbooks:gravity_fissure",
  "cast_time_multiplier": 0.5
}

or:

{
  "spell": "irons_spellbooks:gravity_fissure",
  "cast_time": 6
}

This is separate from the optional pre-cast windup, giving pack authors control over both the warning period and the spell's actual Iron's casting duration.

Spell telegraphs

Dangerous attack spells can visibly warn players before firing.

Telegraphs can use particles based on the spell's magic school, sounds, and an optional glowing outline during the wind-up period.

Pack authors can configure which danger levels should receive telegraphs so minor spells do not create unnecessary visual noise.

Friendly-fire protection

Spellcasters take nearby allies into account before firing.

Protection can cover:

• Owners
• Teammates
• Allied NPCs
• Villagers
• Iron golems
• Tamed animals
• Other protected bystanders
• Players, when enabled

Area-of-effect spells can use larger safety radiuses than ordinary projectiles.

NPC Mod Compatibility

Magic NPCs is built to remain usable without forcing a particular NPC mod into your pack.

Villager Recruits

Villager Recruits has a purpose-built integration.

Recruits:

• Use Recruits' own diplomacy rules when choosing spell targets
• Never intentionally attack their owner or allies
• Respect passive and other command states
• Respect hold-position, follow, movement, and formation orders
• Scale their mana with rank
• Gain higher spell levels as they progress
• Check for allies in their line of fire or blast radius

Curated caster loadouts are included for several Recruit types.

Easy NPC

Easy NPC: Core has a dedicated integration with support for:

• Owner protection
• Faction-aware targeting
• Experience-based caster progression
• Paused NPC state
• Immovable NPCs and home positions
• School assignments
• Spellcasting from Easy NPC dialogs and triggers
• Magic NPCs conditions for dialog options
• A spellcasting objective for Easy NPC's objective system

Pack authors can trigger casts directly from Easy NPC actions with magicnpcs:cast.

The separate Easy NPC configuration UI module is not required.

CustomNPCs

Magic NPCs also includes first-class support for CustomNPCs (GBPort Unofficial).

Because CustomNPCs characters are usually deliberately authored by pack creators, installing Magic NPCs does not automatically turn them into spellcasters. A CustomNPC must be explicitly opted in through a loadout, School Tome or command assignment, or the CustomNPCs school configuration.

The integration understands CustomNPCs information such as:

• Owner
• Faction
• Role
• Job
• AI state
• Movement rules

It also provides integration with CustomNPCs scripting and automatically repairs Magic NPCs casting goals when CustomNPCs rebuilds an NPC's AI.

Owner and faction protections remain respected when deciding whether a spell is safe to cast.

CustomNPCs compatibility is version-checked because the available 1.20.1 build does not provide a stable cross-version API. The currently supported build is CustomNPCs GBPort Unofficial 1.20.1.20260711.

Additional NPC mods

Config-gated datapack compatibility is also available for:

• Guard Villagers
• MCA Reborn
• MineColonies
• Human Companions
• More Villagers
• VillagersPlus

These integrations are disabled by default so installing Magic NPCs does not unexpectedly change existing NPC behavior.

Because the core system works from registered entity types, pack authors can also create their own loadouts for mobs from many other mods.

Built for modpacks

Magic NPCs is highly configurable without requiring Java development.

Pack authors can control:

• Mana and regeneration
• Cooldown scaling
• Casting frequency
• Difficulty scaling
• Spell levels
• NPC progression scaling
• Friendly-fire rules
• Line of sight
• Caster movement
• Support behavior
• Spell telegraphs
• Equipment requirements
• Spell allowlists and denylists
• Whole spell namespaces
• Magic-school generation
• Per-mod compatibility
• Individual shipped loadouts

Most gameplay configuration is server-side and automatically synchronized where needed.

Installation-wide compatibility settings live in config/magicnpcs-common.toml, allowing modpack authors to configure integrations once instead of changing every world individually.

Diagnostics and commands

Magic NPCs includes tools intended to make datapack development and troubleshooting considerably easier.

Find out why an NPC is not casting

/magicnpcs why <entity>

This inspects a live NPC and reports things such as:

• Whether a loadout was applied
• Casting AI status
• Current target
• Line of sight
• Mana
• Cooldowns
• Range
• NPC state restrictions
• Native attack AI conflicts
• The first reason each spell currently cannot be cast

Validate your datapacks

/magicnpcs validate

Shows discovered loadouts and reports whether they are active, replaced, disabled, suppressed, or invalid.

Browse available spells

/magicnpcs spells

Lists registered spells along with useful information such as their school, rarity, cooldown, and NPC compatibility status.

Additional commands are available for loadouts, reconciliation, configuration, spell auditing, and school management.

Requirements

Magic NPCs is currently built for:

• Minecraft 1.20.1
• Forge 47+
• Iron's Spells 'n Spellbooks 1.20.1-3.15.x through 3.16.x for spellcasting

Iron's own dependencies, including GeckoLib, Curios API, and PlayerAnimator, are also required when using Iron's.

Optional integrations include:

• Villager Recruits 1.15.0+
• Easy NPC: Core 7.11.x
• CustomNPCs GBPort Unofficial 1.20.1.20260711

Magic NPCs does not bundle these mods.

The optional integrations are isolated so missing integrations do not prevent Magic NPCs from loading. If Iron's itself is absent, Magic NPCs can still start cleanly, but no spellcasting takes place.

A note about modded mobs

Most ordinary Minecraft mobs and NPC mods use Minecraft's goal-based AI and can be given Magic NPCs casting behavior normally.

A small number of heavily customized mobs use entirely separate brain or animation-driven combat systems and may not run injected Minecraft goals. /magicnpcs why can detect many of these situations so they fail visibly instead of leaving pack authors guessing.

Documentation

For full loadout documentation, spell manifests, compatibility notes, examples, and advanced configuration, see the project's GitHub repository:

Magic NPCs on GitHub

Magic NPCs is open source under the GNU GPLv3 license.