Script API - v1.20.60
    Preparing search index...

    Represents a player within the world.

    Hierarchy (View Summary)

    Index

    Properties

    camera: Camera

    The player's Camera.

    This property can throw when used.

    dimension: Dimension

    Dimension that the entity is currently within.

    This property can throw when used.

    import { ItemStack } from "@minecraft/server";
    entity.dimension.spawnItem(
    new ItemStack("minecraft:diamond_sword"),
    entity.location
    );
    fallDistance: number

    The distance an entity has fallen. The value is reset when the entity is teleported. The value is always 1 when gliding with Elytra.

    This property can throw when used.

    id: string

    Unique 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");
    isClimbing: boolean

    Whether 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.

    system.runInterval(() => {
    const entity = world.getEntity("unique_id");
    if (entity.isSneaking) {
    // force entity not to sneak
    entity.isSneaking = false;
    }
    });
    isEmoting: boolean

    If true, the player is currently emoting.

    This property can throw when used.

    isFalling: boolean

    Whether the entity has a fall distance greater than 0, or greater than 1 while gliding.

    This property can throw when used.

    entity.runCommandAsync("say isClimbing: " + entity.isClimbing);
    isFlying: boolean

    Whether the player is flying. For example, in Creative or Spectator mode.

    This property can throw when used.

    isGliding: boolean

    Whether the player is gliding with Elytra.

    This property can throw when used.

    isInWater: boolean

    Whether any part of the entity is inside a water block.

    This property can throw when used.

    isJumping: boolean

    Whether the player is jumping. This will remain true while the player is holding the jump action.

    This property can throw when used.

    isOnGround: boolean

    Whether the entity is on top of a solid block.

    This property can throw when used.

    isSleeping: boolean

    If true, the entity is currently sleeping.

    This property can throw when used.

    isSneaking: boolean

    Whether the entity is sneaking - that is, moving more slowly and more quietly.

    This property can't be edited in read-only mode.

    entity.runCommandAsync("say isClimbing: " + entity.isClimbing);
    isSprinting: boolean

    Whether 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.

    isSwimming: boolean

    Whether 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.

    level: number

    The current overall level for the player, based on their experience.

    This property can throw when used.

    lifetimeState: EntityLifetimeState

    Whether the entity reference that you have is valid or not. For example, an entity may be unloaded if it moves into a chunk that is unloaded, but may be reactivated if the chunk it is within gets reloaded.

    location: Vector3

    Current 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();
    }
    });
    name: string

    Name of the player.

    This property can throw when used.

    nameTag: string

    Given name of the entity.

    This property can't be edited in read-only mode.

    onScreenDisplay: ScreenDisplay

    Contains methods for manipulating the on-screen display of a Player.

    This property can throw when used.

    scoreboardIdentity?: ScoreboardIdentity

    Returns a scoreboard identity that represents this entity. Will remain valid when the entity is killed.

    selectedSlot: number

    Manages the selected slot in the player's hotbar.

    This property can't be edited in read-only mode.

    target?: Entity

    Retrieves 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.

    totalXpNeededForNextLevel: number

    The overall total set of experience needed to achieve the next level for a player.

    This property can throw when used.

    typeId: string

    Identifier 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
    )}`
    );
    });
    xpEarnedAtCurrentLevel: number

    The current set of experience achieved for the player.

    This property can throw when used.

    Methods

    • Parameters

      • effectType: string | EffectType

        Type of effect to add to the entity.

      • duration: number

        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: EntityEffectOptions

        Additional options for the effect.

      Returns 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.

      This function can throw errors.

      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);
    • Parameters

      • amount: number

        Amount of experience to add. Note that this can be negative. Min/max bounds at -2^24 ~ 2^24

      Returns number

      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.

      const xpAdded = player.addExperience(100);
      console.log(`Player ${player.name} now has ${xpAdded} experience points.`);
    • Parameters

      • amount: number

        Amount to add to the player. Min/max bounds at -2^24 ~ 2^24

      Returns number

      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.

      const levels = player.addLevels(5);
      console.log(`Player ${player.name} now has ${levels} levels.`);
    • Parameters

      • tag: string

        Content of the tag to add. The tag must be less than 256 characters.

      Returns boolean

      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.

      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();
      }
    • Parameters

      Returns boolean

      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.

      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);
      import { world, EntityDamageCause } from "@minecraft/server";
      const player = world.getAllPlayers()[0];
      player.applyDamage(1000, {
      cause: EntityDamageCause.wither,
      });
      const damageApplied = entity.applyDamage(10);
      console.log(`Damage applied: ${damageApplied}`);
    • Parameters

      Returns void

      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.

      const zombie = overworld.spawnEntity("minecraft:zombie", targetLocation);

      zombie.clearVelocity();

      // throw the zombie up in the air
      zombie.applyImpulse({ x: 0, y: 0.5, z: 0 });
    • Parameters

      • directionX: number

        X direction in horizontal plane.

      • directionZ: number

        Z direction in horizontal plane.

      • horizontalStrength: number

        Knockback strength for the horizontal vector.

      • verticalStrength: number

        Knockback strength for the vertical vector.

      Returns void

      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.

      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);
      }
    • Returns void

      Clears all dynamic properties that have been set on this entity.

      This function can throw errors.

      entity.clearDynamicProperties();
    • Returns void

      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.

      const zombie = overworld.spawnEntity("minecraft:zombie", targetLocation);

      zombie.clearVelocity();

      // throw the zombie up in the air
      zombie.applyImpulse({ x: 0, y: 0.5, z: 0 });
    • Beta

      Parameters

      Returns void

      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.

    • Beta

      Parameters

      • OptionaluseEffects: boolean

        Whether to show any visual effects connected to the extinguishing.

      Returns boolean

      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.

      const skelly = overworld.spawnEntity("minecraft:skeleton", targetLocation);

      skelly.setOnFire(20, true);

      mc.system.runTimeout(() => {
      let onfire = skelly.getComponent("onfire") as mc.EntityOnFireComponent;
      log(onfire.onFireTicksRemaining + " fire ticks remaining.");

      skelly.extinguishFire(true);
      log("Never mind. Fire extinguished.");
      }, 20);
      const cow = overworld.spawnEntity("minecraft:cow", targetLocation);

      mc.system.runTimeout(() => {
      cow.teleport(
      { x: targetLocation.x + 2, y: targetLocation.y + 2, z: targetLocation.z + 2 },
      {
      facingLocation: targetLocation,
      }
      );
      }, 20);
    • Parameters

      Returns BlockRaycastHit

      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.

      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.");
      }
    • Type Parameters

      Parameters

      • componentId: T

        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 EntityComponentTypeMap[T]

      Returns the component if it exists on the entity, otherwise undefined.

      Gets a component (that represents additional capabilities) for an entity.

      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);
      }
      const getEntityItemComponent = itemEntity.getComponent("item");
      getEntityItemComponent.itemStack;
      getEntityItemComponent.isValid();
    • Returns EntityComponent[]

      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.

      const components = entity.getComponents();
      console.log(
      `Number of components: ${components.length}: ${components.map(
      (component) => component.typeId
      )}`
      );
    • Parameters

      • identifier: string

        The property identifier.

      Returns string | number | boolean | Vector3

      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 { 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
      );
      });
      });
    • Returns string[]

      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.

    • Returns number

      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.

    • Parameters

      • effectType: string | EffectType

        The effect identifier.

      Returns Effect

      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);
      });
      }
    • Returns Effect[]

      List of effects.

      Returns a set of effects applied to this entity.

      This function can throw errors.

      const effect = entity.getEffect("invisibility");
      effect.amplifier;
      effect.duration;
    • Parameters

      Returns EntityRaycastHit[]

      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";

      // 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
      });
    • Returns Vector3

      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.

    • Beta

      Parameters

      • itemCategory: string

        Specifies the cooldown category to retrieve the current cooldown for.

      Returns number

      Gets the current item cooldown time for a particular cooldown category.

      This function can throw errors.

      const cooldown = player.getItemCooldown("equipment");
      console.log(`Cooldown for the equipment category: ${cooldown} seconds.`);
    • Parameters

      • identifier: string

        The entity Property identifier.

      Returns string | number | boolean

      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.

      entity.setProperty("create:rotation_offset", 1);
      console.warn(entity.getProperty("create:rotation_offset"));
    • Returns Vector2

      Returns a Vec2 containing the rotation of this entity (in degrees).

      Returns the current rotation component of this entity.

      This function can throw errors.

      const rotation = entity.getRotation();
      rotation.x;
      rotation.y;
    • Returns DimensionLocation

      Gets the current spawn point of the player.

      This function can throw errors.

      const spawnPoint = player.getSpawnPoint();
      if (spawnPoint) {
      console.log(
      `Spawn point location: ${spawnPoint.x} ${spawnPoint.y} ${spawnPoint.z} at ${spawnPoint.dimension.id}`
      );
      } else {
      console.log(`No spawn point set.`);
      }
    • Returns string[]

      An array containing all tags as strings.

      Returns all tags associated with the entity.

      This function can throw errors.

      const tags = entity.getTags();
      const jaylyTag = tags.find((tag) => tag.startsWith("jayly:"));
    • Returns number

      Gets the total experience of the Player.

      This function can throw errors.

    • Returns Vector3

      Returns the current velocity vector of the entity.

      Returns the current velocity vector of the entity.

      This function can throw errors.

      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);
    • Returns Vector3

      Returns the current view direction of the entity.

      Returns the current view direction of the entity.

      This function can throw errors.

    • Parameters

      • componentId: string

        The identifier of the component (e.g., 'minecraft:rideable') to retrieve. If no namespace prefix is specified, 'minecraft:' is assumed.

      Returns boolean

      Returns true if the specified component is present on this entity.

      Returns true if the specified component is present on this entity.

      entity.hasComponent("tameable");
      entity.hasComponent("inventory");
      entity.hasComponent("addrider");
      entity.hasComponent("is_tamed");
    • Parameters

      • tag: string

        Identifier of the tag to test for.

      Returns boolean

      Returns whether an entity has a particular tag.

      Returns whether an entity has a particular tag.

      This function can throw errors.

    • Beta

      Returns boolean

      Returns true if this player has operator-level permissions.

      This function can throw errors.

    • Returns boolean

      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.

    • Returns boolean

      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.

      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();
      }
    • Parameters

      Returns boolean

      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 } from "@minecraft/server";
      entity.matches({ gameMode: GameMode.spectator });
    • Beta

      Parameters

      • animationName: string

        The animation identifier. e.g. animation.creeper.swelling

      • Optionaloptions: PlayAnimationOptions

        Additional options to control the playback and transitions of the animation.

      Returns void

      Cause the entity to play the given animation.

      This function can't be called in read-only mode.

      This function can throw errors.

    • Beta

      Parameters

      • trackId: string

        Identifier of the music track to play.

      • OptionalmusicOptions: MusicOptions

        Additional options for the music track.

      Returns void

      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.

    • Parameters

      • soundId: string
      • OptionalsoundOptions: PlayerSoundOptions

        Additional optional options for the sound.

      Returns void

      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.

      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);
    • Beta

      Parameters

      • id: string
      • value: string

      Returns void

      This is an internal-facing method for posting a system message to downstream clients.

      This function can't be called in read-only mode.

      This function can throw errors.

    • Beta

      Parameters

      • trackId: string

        Identifier of the music track to play.

      • OptionalmusicOptions: MusicOptions

        Additional options for the music track.

      Returns void

      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.

    • Returns void

      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.

    • Parameters

      • effectType: string | EffectType

        The effect identifier.

      Returns boolean

      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.

    • Parameters

      • tag: string

        Content of the tag to remove.

      Returns boolean

      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.

    • Returns void

      Resets the level of the player.

      This function can't be called in read-only mode.

      This function can throw errors.

    • Parameters

      • identifier: string

        The Entity Property identifier.

      Returns string | number | boolean

      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.

      minecraftcommon.EngineError

      Error

    • Parameters

      • commandString: string

        The command string. Note: This should not include a leading forward slash.

      Returns CommandResult

      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.

      CommandError

      Error

    • Parameters

      • commandString: string

        Command to run. Note that command strings should not start with slash.

      Returns Promise<CommandResult>

      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.

    • Parameters

      Returns void

      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.

      // 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!");
      let players = mc.world.getPlayers();

      players[0].sendMessage({ translate: "authentication.welcome", with: ["Amazing Player 1"] });
      // Displays "Hello, world!"
      world.sendMessage("Hello, world!");
      // Displays "First or Second"
      const rawMessage = { translate: "accessibility.list.or.two", with: ["First", "Second"] };
      player.sendMessage(rawMessage);
    • Parameters

      • identifier: string

        The property identifier.

      • Optionalvalue: string | number | boolean | Vector3

        Data value of the property to set.

      Returns void

      Sets a specified property to a value.

      This function can throw errors.

      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
      );
      });
      });
    • Beta

      Parameters

      • seconds: number

        Length of time to set the entity on fire.

      • OptionaluseEffects: boolean

        Whether side-effects should be applied (e.g. thawing freeze) and other conditions such as rain or fire protection should be taken into consideration.

      Returns boolean

      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.

      const skelly = overworld.spawnEntity("minecraft:skeleton", targetLocation);

      skelly.setOnFire(20, true);

      mc.system.runTimeout(() => {
      let onfire = skelly.getComponent("onfire") as mc.EntityOnFireComponent;
      log(onfire.onFireTicksRemaining + " fire ticks remaining.");

      skelly.extinguishFire(true);
      log("Never mind. Fire extinguished.");
      }, 20);
      const cow = overworld.spawnEntity("minecraft:cow", targetLocation);

      mc.system.runTimeout(() => {
      cow.teleport(
      { x: targetLocation.x + 2, y: targetLocation.y + 2, z: targetLocation.z + 2 },
      {
      facingLocation: targetLocation,
      }
      );
      }, 20);
    • Beta

      Parameters

      • isOp: boolean

      Returns void

      Will change the specified players permissions, and whether they are operator or not.

      This function can't be called in read-only mode.

      This function can throw errors.

    • Parameters

      • identifier: string

        The Entity Property identifier.

      • value: string | number | boolean

        The property value. The provided type must be compatible with the type specified in the entity's definition.

      Returns void

      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

      tileEntity.setProperty("create:rotation_offset", 1);
      console.warn(tileEntity.getProperty("create:rotation_offset"));
    • Parameters

      • rotation: Vector2

        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.

      Returns void

      Sets the main rotation of the entity.

      This function can't be called in read-only mode.

      This function can throw errors.

    • Beta

      Parameters

      • effectName: string

        Identifier of the particle to create.

      • location: Vector3

        The location at which to create the particle emitter.

      • OptionalmolangVariables: MolangVariableMap

        A set of optional, customizable variables that can be adjusted for this particle.

      Returns void

      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

      LocationInUnloadedChunkError

      LocationOutOfWorldBoundariesError

      for (let i = 0; i < 100; i++) {
      const molang = new mc.MolangVariableMap();

      molang.setColorRGB("variable.color", {
      red: Math.random(),
      green: Math.random(),
      blue: Math.random(),
      alpha: 1,
      });

      let newLocation = {
      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,
      };
      player.spawnParticle("minecraft:colored_flame_particle", newLocation, molang);
      }
    • Beta

      Parameters

      • itemCategory: string

        Specifies the cooldown category to retrieve the current cooldown for.

      • tickDuration: number

        Duration in ticks of the item cooldown.

      Returns void

      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.

    • Beta

      Returns void

      Stops any music tracks from playing for this particular player.

      This function can't be called in read-only mode.

      This function can throw errors.

    • Parameters

      • location: Vector3

        New location for the entity.

      • OptionalteleportOptions: TeleportOptions

        Options regarding the teleport operation.

      Returns void

      Teleports the selected entity to a new location

      This function can't be called in read-only mode.

      This function can throw errors.

      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);
      player.teleport(
      { x: 0, y: 0, z: 0 },
      { dimension: world.getDimension("nether") }
      );
      player.teleport(
      { x: 0, y: 0, z: 0 },
      {
      dimension: world.getDimension("nether"),
      teleportFacing: { x: 100, y: 100, z: 100 },
      }
      );
    • Parameters

      • eventName: string

        Name of the entity type event to trigger. If a namespace is not specified, minecraft: is assumed.

      Returns void

      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.

      const creeper = overworld.spawnEntity("minecraft:creeper", targetLocation);

      creeper.triggerEvent("minecraft:start_exploding_forced");
    • Parameters

      • location: Vector3

        Location to teleport the entity to.

      • OptionalteleportOptions: TeleportOptions

        Options regarding the teleport operation.

      Returns boolean

      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.