Entity API

import { Entity, LivingEntity } from 'yeow-api';

Static Methods

Entity.get(uuid)                // Promise<Entity | null>

Constructor

new Entity(uuid)                // Reference entity by UUID

Properties

Property	Type	Read/Write	Description
uuid	string	Read-only	Entity UUID
type	string	Read-only	Type (minecraft registration key, e.g., minecraft:zombie)
name	string	Read-only	Display name
customName	string | null	Read/Write	Custom name
world	string | null	Read-only	Current world
location	Location | null	Read-only	Current location
isGlowing	boolean	Read/Write	Glowing
isInvulnerable	boolean	Read/Write	Invulnerable
isSilent	boolean	Read/Write	Silent
hasGravity	boolean	Read/Write	Has gravity
passengers	string[]	Read-only	Passenger UUIDs
vehicle	string | null	Read-only	Vehicle UUID

Entity type keys (minecraft:zombie etc.) value domain see Value Domain Appendix · Version Change Domain.

Methods

All async (Promise).

Field Access

Method	Return	Description
getType()	Promise<string>	Type (Minecraft registry key, e.g. minecraft:zombie)
getName()	Promise<string>	Display name
getCustomName() / setCustomName(v)	Promise<string | null> / Promise<void>	Custom name
getWorld()	Promise<string | null>	Current world
getLocation()	Promise<Location | null>	Current location
isGlowing() / setGlowing(v)	Promise<boolean> / Promise<void>	Glowing
isInvulnerable() / setInvulnerable(v)	Promise<boolean> / Promise<void>	Invulnerable
isSilent() / setSilent(v)	Promise<boolean> / Promise<void>	Silent
hasGravity() / setGravity(v)	Promise<boolean> / Promise<void>	Gravity
getPassengers()	Promise<string[]>	Passenger UUIDs
getVehicle()	Promise<string | null>	Vehicle UUID
getBoundingBox()	Promise<BoundingBox>	{ minX, minY, minZ, maxX, maxY, maxZ }
setCustomNameVisible(v)	Promise<void>	Whether the custom name is visible

Prefer await entity.snap() when reading several fields — see Read-only snapshot.

Other

await entity.remove()
await entity.teleport(loc)

Read-only snapshot (snap())

Fetches the entity's common state in a single round trip and returns a frozen EntitySnapshot. Use it instead of N × await getXxx() when reading several fields.

const s = await zombie.snap();
log.info(`${s.type} hp=${s.health}/${s.maxHealth} @${s.location.x},${s.location.y},${s.location.z}`);

Field	Type	Description
uuid / type / name	string	UUID / type (minecraft:zombie) / name
customName	string	Custom name ("" when unset)
world / location	string / Location	World / position (locally built, frozen)
isGlowing / isInvulnerable / isSilent	boolean	State flags
hasGravity / isOnGround	boolean	Gravity / on ground
passengers / vehicle	string[] / string | null	Passenger UUIDs / vehicle UUID
boundingBox	{minX,minY,minZ,maxX,maxY,maxZ}	Bounding box
velocity	{x,y,z}	Velocity
fireTicks / ticksLived	number	Fire ticks / ticks lived
health / maxHealth / isDead	number / number / boolean	Living entities only

Helpers (local, zero round trips): isLiving(), distanceTo({x,y,z}), isWithin({x,y,z}, radius), toObject() / toJSON().

A snapshot is a copy at one point in time; writes still go through setters.

Potion Effects

Potion effects API acting on LivingEntity see Potion documentation.

LivingEntity

Player inherits from LivingEntity, additional properties:

entity.health                // Read/Write
entity.maxHealth             // Read-only
entity.isDead                // Read-only

Async versions:

entity.getHealth()           // Promise<number>
entity.setHealth(value)      // Promise
entity.getMaxHealth()        // Promise<number>
entity.isDeadAsync()         // Promise<boolean>

Basic Operations

All Entity (velocity/fireTicks/ticksLived/isOnGround) and LivingEntity (damage/setTarget):

// Velocity vector (blocks/second)
entity.velocity = { x: 0, y: 1, z: 0 };      // Read/Write
await entity.setVelocity({ x: 0, y: 1, z: 0 });

// On fire / ticks lived / on ground
entity.fireTicks = 20;                        // Read/Write (0 = not on fire)
entity.ticksLived;                            // Read-only
entity.isOnGround;                            // Read-only

// Damage
await entity.damage(5);                       // Apply 5 damage
await entity.damage(5, 'damager-uuid');       // With damage source

// AI target (no guarantee of effectiveness — depends on entity type/pathfinding ability)
await entity.setTarget({ targetUuid: 'target-entity-uuid' });                    // Entity target
await entity.setTarget({ world: 'world', x: 100, y: 64, z: 100, speed: 1.0 });   // Position target (Pathfinder)

setTarget semantics: Requires mob entity (Mob) to take effect; non-mob/entities without pathfinding silently ignore. Position targets use Pathfinder pathfinding, with speed (default 1.0) controlling movement speed.

Example

const e = await Entity.get(uuid);
if (e) {
    console.log(e.type, e.location?.world);
    e.isGlowing = true;
    await e.teleport(new Location(0, 80, 0, 0, 0, 'world'));

    // Potion effects (LivingEntity instance method; type is minecraft registration key)
    await e.addPotionEffect({
        type: 'minecraft:speed', duration: 200, amplifier: 0
    });
}