API reference / @jsprismarine/prismarine / Entities / Item
Class: Item
Defined in: prismarine/src/entity/other/Item.ts:72
The base class for all entities including Player.
Extends
Constructors
Constructor
new Item(
options):Item
Defined in: prismarine/src/entity/other/Item.ts:95
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.
Parameters
options
object & object
The entity's options, and the stack's own.
Returns
Item
Overrides
Properties
attributes
readonlyattributes: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.
Inherited from
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.
Inherited from
Entity.constructor
headYaw
headYaw:
number
Defined in: prismarine/src/entity/Entity.ts:148
Inherited from
metadata
readonlymetadata:Metadata
Defined in: prismarine/src/entity/Entity.ts:153
Entity metadata.
Inherited from
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.
Inherited from
pitch
pitch:
number
Defined in: prismarine/src/entity/Entity.ts:146
Inherited from
yaw
yaw:
number
Defined in: prismarine/src/entity/Entity.ts:147
Inherited from
MOB_ID
staticMOB_ID:string='minecraft:item'
Defined in: prismarine/src/entity/other/Item.ts:73
The entity's namespace ID.
Overrides
Entity.MOB_ID
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.
Inherited from
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
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.
Inherited from
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.
Inherited from
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
Returns
void
Inherited from
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
Inherited from
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.
Inherited from
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.
Inherited from
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));Inherited from
despawnFrom()
despawnFrom(
session):Promise<void>
Defined in: prismarine/src/entity/Entity.ts:1234
Takes this entity off one client.
Parameters
session
The client to remove it from.
Returns
Promise<void>
A promise that resolves once the client has been told.
Inherited from
getAge()
getAge():
number
Defined in: prismarine/src/entity/other/Item.ts:134
The number of ticks this dropped stack has spent in a loaded chunk.
Returns
number
getArmorDefensePoints()
getArmorDefensePoints():
number
Defined in: prismarine/src/entity/Entity.ts:984
Armor points worn by this actor.
Returns
number
Inherited from
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
Inherited from
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
The box, centered on the position and extending up from the feet.
Inherited from
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.
Inherited from
Entity.getDefaultPortalCooldown
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
Inherited from
getFeetY()
getFeetY():
number
Defined in: prismarine/src/entity/other/Item.ts:124
Where the item lies, ITEM_POSITION_OFFSET below the position it reports.
Returns
number
The height of the bottom of the stack.
Overrides
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: SheepInherited from
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.
Inherited from
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.
Inherited from
getItem()
getItem():
ContainerEntry|undefined
Defined in: prismarine/src/entity/other/Item.ts:129
What this entity is on the ground: the stack a player picks up.
Returns
ContainerEntry | undefined
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.
Inherited from
getMaxHealth()
getMaxHealth():
number
Defined in: prismarine/src/entity/Entity.ts:699
The most health this entity can have.
Returns
number
The maximum health.
Inherited from
getMotion()
getMotion():
Vector3
Defined in: prismarine/src/entity/other/Item.ts:116
The speed it is moving at, in blocks per tick, which the client is told when it appears.
Returns
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}`);Inherited from
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);Inherited from
getPickupDelay()
getPickupDelay():
number
Defined in: prismarine/src/entity/other/Item.ts:139
Ticks left before a player may take the stack.
Returns
number
getPortalCooldown()
getPortalCooldown():
number
Defined in: prismarine/src/entity/Entity.ts:581
Ticks left before this entity may enter a portal again.
Returns
number
Inherited from
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.
Inherited from
Entity.getPortalTransitionTicks
getPosition()
getPosition():
Position
Defined in: prismarine/src/entity/Entity.ts:453
Get the entity's position.
Returns
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();Inherited from
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: 1nInherited from
getServer()
getServer():
Server
Defined in: prismarine/src/entity/Entity.ts:1167
Get the server instance.
Returns
The server instance.
Example
const server = entity.getServer();
// Do things with the server.Inherited from
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.
Inherited from
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.
Inherited from
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.
Inherited from
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[]
Inherited from
getTrackingInterval()
getTrackingInterval():
number
Defined in: prismarine/src/entity/other/Item.ts:160
An item moves for about a second after it drops, sliding a block or so, and then lies still.
Returns
number
The interval in ticks.
Overrides
getTrackingRange()
getTrackingRange():
number
Defined in: prismarine/src/entity/other/Item.ts:151
Dropped stacks are followed less far than anything else, as in vanilla.
They are the most numerous entity in any world by a wide margin and the least worth seeing at a distance: one mob farm produces more items than every mob and player put together, and at the generic radius all of them stream to everyone nearby.
Returns
number
The tracking radius in chunks.
Overrides
getType()
getType():
string
Defined in: prismarine/src/entity/Entity.ts:413
Returns
string
Inherited from
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
The actor's current velocity.
Inherited from
getWorld()
getWorld():
World
Defined in: prismarine/src/entity/Entity.ts:469
Gets the world the entity is currently in.
Returns
The world.
Inherited from
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.
Inherited from
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.
Inherited from
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.
Inherited from
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
Inherited from
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.
Inherited from
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
Inherited from
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.
Inherited from
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
Inherited from
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.
Inherited from
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.
Inherited from
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.
Inherited from
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.
Inherited from
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>
Inherited from
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.
Inherited from
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');Inherited from
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
Inherited from
setPosition()
setPosition(
options):Promise<void>
Defined in: prismarine/src/entity/Entity.ts:1303
Set the entity's position and notify the clients.
Parameters
options
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.
Inherited from
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.
Inherited from
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.
Inherited from
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.
Inherited from
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.
Inherited from
spawnTo()
spawnTo(
session):Promise<void>
Defined in: prismarine/src/entity/other/Item.ts:165
A dropped stack goes on the wire as an item actor, not as a generic one.
Parameters
session
Returns
Promise<void>
Overrides
toString()
toString():
string
Defined in: prismarine/src/entity/Entity.ts:424
Convert to a string representation.
Returns
string
The string.
console.log(entity.toString());Inherited from
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
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
Inherited from
update()
update(
tick):Promise<void>
Defined in: prismarine/src/entity/other/Item.ts:181
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);