API reference / @jsprismarine/entities / EntityInstance
Class: EntityInstance
Defined in: entities/src/entityInstance.ts:220
One live entity.
The active component set is the base components plus every active component group, with a later group replacing an earlier component of the same name. It changes only through EntityInstance.applyEffects, so an event's effects land on a tick boundary.
Extends
Constructors
Constructor
new EntityInstance(
holder,options?):EntityInstance
Defined in: entities/src/entityInstance.ts:249
Parameters
holder
A holder from the registry of resolved entity types.
options?
Returns
EntityInstance
Overrides
Properties
goals
readonlygoals:GoalScheduler
Defined in: entities/src/entityInstance.ts:222
The goals registered by the active minecraft:behavior.* components.
holder
readonlyholder:Holder<Type<EntityHooks,EntityTypeFlag>>
Defined in: content/src/instances.ts:23
A holder from the registry of resolved types.
Inherited from
restoring
readonlyrestoring:boolean
Defined in: entities/src/entityInstance.ts:232
Whether this instance is being restored from saved state.
state
state:
EntityState
Defined in: content/src/instances.ts:24
Whatever the domain keeps per instance, such as an item count.
Inherited from
Accessors
actuator
Get Signature
get actuator():
EntityActuator|undefined
Defined in: entities/src/entityInstance.ts:395
The movement and look control the goals use, when the caller supplied one.
Returns
EntityActuator | undefined
attackTarget
Get Signature
get attackTarget():
FilterEntityView|undefined
Defined in: entities/src/entityInstance.ts:802
What the entity is attacking now, which the is_target filter test reads.
Returns
FilterEntityView | undefined
attributes
Get Signature
get attributes():
Attributes
Defined in: entities/src/entityInstance.ts:273
The entity's live attributes.
Returns
componentSetToken
Get Signature
get componentSetToken():
object
Defined in: entities/src/entityInstance.ts:308
The active component map's identity, for caches derived from that set.
Returns
object
homePosition
Get Signature
get homePosition():
EntityPosition|undefined
Defined in: entities/src/entityInstance.ts:556
The position set_home_position recorded, which home_distance measures against and execute_event_on_home_block fires its event on.
Returns
EntityPosition | undefined
javaNavigation
Get Signature
get javaNavigation():
JavaEntityNavigation|undefined
Defined in: entities/src/entityInstance.ts:400
Java's path-navigation and collision rules for this type, when the host supplied them.
Returns
JavaEntityNavigation | undefined
noActionTime
Get Signature
get noActionTime():
number
Defined in: entities/src/entityInstance.ts:283
Ticks since nearby players last kept this entity active.
Returns
number
properties
Get Signature
get properties():
PropertyValues
Defined in: entities/src/entityInstance.ts:278
The entity's live property values.
Returns
random
Get Signature
get random():
RandomSource
Defined in: entities/src/entityInstance.ts:405
The random source this entity draws from.
Returns
riders
Get Signature
get riders(): readonly
EntityInstance[]
Defined in: entities/src/entityInstance.ts:678
Who is riding this entity, in the order they took their seats.
Returns
readonly EntityInstance[]
type
Get Signature
get type():
EntityType
Defined in: entities/src/entityInstance.ts:268
The entity type, with its component groups and its parsed definition.
Returns
Overrides
variables
Get Signature
get variables():
Map<string,MolangValue>
Defined in: entities/src/entityInstance.ts:293
The entity's variable.* Molang storage.
Returns
Map<string, MolangValue>
vehicle
Get Signature
get vehicle():
EntityInstance|undefined
Defined in: entities/src/entityInstance.ts:683
What this entity is riding, which the is_riding filter test reads.
Returns
EntityInstance | undefined
Methods
activeComponentGroups()
activeComponentGroups(): readonly
string[]
Defined in: entities/src/entityInstance.ts:298
The component groups active now, in the order they became active.
Returns
readonly string[]
activeComponents()
activeComponents(): readonly
string[]
Defined in: entities/src/entityInstance.ts:303
Every active component name, base components first and later groups last.
Returns
readonly string[]
applyEffects()
applyEffects(
effects):void
Defined in: entities/src/entityInstance.ts:869
Applies one event's effects now, outside the tick loop.
Parameters
effects
Returns
void
applyQueuedEvents()
applyQueuedEvents():
void
Defined in: entities/src/entityInstance.ts:456
Applies the events already queued without advancing component or goal ticks.
Returns
void
applyStatusEffect()
applyStatusEffect(
target,effect):boolean
Defined in: entities/src/entityInstance.ts:1024
Applies a status effect to the entity represented by a filter view.
Parameters
target
effect
Returns
boolean
blockAt()
blockAt(
position):EntityBlockState|undefined
Defined in: entities/src/entityInstance.ts:1038
Reads one block for a component that watches blocks overlapping this entity.
Parameters
position
The integer block position to read.
Returns
EntityBlockState | undefined
The block, or undefined when the environment cannot answer.
broadcastAnger()
broadcastAnger(
request):void
Defined in: entities/src/entityInstance.ts:836
Asks the world to carry out one minecraft:angry.broadcast_anger request.
Parameters
request
Returns
void
componentParams()
componentParams(
name):unknown
Defined in: entities/src/entityInstance.ts:328
The parsed parameters of an active component, or undefined when it is not active.
Parameters
name
string
Returns
unknown
damage()
damage(
event):DamageResult
Defined in: entities/src/entityInstance.ts:497
Applies one damage event.
The first component that answers onDamage decides the amount, which is what minecraft:damage_sensor does. An immunity component then turns the cause aside, after the sensors have seen it, so a sensor still fires its event on damage the entity ends up ignoring. What is left comes off the health attribute, and minecraft:on_hurt, minecraft:on_hurt_by_player and minecraft:on_death fire in that order.
Parameters
event
Returns
What landed, with the events queued for the entity's next tick.
dismount()
dismount(
rider):boolean
Defined in: entities/src/entityInstance.ts:720
Takes a rider off this entity, firing on_rider_exit_event.
Parameters
rider
EntityInstance
Returns
boolean
Whether the rider was on this entity.
dispatch()
dispatch<
K>(hook, ...args):void
Defined in: entities/src/entityInstance.ts:410
Dispatches through the active component set rather than the type's base components.
Type Parameters
K
K extends "onInitialize" | "onRemove" | "onTick" | "onFriendlyAnger" | "onBlockBroken" | "onEquipmentChanged" | "onAttack" | "onAttackTargetKilled" | "onDamage" | "onDamageProcessed" | "onProjectileHit" | "onInteractWithItem"
Parameters
hook
K
args
...Parameters<EntityHooks[K]>
Returns
void
Overrides
dispatchFirst()
dispatchFirst<
K>(hook, ...args):ReturnType<EntityHooks[K]> |undefined
Defined in: entities/src/entityInstance.ts:415
Dispatches through the active component set until one handler answers.
Type Parameters
K
K extends "onInitialize" | "onRemove" | "onTick" | "onFriendlyAnger" | "onBlockBroken" | "onEquipmentChanged" | "onAttack" | "onAttackTargetKilled" | "onDamage" | "onDamageProcessed" | "onProjectileHit" | "onInteractWithItem"
Parameters
hook
K
args
...Parameters<EntityHooks[K]>
Returns
ReturnType<EntityHooks[K]> | undefined
Overrides
ejectRiders()
ejectRiders():
void
Defined in: entities/src/entityInstance.ts:733
Takes every rider off, which is what losing minecraft:rideable does.
Returns
void
entitySensorCandidates()
entitySensorCandidates(
query): readonlyEntitySensorCandidate[]
Defined in: entities/src/entityInstance.ts:1019
Returns entities in the configured range for the active minecraft:entity_sensor.
Parameters
query
Returns
readonly EntitySensorCandidate[]
equipment()
equipment():
EquipmentParams|undefined
Defined in: entities/src/entityInstance.ts:765
What the active minecraft:equipment component declares: the loot table the entity equips from, and the chance each slot's contents survive its death.
Read off the active set for the same reason EntityInstance.lootTable is. Of the 28 vanilla instances of the component, 15 sit in a component group rather than in base components: a piglin's weapon depends on whether melee_unit or ranged_unit was added, and a type-level read would find neither.
Returns
EquipmentParams | undefined
The component's parameters, or undefined when no active component is minecraft:equipment.
evaluate()
evaluate(
source):PropertyValue|undefined
Defined in: entities/src/entityInstance.ts:673
Evaluates a Molang expression a component body carries against this entity, such as minecraft:ambient_sound_interval's condition.
Parameters
source
string
Returns
PropertyValue | undefined
The value, or undefined when the environment supplies no evaluator or the expression does not evaluate.
families()
families(): readonly
string[]
Defined in: entities/src/entityInstance.ts:777
The type families of the active minecraft:type_family component.
Returns
readonly string[]
filterContext()
filterContext():
FilterContext
Defined in: entities/src/entityInstance.ts:900
Builds the filter context for this entity, with its own facts filled in.
Returns
fire()
fire(
event):EventEffects
Defined in: entities/src/entityInstance.ts:444
Runs an event and queues its effects for the entity's next tick.
Parameters
event
string
Returns
What the event determined, which is settled now even though it lands later.
getTags()
getTags(): readonly
string[]
Defined in: entities/src/entityInstance.ts:318
The Java datapack entity type tags on this instance's type.
Returns
readonly string[]
hasAnyFamily()
hasAnyFamily(
families):boolean
Defined in: entities/src/entityInstance.ts:790
Whether the active type-family component contains any requested family.
Parameters
families
readonly string[]
Returns
boolean
hasComponent()
hasComponent(
name):boolean
Defined in: entities/src/entityInstance.ts:313
Whether a component is active on the entity now.
Parameters
name
string
Returns
boolean
hasTag()
hasTag(
tag):boolean
Defined in: entities/src/entityInstance.ts:323
Whether a Java datapack entity type tag includes this instance's type.
Parameters
tag
string
Returns
boolean
interactWithItem()
interactWithItem(
itemIdentifier,other?,state?):boolean
Defined in: entities/src/entityInstance.ts:339
Applies one held item through the active components.
Parameters
itemIdentifier
string
The held item's identifier.
other?
The player or entity applying the item, for interaction filters.
state?
Runtime-owned timers that gate stateful item interactions.
Returns
boolean
Whether an active component accepted the item.
interactWithItemResult()
interactWithItemResult(
itemIdentifier,other?,state?):boolean|EntityItemInteractionEffect
Defined in: entities/src/entityInstance.ts:381
Dispatches one held item and returns any data-defined effect it requests. A recognized spawn egg routes only through minecraft:spawn_egg_interaction.
Parameters
itemIdentifier
string
The held item's identifier.
other?
The player or entity applying the item, for interaction filters.
state?
Runtime-owned timers and resolved spawn-egg data for stateful interactions.
Returns
boolean | EntityItemInteractionEffect
False when no active component accepts the item, true when it accepts without inventory changes, or the item changes requested by the active component.
lootTable()
lootTable():
string|undefined
Defined in: entities/src/entityInstance.ts:747
The pack-relative loot table path of the active minecraft:loot component.
Read off the active set rather than off the type, because most vanilla mobs declare the component in a component group rather than in their base components: the cow carries it in minecraft:cow_adult, so a type-level read finds nothing and a calf and a grown cow would drop the same thing, which is nothing.
Returns
string | undefined
The path, or undefined when no active component names one.
mount()
mount(
rider):boolean
Defined in: entities/src/entityInstance.ts:698
Seats a rider on this entity.
The seat count caps the riders and family_types decides who is let in. A rider already on something else leaves it first, and a seat taken fires on_rider_enter_event on the vehicle.
Parameters
rider
EntityInstance
Returns
boolean
Whether the rider took a seat. False means the entity carries no active minecraft:rideable, the seats are full, the rider is not of an allowed family, or the two are already in one riding chain.
nameWithNameTag()
nameWithNameTag(
name):boolean
Defined in: entities/src/entityInstance.ts:353
Applies a name tag through the active minecraft:nameable component.
Parameters
name
string
The custom name being assigned.
Returns
boolean
Whether the active component accepts name-tag renaming.
notifyAttack()
notifyAttack(
target):void
Defined in: entities/src/entityInstance.ts:821
Dispatches an attack to the active components.
Parameters
target
Returns
void
notifyAttackTargetKilled()
notifyAttackTargetKilled(
killer):void
Defined in: entities/src/entityInstance.ts:826
Notifies active components that this entity's current attack target was killed.
Parameters
killer
Returns
void
notifyProjectileHit()
notifyProjectileHit(
projectile):boolean
Defined in: entities/src/entityInstance.ts:831
Lets active components evade a projectile before its hit effects are applied.
Parameters
projectile
Returns
boolean
perform()
perform(
action):boolean
Defined in: entities/src/entityInstance.ts:576
Carries out one event action.
set_home_position and stop_movement go through the actuator and reset_target moves state the entity owns; the other six leave through EntityEnvironment.effects.
Parameters
action
Returns
boolean
Whether anything carried the action out. False means the environment left the member out or the actuator is absent, which the caller reports.
queued()
queued(): readonly
EventEffects[]
Defined in: entities/src/entityInstance.ts:451
The events waiting for the next tick, oldest first.
Returns
readonly EventEffects[]
raise()
raise(
event,target,source):string|undefined
Defined in: entities/src/entityInstance.ts:653
Fires an event on one of the entity's subjects, which is what a component's {event, target} pair names.
A self target queues the event for the entity's next tick. Any other target leaves as an outgoing trigger for the environment to route.
Parameters
event
string
target
"self" | "other" | "player" | "target" | "parent" | "baby" | "block" | "holder"
source
string
What asked for the event, which names the report when nothing routes it.
Returns
string | undefined
The event when it was raised, or undefined when nothing routed it.
remove()
remove(
reason):void
Defined in: entities/src/entityInstance.ts:544
Asks the world to take the entity out, which is what the despawn components do.
Parameters
reason
string
What asked for the removal; it reaches the report when nothing in the environment handles removal.
Returns
void
removeStatusEffect()
removeStatusEffect(
target,identifier):boolean
Defined in: entities/src/entityInstance.ts:1029
Removes a status effect from the entity represented by a filter view.
Parameters
target
identifier
string
Returns
boolean
report()
report(
message):void
Defined in: entities/src/entityInstance.ts:1009
Passes one line to the environment's report, which is where everything the runtime met and did not carry out goes.
Parameters
message
string
Returns
void
requestSpawn()
requestSpawn(
request,source?):boolean
Defined in: entities/src/entityInstance.ts:860
Asks the world to create an entity or item a component describes.
Parameters
request
The entity or item, count, and event the component configured.
source?
string = 'minecraft:spawn_entity'
The component asking the world to create it.
Returns
boolean
Whether the world accepted the request.
resetNoActionTime()
resetNoActionTime():
void
Defined in: entities/src/entityInstance.ts:288
Clears the inactivity counter, as Mob.checkDespawn does near a player.
Returns
void
setAttackTarget()
setAttackTarget(
view):void
Defined in: entities/src/entityInstance.ts:814
Points the entity at a target, or clears it when passed undefined.
Taking a target fires minecraft:on_target_acquired and losing one fires minecraft:on_target_escape, each only when the target actually changes, so a goal that reasserts the same target every tick fires neither.
Parameters
view
FilterEntityView | undefined
Returns
void
setHomePosition()
setHomePosition(
position):void
Defined in: entities/src/entityInstance.ts:561
Records where the entity's home is, which minecraft:home restricts it to.
Parameters
position
EntityPosition | undefined
Returns
void
spawn()
spawn(
cause?,named?):EventEffects
Defined in: entities/src/entityInstance.ts:432
Runs the one event an entity gets when it is created.
Exactly one spawn event runs: the built-in event for the cause, or the one the caller named, never both. Its effects apply at once, because the entity has no earlier tick to defer to.
Parameters
cause?
SpawnCause = 'spawned'
named?
string
The event /summon, a spawn rule or a transformation asked for.
Returns
What the event determined.
targetProximity()
targetProximity():
EntityTargetProximity|undefined
Defined in: entities/src/entityInstance.ts:1014
The current target's range and visibility, or undefined when no world target is known.
Returns
EntityTargetProximity | undefined
tick()
tick(
runGoals?):void
Defined in: entities/src/entityInstance.ts:468
Runs one server tick: applies queued events and active component tick handlers, then the goal scheduler when this entity uses the Bedrock goal system.
Parameters
runGoals?
boolean = true
Whether to advance the Bedrock goal scheduler for this tick.
Returns
void
transform()
transform(
request):void
Defined in: entities/src/entityInstance.ts:845
Asks the world to replace the entity with another type, for minecraft:transformation.
Parameters
request
Returns
void
trigger()
trigger(
component,subjects?):string|undefined
Defined in: entities/src/entityInstance.ts:633
Fires one of the ten event-shaped minecraft:on_* components.
The component's own filters gate it, a self target queues the event for the entity's next tick, and any other target leaves as an outgoing trigger for the environment to route. Nothing happens when the component is not active or names no event, which four vanilla bodies do.
Parameters
component
"minecraft:on_death" | "minecraft:on_friendly_anger" | "minecraft:on_hurt" | "minecraft:on_hurt_by_player" | "minecraft:on_ignite" | "minecraft:on_start_landing" | "minecraft:on_start_takeoff" | "minecraft:on_target_acquired" | "minecraft:on_target_escape" | "minecraft:on_wake_with_owner"
subjects?
FilterSubjects = {}
Extra filter subjects the fixed point knows about, such as the damager behind minecraft:on_hurt_by_player.
Returns
string | undefined
The event that fired, or undefined when nothing did.