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: CompassDirection — Read-Only

The compass direction this entity is facing.

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:

1. Modify the copy and reassign:

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

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

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

Assigning a table replaces the whole NBT: keys the table omits are removed. To remove single values, use removeNbt(...). The UUID can't be changed: writing a new one is ignored.

Text components such as CustomName are tables in this Minecraft version, e.g. { text = "Grumpy Pig" }. Minecraft 1.21.4 and earlier used JSON strings ('{"text":"Grumpy Pig"}'). Written here, such a string is taken as literal text, without an error.

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("mainhand")
spell.owner:dropItem(item, -2)
spell.owner:setItemInHand("mainhand", 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.

isHiddenFrom(player: Player) → hidden: boolean

Tells whether this entity is hidden from the given player, see setHiddenFrom.

Example

local player = spell.owner --[[@as Player]]
for _, entity in ipairs(spell:findEntities("@e[type=armor_stand,distance=..20]")) do
  if entity:isHiddenFrom(player) then
    print("You don't see the armor stand at", entity.pos)
  end
end

Parameters

• player: Player — The player to check.

Returns

• hidden: boolean — true if the entity is hidden from the player.

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(nbtOrPath: table|string, value?: any) → changed: integer?

Merges NBT data into this entity. There are two forms:

• putNbt(nbt) merges the table into the entity's NBT. Keys the table omits are left alone. List entries in Items, Inventory, EnderItems, active_effects and attributes are matched by Slot or id; other lists are merged by position.

• putNbt(path, value) merges value at every tag the NBT path matches, with the same rules, and returns the number of changed tags. Missing keys along the path are created. The path uses the syntax of the /data command, so it can select list elements by content.

In a path, filters are SNBT and must match the stored type exactly (Slot:0b, not Slot:0), and ids are namespaced ("minecraft:speed"). A filter that matches nothing changes nothing.

Example

local pig = spell:summon("pig")
pig:putNbt({ equipment = { saddle = { id = "saddle" } } })
pig:putNbt("NoAI", 1)
pig:putNbt('active_effects[{id:"minecraft:speed"}]', { amplifier = 2 })

Parameters

• nbtOrPath: table|string — The NBT data to merge, or an NBT path.
• value?: any — The value to merge at the path. Required when nbtOrPath is a path.

Returns

• changed: integer? — The number of changed tags if a path was given, otherwise nil.

raycast(maxDistance: number) → hit: HitResult?

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? — The result of the raycast, indicating the first block or entity hit.

raycastBlock(maxDistance: number) → hit: BlockHitResult?

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? — The result of the raycast, indicating the block hit.

raycastEntity(maxDistance: number) → hit: EntityHitResult?

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? — The result of the raycast, indicating the entity hit.

removeNbt(path: string, ...: string) → removed: integer

Removes every tag the given NBT paths match and returns how many were removed.

The paths use the syntax of the /data command, see putNbt(path, value). A path that matches nothing is not an error.

Some values are only read by Minecraft when they are present, so omitting them does not clear them. removeNbt clears the known cases itself (custom name, tags, effects, attributes and their modifiers, health) and raises an error if a removed value is still there afterwards, for example the UUID. A value that is reset to its default counts as removed.

Example

local pig = spell:summon("pig")
pig:putNbt({ Tags = { "tamed", "fast" } })
pig:removeNbt("CustomName", 'active_effects[{id:"minecraft:speed"}]')
local removed = pig:removeNbt("Tags")

Parameters

• path: string — An NBT path.
• ...: string — More NBT paths.

Returns

• removed: integer — The number of removed tags.

setHiddenFrom(player: Player|Player[ ], hidden: boolean)

Hides this entity from the given player, or shows it again. A list of players switches it for all of them at once. An entity is hidden from nobody at first.

A player the entity is hidden from is not told about it at all. For that player it isn't there: they don't see it, its equipment or its name, and they can neither hit it nor click it nor be pushed by it. The entity itself is not changed: all other players see it as before, and it still acts on the player it is hidden from, so a hidden zombie still hurts them. That player also still hears its sounds and sees what it shoots, and a hidden player keeps their entry in the player list.

This is independent of invisible and of LivingEntity:setHidden, which hide something from all players alike. A player can't be hidden from themselves.

The settings are not saved: they are gone when the entity is unloaded and when a hidden player logs out. A hidden player keeps them through death and respawn. Any other entity also loses them when it changes the dimension, because the game makes a new entity of it there. A player the entity is hidden from can respawn, or leave and join again, and still doesn't see it. To hide an entity from the players who join later, hide it from each of them at their PlayerJoinedEvent.

Example

-- A marker that only the owner of this spell sees
local marker = spell:summon("armor_stand")
local owner = spell.owner
for _, player in ipairs(spell:findEntities("@a")) do
  if player ~= owner then
    marker:setHiddenFrom(player, true)
  end
end

Parameters

• player: Player|Player[ ] — The player to hide the entity from, or a list of players.
• hidden: boolean — true to hide the entity from the player, false to show it again.