Skip to content

Wizards of Lua — Getting Started

Before you begin, set up a mod loader for Minecraft, one of these:

Wizards of Lua comes as a separate JAR for each loader. Most features work the same on both; the FAQ lists the differences.

Cast Your First Spell

In Wizards of Lua, a Spell is a running Lua script that executes inside the Minecraft world. Think of it like a lightweight process that you launch with /lua.

1) Download the latest mod JAR for your Minecraft version and loader from Modrinth (wizards-of-lua-fabric-...jar or wizards-of-lua-neoforge-...jar) and place it in the mods folder of your Minecraft installation.

Note: On Fabric, optionally install the Placeholder API into the same mods folder to enable placeholder evaluation.

2) Launch Minecraft and enter your world.
You need extended permissions to use /lua and /wol:

  • For multiplayer: make sure you're an operator with permission level 2 or higher.
  • For singleplayer: create your world in Creative mode.

3) Open the chat (press T) and type:

/lua print("Hello, Wizard!")

4) You should see:

Hello, Wizard!

Congratulations. You've just cast your first spell!

Using Lua Script Files

Scripts are written in Lua 5.3.
You can store your .lua files in the config/wizards-of-lua folder and load them using the require keyword.

Example:

1) Create a file at config/wizards-of-lua/test.lua with the following code:

local hit = spell.owner:raycastBlock(5)
if hit then
  spell.pos = hit.blockPos
else
  spell.pos = spell.owner.eyePos + spell.owner.lookVec * 5
end
spell.block = Block:new("stone")

2) In Minecraft, run:

/lua require "test"

This command creates a new spell, loads your script from the file system, and places a stone block at the position you're looking at.

Wizards of Lua API

The Lua API Reference documents the classes and functions available for manipulating blocks, entities, and responding to game events.

Autocompletion in Visual Studio Code

Wizards of Lua supports full IntelliSense for easier scripting in Visual Studio Code.

Setup

1) Install Visual Studio Code.

2) Install the Lua Language Server extension.

3) In Minecraft, run:

/wol extract api

This extracts the API files into your config/wizards-of-lua/api folder.

Note: After updating the mod, run this command again to refresh the API files to the latest version.

4) Open the config/wizards-of-lua folder in VS Code.

5) Press Ctrl+Shift+P and select Developer: Reload Window to force a reload.

You now have autocompletion and type hints while writing scripts.

Edit Scripts on a Remote Server

You can edit Lua scripts directly on a remote Minecraft server using Visual Studio Code.

1) Open VS Code.
2) Install the Remote - SSH extension.
3) Follow the step-by-step tutorial to connect.

Managing Spells

You can manage your active spells using these commands:

For more control, such as breaking spells by name or ID, see the Commands reference.

What's next?