Skip to content

Wizards of Lua — Frequently Asked Questions

Where do I save my custom scripts?

Place your .lua scripts in the config/wizards-of-lua/ directory or any of its subfolders. You can organize them however you like and reference them from other scripts or the /lua command using Lua’s require keyword.

How can I include a script file from the /lua command?

For example, if a script file is located at config/wizards-of-lua/mickkay/hello.lua, you can include it like this:

/lua require "mickkay.hello"

How do I cast a spell in the Nether?

By default, a spell is created in the same dimension as the caster. You have three options for casting in the Nether:

  • Cast directly while inside the Nether. The spell stays active even after you leave.
  • Cast remotely using the /execute in command:

/execute in the_nether run lua print("This spell is at " .. spell.pos:floor() .. " in " .. spell.world.dimension)
- Move an existing spell to the Nether by assigning its world:

/lua spell.world = spell.server:getWorld("the_nether"); print("This spell is at " .. spell.pos:floor() .. " in " .. spell.world.dimension)

How do I cast a spell on server startup?

Create a file named startup.lua inside the config/wizards-of-lua/ folder or one of its subdirectories:

print("This is executed during the startup sequence")

At startup, the mod recursively searches for all startup.lua files and launches them. Files in upper directories run first, and subdirectory files are launched afterward.

Tip: You can manually trigger the startup sequence with:

/wol startup

How long does a spell stay active?

A spell is a running Lua script that continues until it completes or is stopped. Spells execute as Lua coroutines on the main game thread until they either complete or hit the per-tick limit (currently 50,000 Lua operations). When that limit is reached, the coroutine yields and picks up exactly where it left off at the start of the next tick.

You can also call spell:sleep(n) to pause your spell’s coroutine for n game ticks, even if you haven’t reached the per-tick limit. Once the sleep period ends, the coroutine automatically resumes.

How do I stop an active spell?

You can break all your active spells using:

/wol spell break

This is especially helpful if a spell enters an infinite loop or causes unexpected behavior.

How do I hide spell output?

An active spell sends feedback in two cases:

  1. When you use print(...), its output is sent as command feedback.
  2. When you run commands using spell:execute(...), their output is also sent as command feedback.

You can globally suppress all command feedback using this gamerule:

/gamerule sendCommandFeedback false

However, this is often too broad, as it affects all commands. You can achieve better results by only suppressing the output of spells:

Suppressing print(...) Output

Use log(...) instead of print(...). This logs messages through the WizardsOfLua.log system, which gives you fine-grained control.

You can configure the log target by setting the WizardsOfLua.log property to one of:

  • "source" — the command source that ran the spell
  • "operators" — all online operators
  • "console" — only the server console
  • "none" — discard all output

For full details, see the WizardsOfLua module documentation.

Suppressing Command Feedback from spell:execute(...)

Instead of spell:execute(...), use:

spell:executeSilent(...)

This executes the command without sending any feedback to the command source. You can still capture the output manually with a Trace object if needed.

How do I add a custom method to an existing class?

You can extend any Wizards of Lua class (such as Entity, Spell, Vec3, etc.) by defining new methods in your own Lua files.

For example, to add a say method to all Entity objects, place the following code in a new file — for example, extensions.lua:

function Entity:say(text)
  spell:execute("execute as " .. self.uuid .. " run say " .. text)
end

Usage

To use this in your script, load the file using require:

require "extensions"

spell.owner:say("Hi there!")
This will make the spell caster say “Hi there!” in chat.

Note: You must include require "extensions" in every script where you want to use say.

How do I override an existing method?

You can override existing methods of Wizards of Lua classes by saving a reference to the original method and then redefining it with custom behavior.

For example, to log a message every time an Entity drops an item, place the following code in a new file — for example, extensions.lua:

local _dropItem = Entity.dropItem

function Entity:dropItem(object, yOffset)
  log("dropping item " .. object.name)
  return _dropItem(self, object, yOffset)
end

This wraps the original method and adds a log message before calling the original implementation.

Usage

To use the overridden method, load the file using require:

require "extensions"

local item = spell.owner:dropItem(Item:new("diamond_sword"), 4)

This will print dropping item diamond_sword to the log and drop the item as usual.

Note: You must include require "extensions" in every script where you want the overridden method to apply.

What's next?