Private constructorReadonly cameraThe player's Camera.
This property can throw when used.
import { EasingType, system, world } from "@minecraft/server";
function runCutscene() {
for (const player of world.getPlayers()) {
const location = player.location;
player.camera.setCamera("minecraft:free", {
location: { x: location.x, y: location.y + 10, z: location.z },
rotation: { x: 90, y: 0 },
});
system.run(() => {
player.camera.setCamera("minecraft:free", {
location: player.getHeadLocation(),
rotation: player.getRotation(),
easeOptions: {
easeTime: 1.0,
easeType: EasingType.InCubic,
},
});
system.runTimeout(() => {
player.camera.clear();
player.runCommandAsync("/inputpermission @s camera enabled");
player.runCommandAsync("/inputpermission @s movement enabled");
}, 20);
});
player.runCommandAsync("/inputpermission @s camera disabled");
player.runCommandAsync("/inputpermission @s movement disabled");
}
}
runCutscene();
Readonly Beta clientContains the player's device information.
This property can throw when used.
Error
Readonly dimensionDimension that the entity is currently within.
This property can throw when used.
import { ItemStack, world } from "@minecraft/server";
for (const entity of world.getDimension("overworld").getEntities()) {
entity.dimension.spawnItem(
new ItemStack("minecraft:diamond_sword"),
entity.location
);
}
Readonly idUnique 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.
import { world } from "@minecraft/server";
const id = "-0123456789101"; // entity.id
const entity = world.getEntity(id);
entity.runCommandAsync("say hello");
Readonly inputInput permissions of the player.
Readonly isWhether the entity is touching a climbable block. For example, a player next to a ladder or a spider next to a stone wall.
This property can throw when used.
import { system, world } from "@minecraft/server";
system.runInterval(() => {
for (const entity of world.getDimension("overworld").getEntities()) {
// Force entity to not sneak
entity.isSneaking = false;
}
});
Readonly isIf true, the player is currently emoting.
This property can throw when used.
Readonly isWhether the entity has a fall distance greater than 0, or greater than 1 while gliding.
This property can throw when used.
import { system, world } from "@minecraft/server";
system.runInterval(() => {
for (const player of world.getAllPlayers()) {
player.sendMessage(`isClimbing - ${player.isClimbing}`);
}
});
Readonly isWhether the player is flying. For example, in Creative or Spectator mode.
This property can throw when used.
import { system, world } from "@minecraft/server";
system.runInterval(() => {
for (const player of world.getAllPlayers()) {
player.sendMessage(`player is flying: ${player.isFlying}`);
}
});
Readonly isWhether the player is gliding with Elytra.
This property can throw when used.
import { system, world } from "@minecraft/server";
system.runInterval(() => {
for (const player of world.getAllPlayers()) {
player.sendMessage(
`player is gliding with Elytra: ${player.isGliding}`
);
}
});
Readonly isWhether any part of the entity is inside a water block.
This property can throw when used.
import { system, world } from "@minecraft/server";
system.runInterval(() => {
for (const player of world.getAllPlayers()) {
player.sendMessage(`player in water: ${player.isInWater}`);
}
});
Readonly isWhether the player is jumping. This will remain true while the player is holding the jump action.
This property can throw when used.
import { system, world } from "@minecraft/server";
system.runInterval(() => {
for (const player of world.getAllPlayers()) {
player.sendMessage(`player is jumping: ${player.isJumping}`);
}
});
Readonly isWhether the entity is on top of a solid block. This property may behave in unexpected ways. This property will always be true when an Entity is first spawned, and if the Entity has no gravity this property may be incorrect.
This property can throw when used.
import { system, world } from "@minecraft/server";
system.runInterval(() => {
for (const player of world.getAllPlayers()) {
player.sendMessage(`player on ground: ${player.isOnGround}`);
}
});
Readonly isIf true, the entity is currently sleeping.
This property can throw when used.
Whether 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 isWhether the entity is sprinting. For example, a player using the sprint action, an ocelot running away or a pig boosting with Carrot on a Stick.
This property can throw when used.
Readonly isWhether the entity is in the swimming state. For example, a player using the swim action or a fish in water.
This property can throw when used.
Readonly levelThe current overall level for the player, based on their experience.
This property can throw when used.
import { Player, system, world } from "@minecraft/server";
function countdownFromTen(player: Player) {
player.addLevels(-10000);
player.addLevels(11);
const id = system.runInterval(() => {
player.addExperience(
Math.round(-player.totalXpNeededForNextLevel / 10)
);
if (player.getTotalXp() === 0) {
system.clearRun(id);
}
if (player.xpEarnedAtCurrentLevel == 0) {
player.addLevels(-1);
player.addExperience(player.totalXpNeededForNextLevel - 1);
}
}, 2);
}
for (const player of world.getPlayers()) {
countdownFromTen(player);
}
import { world } from "@minecraft/server";
for (const player of world.getAllPlayers()) {
player.onScreenDisplay.setActionBar(
`Level: ${player.level}, xp at current level: ${player.xpEarnedAtCurrentLevel} / ${player.totalXpNeededForNextLevel}`
);
}
Readonly locationCurrent location of the entity.
This property can throw when used.
import { world } from "@minecraft/server";
world.afterEvents.buttonPush.subscribe((event) => {
if (event.source.typeId === "minecraft:player") {
event.source.kill();
}
});
Readonly nameName of the player.
This property can throw when used.
import { world } from "@minecraft/server";
world.afterEvents.playerSpawn.subscribe((event) => {
world.sendMessage("Welcome to the server, " + event.player.name + "!");
});
Given name of the entity.
This property can't be edited in read-only mode.
import { system, world } from "@minecraft/server";
system.afterEvents.scriptEventReceive.subscribe(({ message }) => {
if (message === "dinnerbone:true") {
for (const entity of world.getDimension("overworld").getEntities()) {
entity.nameTag = "Dinnerbone";
}
}
});
Readonly onContains methods for manipulating the on-screen display of a Player.
This property can throw when used.
import { world } from "@minecraft/server";
for (const player of world.getAllPlayers()) {
player.onScreenDisplay.setActionBar("Hello World");
}
import { HudElement, world } from "@minecraft/server";
for (const player of world.getAllPlayers()) {
player.onScreenDisplay.hideAllExcept([HudElement.Hotbar]);
}
import { world } from "@minecraft/server";
for (const player of world.getAllPlayers()) {
player.onScreenDisplay.setTitle(" "); // spaces needed
player.onScreenDisplay.updateSubtitle("Insert Subtitle");
}
import { world } from "@minecraft/server";
for (const player of world.getAllPlayers()) {
player.onScreenDisplay.setTitle("Hello World");
player.onScreenDisplay.updateSubtitle("Welcome to the server!");
}
Optional Readonly scoreboardReturns a scoreboard identity that represents this entity. Will remain valid when the entity is killed.
This property can't be edited in read-only mode.
import { world } from "@minecraft/server";
for (const player of world.getPlayers()) {
const inventory = player.getComponent("inventory");
const selectedItem = inventory.container.getItem(player.selectedSlotIndex);
player.sendMessage("Selected Item: " + selectedItem.typeId);
}
Optional Readonly Beta targetRetrieves or sets an entity that is used as the target of AI-related behaviors, like attacking. If the entity currently has no target returns undefined.
This property can throw when used.
Readonly totalThe overall total set of experience needed to achieve the next level for a player.
This property can throw when used.
Readonly typeIdentifier 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
)}`
);
});
Readonly xpThe current set of experience achieved for the player.
This property can throw when used.
Type 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].
Optional options: EntityEffectOptionsAdditional options for the effect.
Optional 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.
This function can throw errors.
// 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;
}
Amount of experience to add. Note that this can be negative. Min/max bounds at -2^24 ~ 2^24
Returns the current experience of the Player.
Adds/removes experience to/from the Player and returns the current experience of the Player.
This function can't be called in read-only mode.
This function can throw errors.
import { Player, world } from "@minecraft/server";
// Command equivalent to /xp player 100
function addExperience(player: Player) {
const xpAdded = player.addExperience(100);
console.log(`Player ${player.name} now has ${xpAdded} experience points.`);
}
for (const player of world.getPlayers()) {
addExperience(player);
}
Amount to add to the player. Min/max bounds at -2^24 ~ 2^24
Returns the current level of the Player.
Adds/removes level to/from the Player and returns the current level of the Player.
This function can't be called in read-only mode.
This function can throw errors.
import { Player, world } from "@minecraft/server";
// Command equivalent to /xp player 5L
function addLevels(player: Player) {
const levels = player.addLevels(5);
console.log(`Player ${player.name} now has ${levels} levels.`);
}
Content of the tag to add. The tag must be less than 256 characters.
Returns true if the tag was added successfully. This can fail if the tag already exists on the entity.
Adds a specified tag to an entity.
This function can't be called in read-only mode.
This function can throw errors.
Amount of damage to apply.
Optional options: EntityApplyDamageByProjectileOptions | EntityApplyDamageOptionsAdditional options about the source of damage, which may add additional effects or spur additional behaviors on this entity.
Optional 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.
Applies a set of damage to an entity.
This function can't be called in read-only mode.
This function can throw errors.
// 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)
}
import { world, EntityDamageCause } from "@minecraft/server";
const player = world.getAllPlayers()[0];
player.applyDamage(1000, {
cause: EntityDamageCause.wither,
});
import { world } from "@minecraft/server";
world.afterEvents.itemUse.subscribe((event) => {
const player = event.source;
const damageApplied = player.applyDamage(10);
console.log(`Damage applied: ${damageApplied}`);
});
Impulse vector.
Applies impulse vector to the current velocity of the entity.
This function can't be called in read-only mode.
This function can throw errors.
// 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 });
}
X 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.
This function can throw errors.
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);
}
}
Clears all dynamic properties that have been set on this entity.
This function can throw errors.
import { world } from "@minecraft/server";
for (const entity of world.getDimension("overworld").getEntities()) {
entity.clearDynamicProperties();
}
Sets 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.
This function can throw errors.
// 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 });
}
Beta
The item to eat.
Eats an item, providing the item's hunger and saturation effects to the player. Can only be used on food items.
This function can't be called in read-only mode.
Throws if the item is not a food item.
Optional useEffects: booleanWhether to show any visual effects connected to the extinguishing.
Optional 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.
This function can throw errors.
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
}
Optional options: BlockRaycastOptionsAdditional configuration options for the ray cast.
Optional Returns the first intersecting block from the direction that this entity is looking at.
Returns the first intersecting block from the direction that this entity is looking at.
This function can throw errors.
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.");
}
The 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.
Gets a component (that represents additional capabilities) for an entity.
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
}
import { ItemStack, world } from "@minecraft/server";
world.afterEvents.buttonPush.subscribe((event) => {
const entity = event.source;
entity
.getComponent("inventory")
.container.addItem(new ItemStack("minecraft:dirt", 1));
});
import { world } from "@minecraft/server";
const itemEntities = world
.getDimension("overworld")
.getEntities({ type: "minecraft:item" });
for (const itemEntity of itemEntities) {
const item = itemEntity.getComponent("item");
item.itemStack.keepOnDeath = true;
}
Returns all components that are both present on this entity and supported by the API.
Returns all components that are both present on this entity and supported by the API.
import { world } from "@minecraft/server";
for (const entity of world.getDimension("overworld").getEntities()) {
const components = entity.getComponents();
console.log(
`Number of components: ${components.length}: ${components.map(
(component) => component.typeId
)}`
);
}
The property identifier.
Returns the value for the property, or undefined if the property has not been set.
Returns a property value.
This function can throw errors.
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);
});
});
A 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.
This function can throw errors.
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)}`
);
}
}
});
Returns 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.
This function can throw errors.
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}`
);
}
});
The 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.
Returns the effect for the specified EffectType on the entity, undefined if the effect is not present, or throws an error if the effect does not exist.
This function can throw errors.
import { world } from "@minecraft/server";
const entities = world.getDimension("overworld").getEntities();
for (const entity of entities) {
entity.getEffects().forEach((effect) => {
console.log(effect.typeId, effect.amplifier, effect.duration);
});
}
List of effects.
Returns a set of effects applied to this entity.
This function can throw errors.
import { world } from "@minecraft/server";
for (const entity of world.getDimension("overworld").getEntities()) {
const effect = entity.getEffect("invisibility");
effect.amplifier;
effect.duration;
}
Optional options: EntityRaycastOptionsAdditional configuration options for the ray cast.
Optional 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.
This function can throw errors.
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
});
}
Retrieves the active gamemode for this player, if specified.
This function can throw errors.
import { world } from "@minecraft/server";
for (const player of world.getAllPlayers()) {
const gameMode = player.getGameMode();
player.sendMessage(`Your game mode is ${gameMode}`);
}
Returns the current location of the head component of this entity.
Returns the current location of the head component of this entity.
This function can throw errors.
import { Player } from "@minecraft/server";
function freezePlayerCamera(player: Player) {
player.camera.setCamera("minecraft:free", {
location: player.getHeadLocation(),
rotation: player.getRotation(),
});
}
Specifies the cooldown category to retrieve the current cooldown for.
Gets the current item cooldown time for a particular cooldown category.
This function can throw errors.
import { world } from "@minecraft/server";
const player = world.getAllPlayers()[0];
const cooldown = player.getItemCooldown("equipment");
console.log(`Cooldown for the equipment category: ${cooldown} seconds.`);
The 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.
Gets an entity Property value. If the property was set using the setProperty function within the same tick, the updated value will not be reflected until the subsequent tick.
Throws if the entity is invalid.
import { world } from "@minecraft/server";
const entity = world
.getDimension("overworld")
.getEntities({ type: "create:dummy" })[0];
entity.setProperty("create:rotation_offset", 1);
console.warn(entity.getProperty("create:rotation_offset"));
Returns a Vec2 containing the rotation of this entity (in degrees).
Returns the current rotation component of this entity.
This function can throw errors.
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}`);
}
});
Gets the current spawn point of the player.
This function can throw errors.
import { world } from "@minecraft/server";
world.beforeEvents.chatSend.subscribe((event) => {
const message = event.message;
const player = event.sender;
if (message === "spawnpoint get") {
event.cancel = true;
const spawnPoint = player.getSpawnPoint();
if (spawnPoint) {
player.sendMessage(
`Spawn point location: ${spawnPoint.x} ${spawnPoint.y} ${spawnPoint.z} at ${spawnPoint.dimension.id}`
);
} else {
player.sendMessage(`No spawn point set.`);
}
}
});
An array containing all tags as strings.
Returns all tags associated with the entity.
This function can throw errors.
import { world } from "@minecraft/server";
for (const entity of world.getDimension("overworld").getEntities()) {
const tags = entity.getTags();
const jaylyTag = tags.find((tag) => tag.startsWith("jayly:"));
if (jaylyTag) {
world.sendMessage(`${entity.id}: ${jaylyTag}`);
}
}
Returns the current velocity vector of the entity.
Returns the current velocity vector of the entity.
This function can throw errors.
// 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);
}
The identifier of the component (e.g., 'minecraft:rideable') to retrieve. If no namespace prefix is specified, 'minecraft:' is assumed.
Returns true if the specified component is present on this entity.
Returns true if the specified component is present on this entity.
import { world } from "@minecraft/server";
const entity = world
.getDimension("overworld")
.getEntities({ type: "minecraft:villager" })[0];
entity.hasComponent("tameable");
entity.hasComponent("inventory");
entity.hasComponent("addrider");
entity.hasComponent("is_tamed");
Whether 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)})`
);
}
});
Returns 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.
This function can throw errors.
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();
}
}
The 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.
Throws if the query options are misconfigured.
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");
}
}
});
The animation identifier. e.g. animation.creeper.swelling
Optional options: PlayAnimationOptionsAdditional options to control the playback and transitions of the animation.
Optional Cause the entity to play the given animation.
This function can't be called in read-only mode.
This function can throw errors.
Identifier of the music track to play.
Optional musicOptions: MusicOptionsAdditional options for the music track.
Optional Plays a music track that only this particular player can hear.
This function can't be called in read-only mode.
This function can throw errors.
Optional soundOptions: PlayerSoundOptionsAdditional optional options for the sound.
Optional Plays a sound that only this particular player can hear.
This function can't be called in read-only mode.
This function can throw errors.
import { Player } from "@minecraft/server";
// Scripting code for `playsound
function playCreatorMusicBoxRecord(player: Player) {
player.playSound("record.creator_music_box", { location: player.location });
}
Identifier of the music track to play.
Optional musicOptions: MusicOptionsAdditional options for the music track.
Optional Queues an additional music track that only this particular player can hear. If a track is not playing, a music track will play.
This function can't be called in read-only mode.
An error will be thrown if volume is less than 0.0. An error will be thrown if fade is less than 0.0.
import { Player } from "@minecraft/server";
// Surely someone enjoy minecraft ambient music
const allMusic = [
"music.overworld.bamboo_jungle",
"music.overworld.bamboo_jungle",
"music.game.basalt_deltas",
"music.game_and_wild_equal_chance",
"music.game_and_wild_equal_chance",
"music.game_and_wild_favor_game",
"music.overworld.cherry_grove",
"music.game.creative",
"music.game.credits",
"music.game.crimson_forest",
"music.overworld.deep_dark",
"music.overworld.desert",
"music.overworld.desert",
"music.overworld.desert",
"music.overworld.dripstone_caves",
"music.game.end",
"music.game.endboss",
"music.overworld.flower_forest",
"music.game_and_wild_equal_chance",
"music.game.frozen_peaks",
"music.game",
"music.overworld.grove",
"music.game.nether_wastes",
"music.overworld.jagged_peaks",
"music.overworld.jungle",
"music.overworld.jungle_edge",
"music.overworld.jungle",
"music.overworld.jungle",
"music.game_and_wild_equal_chance",
"music.overworld.lush_caves",
"music.game.swamp_music",
"music.game.meadow",
"music.game_and_wild_favor_game",
"music.menu",
"music.overworld.mesa",
"music.overworld.mesa",
"music.overworld.mesa",
"music.game.nether",
"music.game_and_wild_favor_game",
"music.game_and_wild_favor_game",
"music.game_and_wild_equal_chance",
"music.game_and_wild_equal_chance",
"music.overworld.snowy_slopes",
"music.game.soulsand_valley",
"music.overworld.stony_peaks",
"music.game.swamp_music",
"music.game.swamp_music",
"music.game.water",
];
function queueAllMusic(player: Player) {
for (const musicTrackId of allMusic) {
player.queueMusic(musicTrackId, { fade: 1.0 });
}
}
Immediately removes the entity from the world. The removed entity will not perform a death animation or drop loot upon removal.
This function can't be called in read-only mode.
This function can throw errors.
import { world } from "@minecraft/server";
// Note: You cannot despawn players via entity.remove()
const entities = world
.getDimension("overworld")
.getEntities({ excludeTypes: ["minecraft:player"] });
for (const entity of entities) {
entity.remove();
}
The effect identifier.
Returns true if the effect has been removed. Returns false if the effect is not found or does not exist.
Removes the specified EffectType on the entity, or returns false if the effect is not present.
This function can't be called in read-only mode.
This function can throw errors.
Content of the tag to remove.
Returns whether the tag existed on the entity.
Removes a specified tag from an entity.
This function can't be called in read-only mode.
This function can throw errors.
import { world } from "@minecraft/server";
for (const player of world.getAllPlayers()) {
player.removeTag("admin");
}
The 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.
Resets an Entity Property back to its default value, as specified in the Entity's definition. 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.
Error
The command string. Note: This should not include a leading forward slash.
A command result containing whether the command was successful.
Runs a synchronous command on the entity.
This function can't be called in read-only mode.
This function can throw errors.
Error
import { world } from "@minecraft/server";
world.afterEvents.entityDie.subscribe((event) => {
event.deadEntity.runCommand("say I am dead!");
});
Command to run. Note that command strings should not start with slash.
For commands that return data, returns a JSON structure with command response values.
Runs a particular command asynchronously from the context of this entity. Note that there is a maximum queue of 128 asynchronous commands that can be run in a given tick.
This function can throw errors.
import { world } from "@minecraft/server";
world.beforeEvents.explosion.subscribe((event) => {
event.source?.runCommandAsync("say I exploded!");
});
The message to be displayed.
Sends a message to the player.
This method can throw if the provided RawMessage is
in an invalid format. For example, if an empty name string
is provided to score.
import { Player } from "@minecraft/server";
function sendPlayerMessages(player: Player) {
// Displays "First or Second"
const rawMessage = { translate: 'accessibility.list.or.two', with: ['First', 'Second'] };
player.sendMessage(rawMessage);
// Displays "Hello, world!"
player.sendMessage('Hello, world!');
// Displays "Welcome, Amazing Player 1!"
player.sendMessage({ translate: 'authentication.welcome', with: ['Amazing Player 1'] });
// Displays the player's score for objective "obj". Each player will see their own score.
const rawMessageWithScore = { score: { name: '*', objective: 'obj' } };
player.sendMessage(rawMessageWithScore);
// Displays "Apple or Coal"
const rawMessageWithNestedTranslations = {
translate: 'accessibility.list.or.two',
with: { rawtext: [{ translate: 'item.apple.name' }, { translate: 'item.coal.name' }] },
};
player.sendMessage(rawMessageWithNestedTranslations);
}
The property identifier.
Optional value: string | number | boolean | Vector3Data value of the property to set.
Optional Sets a specified property to a value.
This function can throw errors.
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);
});
});
Optional gameMode: GameModeActive gamemode.
Optional Sets a gamemode override for this player.
This function can't be called in read-only mode.
This function can throw errors.
import { GameMode, world } from "@minecraft/server";
for (const player of world.getAllPlayers()) {
player.setGameMode(GameMode.creative);
}
Length of time to set the entity on fire.
Optional useEffects: booleanWhether side-effects should be applied (e.g. thawing freeze) and other conditions such as rain or fire protection should be taken into consideration.
Optional 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.
This function can throw errors.
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
}
The 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
import { world } from "@minecraft/server";
const tileEntity = world
.getDimension("overworld")
.getEntities({ type: "create:dummy" })[0];
tileEntity.setProperty("create:rotation_offset", 1);
console.warn(tileEntity.getProperty("create:rotation_offset"));
The x and y rotation of the entity (in degrees). For most mobs, the x rotation controls the head tilt and the y rotation controls the body rotation.
Sets the main rotation of the entity.
This function can't be called in read-only mode.
This function can throw errors.
Optional spawnPoint: DimensionLocationOptional Sets the current starting spawn point for this particular player.
This function can't be called in read-only mode.
This function can throw errors.
Error
Beta
Identifier of the particle to create.
The location at which to create the particle emitter.
Optional molangVariables: MolangVariableMapA set of optional, customizable variables that can be adjusted for this particle.
Optional Creates a new particle emitter at a specified location in the world. Only visible to the target player.
This function can't be called in read-only mode.
This function can throw errors.
Error
LocationOutOfWorldBoundariesError
import { world, MolangVariableMap, Vector3 } from '@minecraft/server';
world.afterEvents.playerSpawn.subscribe(event => {
const targetLocation = event.player.location;
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: targetLocation.x + Math.floor(Math.random() * 8) - 4,
y: targetLocation.y + Math.floor(Math.random() * 8) - 4,
z: targetLocation.z + Math.floor(Math.random() * 8) - 4,
};
event.player.spawnParticle('minecraft:colored_flame_particle', newLocation, molang);
}
});
Specifies the cooldown category to retrieve the current cooldown for.
Duration in ticks of the item cooldown.
Sets the item cooldown time for a particular cooldown category.
This function can't be called in read-only mode.
This function can throw errors.
New location for the entity.
Optional teleportOptions: TeleportOptionsOptions regarding the teleport operation.
Optional Teleports the selected entity to a new location
This function can't be called in read-only mode.
This function can throw errors.
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 },
}
);
}
});
Name 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.
If the event is not defined in the definition of the entity, an error will be thrown.
// 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');
}
Location to teleport the entity to.
Optional teleportOptions: TeleportOptionsOptions regarding the teleport operation.
Optional Returns whether the teleport succeeded. This can fail if the destination chunk is unloaded or if the teleport would result in intersecting with blocks.
Attempts to try a teleport, but may not complete the teleport operation (for example, if there are blocks at the destination.)
This function can't be called in read-only mode.
This function can throw errors.
A simulated player can be used within GameTests to represent how a player moves throughout the world and to support testing of how entities and the environment will react to a player. This type derives much of its structure and methods from the @minecraft/server.Player type. Note that many types of events that may be available for entities more broadly, such as item use events, may not fire in the same capacity for simulated players.