Skip to content

entity_api.md

Latest commit

 

History

History
348 lines (243 loc) · 5.72 KB

entity_api.md

File metadata and controls

348 lines (243 loc) · 5.72 KB
Raw

Entity API Documentation

The Entity API provides Lua scripts with access to manipulate entities in Minecraft, including spawning, teleporting, damaging, and getting/setting entity properties.

Global Access

The API is accessed via the global EntityApi table in Lua scripts.

Methods

spawn

Spawns an entity at a specified location.

Syntax:

local entity = EntityApi:spawn(location, entityType)

Parameters:

  • location (userdata): The Location where the entity will spawn
  • entityType (string): The entity type name (e.g., "ZOMBIE", "COW", "PLAYER")

Returns:

  • entity (userdata): The spawned Entity object, or nil on failure

Example:

local location = player:getLocation()
local zombie = EntityApi:spawn(location, "ZOMBIE")

teleport

Teleports an entity to a new location.

Syntax:

EntityApi:teleport(entity, location)

Parameters:

  • entity (userdata): The Entity to teleport
  • location (userdata): The target Location

Example:

local newLoc = location:clone():add(0, 10, 0)
EntityApi:teleport(zombie, newLoc)

getType

Gets the entity type name.

Syntax:

local entityType = EntityApi:getType(entity)

Parameters:

  • entity (userdata): The Entity to query

Returns:

  • entityType (string): The entity type name (e.g., "ZOMBIE", "PLAYER")

Example:

local type = EntityApi:getType(zombie)
print(type) -- "ZOMBIE"

getLocation

Gets the entity's current location.

Syntax:

local location = EntityApi:getLocation(entity)

Parameters:

  • entity (userdata): The Entity to query

Returns:

  • location (userdata): The entity's Location

Example:

local loc = EntityApi:getLocation(zombie)
print(loc:getX(), loc:getY(), loc:getZ())

getWorld

Gets the world the entity is in.

Syntax:

local world = EntityApi:getWorld(entity)

Parameters:

  • entity (userdata): The Entity to query

Returns:

  • world (userdata): The World object

Example:

local world = EntityApi:getWorld(zombie)
print(world:getName())

isDead

Checks if the entity is dead.

Syntax:

local dead = EntityApi:isDead(entity)

Parameters:

  • entity (userdata): The Entity to query

Returns:

  • dead (boolean): true if the entity is dead, false otherwise

Example:

if EntityApi:isDead(zombie) then
    print("Zombie is dead")
end

setVelocity

Sets the entity's velocity.

Syntax:

EntityApi:setVelocity(entity, velocity)

Parameters:

  • entity (userdata): The Entity to modify
  • velocity (userdata): A Vector object representing the velocity

Example:

local velocity = class("org.bukkit.util.Vector"):new(0, 0.5, 0)
EntityApi:setVelocity(zombie, velocity)

getVelocity

Gets the entity's current velocity.

Syntax:

local velocity = EntityApi:getVelocity(entity)

Parameters:

  • entity (userdata): The Entity to query

Returns:

  • velocity (userdata): A Vector object representing the velocity

Example:

local vel = EntityApi:getVelocity(zombie)
print(vel:getY())

damage

Damages an entity.

Syntax:

EntityApi:damage(entity, damage, [source])

Parameters:

  • entity (userdata): The Entity to damage
  • damage (number): The amount of damage to deal
  • source (userdata, optional): An Entity that caused the damage

Example:

EntityApi:damage(zombie, 5)
EntityApi:damage(zombie, 5, player) -- player caused the damage

getHealth

Gets the entity's current health.

Syntax:

local health = EntityApi:getHealth(entity)

Parameters:

  • entity (userdata): The Entity to query

Returns:

  • health (number): The entity's current health

Example:

local health = EntityApi:getHealth(zombie)
print("Health: " .. health)

setHealth

Sets the entity's health.

Syntax:

EntityApi:setHealth(entity, health)

Parameters:

  • entity (userdata): The Entity to modify
  • health (number): The health value to set (clamped to [0, maxHealth])

Example:

EntityApi:setHealth(zombie, 10)

getMaxHealth

Gets the entity's maximum health.

Syntax:

local maxHealth = EntityApi:getMaxHealth(entity)

Parameters:

  • entity (userdata): The Entity to query

Returns:

  • maxHealth (number): The entity's maximum health

Example:

local maxHealth = EntityApi:getMaxHealth(zombie)
print("Max health: " .. maxHealth)

setCustomName

Sets a custom name for the entity.

Syntax:

EntityApi:setCustomName(entity, nameComponent)

Parameters:

  • entity (userdata): The Entity to modify
  • nameComponent (userdata): A Component object (from AdventureApi)

Example:

local name = AdventureApi:parseMiniMessage("<red>Test Zombie</red>")
EntityApi:setCustomName(zombie, name)

getCustomName

Gets the entity's custom name.

Syntax:

local nameComponent = EntityApi:getCustomName(entity)

Parameters:

  • entity (userdata): The Entity to query

Returns:

  • nameComponent (userdata): A Component object, or nil if no custom name

Example:

local name = EntityApi:getCustomName(zombie)

kill

Kills the entity instantly.

Syntax:

EntityApi:kill(entity)

Parameters:

  • entity (userdata): The Entity to kill

Example:

EntityApi:kill(zombie)

Notes

  • Health values are automatically clamped between 0 and the entity's max health
  • The damage source parameter is optional; if provided, it must be a valid Entity
  • Custom names use Adventure API Components for formatting
  • Killing an entity removes it from the world permanently