Entity¶

Represents an in-game entity, providing properties and methods for interacting with it.

Fields¶

age: number — Read-Only¶

The age of the entity in game ticks.

alive: boolean — Read-Only¶

Specifies if the entity is alive.

crawling: boolean — Read-Only¶

Specifies if the entity is crawling.

extra: table — Read/Write¶

A copy of custom dynamic data associated with the entity. This data is persisted alongside the regular NBT and can be used to store arbitrary script-defined state. Like nbt, this field returns a copy. Changes must be reassigned or applied via putExtra(...).

Example:

local copy = entity.extra
copy.tagged = true
entity.extra = copy
-- or directly
entity:putExtra({ tagged = true })

eyePos: Vec3 — Read-Only¶

A copy of the position of the entity’s eyes, often used for vision or raycasting.

facing: string — Read-Only¶

The compass direction this entity is facing. This is one of ‘north’, ‘east’, ‘south’, and ‘west’.

invisible: boolean — Read/Write¶

Indicates whether the entity is currently invisible.

lookVec: Vec3 — Read-Only¶

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

name: string — Read/Write¶

The name of the entity.

nbt: table — Read/Write¶

A copy of the NBT (Named Binary Tag) data attached to the entity. Changes to this table are not automatically applied to the entity.

To persist changes, either:

Modify the copy and reassign:

local copy = entity.nbt
copy.CustomName = { text = "Grumpy Pig", italic=true, color="gold" }
entity.nbt = copy

Use putNbt(...) to merge changes directly:

entity:putNbt({ CustomName = { text = "Grumpy Pig", italic=true, color="gold" } })

pitch: number — Read/Write¶

The pitch rotation angle of the entity.

pos: Vec3 — Read/Write¶

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

sneaking: boolean — Read/Write¶

Indicates whether the entity is currently sneaking.

sprinting: boolean — Read/Write¶

Indicates whether the entity is currently sprinting.

type: EntityType — Read-Only¶

The specific type of the entity.

uuid: string — Read-Only¶

The UUID of the entity.

velocity: Vec3 — Read/Write¶

A copy of the movement velocity of the entity.

world: World — Read-Only¶

A reference to the world in which the entity exists.

yaw: number — Read/Write¶

The yaw rotation angle of the entity.

Methods¶

dropItem(object: any, yOffset?: number) → item: ItemEntity¶

Drops a copy of an item as an item entity from this entity's position with an optional vertical offset.

The original item is not consumed or removed from any inventory. If you want to remove it from a player's hand or inventory, do so explicitly after calling this.

Example

local item = spell.owner:getItemInHand("MAIN_HAND")
spell.owner:dropItem(item, -2)
spell.owner:setItemInHand("MAIN_HAND", nil) -- Clears the item from the player's main hand

Parameters

object: any — The item to drop; may be Item, BlockType, or ItemType.
yOffset?: number — Vertical offset relative to this entity's position. Defaults to 0. Positive drops higher; negative drops lower.

Returns

item: ItemEntity — A reference to the dropped item entity.

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 player = spell.owner
local text = "%player:name%'s ping: %player:ping%"
local value = player:evaluate(text)
print(value)

Parameters

text: string — The text to evaluate using the Placeholder API.

Returns

result: string — The evaluated text with placeholders replaced.

kill()¶

Kills this entity, marking it as no longer alive and removing it from the game.

Example

local entities = spell:findEntities("@e[type=pig]")
for i, v in ipairs(entities) do
    if v.nbt.Saddle == 1 then
        v:kill()
    end
end

putExtra(nbt: table)¶

Merges the given data into the entity's extra field. Use this to store custom script-defined values that persist with the entity.

Example

spell.owner:putExtra({notes = "temporary invincibility", expires = 600})
print(spell.owner.extra.notes)

Parameters

nbt: table — The extra data to merge into the extra field.

putNbt(nbt: table)¶

Merges the specified NBT data into this entity's existing data.

Example

local pig = spell:summon("pig")
pig:putNbt({ equipment = { saddle = { id = "saddle" } } })

Parameters

nbt: table — The NBT data to merge, which can include custom properties and attributes.

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

Issues a raycast from this entity's eye position in the direction of its look vector, and returns a HitResult indicating the first block or entity encountered within the specified distance.

Example

local function scan()
    local o = spell.owner
    local h = o:raycast(8)
    if h then
        if h.type == "ENTITY" then
            ---@cast h EntityHitResult
            print("\"" .. h.entity.name .. "\"", h.entity.type.id)
        elseif h.type == "BLOCK" then
            ---@cast h BlockHitResult
            if spell.block.type.id ~= "air" then
                print("\"" .. spell.block.type.name .. "\"", spell.block.type.id)
            end
        end
    end
end
while true do
    scan()
    sleep(20)
end

Parameters

maxDistance: number — The maximum distance to cast the ray.

Returns

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

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

Issues a raycast from this entity's eye position in the direction of its look vector, and returns a BlockHitResult indicating the first block encountered within the specified distance.

Example

local function scan()
    local o = spell.owner
    local h = o:raycastBlock(5)
    spell.pos = h.blockPos
    if spell.block.type.id == "air" then
        return
    end
    print("\"" .. spell.block.type.name .. "\"", spell.block.type.id)
end
while true do
    scan()
    sleep(20)
end

Parameters

maxDistance: number — The maximum distance to cast the ray.

Returns

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

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

Issues a raycast from this entity's eye position in the direction of its look vector, and returns an EntityHitResult indicating the first entity encountered within the specified distance.

Example

local function scan()
    local o = spell.owner
    local h = o:raycastEntity(8)
    if h then
        print("\"" .. h.entity.name .. "\"", h.entity.type.id)
    end
end
while true do
    scan()
    sleep(20)
end

Parameters

maxDistance: number — The maximum distance to cast the ray.

Returns

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