BetaReadonly BetadimensionReadonly BetaidUnique identifier of the entity. This identifier is intended to be consistent across loads of a world instance. No meaning should be inferred from the value and structure of this unique identifier - do not parse or interpret it. This property is accessible even if Entity.isValid is false.
Readonly BetaisReadonly BetaisReadonly BetaisReadonly BetaisReadonly BetaisBetaisWhether the entity is sneaking - that is, moving more slowly and more quietly.
This property can't be edited in read-only mode.
import { system, world } from "@minecraft/server";
system.runInterval(() => {
for (const player of world.getAllPlayers()) {
player.isSneaking = true;
}
});
import {
DimensionLocation,
MolangVariableMap,
Vector3,
system,
world,
} from "@minecraft/server";
function spawnConfetti(location: DimensionLocation) {
for (let i = 0; i < 100; i++) {
const molang = new MolangVariableMap();
molang.setColorRGB("variable.color", {
red: Math.random(),
green: Math.random(),
blue: Math.random(),
});
const newLocation: Vector3 = {
x: location.x + Math.floor(Math.random() * 8) - 4,
y: location.y + Math.floor(Math.random() * 8) - 4,
z: location.z + Math.floor(Math.random() * 8) - 4,
};
location.dimension.spawnParticle(
"minecraft:colored_flame_particle",
newLocation,
molang
);
}
}
system.runInterval(() => {
for (const player of world.getPlayers()) {
if (player.isSneaking) {
spawnConfetti({
dimension: player.dimension,
x: player.location.x,
y: player.location.y,
z: player.location.z,
});
player.sendMessage("player is sneaking");
}
}
});
Readonly BetaisReadonly BetaisReadonly BetalocationBetanameOptional Readonly BetascoreboardOptional Readonly BetatargetReadonly BetatypeIdentifier of the type of the entity - for example, 'minecraft:skeleton'. This property is accessible even if Entity.isValid is false.
import { system, world } from "@minecraft/server";
// This event triggers when world is loaded
system.runInterval(() => {
const entity = world.getDimension("overworld").getEntities()[0];
// Finally, show that location as title
entity.runCommandAsync(
`title @a actionbar X: ${Math.floor(
entity.location.x
)} | Y: ${Math.floor(entity.location.y)} | Z: ${Math.floor(
entity.location.z
)}`
);
});
BetaType of effect to add to the entity.
Amount of time, in ticks, for the effect to apply. There are 20 ticks per second. Use TicksPerSecond constant to convert between ticks and seconds. The value must be within the range [0, 20000000].
Optionaloptions: EntityEffectOptionsAdditional options for the effect.
Returns nothing if the effect was added or updated successfully. This can throw an error if the duration or amplifier are outside of the valid ranges, or if the effect does not exist.
Adds or updates an effect, like poison, to the entity.
This function can't be called in read-only mode.
// Spawns a villager and gives it the poison effect
import {
DimensionLocation,
} from '@minecraft/server';
import { MinecraftEffectTypes } from '@minecraft/vanilla-data';
function spawnPoisonedVillager(location: DimensionLocation) {
const villagerType = 'minecraft:villager_v2<minecraft:ageable_grow_up>';
const villager = location.dimension.spawnEntity(villagerType, location);
const duration = 20;
villager.addEffect(MinecraftEffectTypes.Poison, duration, { amplifier: 1 });
}
// Spawns a fox over a dog
import { DimensionLocation } from '@minecraft/server';
import { MinecraftEntityTypes } from '@minecraft/vanilla-data';
function spawnAdultHorse(location: DimensionLocation) {
// Create fox (our quick brown fox)
const fox = location.dimension.spawnEntity(MinecraftEntityTypes.Fox, {
x: location.x,
y: location.y + 2,
z: location.z,
});
fox.addEffect('speed', 10, {
amplifier: 2,
});
// Create wolf (our lazy dog)
const wolf = location.dimension.spawnEntity(MinecraftEntityTypes.Wolf, location);
wolf.addEffect('slowness', 10, {
amplifier: 2,
});
wolf.isSneaking = true;
}
BetaAmount of damage to apply.
Optionaloptions: EntityApplyDamageByProjectileOptions | EntityApplyDamageOptionsAdditional options about the source of damage, which may add additional effects or spur additional behaviors on this entity.
Whether the entity takes any damage. This can return false if the entity is invulnerable or if the damage applied is less than or equal to 0.
// A function that applies damage and then heals the entity
import { Entity, EntityComponentTypes, system, world } from '@minecraft/server';
function applyDamageAndHeal(entity: Entity) {
entity.applyDamage(19); // Many mobs have max damage of 20 so this is a near-death mob
system.runTimeout(() => {
const health = entity.getComponent(EntityComponentTypes.Health);
if (health) {
world.sendMessage(`Entity health before heal: ${health.currentValue}`);
health.resetToMaxValue();
world.sendMessage(`Entity after before heal: ${health.currentValue}`);
} else {
console.warn('Entity does not have health component');
}
}, 40); // Run in a few seconds (40 ticks)
}
BetaImpulse vector.
Applies impulse vector to the current velocity of the entity.
This function can't be called in read-only mode.
// A function that throws entities up in the air
import { Entity } from '@minecraft/server';
function yeetEntity(entity: Entity) {
// Zero out the entity's velocity before applying impulse
entity.clearVelocity();
// throw the zombie up in the air
entity.applyImpulse({ x: 0, y: 15, z: 0 });
}
BetaX direction in horizontal plane.
Z direction in horizontal plane.
Knockback strength for the horizontal vector.
Knockback strength for the vertical vector.
Applies impulse vector to the current velocity of the entity.
This function can't be called in read-only mode.
import { EntityQueryOptions, DimensionLocation } from '@minecraft/server';
function mobParty(targetLocation: DimensionLocation) {
const mobs = ['creeper', 'skeleton', 'sheep'];
// create some sample mob data
for (let i = 0; i < 10; i++) {
targetLocation.dimension.spawnEntity(mobs[i % mobs.length], targetLocation);
}
const eqo: EntityQueryOptions = {
type: 'skeleton',
};
for (const entity of targetLocation.dimension.getEntities(eqo)) {
entity.applyKnockback(0, 0, 0, 1);
}
}
BetaSets the current velocity of the Entity to zero. Note that this method may not have an impact on Players.
This function can't be called in read-only mode.
// A function that throws entities up in the air
import { Entity } from '@minecraft/server';
function yeetEntity(entity: Entity) {
// Zero out the entity's velocity before applying impulse
entity.clearVelocity();
// throw the zombie up in the air
entity.applyImpulse({ x: 0, y: 15, z: 0 });
}
BetaOptionaluseEffects: booleanWhether to show any visual effects connected to the extinguishing.
Returns whether the entity was on fire.
Extinguishes the fire if the entity is on fire. Note that you can call getComponent('minecraft:onfire') and, if present, the entity is on fire.
This function can't be called in read-only mode.
import { world, Entity, EntityComponentTypes, system } from "@minecraft/server";
function setAblaze(entity: Entity) {
entity.setOnFire(20, true);
system.runTimeout(() => {
const onfire = entity.getComponent(EntityComponentTypes.OnFire);
if (onfire) {
world.sendMessage(`${onfire.onFireTicksRemaining} fire ticks remaining, extinguishing the entity.`);
}
// This will extinguish the entity
entity.extinguishFire(true);
}, 30); // Run in 30 ticks or ~1.5 seconds
}
BetaOptionaloptions: BlockRaycastOptionsAdditional configuration options for the ray cast.
Returns the first intersecting block from the direction that this entity is looking at.
import { world } from "@minecraft/server";
for (const entity of world.getDimension("overworld").getEntities()) {
const blockHit = entity.getBlockFromViewDirection();
if (blockHit) {
console.log("Block Hit:");
console.log("Block:", blockHit.block);
console.log("Face:", blockHit.face);
console.log("Face Location:", JSON.stringify(blockHit.faceLocation));
} else {
console.log("No block in view direction.");
}
}
import { BlockPermutation, world } from "@minecraft/server";
const entity = world
.getDimension("overworld")
.spawnEntity("minecraft:fox", { x: 0, y: 0, z: 0 });
const blockHit = entity.getBlockFromViewDirection();
if (blockHit) {
blockHit.block.setPermutation(
BlockPermutation.resolve("minecraft:bedrock")
);
} else {
console.log("No block in view direction.");
}
BetaThe identifier of the component (e.g., 'minecraft:health'). If no namespace prefix is specified, 'minecraft:' is assumed. Available component IDs can be found as part of the EntityComponentTypes enum.
Returns the component if it exists on the entity, otherwise undefined.
import { world } from "@minecraft/server";
for (const player of world.getPlayers()) {
const health = player.getComponent("health");
player.sendMessage(
"Your health is " + health.currentValue + "/" + health.effectiveMax
);
health.setCurrentValue(15); // set player to 15 hp
health.resetToMaxValue(); // reset player to max hp
}
BetaReturns all components that are both present on this entity and supported by the API.
BetaThe property identifier.
Returns the value for the property, or undefined if the property has not been set.
import { Vector3, system, world } from "@minecraft/server";
world.afterEvents.entitySpawn.subscribe((event) => {
event.entity.setDynamicProperty("spawn_location", event.entity.location); // set location spawn
});
world.beforeEvents.entityRemove.subscribe((event) => {
const location = event.removedEntity.getDynamicProperty(
"spawn_location"
) as Vector3; // get location spawn
const dimension = event.removedEntity.dimension;
system.run(() => {
dimension.spawnEntity(event.removedEntity.typeId, location);
});
});
BetaA string array of the dynamic properties set on this entity.
Returns the available set of dynamic property identifiers that have been used on this entity.
import { Player, system } from "@minecraft/server";
system.afterEvents.scriptEventReceive.subscribe((event) => {
// Type /scriptevent bp:entries to see this message
if (event.id === "bp:entries" && event.sourceEntity instanceof Player) {
event.sourceEntity.sendMessage(
"Here's your dynamic properties entries:"
);
// Display all dynamic properties
for (const id of event.sourceEntity.getDynamicPropertyIds()) {
event.sourceEntity.sendMessage(
`- ${id}: ${event.sourceEntity.getDynamicProperty(id)}`
);
}
}
});
BetaReturns the total size, in bytes, of all the dynamic properties that are currently stored for this entity. This includes the size of both the key and the value. This can be useful for diagnosing performance warning signs - if, for example, an entity has many megabytes of associated dynamic properties, it may be slow to load on various devices.
import { Player, system } from "@minecraft/server";
system.afterEvents.scriptEventReceive.subscribe((event) => {
// Type /scriptevent dp:size to see this message
if (event.id === "dp:size" && event.sourceEntity instanceof Player) {
// Returns the total size, in bytes, of all the dynamic properties that are currently stored for this entity.
const byteCount = event.sourceEntity.getDynamicPropertyTotalByteCount();
// Send the byte count to the player
event.sourceEntity.sendMessage(
`Dynamic Properties Byte Count: ${byteCount}`
);
}
});
BetaThe effect identifier.
Effect object for the specified effect, undefined if the effect is not present, or throws an error if the effect does not exist.
BetaOptionaloptions: EntityRaycastOptionsAdditional configuration options for the ray cast.
Returns a set of entities from the direction that this entity is looking at.
Gets the entities that this entity is looking at by performing a ray cast from the view of this entity.
import type { EntityRaycastOptions } from "@minecraft/server";
import { world } from "@minecraft/server";
// Optional: Configure ray cast options
const raycastOptions: EntityRaycastOptions = {
maxDistance: 10, // Set your desired maximum distance
};
// Perform the ray cast
for (const entity of world.getDimension("overworld").getEntities()) {
const entitiesInView = entity.getEntitiesFromViewDirection(raycastOptions);
// Log the results
entitiesInView.forEach((hit) => {
console.log(`Entity hit at distance ${hit.distance} blocks.`);
console.log("Entity details:", hit.entity); // You can access properties/methods of the hit entity
});
}
BetaThe entity Property identifier.
Returns the current property value. For enum properties, a string is returned. For float and int properties, a number is returned. For undefined properties, undefined is returned.
BetaReturns a Vec2 containing the rotation of this entity (in degrees).
import { world } from "@minecraft/server";
world.beforeEvents.chatSend.subscribe((event) => {
const message = event.message;
const player = event.sender;
if (message === "rotation get") {
event.cancel = true;
const rotation = player.getRotation();
player.sendMessage(`Spawn point location: ${rotation.x} ${rotation.y}`);
}
});
BetaReturns the current velocity vector of the entity.
// A function that spawns fireworks and logs their velocity after 5 ticks
import { DimensionLocation, system, world } from '@minecraft/server';
import { MinecraftEntityTypes } from '@minecraft/vanilla-data';
function spawnFireworks(location: DimensionLocation) {
const fireworkRocket = location.dimension.spawnEntity(MinecraftEntityTypes.FireworksRocket, location);
system.runTimeout(() => {
const velocity = fireworkRocket.getVelocity();
world.sendMessage(`Velocity of firework is: ${velocity.x}, ${velocity.y}, ${velocity.z}`);
}, 5);
}
BetaWhether the entity is valid.
Returns whether the entity can be manipulated by script. A Player is considered valid when it's EntityLifetimeState is set to Loaded.
import { system, world } from "@minecraft/server";
const zombie = world
.getDimension("overworld")
.spawnEntity("minecraft:zombie", world.getDefaultSpawnLocation());
const id = system.runInterval(() => {
if (!zombie.isValid()) {
system.clearRun(id);
return;
}
const location = zombie.location;
for (const player of world.getPlayers()) {
player.sendMessage(
`Zombie location: (${location.x.toFixed(2)}, ${location.y.toFixed(
2
)}, ${location.z.toFixed(2)})`
);
}
});
BetaReturns true if entity can be killed (even if it is already dead), otherwise it returns false.
Kills this entity. The entity will drop loot as normal.
This function can't be called in read-only mode.
import { EntityQueryOptions, DimensionLocation } from '@minecraft/server';
function mobParty(targetLocation: DimensionLocation) {
const mobs = ['creeper', 'skeleton', 'sheep'];
// create some sample mob data
for (let i = 0; i < 10; i++) {
const mobTypeId = mobs[i % mobs.length];
const entity = targetLocation.dimension.spawnEntity(mobTypeId, targetLocation);
entity.addTag('mobparty.' + mobTypeId);
}
const eqo: EntityQueryOptions = {
tags: ['mobparty.skeleton'],
};
for (const entity of targetLocation.dimension.getEntities(eqo)) {
entity.kill();
}
}
BetaThe query to perform the match against.
Returns true if the entity matches the criteria in the passed in EntityQueryOptions, otherwise it returns false.
Matches the entity against the passed in options. Uses the location of the entity for matching if the location is not specified in the passed in EntityQueryOptions.
import { GameMode, system, world } from "@minecraft/server";
system.runInterval(() => {
for (const player of world.getAllPlayers()) {
const isSpectating = player.matches({ gameMode: GameMode.spectator });
if (isSpectating) {
player.onScreenDisplay.setActionBar("You are spectating");
}
}
});
BetaThe animation identifier. e.g. animation.creeper.swelling
Optionaloptions: PlayAnimationOptionsAdditional options to control the playback and transitions of the animation.
BetaThe effect identifier.
Returns true if the effect has been removed. Returns false if the effect is not found or does not exist.
BetaThe Entity Property identifier.
Returns the default property value. For enum properties, a string is returned. For float and int properties, a number is returned. For undefined properties, undefined is returned.
BetaThe command string. Note: This should not include a leading forward slash.
A command result containing whether the command was successful.
BetaCommand to run. Note that command strings should not start with slash.
For commands that return data, returns a JSON structure with command response values.
BetaThe property identifier.
Optionalvalue: string | number | boolean | Vector3Data value of the property to set.
import { Vector3, system, world } from "@minecraft/server";
world.afterEvents.entitySpawn.subscribe((event) => {
event.entity.setDynamicProperty("spawn_location", event.entity.location); // set location spawn
});
world.beforeEvents.entityRemove.subscribe((event) => {
const location = event.removedEntity.getDynamicProperty(
"spawn_location"
) as Vector3; // get location spawn
const dimension = event.removedEntity.dimension;
system.run(() => {
dimension.spawnEntity(event.removedEntity.typeId, location);
});
});
BetaLength of time to set the entity on fire.
OptionaluseEffects: booleanWhether side-effects should be applied (e.g. thawing freeze) and other conditions such as rain or fire protection should be taken into consideration.
Whether the entity was set on fire. This can fail if seconds is less than or equal to zero, the entity is wet or the entity is immune to fire.
Sets an entity on fire (if it is not in water or rain). Note that you can call getComponent('minecraft:onfire') and, if present, the entity is on fire.
This function can't be called in read-only mode.
import { world, Entity, EntityComponentTypes, system } from "@minecraft/server";
function setAblaze(entity: Entity) {
entity.setOnFire(20, true);
system.runTimeout(() => {
const onfire = entity.getComponent(EntityComponentTypes.OnFire);
if (onfire) {
world.sendMessage(`${onfire.onFireTicksRemaining} fire ticks remaining, extinguishing the entity.`);
}
// This will extinguish the entity
entity.extinguishFire(true);
}, 30); // Run in 30 ticks or ~1.5 seconds
}
BetaThe Entity Property identifier.
The property value. The provided type must be compatible with the type specified in the entity's definition.
Sets an Entity Property to the provided value. This property change is not applied until the next tick.
This function can't be called in read-only mode.
Throws if the entity is invalid. Throws if an invalid identifier is provided. Throws if the provided value type does not match the property type. Throws if the provided value is outside the expected range (int, float properties). Throws if the provided string value does not match the set of accepted enum values (enum properties
BetaNew location for the entity.
OptionalteleportOptions: TeleportOptionsOptions regarding the teleport operation.
Teleports the selected entity to a new location
This function can't be called in read-only mode.
import { world, system } from '@minecraft/server';
const overworld = world.getDimension('overworld');
const targetLocation = { x: 0, y: 0, z: 0 };
const pig = overworld.spawnEntity('minecraft:pig', targetLocation);
let inc = 1;
const runId = system.runInterval(() => {
pig.teleport(
{ x: targetLocation.x + inc / 4, y: targetLocation.y + inc / 4, z: targetLocation.z + inc / 4 },
{
facingLocation: targetLocation,
},
);
if (inc > 100) {
system.clearRun(runId);
}
inc++;
}, 4);
import { system, world } from "@minecraft/server";
system.afterEvents.scriptEventReceive.subscribe(({ sourceEntity, message }) => {
if (!sourceEntity) return;
if (message === "tp:nether") {
sourceEntity.teleport(
{ x: 0, y: 0, z: 0 },
{ dimension: world.getDimension("nether") }
);
}
});
import { system, world } from "@minecraft/server";
system.afterEvents.scriptEventReceive.subscribe(({ sourceEntity, message }) => {
if (!sourceEntity) return;
if (message === "tp:nether") {
sourceEntity.teleport(
{ x: 0, y: 0, z: 0 },
{
dimension: world.getDimension("nether"),
facingLocation: { x: 100, y: 100, z: 100 },
}
);
}
});
BetaName of the entity type event to trigger. If a namespace is not specified, minecraft: is assumed.
Triggers an entity type event. For every entity, a number of events are defined in an entities' definition for key entity behaviors; for example, creepers have a minecraft:start_exploding type event.
This function can't be called in read-only mode.
// A function that spawns a creeper and triggers it to explode immediately
import { DimensionLocation } from '@minecraft/server';
import { MinecraftEntityTypes } from '@minecraft/vanilla-data';
function spawnExplodingCreeper(location: DimensionLocation) {
const creeper = location.dimension.spawnEntity(MinecraftEntityTypes.Creeper, location);
creeper.triggerEvent('minecraft:start_exploding_forced');
}
BetaLocation to teleport the entity to.
OptionalteleportOptions: TeleportOptionsOptions regarding the teleport operation.
Returns whether the teleport succeeded. This can fail if the destination chunk is unloaded or if the teleport would result in intersecting with blocks.
Represents the state of an entity (a mob, the player, or other moving objects like minecarts) in the world.