BetaReadonly BetacameraReadonly BetadimensionReadonly BetaheadReadonly 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 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.
BetaisReturns whether the simulated player is sprinting.
This property can't be edited in read-only mode.
Readonly BetaisReadonly BetalevelReadonly BetalocationReadonly BetanameBetanameReadonly BetaonOptional Readonly BetascoreboardReadonly BetatotalReadonly 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
)}`
);
});
Readonly BetaxpBetaType 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.
const villagerId = 'minecraft:villager_v2<minecraft:ageable_grow_up>';
const villagerLoc: mc.Vector3 = { x: 1, y: 2, z: 1 };
const villager = test.spawn(villagerId, villagerLoc);
const duration = 20;
villager.addEffect(EffectTypes.get('poison'), duration, { amplifier: 1 });
const overworld = mc.world.getDimension("overworld");
const fox = overworld.spawnEntity("minecraft:fox", {
x: targetLocation.x + 1,
y: targetLocation.y + 2,
z: targetLocation.z + 3,
});
fox.addEffect("speed", 10, {
amplifier: 2,
});
log("Created a fox.");
const wolf = overworld.spawnEntity("minecraft:wolf", {
x: targetLocation.x + 4,
y: targetLocation.y + 2,
z: targetLocation.z + 3,
});
wolf.addEffect("slowness", 10, {
amplifier: 2,
});
wolf.isSneaking = true;
log("Created a sneaking wolf.", 1);
BetaAmount 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.
BetaAmount 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.
BetaContent 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.
let mobs = ["creeper", "skeleton", "sheep"];
// create some sample mob data
for (let i = 0; i < 10; i++) {
let mobTypeId = mobs[i % mobs.length];
let entity = overworld.spawnEntity(mobTypeId, targetLocation);
entity.addTag("mobparty." + mobTypeId);
}
let eqo: mc.EntityQueryOptions = {
tags: ["mobparty.skeleton"],
};
for (let entity of overworld.getEntities(eqo)) {
entity.kill();
}
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.
const skelly = overworld.spawnEntity("minecraft:skeleton", targetLocation);
skelly.applyDamage(19); // skeletons have max damage of 20 so this is a near-death skeleton
mc.system.runTimeout(() => {
let health = skelly.getComponent("health") as mc.EntityHealthComponent;
log("Skeleton health before heal: " + health.currentValue);
health.resetToMaxValue();
log("Skeleton health after heal: " + health.currentValue);
}, 20);
BetaImpulse vector.
Applies impulse vector to the current velocity of the entity.
This function can't be called in read-only mode.
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.
let mobs = ["creeper", "skeleton", "sheep"];
// create some sample mob data
for (let i = 0; i < 10; i++) {
overworld.spawnEntity(mobs[i % mobs.length], targetLocation);
}
let eqo: mc.EntityQueryOptions = {
type: "skeleton",
};
for (let entity of overworld.getEntities(eqo)) {
entity.applyKnockback(0, 0, 0, 1);
}
BetaCauses the simulated player to make an attack 'swipe'. Returns true if the attack was performed - for example, the player was not on cooldown and had a valid target. Target selection is performed by raycasting from the player's head.
This function can't be called in read-only mode.
BetaCauses the simulated player to attack the provided target. Returns true if the attack was performed - for example, the player was not on cooldown and had a valid target. The attack can be performed at any distance and does not require line of sight to the target entity.
This function can't be called in read-only mode.
BetaDestroys the block at blockLocation, respecting the rules of the server player's game mode. The block will be hit until broken, an item is used or stopBreakingBlock is called. Returns true if the block at blockLocation is solid.
This function can't be called in read-only mode.
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.
BetaSimulates and performs a disconnection of the simulated player from the world.
This function can't be called in read-only mode.
BetaBetaCauses the simulated player to start flying as though they were flying in creative mode. For flying with Elytra, see function glide.
This function can't be called in read-only mode.
BetaOptionaloptions: BlockRaycastOptionsAdditional configuration options for the ray cast.
Returns the first intersecting block from the direction that this entity is looking at.
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.
const getEntityHealthComponent = entity.getComponent("health");
getEntityHealthComponent.currentValue;
getEntityHealthComponent.defaultValue;
getEntityHealthComponent.effectiveMax;
getEntityHealthComponent.effectiveMin;
getEntityHealthComponent.resetToDefaultValue();
getEntityHealthComponent.resetToMaxValue();
getEntityHealthComponent.resetToMinValue();
getEntityHealthComponent.setCurrentValue(100); // Assuming 100 as an example value
// Custom function to check if the health attribute is within a valid range
function isValidHealthValue(value) {
return (
value >= getEntityHealthComponent.effectiveMin &&
value <= getEntityHealthComponent.effectiveMax
);
}
// Example usage of the custom isValidHealthValue function
const newHealthValue = 80;
if (isValidHealthValue(newHealthValue)) {
getEntityHealthComponent.setCurrentValue(newHealthValue);
}
import { ItemStack } from "@minecraft/server";
const getEntityInventoryComponent = entity.getComponent("inventory");
getEntityInventoryComponent.additionalSlotsPerStrength;
getEntityInventoryComponent.canBeSiphonedFrom;
const inventoryContainer = getEntityInventoryComponent.container;
getEntityInventoryComponent.containerType;
getEntityInventoryComponent.inventorySize;
getEntityInventoryComponent.private;
getEntityInventoryComponent.restrictToOwner;
getEntityInventoryComponent.isValid();
// Custom function to add an item to the inventory
function addItemToInventory(itemStack) {
return inventoryContainer.addItem(itemStack);
}
// Custom function to move an item within the inventory
function moveItemWithinInventory(fromSlot, toSlot) {
inventoryContainer.moveItem(fromSlot, toSlot, inventoryContainer);
}
// Custom function to transfer an item from inventory to another container
function transferItemToContainer(fromSlot, targetContainer) {
return inventoryContainer.transferItem(fromSlot, targetContainer);
}
// Example usage of the custom functions
const newItemStack = new ItemStack("apple", 10); // Assuming "apple" is a valid item
const addedItem = addItemToInventory(newItemStack);
if (addedItem) {
console.log("Item added to inventory:", addedItem);
}
const sourceSlot = 2;
const destinationSlot = 5;
moveItemWithinInventory(sourceSlot, destinationSlot);
const targetContainer = someOtherContainer; // Assuming 'someOtherContainer' is an instance of another container
const transferredItem = transferItemToContainer(0, targetContainer);
if (transferredItem) {
console.log("Item transferred to another container:", transferredItem);
}
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 { 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) => {
// @ts-ignore
const location = event.removedEntity.getDynamicProperty("spawn_location"); // get location spawn
system.run(() => {
event.removedEntity.dimension.spawnEntity(
event.removedEntity.typeId,
location
);
});
});
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.
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";
// Optional: Configure ray cast options
const raycastOptions: EntityRaycastOptions = {
maxDistance: 10, // Set your desired maximum distance
};
// Perform the ray cast
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 the current velocity vector of the entity.
const fireworkRocket = overworld.spawnEntity("minecraft:fireworks_rocket", targetLocation);
mc.system.runTimeout(() => {
let velocity = fireworkRocket.getVelocity();
log("Velocity of firework is: (x: " + velocity.x + ", y:" + velocity.y + ", z:" + velocity.z + ")");
}, 5);
BetaItem to give.
OptionalselectSlot: booleanWhether to set the selected slot once given.
Gives the simulated player a particular item stack.
This function can't be called in read-only mode.
BetaReturns true if the simulated player begins to glide. Returns false if the player is already gliding, or the player does not have Elytra equipped, is in water or is on the ground.
Causes the simulated player to start gliding. Elytra must be equipped and the player must be in the air.
This function can't be called in read-only mode.
BetaThe 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.
BetaPerforms a raycast from the player’s head and interacts with the first intersected block or entity. Returns true if the interaction was successful. Maximum range is 6 blocks.
This function can't be called in read-only mode.
BetaCauses the simulated player to interact with a block. The block at the specified block location must be solid. Returns true if the interaction was performed.
This function can't be called in read-only mode.
BetaEntity to interact with.
Causes the simulated player to interact with a mob. Returns true if the interaction was performed.
This function can't be called in read-only mode.
BetaTrue if a jump was performed.
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.
let mobs = ["creeper", "skeleton", "sheep"];
// create some sample mob data
for (let i = 0; i < 10; i++) {
let mobTypeId = mobs[i % mobs.length];
let entity = overworld.spawnEntity(mobTypeId, targetLocation);
entity.addTag("mobparty." + mobTypeId);
}
let eqo: mc.EntityQueryOptions = {
tags: ["mobparty.skeleton"],
};
for (let entity of overworld.getEntities(eqo)) {
entity.kill();
}
BetaOptionalduration: LookDurationRotates the simulated player's head/body to look at the given block location.
This function can't be called in read-only mode.
BetaOptionalduration: LookDurationRotates the simulated player's head/body to look at the given entity.
This function can't be called in read-only mode.
BetaOptionalduration: LookDurationRotates the simulated player's head/body to look at the given location.
This function can't be called in read-only mode.
BetaThe query to perform the match against.
Returns true if the entity matches the criteria in the passed in EntityQueryOptions, otherwise it returns false.
BetaOptionalspeed: numberOrders the simulated player to walk in the given direction relative to the GameTest.
This function can't be called in read-only mode.
BetaOptionalspeed: numberOrders the simulated player to walk in the given direction relative to the player's current rotation.
This function can't be called in read-only mode.
BetaOptionaloptions: MoveToOptionsOrders the simulated player to move to the given block location in a straight line. If a move or navigation is already playing, this will override the last move/navigation.
This function can't be called in read-only mode.
BetaOptionaloptions: MoveToOptionsOrders the simulated player to move to the given location in a straight line. If a move or navigation is already playing, this will override the last move/navigation.
This function can't be called in read-only mode.
BetaOptionalspeed: numberOrders the simulated player to move to a specific block location using navigation. If a move or navigation is already playing, this will override the last move/walk. Note that if the simulated player gets stuck, that simulated player will stop. The player must be touching the ground in order to start navigation.
This function can't be called in read-only mode.
BetaOptionalspeed: numberWill use navigation to follow the selected entity to within a one block radius. If a move or navigation is already playing, this will override the last move/navigation.
This function can't be called in read-only mode.
BetaOptionalspeed: numberOrders the simulated player to move to a specific location using navigation. If a move or navigation is already playing, this will override the last move/walk. Note that if the simulated player gets stuck, that simulated player will stop. The player must be touching the ground in order to start navigation.
This function can't be called in read-only mode.
BetaA list of locations to use for routing.
Optionalspeed: numberNet speed to use for doing the navigation.
Use navigation to follow the route provided via the locations parameter. If a move or navigation is already playing, this will override the last move/navigation.
This function can't be called in read-only mode.
BetaOptionalsoundOptions: PlayerSoundOptionsAdditional optional options for the sound.
Plays a sound that only this particular player can hear.
This function can't be called in read-only mode.
let players = mc.world.getPlayers();
const musicOptions: mc.MusicOptions = {
fade: 0.5,
loop: true,
volume: 1.0,
};
mc.world.playMusic("music.menu", musicOptions);
const worldSoundOptions: mc.WorldSoundOptions = {
pitch: 0.5,
volume: 4.0,
};
mc.world.playSound("ambient.weather.thunder", targetLocation, worldSoundOptions);
const playerSoundOptions: mc.PlayerSoundOptions = {
pitch: 1.0,
volume: 1.0,
};
players[0].playSound("bucket.fill_water", playerSoundOptions);
BetaImmediately 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.
BetaThe 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.
BetaContent of the tag to remove.
Returns whether the tag existed on the entity.
BetaBetaThe 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.
BetaBetaCauses the simulated player to turn by the provided angle, relative to the player's current rotation.
This function can't be called in read-only mode.
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 message to be displayed.
This method can throw if the provided RawMessage is
in an invalid format. For example, if an empty name string
is provided to score.
// Displays "Apple or Coal"
let rawMessage = {
translate: "accessibility.list.or.two",
with: { rawtext: [{ translate: "item.apple.name" }, { translate: "item.coal.name" }] },
};
player.sendMessage(rawMessage);
// Displays the player's score for objective "obj". Each player will see their own score.
const rawMessage = { score: { name: "*", objective: "obj" } };
world.sendMessage(rawMessage);
let players = mc.world.getPlayers();
players[0].sendMessage("Hello World!");
BetaCauses the simulated player to turn to face the provided angle, relative to the GameTest.
This function can't be called in read-only mode.
BetaThe property identifier.
Optionalvalue: string | number | boolean | Vector3Data value of the property to set.
import { 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) => {
// @ts-ignore
const location = event.removedEntity.getDynamicProperty("spawn_location"); // get location spawn
system.run(() => {
event.removedEntity.dimension.spawnEntity(
event.removedEntity.typeId,
location
);
});
});
BetaGame mode to set.
Sets the game mode that the simulated player is operating under.
This function can't be called in read-only mode.
BetaItem to set.
Slot to place the given item in.
OptionalselectSlot: booleanWhether to set the selected slot once set.
Sets a particular item for the simulated player.
This function can't be called in read-only mode.
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
BetaThe 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.
BetaOptionalspawnPoint: DimensionLocationSets the current starting spawn point for this particular player.
This function can't be called in read-only mode.
BetaOptionalslot: numberThis function can't be called in read-only mode.
BetaStops destroying the block that is currently being hit.
This function can't be called in read-only mode.
BetaBetaCauses the simulated player to stop gliding.
This function can't be called in read-only mode.
BetaBetaStops moving/walking/following if the simulated player is moving.
This function can't be called in read-only mode.
BetaCauses the simulated player to stop swimming.
This function can't be called in read-only mode.
BetaCauses the simulated player to start swimming.
This function can't be called in read-only mode.
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.
const pig = overworld.spawnEntity("minecraft:pig", targetLocation);
let inc = 1;
let runId = mc.system.runInterval(() => {
pig.teleport(
{ x: targetLocation.x + inc / 4, y: targetLocation.y + inc / 4, z: targetLocation.z + inc / 4 },
{
facingLocation: targetLocation,
}
);
if (inc > 100) {
mc.system.clearRun(runId);
}
inc++;
}, 4);
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.
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.
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.
BetaItem to use.
Causes the simulated player to use an item. Does not consume the item. Returns false if the item is on cooldown.
This function can't be called in read-only mode.
BetaIndex of the inventory slot.
Causes the simulated player to hold and use an item in their inventory.
This function can't be called in read-only mode.
BetaCauses the simulated player to use an item in their inventory on a block. The block at the specified block location must be solid. Returns true if the item was used.
This function can't be called in read-only mode.
BetaCauses the simulated player to use an item on a block. The block at the specified block location must be solid. Returns true if the item was used.
This function can't be called in read-only mode.
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.