Wizards of Lua

Wizards of Lua is a server-side Fabric mod that lets you write spells in Lua and cast them inside Minecraft. No Java or modding experience needed, no server restarts, no client mods.

Type a one-liner in the chat to change something on the spot:

/lua spell:move("down"); spell.block = Block:new("gold_block")

Turns the block at your feet into gold.

Or start a long-running spell that reacts to everything happening in your world:

/lua require "midas"

Starts the spell in config/wizards-of-lua/midas.lua which turns every block a player hits into gold:

local queue = spell:collect("PlayerAttackBlockEvent")
while true do
  local event = queue:next()
  spell.pos = event.pos
  spell.block = Block:new("gold_block")
end

Browse the Examples to see what else you can build with a few lines of Lua.

Get Started

The Quickstart Video walks you through installing the mod and casting your first spell in under two minutes. The Getting Started Guide covers the same ground in writing, and goes on from there.

What You Can Do

• Run Lua in-game: Cast spells with the /lua command, either as inline code or from files in config/wizards-of-lua. Edited files are recompiled the next time they're used, so no server restart is needed.
• Change the world: Place blocks, summon mobs, edit items and entities, all through an extensive Lua API.
• Give mobs orders: Send any mob walking to a spot, following or fleeing from someone, standing guard or attacking a target. An order only borrows the mob's attention: when it's done, the mob goes back to its own business.
• Play with bots: Spawn bot players that join like real players and that spells control: they walk, fight, dig, build and chat, so you can play-test a mini-game alone or have companions at your side.
• React to events: Respond when players join, break blocks or swing tools, and cancel or extend what happens next.
• Add your own commands: Register Brigadier commands at runtime, with typed arguments and auto-completion.
• Code with autocompletion: Write spells in Visual Studio Code with full type support.
• Stay in control: Spells run on a per-tick budget and yield automatically, so a busy spell doesn't freeze your server. Access is controlled by permission levels and nodes, compatible with LuckPerms. Use /wol spell list all to see what's running and /wol spell break all to stop it.
• Install on the server only: Works in singleplayer and multiplayer. Players don't need to install anything.

What People Build

• Safe zones where PvP is disabled
• Minecarts that climb ladders
• A magic wand that strikes hostile mobs with lightning
• A spider bodyguard that stays at your side and attacks whoever hurts you
• Piglin guards who hold their posts against hostile mobs without chasing them too far
• A squire, a bot player who follows you, fights at your side behind its shield, and holds a spot when you tell it to
• A piglin miner who digs a tunnel, lights it with torches, and fetches a fresh pickaxe from a chest when his breaks
• A lumberjack spell that makes the whole tree fall when any player breaks a single log
• A magic hoe that harvests a whole wheat field with one swing
• Mini-games like Journey

Versioning

Versions follow the format MAJOR.MINOR.PATCH-MCVERSION, for example 7.0.0-1.21.11. The first part follows Semantic Versioning and describes compatibility with your scripts. The part after the - is the Minecraft version.

Updates that raise MINOR or PATCH are safe. If MAJOR increases, check the changelog first, because your scripts may need changes.

Learn More

This mod is a complete rewrite for Fabric of the original Wizards of Lua for Forge, which is no longer maintained. The two APIs differ, and scripts written for the Forge version won't run unchanged.

New here? Watch the Quickstart Video, then find guides, examples and the full API reference at wizards-of-lua.net.