Spell¶

Represents a spell in the game, providing methods for interacting with the world, entities, and events.

Fields¶

world: World — Read/Write¶

A reference to the world in which the spell exists.

id: number — Read-Only¶

The ID of the spell.

name: string — Read/Write¶

The name of the spell.

owner: Entity — Read-Only¶

A reference to the entity that owns or cast this spell.

age: number — Read-Only¶

The age of the spell in game ticks.

pos: Vec3 — Read/Write¶

A copy of the position of the spell in the world.

lookVec: Vec3 — Read-Only¶

A copy of the direction vector in which the spell is looking.

facing: string — Read-Only¶

The compass direction this spell is facing. One of ‘north’, ‘east’, ‘south’, and ‘west’.

pitch: number — Read/Write¶

The pitch rotation angle of the spell.

yaw: number — Read/Write¶

The yaw rotation angle of the spell.

velocity: Vec3 — Read/Write¶

A copy of the velocity of the spell.

block: Block — Read/Write¶

A copy of the block at the spell's position.

blockEntity: BlockEntity — Read-Only¶

A reference to the block entity at the spell's position, if any.

forceChunk: boolean — Read/Write¶

Specifies whether the chunk containing this spell should stay loaded in memory. Default is true.

visible: boolean — Read/Write¶

Specifies whether this spell is visible to players. Default is false.

server: Server — Read-Only¶

Reference to the Minecraft server.

tickLimit: number — Read/Write¶

The per-tick execution budget for this spell, measured in Lua operations. When the budget is exhausted, the spell automatically yields and resumes next tick. Default is 50000. Increasing the value lets a spell do more work in one tick (potential TPS impact); lowering makes it yield more often for smoother pacing.

biome: string — Read-Only¶

The biome ID at the spell’s current position (e.g., "plains", "forest", "ocean"). The value reflects the biome at spell.pos and changes as the spell moves.

Methods¶

execute(command: string, trace: Trace|nil) → result: number¶

Executes a Minecraft command on behalf of this spell.

By default, the command's output is sent to the spell's command source. To inspect the output programmatically instead, you can pass a Trace object to capture it.

The return value is the command result value as defined by the Minecraft command system: usually the number of entities or blocks affected by the command.

Example

spell:execute("say Hello, World!")

Example with Trace

local trace = Trace:new()
local result = spell:execute("/data get entity @p", trace)
print("Command returned: " .. result)
print("Command output:\n" .. trace.content)

Parameters

Name	Type	Description
`command`	`string`	The command to execute.
`trace`	`Trace`\|`nil`	Optional. A `Trace` object to collect the command's output.

Returns

number — result The command result value, usually representing the number of entities or blocks affected.

executeSilent(command: string, trace: Trace|nil) → result: number¶

Executes a Minecraft command silently on behalf of this spell.

In contrast to spell:execute, this version does not forward the command's output to the spell’s command source. You can use a Trace object to capture the output programmatically.

The return value is the command result value as defined by the Minecraft command system: usually the number of entities or blocks affected by the command.

Example

spell:executeSilent("say Hello, World!")

Example with Trace

local trace = Trace:new()
local result = spell:executeSilent("/data get entity @p", trace)
print("Command returned: " .. result)
print("Command output:\n" .. trace.content)

Parameters

Name	Type	Description
`command`	`string`	The command to execute.
`trace`	`Trace`\|`nil`	Optional. A `Trace` object to collect the command's output.

Returns

number — result The command result value, usually representing the number of entities or blocks affected.

sleep(ticks: number)¶

Pauses this spell's execution for a specified number of game ticks.

Example

spell:sleep(40)  -- Pauses for 2 seconds (assuming 20 ticks per second)

Parameters

Name	Type	Description
`ticks`	`number`	The number of game ticks to pause for.

summon(id: string, nbt: table|nil) → entity: Entity¶

Summons an entity with the given entity ID at the spell's position. Optionally, merges a subset of NBT data into the newly created entity.

Example

local pig = spell:summon("pig", { CustomName = { text = "Grumpy Pig", italic = true, color = "gold" } })
print("Summoned entity:", pig.name)

Parameters

Name	Type	Description
`id`	`string`	The ID of the entity to summon.
`nbt`	`table`\|`nil`	Optional NBT data to merge into the entity.

Returns

Entity — entity A reference to the summoned entity. The returned entity may be a subclass of Entity.

findEntities(selector: string) → list: Entity[]¶

Finds and returns a list of entities matching the specified selector.

Example

local nearbyZombies = spell:findEntities("@e[type=zombie,distance=..10]")
for _, entity in ipairs(nearbyZombies) do
    print("Found entity:", entity.name)
end

Parameters

Name	Type	Description
`selector`	`string`	The selector used to find entities (e.g., "@e[type=zombie,distance=..10]").

Returns

Entity[ ] — list A table of references to entities that match the selector criteria.

findSpells(criteria: table) → list: Spell[]¶

Finds and returns a list of spells that match the given search criteria.

Example: Search by name:

local spellsByName = spell:findSpells({ name = "My Spell" })
for _, s in ipairs(spellsByName) do
    print("Found spell:", s.name)
end

Example: Search within a radius by owner:

local nearbySpells = spell:findSpells({ owner = "MickKay", maxradius = 50, excludeSelf = true })
for _, s in ipairs(nearbySpells) do
    print("Nearby spell owned by MickKay:", s.name)
end

Example: Search by spell ID:

local specificSpell = spell:findSpells({ sid = 1029 })
if specificSpell[1] then
    print("Found spell with ID 1029:", specificSpell[1].name)
else
    print("No spell found with ID 1029.")
end

Parameters

Name	Type	Description
`criteria`	`table`	The search criteria. Can include: - `name` (string): The spell's name. - `owner` (string): The owner's name. - `tag` (string): A tag associated with the spell. - `sid` (number): The spell ID. - `maxradius` (number): Maximum radius for the search. - `minradius` (number): Minimum radius for the search. - `excludeSelf` (boolean): Whether to exclude this spell.

Returns

Spell[ ] — list A table of references to spells that match the criteria.

collect(...: string) → queue: EventQueue¶

Collects events matching the specified names into an event queue.

Example

local queue = spell:collect("ChatMessageEvent", "PlayerJoinedEvent")
while true do
    local event = queue:next()
    if event then
        print("Collected event:", event.name)
    end
    sleep(20)
end

Parameters

Name	Type	Description
`...`	`string`	The names of events to collect.

Returns

EventQueue — queue The event queue collecting matching events.

intercept(names: table, callback: function) → interceptor: EventInterceptor¶

Intercepts events matching the specified names and handles them using a callback. To cancel an event, return false from within the callback.

The interceptor stays active only while the spell is running. If the spell ends, the interceptor stops automatically.

Example

local interceptor = spell:intercept({"BeforePlayerBlockBreakEvent"}, function(evt)
  local blockName = evt.block.type.id
  if blockName == "short_grass" then
      spell.pos = evt.pos:floor() + Vec3(0.5, 0, 0.5)
      spell:summon("pig", { Pos = evt.pos, Saddle = true })
      return false
  end
  return true
end)

-- Keep the spell running so the interceptor remains active
while true do
  sleep(20)
end

Parameters

Name	Type	Description
`names`	`table`	A table of event names to intercept.
`callback`	`function`	A function that handles events. Return `true` to allow, `false` to cancel.

Returns

EventInterceptor — interceptor An interceptor that manages the event interception.

raycastBlock(maxDistance: number) → hit: BlockHitResult|nil¶

Issues a raycast from this spell’s position and returns the first block hit. See also Entity:raycastBlock.

Parameters

Name	Type	Description
`maxDistance`	`number`	The maximum distance to cast the ray.

Returns

BlockHitResult|nil — hit The result of the raycast, indicating the block hit.

raycastEntity(maxDistance: number) → hit: EntityHitResult|nil¶

Issues a raycast from this spell’s position and returns the first entity hit. See also Entity:raycastEntity.

Parameters

Name	Type	Description
`maxDistance`	`number`	The maximum distance to cast the ray.

Returns

EntityHitResult|nil — hit The result of the raycast, indicating the entity hit.

raycast(maxDistance: number) → hit: HitResult|nil¶

Issues a raycast from this spell’s position and returns the first block or entity hit. See also Entity:raycast.

Parameters

Name	Type	Description
`maxDistance`	`number`	The maximum distance to cast the ray.

Returns

HitResult|nil — hit The result of the raycast, indicating the first block or entity hit.

fire(name: string, data: table|nil) → proceed: boolean¶

Fires a custom event with the specified name and optional data.

This method triggers a CustomEvent that can be intercepted or collected by other spells. If any interceptor returns false, the event is considered canceled, and this method returns false.

If the optional data table is provided, it is passed by reference to all receivers. That means interceptors and collectors can directly mutate its contents, and the changes will be reflected in the original table after the event is fired.

Example: Event without data

local proceed = spell:fire("CustomSpellEvent")
if proceed then
    print("Event handled without cancellation.")
else
    print("Event was canceled.")
end

Example: Event with shared data

local payload = { message = "Hello World!", count = 1 }
local proceed = spell:fire("CustomSpellEvent", payload)
if not proceed then
    print("Event was canceled.")
end
print("Modified count:", payload.count)

Receiver example

spell:intercept({ "CustomSpellEvent" }, function(event)
  event.data.count = event.data.count + 1
end)

In this example, after spell:fire(...), the payload.count will be incremented by the receiver.

Parameters

Name	Type	Description
`name`	`string`	The name of the custom event.
`data`	`table`\|`nil`	Optional table passed to event handlers; can be modified by them.

Returns

boolean — proceed true if the event was not canceled; false otherwise.

move(direction: string, distance: number|nil)¶

Moves this spell's position in the specified direction by a given distance.

Accepts absolute directions ("north", "south", "east", "west", "up", "down") and relative directions ("forward", "back", "left", "right"). Relative directions use the spell's current yaw rotation.

The distance is measured in blocks. If omitted, the spell moves by 1 block.

Example: Move 5 blocks north

spell:move("north", 5)

Example: Move up by 2 blocks

spell:move("up", 2)

Example: Move forward in the direction the spell is facing

spell:move("forward", 3)

Parameters

Name	Type	Description
`direction`	`string`	The direction to move: "north", "south", "west", "east", "up", "down", "forward", "back", "left", or "right".
`distance`	`number`\|`nil`	Optional. The distance to move. Defaults to 1 block.

evaluate(text: string) → result: string¶

Evaluates the given text using the Placeholder API. This function requires the Placeholder API jar to be present in the mods folder.

Example

local text = "Number of players online: %world:player_count%"
local value = spell:evaluate(text)
print(value)

Parameters

Name	Type	Description
`text`	`string`	The text to evaluate using the Placeholder API.

Returns

string — result The evaluated text with placeholders replaced.

copyStructure(oppositeCorner: Vec3, includeEntities: boolean|nil, ignoreBlockId: string|nil) → structure: Structure¶

Copies a box-shaped region of the world as a structure.

The region is defined by the spell's position and the opposite corner. The copied structure can be pasted into the world or saved to the server's filesystem.

Example: Copy and paste a structure

local oppositeCorner = spell.pos + Vec3(10, 5, 10)
local struct = spell:copyStructure(oppositeCorner)
spell.pos = spell.pos + Vec3(0, 0, 15)
spell:pasteStructure(struct)

Example: Copy and save a structure

local oppositeCorner = spell.pos + Vec3(10, 10, 10)
local struct = spell:copyStructure(oppositeCorner)
local filepath = spell.server:saveStructure("arena", struct)
print("Structure saved at " .. filepath)

Parameters

Name	Type	Description
`oppositeCorner`	`Vec3`	The corner position opposite to the spell's current position. Defines the region to copy.
`includeEntities`	`boolean`\|`nil`	Optional. Copy entities within the region. Default is false.
`ignoreBlockId`	`string`\|`nil`	Optional. Block ID to ignore when copying. Default is none.

Returns

Structure — structure The copied structure object.

pasteStructure(structure: Structure, originPos: Vec3|nil, ignoreBlockIds: table|nil)¶

Pastes a structure into the world at the spell's position.

By setting originPos, you choose which block in the structure’s internal coordinate system will be placed at the spell’s position. If not provided, (0, 0, 0) is used. Before placement, the structure is rotated clockwise around originPos to match the spell’s facing property: "south" = 0°, "east" = 90°, "west" = -90°, "north" = 180°.

Example: Paste a loaded structure (default origin)

local struct = spell.server:loadStructure("arena")
spell:pasteStructure(struct)

Example: Paste using a different origin block

-- Use the block at (5, 0, 0) in the structure as origin and pivot, placing it at spell.pos
spell:pasteStructure(struct, Vec3(5, 0, 0))

Example: Ignore certain blocks when pasting

spell:pasteStructure(struct, nil, { "minecraft:air" })

Parameters

Name	Type	Description
`structure`	`Structure`	The structure to paste.
`originPos`	`Vec3`\|`nil`	Optional. Block in the structure to use as the origin and rotation pivot. Default is Vec3(0,0,0).
`ignoreBlockIds`	`table`\|`nil`	Optional. Table of block IDs to ignore when pasting.

setYaw(direction: string)¶

Sets the spell's yaw so that it faces the given compass direction.

Valid directions: "north", "south", "west", "east".

The spell’s yaw property will be updated to the angle corresponding to the direction.

Example

spell:setYaw("north")
print(spell.yaw) -- prints 180

Parameters

Name	Type	Description
`direction`	`string`	The compass direction: "north", "south", "west", or "east".