API reference / @jsprismarine/prismarine / Entity

Class: Entity

Defined in: prismarine/src/entity/Entity.ts:114

The base class for all entities including Player.

Extended by

• Item

Constructors

Constructor

new Entity(options): Entity

Defined in: prismarine/src/entity/Entity.ts:264

Entity constructor.

Parameters

options

The entity options.

attributes?

Attribute[]

Initial attributes, or this entity's defaults when omitted.

headYaw?

number = 0

The head yaw.

pitch?

number = 0

The pitch.

position

Position

Where the entity is, and in which world.

runtimeId?

bigint

An id already drawn from Entity.runtimeIdCount, for a body whose entity was given its id elsewhere: a data-driven mob's runtime draws from the same counter, and its body takes that id so the mob has one id rather than two.

yaw?

number = 0

The yaw.

Returns

Entity

The entity instance.

Remarks

The server is taken from the position's world rather than passed alongside it, so the two can never disagree about which server the entity belongs to.

Example

const world = server.getWorldManager().getDefaultWorld();
const entity = new Entity({ position: new Position(0, 64, 0, world) });

Properties

attributes

readonly attributes: Attributes

Defined in: prismarine/src/entity/Entity.ts:168

Entity attributes.

What is in it is decided by Entity.getDefaultAttributes, which subclasses override - a player has a food bar, a cow does not.

---

constructor

constructor: typeof Entity

Defined in: prismarine/src/entity/Entity.ts:119

TypeScript types this.constructor as Function. Declaring it as the class itself lets Entity.getType read the static MOB_ID the subclass set. Emits nothing.

---

headYaw

headYaw: number

Defined in: prismarine/src/entity/Entity.ts:148

---

metadata

readonly metadata: Metadata

Defined in: prismarine/src/entity/Entity.ts:153

Entity metadata.

---

persistentNbt

persistentNbt: NBTTagCompound | null = null

Defined in: prismarine/src/entity/Entity.ts:178

Everything the world file said about this entity that the server does not model.

Vanilla actor NBT carries a definitions list naming the behavior pack component groups the entity was built from, along with its attributes, tags and variant. An actor written back without them spawns broken or despawns on sight, so the remainder is kept here and written out again by EntitySerializer. Null for an entity that was never read from disk.

---

pitch

pitch: number

Defined in: prismarine/src/entity/Entity.ts:146

---

yaw

yaw: number

Defined in: prismarine/src/entity/Entity.ts:147

Accessors

[toStringTag]

Get Signature

get [toStringTag](): string

Defined in: prismarine/src/entity/Entity.ts:409

Get the entity type.

Example

const entityType = entity.getType();
console.log(`Entity type: ${entityType}`);

Returns

string

The entity's namespace ID.

Methods

addStatusEffect()

addStatusEffect(input, notify?): boolean

Defined in: prismarine/src/entity/Entity.ts:747

Applies or refreshes a status effect.

A stronger Bedrock effect replaces the weaker one. An equal-strength effect only replaces the current value when it lasts longer or changes its visible state.

Parameters

input

StatusEffectInput

The effect and its duration, potency, and display flags.

notify?

boolean = true

Whether to send an effect packet for an accepted change.

Returns

boolean

Whether the effect changed.

---

addTag()

addTag(tag): boolean

Defined in: prismarine/src/entity/Entity.ts:1358

Adds one of /tag's arbitrary string tags.

Java's /tag is exactly this and nothing more: a set of strings on the entity that @e[tag=...] tests and nothing else reads. The Bedrock client has no notion of it, so it never reaches the wire.

Parameters

tag

string

The tag.

Returns

boolean

true when the entity did not already carry it.

---

applyImpulse()

applyImpulse(_impulse): void

Defined in: prismarine/src/entity/Entity.ts:981

Applies a world-space impulse to an entity with a movement owner.

Parameters

_impulse

EntityPosition

Returns

void

---

applyKnockback()

applyKnockback(_directionX, _directionZ, _strength, _damping?): void

Defined in: prismarine/src/entity/Entity.ts:973

Shove this entity away from whatever hit it.

A no-op here, because the base entity has no velocity to shove. The two things that do override it, and they could hardly differ more: the body of a data-driven entity hands the impulse to the entity behind it and lets the runtime carry it, while a Player has to be asked - a player's position comes from their own client, so a server that moved them would be overruled on the next movement packet and read as rubber-banding.

Parameters

_directionX

number

Unit vector away from the blow, x.

_directionZ

number

Unit vector away from the blow, z.

_strength

number

How hard, with knockback resistance already taken off.

_damping?

number = SINGLE_DAMPING

How much of the existing motion survives.

Returns

void

---

claimUpdate()

claimUpdate(tick): boolean

Defined in: prismarine/src/entity/Entity.ts:613

Claims this entity's one update of a server tick for the world asking.

The level ticks its worlds one after another, and a portal trip moves an entity from the world being ticked into one that is ticked later in the same pass. That world finds the arrival in its roster and would update it a second time. The first world claims the tick before updating; the second sees the claim and leaves the entity for the next tick.

Parameters

tick

number

The server's tick counter.

Returns

boolean

True the first time a world asks for a given tick, false for every later ask.

---

clearStatusEffects()

clearStatusEffects(notify?): number

Defined in: prismarine/src/entity/Entity.ts:778

Removes every active status effect.

Parameters

notify?

boolean = true

Whether to send a removal packet for each effect.

Returns

number

The number of effects cleared.

---

damage()

damage(amount, source?): Promise<boolean>

Defined in: prismarine/src/entity/Entity.ts:828

Hurt the entity.

The whole pipeline, in vanilla's order: grace period, then the cancellable event, then armor and its enchantments, then resistance, then absorption, and only what is left of all that comes off the health.

Takes a bare DamageCause as readily as a full DamageSource, which is what let the attacker be threaded through without touching any of the call sites - falling, drowning and starving never had one and still do not need one.

Parameters

amount

number

Half-hearts of damage, before any reduction. Ignored if not positive.

source?

DamageCause | DamageSource = DamageCause.Generic

What did it, and who.

Returns

Promise<boolean>

true if the blow landed.

Example

await player.damage(2, DamageCause.Drowning);
await zombie.damage(7, DamageSource.entity(player));

---

despawnFrom()

despawnFrom(session): Promise<void>

Defined in: prismarine/src/entity/Entity.ts:1234

Takes this entity off one client.

Parameters

session

PlayerSession

The client to remove it from.

Returns

Promise<void>

A promise that resolves once the client has been told.

---

getArmorDefensePoints()

getArmorDefensePoints(): number

Defined in: prismarine/src/entity/Entity.ts:984

Armor points worn by this actor.

Returns

number

---

getArmorToughness()

getArmorToughness(): number

Defined in: prismarine/src/entity/Entity.ts:996

Armor toughness worn, which softens what a hard blow does to that armor.

Returns

number

---

getBox()

getBox(): EntityBox

Defined in: prismarine/src/entity/Entity.ts:311

How big this entity is, in blocks.

Read from the minecraft:collision_box of its type in the running content build rather than from a table in this repository, so the one number is whatever the pack stack says.

Returns

EntityBox

The box, centered on the position and extending up from the feet.

---

getDefaultPortalCooldown()

getDefaultPortalCooldown(): number

Defined in: prismarine/src/entity/Entity.ts:574

How long this entity refuses portals after a dimension change.

Vanilla's getDimensionChangingDelay: 300 ticks for an entity, and Player overrides it with 10.

Returns

number

The cooldown in ticks, from PORTAL_COOLDOWN_TICKS.

---

getEquipment()

getEquipment(): ViewableEquipment

Defined in: prismarine/src/entity/Entity.ts:1013

What this entity is wearing and holding, by equipment slot.

Data-driven entities mirror equipment tables and interactions here. A Human overrides it from the armor container, the hand and the off hand.

Returns

ViewableEquipment

---

getFeetY()

getFeetY(): number

Defined in: prismarine/src/entity/Entity.ts:669

The world height the bottom of this entity's body sits at.

The same as its position for everything the server moves itself, and deliberately a method rather than a read of position.getY() at each call site: a player's position is not its feet - see Human - so any comparison of one body against another has to go through this.

Returns

number

Where the body starts, in world coordinates.

---

getFormattedUsername()

getFormattedUsername(): string

Defined in: prismarine/src/entity/Entity.ts:1388

Get the entity's formatted name.

Returns

string

The entity's formatted name (including prefix & suffix).

Example

const formattedName = entity.getFormattedUsername();
console.log(`Entity formatted name: ${formattedName}`); // Entity formatted name: Sheep

---

getHealth()

getHealth(): number

Defined in: prismarine/src/entity/Entity.ts:691

The entity's health, out of Entity.getMaxHealth.

Health is an attribute, not a field beside one: it is the same number the client draws its hearts from, so there is nowhere for the two to disagree.

Returns

number

The health.

---

getHeldItem()

getHeldItem(): Item | null

Defined in: prismarine/src/entity/Entity.ts:331

What this entity is holding, for whoever has to draw it.

Returns

Item | null

The item, or null for empty hands.

---

getLastDamageSource()

getLastDamageSource(): DamageSource | null

Defined in: prismarine/src/entity/Entity.ts:1123

What last hurt this entity, if anything has.

How a mob knows who to fight back against, and how a death is reported as the work of somebody rather than of nothing in particular.

Returns

DamageSource | null

The last source, or null if it has never been hurt.

---

getMaxHealth()

getMaxHealth(): number

Defined in: prismarine/src/entity/Entity.ts:699

The most health this entity can have.

Returns

number

The maximum health.

---

getName()

getName(): string

Defined in: prismarine/src/entity/Entity.ts:1333

Get the entity's (potentially custom) name.

Returns

string

The entity's name without formatting (usually prefix & suffix).

Example

const name = entity.getName();
console.log(`Entity name: ${name}`);

---

getNearestEntity()

getNearestEntity(entities?): Entity[]

Defined in: prismarine/src/entity/Entity.ts:484

Returns the nearest entity from the current entity.

Parameters

entities?

Entity[] = ...

The entities to compare the distance between.

Returns

Entity[]

The nearest entity.

Todo

Customizable radius

Example

const nearestEntity = entity.getNearestEntity();
console.log('Nearest entity:', nearestEntity);

---

getPortalCooldown()

getPortalCooldown(): number

Defined in: prismarine/src/entity/Entity.ts:581

Ticks left before this entity may enter a portal again.

Returns

number

---

getPortalTransitionTicks()

getPortalTransitionTicks(_rule?): number

Defined in: prismarine/src/entity/Entity.ts:563

Ticks this entity has to stand in a portal before it goes through.

Zero for everything that is not a player, as in vanilla: an item or a mob travels on the first contact tick. Player answers from its game mode and the portal's own delays.

Parameters

_rule?

PortalRule

The rule of the portal the entity stands in, when known. A nether portal holds a player for 80 ticks in survival and an end portal for none.

Returns

number

The delay in ticks, from PORTAL_TRANSITION_TICKS.

---

getPosition()

getPosition(): Position

Defined in: prismarine/src/entity/Entity.ts:453

Get the entity's position.

Returns

Position

Where the entity is, and in which world.

Remarks

The stored position, not a copy. It is safe to hand out because a position derives new instances instead of mutating itself, so a caller cannot move the entity through it. Previously this built a fresh Vector3 on every call - one allocation per packet - and that vector had dropped the world, so getWorld() on it was unavailable.

Example

const position = entity.getPosition();

---

getRuntimeId()

getRuntimeId(): bigint

Defined in: prismarine/src/entity/Entity.ts:437

Get the entity's runtime id.

Returns

bigint

The entity's runtime id.

Example

const entityId = entity.getRuntimeId();
console.log(entityId); // Ex. Output: 1n

---

getServer()

getServer(): Server

Defined in: prismarine/src/entity/Entity.ts:1167

Get the server instance.

Returns

Server

The server instance.

Example

const server = entity.getServer();
// Do things with the server.

---

getStatusEffect()

getStatusEffect(identifier): StatusEffect | undefined

Defined in: prismarine/src/entity/Entity.ts:724

Reads one active effect by its namespaced id or bare Bedrock effect name.

Parameters

identifier

string

The effect name.

Returns

StatusEffect | undefined

The active effect, or undefined when it is absent.

---

getStatusEffects()

getStatusEffects(): readonly StatusEffect[]

Defined in: prismarine/src/entity/Entity.ts:715

The active effects this entity currently carries.

Returns

readonly StatusEffect[]

A snapshot of the active effect instances.

---

getSyncedProperties()

getSyncedProperties(): SyncedProperties

Defined in: prismarine/src/entity/Entity.ts:1024

The properties this actor sends alongside its metadata.

Most entities do not have data-driven properties. Data-driven entity bodies override this with their current client-synced values.

Returns

SyncedProperties

The actor's current property snapshot.

---

getTags()

getTags(): readonly string[]

Defined in: prismarine/src/entity/Entity.ts:1375

The /tag tags this entity carries, in the order they were added.

Returns

readonly string[]

---

getTrackingInterval()

getTrackingInterval(): number

Defined in: prismarine/src/entity/Entity.ts:1209

Ticks between visibility passes for this entity.

Only governs entities approaching a standing player: a player who moves crosses a chunk boundary and forces a pass regardless. Things that never move on their own can afford a long interval.

Returns

number

The interval in ticks.

---

getTrackingRange()

getTrackingRange(): number

Defined in: prismarine/src/entity/Entity.ts:1197

How far clients follow this entity, in chunks.

Per type rather than one number for everything, which is how vanilla does it: a client is told about players as far as it can see, ordinary mobs a little less far, and dropped items less far still. Items are the reason the distinction matters - they are by far the most numerous entity and the least interesting at a distance, so a single radius means a mob farm streams thousands of them to everyone in range.

Always narrowed by the recipient's own view distance, so this can never widen an audience past the terrain that client actually holds.

Returns

number

The tracking radius in chunks.

---

getType()

getType(): string

Defined in: prismarine/src/entity/Entity.ts:413

Returns

string

---

getVelocity()

getVelocity(): Vector3

Defined in: prismarine/src/entity/Entity.ts:461

The actor's current velocity in blocks per tick, or zero when it has none.

Returns

Vector3

The actor's current velocity.

---

getWorld()

getWorld(): World

Defined in: prismarine/src/entity/Entity.ts:469

Gets the world the entity is currently in.

Returns

World

The world.

---

hasStatusEffect()

hasStatusEffect(identifier): boolean

Defined in: prismarine/src/entity/Entity.ts:733

Whether one status effect is active.

Parameters

identifier

string

The effect name.

Returns

boolean

Whether it is active.

---

heal()

heal(amount): Promise<boolean>

Defined in: prismarine/src/entity/Entity.ts:1137

Heal the entity, up to its maximum.

Parameters

amount

number

Half-hearts to restore. Ignored if not positive.

Returns

Promise<boolean>

true if any health was actually restored.

---

isAlive()

isAlive(): boolean

Defined in: prismarine/src/entity/Entity.ts:707

Whether the entity has any health left.

Returns

boolean

true while it is alive.

---

isInvulnerableToHits()

isInvulnerableToHits(): boolean

Defined in: prismarine/src/entity/Entity.ts:1128

Whether the entity is still inside the grace period after a hit.

Returns

boolean

---

isOnGround()

isOnGround(): boolean

Defined in: prismarine/src/entity/Entity.ts:371

Whether this entity is standing on something.

What MoveActorAbsolutePacket's on-ground flag carries, and what the is_on_ground predicate reads. False for anything nothing keeps the state for, which is every entity but a data-driven mob and a player: a projectile in flight and a dropped item are both drawn by the client from its own guess, as they were before the flag was sent at all.

Returns

boolean

Whether it is grounded.

---

isOnPortalCooldown()

isOnPortalCooldown(): boolean

Defined in: prismarine/src/entity/Entity.ts:598

Whether this entity is still refusing portals after a recent dimension change.

Returns

boolean

---

occupiesSpace()

occupiesSpace(): boolean

Defined in: prismarine/src/entity/Entity.ts:657

Whether other entities are kept out of the space this one is in.

False for nearly everything, and deliberately: an arrow in flight, an item on the floor and a painting on the wall are all things you walk through, and shoving a mob aside for them would be both wrong and expensive. Human overrides it, which is what shoves a mob out of a player's way.

Returns

boolean

Whether this entity displaces others.

---

portalContact()

portalContact(): PortalContact | undefined

Defined in: prismarine/src/entity/Entity.ts:622

The portal this entity is currently in contact with, if any.

Returns

PortalContact | undefined

---

removeStatusEffect()

removeStatusEffect(identifier, notify?): boolean

Defined in: prismarine/src/entity/Entity.ts:764

Removes one status effect.

Parameters

identifier

string

The effect name.

notify?

boolean = true

Whether to send a removal packet.

Returns

boolean

Whether an active effect was removed.

---

removeTag()

removeTag(tag): boolean

Defined in: prismarine/src/entity/Entity.ts:1370

Removes one of /tag's tags.

Parameters

tag

string

The tag.

Returns

boolean

true when the entity carried it.

---

setEquipment()

setEquipment(equipment): this

Defined in: prismarine/src/entity/Entity.ts:357

Replaces everything this entity is holding and wearing.

Stored rather than broadcast, for the reason Entity.setHeldItem is. The two places that put it on the wire are PlayerSession.sendAddActor, for a client being shown the entity, and WorldChangeSink.entityEquipmentChanged, for one already holding it.

Parameters

equipment

ViewableEquipment

The new set, replacing the old one whole.

Returns

this

The entity, so a caller can chain.

---

setGrounded()

setGrounded(grounded): this

Defined in: prismarine/src/entity/Entity.ts:384

Records whether this entity is standing on something.

Named apart from Player.setOnGround, which is the client reporting it for its own entity and which also pays out the fall damage the landing earned. This one is the server's own answer for an entity it is moving itself.

Parameters

grounded

boolean

Whether it is standing on something.

Returns

this

The entity, so a caller can chain.

---

setHealth()

setHealth(health, source?): Promise<void>

Defined in: prismarine/src/entity/Entity.ts:792

Set the entity's health, killing it if that leaves it at zero.

Parameters

health

number

The wanted health; clamped to the attribute's bounds.

source?

DamageCause | DamageSource = DamageCause.Generic

What to report as the cause if this kills it.

Returns

Promise<void>

---

setHeldItem()

setHeldItem(item): this

Defined in: prismarine/src/entity/Entity.ts:344

Puts something in this entity's hand.

Stored rather than broadcast, because an entity is often given its item before it is in a world and there is nobody to tell. Everyone who can see it is told when it is spawned to them - see PlayerSession.sendAddActor.

Parameters

item

Item | null

What to hold.

Returns

this

The entity, so a caller can chain.

---

setName()

setName(name): void

Defined in: prismarine/src/entity/Entity.ts:1345

Set the entity's name.

Parameters

name

string

The name.

Returns

void

Example

entity.setName('Mr. Sheep');

---

setPortalCooldown()

setPortalCooldown(ticks?): void

Defined in: prismarine/src/entity/Entity.ts:591

Starts the portal cooldown.

Called on departure, and by the serializer when restoring a saved actor.

Parameters

ticks?

number = ...

The cooldown in ticks. Defaults to Entity.getDefaultPortalCooldown.

Returns

void

---

setPosition()

setPosition(options): Promise<void>

Defined in: prismarine/src/entity/Entity.ts:1303

Set the entity's position and notify the clients.

Parameters

options

EntityPositionOptions

The position options.

Returns

Promise<void>

A promise that resolves when the position is set.

Throws

When a coordinate is NaN or infinite. The entity stays where it was, since a position like that cannot be encoded for the client anyway.

Remarks

A bare Vector3 is taken to mean the same world the entity is already in; moving between worlds goes through the world change on Player, not through here.

---

setX()

setX(x, suppress?): Promise<void>

Defined in: prismarine/src/entity/Entity.ts:1252

Set the x position.

Parameters

x

number

The x coordinate.

suppress?

boolean = false

If true, the client won't be notified about the position change.

Returns

Promise<void>

A promise that resolves when the x position is set.

Example

await entity.setX(10);

Remarks

This method will also send the position update to the client if suppress is false. The test read the flag the wrong way round, so it notified only when asked not to - which, since nothing passed the flag, meant an entity could be moved anywhere without a single client hearing about it.

---

setY()

setY(y, suppress?): Promise<void>

Defined in: prismarine/src/entity/Entity.ts:1268

Set the y position.

Parameters

y

number

The y coordinate.

suppress?

boolean = false

If true, the client won't be notified about the position change.

Returns

Promise<void>

A promise that resolves when the y position is set.

Example

await entity.setY(10);

Remarks

This method will also send the position update to the client if suppress is false.

---

setZ()

setZ(z, suppress?): Promise<void>

Defined in: prismarine/src/entity/Entity.ts:1284

Set the z position.

Parameters

z

number

The z coordinate.

suppress?

boolean = false

If true, the client won't be notified about the position change.

Returns

Promise<void>

A promise that resolves when the z position is set.

Example

await entity.setZ(10);

Remarks

This method will also send the position update to the client if suppress is false.

---

shouldPersist()

shouldPersist(): boolean

Defined in: prismarine/src/entity/Entity.ts:680

Whether the world should include this entity in saved actor records.

Most entities survive a world save. A data-driven entity can opt out with Bedrock's minecraft:transient component.

Returns

boolean

Whether this entity should be persisted.

---

spawnTo()

spawnTo(session): Promise<void>

Defined in: prismarine/src/entity/Entity.ts:1225

Shows this entity to one client.

The entity names the call that represents it and nothing more: it builds no packet and does not go looking for an audience. Deciding who is shown what belongs to the world, and what that looks like on the wire belongs to the session.

A subclass overrides this when it appears as something other than a generic actor - which is why this is a method and not a type test inside the session.

Parameters

session

PlayerSession

The client to show it to.

Returns

Promise<void>

A promise that resolves once the client has been told.

---

toString()

toString(): string

Defined in: prismarine/src/entity/Entity.ts:424

Convert to a string representation.

Returns

string

The string.

console.log(entity.toString());

---

touchPortal()

touchPortal(at, portal?): void

Defined in: prismarine/src/entity/Entity.ts:638

Records that this entity overlaps a portal block on the current tick.

The world calls this once per tick for each entity whose box overlaps a portal. The first call opens the contact; later calls refresh it. A touch while on cooldown opens nothing and winds the cooldown back to its full length instead, as Java's Entity.setAsInsidePortal does, so an entity that has just arrived only travels again after it has left the portal for the whole cooldown and stepped back in.

Parameters

at

Vector3

Where the entity stands, kept as the contact's entry position.

portal?

PortalBlockRef

The portal block overlapped, which the trip is resolved from. Without one the contact counts but never travels.

Returns

void

---

update()

update(_tick): Promise<void>

Defined in: prismarine/src/entity/Entity.ts:514

Fired every tick by the world.

Subclasses that override this must call up, or the grace period after a hit never runs down and the entity becomes permanently unhurtable after the first blow.

Parameters

_tick

number

The current world-tick.

Returns

Promise<void>

A promise that resolves when the update is complete.

Example

entity.update(10);