Entity¶

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

Fields¶

world: World — Read-Only¶

A reference to the world in which the entity exists.

name: string — Read/Write¶

The name of the entity.

uuid: string — Read-Only¶

The UUID of the entity.

type: EntityType — Read-Only¶

The specific type of the entity.

age: number — Read-Only¶

The age of the entity in game ticks.

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" } })

pos: Vec3 — Read/Write¶

The position of the entity in the world.

eyePos: Vec3 — Read-Only¶

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

lookVec: Vec3 — Read-Only¶

The direction vector in which the entity is looking.

facing: string — Read-Only¶

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

pitch: number — Read/Write¶

The pitch rotation angle of the entity.

yaw: number — Read/Write¶

The yaw rotation angle of the entity.

velocity: Vec3 — Read/Write¶

The movement velocity of the entity.

invisible: boolean — Read/Write¶

Indicates whether the entity is currently invisible.

alive: boolean — Read-Only¶

Specifies if the entity is alive.

sprinting: boolean — Read/Write¶

Indicates whether the entity is currently sprinting.

crawling: boolean — Read-Only¶

Specifies if the entity is crawling.

sneaking: boolean — Read/Write¶

Indicates whether the entity is currently sneaking.

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 })

Methods¶

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

Name	Type	Description
`nbt`	`table`	The NBT data to merge, which can include custom properties and attributes.

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

Name	Type	Description
`nbt`	`table`	The extra data to merge into the `extra` field.

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

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 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

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 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

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.

dropItem(object: any, yOffset: number|nil) → 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

Name	Type	Description
`object`	`any`	The item to drop; may be Item, BlockType, or ItemType.
`yOffset`	`number`\|`nil`	Optional vertical offset relative to this entity's position (defaults to 0). Positive drops higher; negative drops lower.

Returns

ItemEntity — item 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

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

Returns

string — result The evaluated text with placeholders replaced.