Entity
The entity wrapper provides access to any Minecraft entity. Player entities extend this wrapper — see Player API.
Metatable name: "entity"
Properties
Section titled “Properties”All properties are read/write unless noted as read-only.
entity.uuid
Section titled “entity.uuid”type: string (read-only)
entity.type
Section titled “entity.type”type: string (read-only)
Entity type (e.g. "minecraft:zombie").
entity.name
Section titled “entity.name”type: string (read-only)
entity.displayName
Section titled “entity.displayName”type: string (read-only)
entity.customName
Section titled “entity.customName”type: string or nil
entity.world
Section titled “entity.world”type: World (read-only)
entity.pos
Section titled “entity.pos”type: Vector
entity.dir
Section titled “entity.dir”type: Vector
The direction of the head.
entity.bodyDir
Section titled “entity.bodyDir”type: Vector
entity.isSneaking
Section titled “entity.isSneaking”type: boolean
entity.isSprinting
Section titled “entity.isSprinting”type: boolean
entity.fallDistance
Section titled “entity.fallDistance”type: number
Idk what it means, but it exists.
entity.removed
Section titled “entity.removed”type: boolean (read-only)
entity.health
Section titled “entity.health”type: number
entity.maxHealth
Section titled “entity.maxHealth”type: number
entity.air
Section titled “entity.air”type: number
entity.maxAir
Section titled “entity.maxAir”type: number (read-only)
entity.fireTicks
Section titled “entity.fireTicks”type: number
-1 means not on fire.
entity.glowing
Section titled “entity.glowing”type: boolean
entity.invulnerable
Section titled “entity.invulnerable”type: boolean
Equipment
Section titled “Equipment”entity.mainhand
Section titled “entity.mainhand”type: ItemStack or nil
entity.offhand
Section titled “entity.offhand”type: ItemStack or nil
entity.head
Section titled “entity.head”type: ItemStack or nil
entity.chest
Section titled “entity.chest”type: ItemStack or nil
entity.legs
Section titled “entity.legs”type: ItemStack or nil
entity.feet
Section titled “entity.feet”type: ItemStack or nil
Attributes
Section titled “Attributes”All attributes are read/write (base value).
entity.speed
Section titled “entity.speed”type: number
Movement speed.
entity.armor
Section titled “entity.armor”type: number
Armor value.
entity.armorToughness
Section titled “entity.armorToughness”type: number
Armor toughness.
entity.attackDamage
Section titled “entity.attackDamage”type: number
Attack damage.
entity.attackSpeed
Section titled “entity.attackSpeed”type: number
Attack speed.
entity.knockbackResistance
Section titled “entity.knockbackResistance”type: number
Knockback resistance.
entity.luck
Section titled “entity.luck”type: number
Luck attribute.
entity.stepHeight
Section titled “entity.stepHeight”type: number
Step height.
entity.blockBreakSpeed
Section titled “entity.blockBreakSpeed”type: number
Block break speed.
entity.gravity
Section titled “entity.gravity”type: number
Gravity multiplier.
entity.scale
Section titled “entity.scale”type: number
Entity scale.
entity.safeFallDistance
Section titled “entity.safeFallDistance”type: number
Safe fall distance.
entity.flyingSpeed
Section titled “entity.flyingSpeed”type: number
Flying speed.
entity.tags
Section titled “entity.tags”type: table
Scoreboard tags. Read to iterate; assign boolean values to add (true) or remove (false) tags.
for _, tag in ipairs(entity.tags) do print(tag)endentity.tags["my_tag"] = true -- addentity.tags["old_tag"] = false -- removeMethods
Section titled “Methods”entity:damage(amount, source?)
Section titled “entity:damage(amount, source?)”Deals damage to the entity.
amount(number) — Damage amountsource(Entity, optional) — Attacking entity
entity:damage(10)entity:damage(5, attacker)entity:raycast(range, includeFluids?, includeEntities?)
Section titled “entity:raycast(range, includeFluids?, includeEntities?)”Performs a raycast from the entity’s eyes.
range(number) — Max distanceincludeFluids(boolean, optional) — Include fluid blocksincludeEntities(boolean, optional, defaulttrue) — Include entity hits
Returns a hit result or nil.
local hit = entity:raycast(10)if hit then -- hit.pos, hit.entity, hit.blockendentity:addEffect(effectId, duration, amplifier?, particles?, icon?)
Section titled “entity:addEffect(effectId, duration, amplifier?, particles?, icon?)”Adds a potion effect.
| Param | Type | Default | Description |
|---|---|---|---|
effectId | string | — | Effect type ID (e.g. "minecraft:speed") |
duration | number | — | Duration in ticks |
amplifier | number | 0 | Effect amplifier |
particles | boolean | true | Show particles |
icon | boolean | true | Show effect icon |
entity:addEffect("minecraft:speed", 600, 1, true, true) -- Speed II, 30sentity:removeEffect(effectId)
Section titled “entity:removeEffect(effectId)”Removes a potion effect.
effectId(string) — Effect type ID (e.g."minecraft:speed")
entity:removeEffect("minecraft:speed")entity:hasEffect(effectId)
Section titled “entity:hasEffect(effectId)”Checks if an effect is active.
effectId(string) — Effect type ID (e.g."minecraft:speed")
Returns true or false.
entity:setOnFireFor(ticks)
Section titled “entity:setOnFireFor(ticks)”Sets the entity on fire for a duration.
ticks(number) — Duration in ticks
entity:setOnFireFor(100) -- 5 secondsentity:readNbt()
Section titled “entity:readNbt()”Returns the entity’s NBT data as a Lua table.
entity:writeNbt(data)
Section titled “entity:writeNbt(data)”Writes NBT data from a Lua table. Lua types are converted:
| Lua value | NBT type |
|---|---|
number | Double (whole numbers in int range stored as Int) |
string | String |
boolean | Byte (0/1) |
table (string keys) | Compound |
table (1-indexed numeric) | List |
nil | Key deletion |
Text components must be passed as JSON strings ('{"text":"Bob"}'), not as Lua tables.
data(table) — NBT data
entity:writeNbt({ CustomName = '{"text":"Bob"}', Health = 40.0 })Note: writeNbt modifies the entity on the server, but may not sync to clients
immediately. Use with entity-specific tags that Minecraft re-reads each tick (health,
custom name). Changes to visual-only tags may require re-spawning the entity.