Wizards of Lua

Wizards of Lua is a server-side Fabric mod that lets you write spells in Lua and cast them inside Minecraft.

Type a one-liner in the chat for an instant change, or start a long-running spell that reacts to everything happening in your world. No Java or modding experience needed, no server restarts, no client mods.

/lua require "greeting"

Casts a spell using the code from config/wizards-of-lua/greeting.lua.

local queue = spell:collect("PlayerJoinedEvent")
while true do
  local evt = queue:next()
  spell:execute("/say Welcome, " .. evt.player.name .. "!")
end

Greets every player who joins.

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.
• 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
• Guards who hold their posts against hostile mobs without chasing them too far
• A 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 6.1.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.