Globals¶

These variables and functions are available in every Wizards of Lua script without any require.

Variables¶

spell: Spell¶

A reference to the spell that runs this program.

Every Lua program that Wizards of Lua runs is a spell: a /lua command, a file loaded with require, the code of a dynamic command, a startup.lua. spell is available in each of them without any require, and each program has its own.

The spell is the program's place in the world. It has a position and a world, reads and places blocks at its position, summons entities there, executes commands from there, and collects and intercepts events. See Spell for all its properties and functions.

Example

spell.pos = spell.owner.pos + Vec3(0, -1, 0)
spell.block = Block:new("glass")
print("Spell " .. spell.id .. " placed glass in " .. spell.world.dimension)

Functions¶

assert(value: T, fmt?: string, ...: any) → value: T¶

Raises an error with a message formatted like string.format(fmt, ...) if value is false or nil, and otherwise returns value.

It replaces Lua's built-in assert: the arguments after the second one are the values for the format.

Example

assert(radius >= 1, "The radius must be at least 1, not %d.", radius)

Parameters

value: T — The value to check.
fmt?: string — The message, or a format like in string.format.
...: any — The values for the format.

Returns

value: T — value

declare(name: string, superclass_metatable: table?) → metatable: table¶

Declares a new class type with the given name.

This function creates a new class metatable, optionally inheriting from a superclass metatable.

Example

MyClass = declare("MyClass")
SubClass = declare("SubClass", MyClass)

Parameters

name: string — The name of the class to declare.
superclass_metatable: table? — The metatable of the superclass, or nil for a base class.

Returns

metatable: table — The metatable for the newly declared class.

error(fmt?: string, ...: any)¶

Raises an error with a message formatted like string.format(fmt, ...).

It replaces Lua's built-in error: the arguments after the first one are the values for the format, not the error level. Without any argument it raises an error without a message.

Example

if length > 128 then
  error("The length must be at most %d, not %d.", 128, length)
end

Parameters

fmt?: string — The message, or a format like in string.format.
...: any — The values for the format.

inspect(value: any, options?: table) → result: string¶

Converts the given Lua value into a human-readable string representation.

This function is especially useful for printing or logging deeply nested tables, such as configurations, game state, or debug info. It safely handles cyclic references, shared references, metatables, and offers advanced formatting via the process callback.

Example

local t = { foo = "bar", list = {1, 2, 3} }
print(inspect(t))  -- => { foo = "bar", list = { 1, 2, 3 } }

Options

depth (number): Maximum depth to recurse into nested tables. Default: math.huge.
newline (string): Line separator used in output. Default: "\n".
indent (string): Indentation string per level. Default: " " (two spaces).
metatables (boolean): Whether to include metatables. Default: true.
process (fun(value: any, path: table): any): Callback to transform values before they’re printed. Receives the value and its path in the table.

Example with Options

local t = { player = { name = "Steve", score = 42 } }
print(inspect(t, {
  depth = 1,
  indent = "\t",
  metatables = false
}))

Example with process Option

print(inspect(gameData, {
  process = function(value, path)
    if type(value) == "string" and #value > 50 then
      return "<string truncated>"
    end
    return value
  end
}))

Parameters

value: any — The Lua value to inspect (usually a table, but can be any type).
options?: table — Formatting options (see above).

Returns

result: string — A formatted string representing the structure and content of the value.

instanceOf(class_metatable: table, object: table) → result: boolean¶

Checks whether the given object is an instance of the specified class.

This performs a recursive check using metatable inheritance.

Example

if instanceOf(MyClass, obj) then
  print("This is an instance of MyClass!")
end

Parameters

class_metatable: table — The metatable of the class to check against.
object: table — The object to check.

Returns

result: boolean — true if the object is an instance of the class, false otherwise.

log(value: any, ...: any)¶

Sends a message to the configured logging target, independently of the sendCommandFeedback gamerule.

The log(...) function behaves like Lua's built-in print(...), but its output is controlled by the WizardsOfLua.log setting. This allows consistent debugging output even when command feedback is globally suppressed.

See WizardsOfLua.log for details on how to configure the output target.

Example

log("Spell is active at", spell.pos)
log("Block type:", spell.block.type.id)

Parameters

value: any — The first value to log.
...: any — Additional values to log, all will be converted to strings and space-separated.

logToConsole(value: any, ...: any)¶

Writes a message to the server console and the server log, regardless of the WizardsOfLua.log setting.

The logToConsole(...) function formats its arguments like print(...) and log(...). Use it for output that must end up in the server log, for example from a spell started by the server console, a command block or a remote console (RCON), where print(...) has no one to show its output to.

Example

logToConsole("Spell", spell.id, "started at", spell.pos)

Parameters

value: any — The first value to log.
...: any — Additional values to log, all will be converted to strings and space-separated.

sleep(ticks?: number)¶

Pauses this program's execution for the specified number of game ticks.

If no ticks value is given, the spell automatically yields for one tick once it has used up half of its per-tick operation budget (see Spell.tickLimit, default 50000). This gives the game a chance to process other work before the spell continues.

Example: Pause the spell's execution for 20 ticks

sleep(20) -- pauses for 1 second (assuming 20 ticks per second)

Parameters

ticks?: number — The number of game ticks to pause for. If omitted, yields once half the spell's tick limit is reached.

str(obj: any) → result: string¶

Converts the given object into a string representation.

This is a simplified alias for inspect(obj, { metatables = false }), omitting metatables for cleaner output.

Example

print(str({foo = "bar"}))  -- => { foo = "bar" }

Parameters

obj: any — The object to convert.

Returns

result: string — A string representation of the object.

type(value: any) → type: string¶

Returns the type of the given value as a string.

It works like Lua's built-in type, but knows the classes of Wizards of Lua and those declared with declare: for an instance it returns the name of its class, e.g. "Vec3" or "Entity", and for a class itself "class". For all other values it returns what Lua's type returns, e.g. "number", "string", "table" or "nil".

Example

print(type(spell.pos))   -- Vec3
print(type(spell.owner)) -- Player
print(type(42))          -- number

Parameters

value: any — The value whose type to return.

Returns

type: string — The name of the value's class or type.