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

    Class Entity

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Properties

    dimension id isClimbing isFalling isInWater isOnGround isSleeping isSneaking isSprinting isSwimming isValid localizationKey location nameTag scoreboardIdentity? typeId

    Methods

    addEffect addTag applyDamage applyImpulse applyKnockback clearDynamicProperties clearVelocity extinguishFire getAABB getAllBlocksStandingOn getBlockFromViewDirection getBlockStandingOn getComponent getComponents getDynamicProperty getDynamicPropertyIds getDynamicPropertyTotalByteCount getEffect getEffects getEntitiesFromViewDirection getHeadLocation getProperty getRotation getTags getVelocity getViewDirection hasComponent hasTag kill lookAt matches playAnimation remove removeEffect removeTag resetProperty runCommand setDynamicProperties setDynamicProperty setOnFire setProperty setRotation teleport triggerEvent tryTeleport

    Constructors

    Properties

    dimension: Dimension

    This property can throw errors.

    minecraftcommon.EngineError

    InvalidEntityError

    This property can't be read in early-execution mode.

    import { ItemStack, world } from "@minecraft/server";

    for (const entity of world.getDimension("overworld").getEntities()) {
    entity.dimension.spawnItem(new ItemStack("minecraft:diamond_sword"), entity.location);
    }
    id: string
    import { Entity, world } from "@minecraft/server";

    /**
    Gets entity id
    @param {Entity} entity
    /
    function showId(entity) {
       entity.runCommand("say My entity ID: " + entity.id);
    }

    for (const entity of world.getDimension("overworld").getEntities()) {
       showId(entity);
    }
    isClimbing: boolean

    This property can throw errors.

    InvalidEntityError

    This property can't be read in early-execution mode.

    import { system, world } from "@minecraft/server";

    system.runInterval(() => {
    // Get all overworld entities
    for (const entity of world.getDimension("overworld").getEntities()) {
       if (entity.isClimbing) {
           entity.runCommand("say I'm climbing!");
       }
    }
    });
    isFalling: boolean

    This property can throw errors.

    InvalidEntityError

    This property can't be read in early-execution mode.

    import { system, world } from "@minecraft/server";

    system.runInterval(() => {
    for (const player of world.getAllPlayers()) {
       player.sendMessage(`isFalling - ${player.isFalling}`);
    }
    });
    isInWater: boolean

    This property can throw errors.

    InvalidEntityError

    This property can't be read in early-execution mode.

    import { system, world } from "@minecraft/server";

    system.runInterval(() => {
    for (const player of world.getAllPlayers()) {
       player.sendMessage(`player in water: ${player.isInWater}`);
    }
    });
    isOnGround: boolean

    This property can throw errors.

    InvalidEntityError

    This property can't be read in early-execution mode.

    import { system, world } from "@minecraft/server";

    system.runInterval(() => {
    for (const player of world.getAllPlayers()) {
       player.sendMessage(`player on ground: ${player.isOnGround}`);
    }
    });
    isSleeping: boolean

    This property can throw errors.

    InvalidEntityError

    This property can't be read in early-execution mode.

    isSneaking: boolean

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

    This property can't be read in early-execution mode.

    import { system, world } from "@minecraft/server";

    system.runInterval(() => {
    for (const entity of world.getDimension("overworld").getEntities()) {
       // Force entity to not sneak
       entity.isSneaking = false;
    }
    });

    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");
       }
    }
    });
    isSprinting: boolean

    This property can throw errors.

    InvalidEntityError

    This property can't be read in early-execution mode.

    isSwimming: boolean

    This property can throw errors.

    InvalidEntityError

    This property can't be read in early-execution mode.

    isValid: boolean
    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)})`
           );
       }
    });
    localizationKey: string

    This property can throw errors.

    InvalidEntityError

    This property can't be read in early-execution mode.

    location: Vector3

    This property can throw errors.

    InvalidEntityError

    This property can't be read in early-execution mode.

    import { Player, world } from "@minecraft/server";

    world.afterEvents.buttonPush.subscribe((event) => {
    if (event.source instanceof Player) {
       const { x, y, z } = event.source.location;
       event.source.sendMessage(`Your location: ${x}, ${y}, ${z}`);
    }
    });
    nameTag: string

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

    This property can't be read in early-execution 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";
       }
    }
    });
    scoreboardIdentity?: ScoreboardIdentity
    typeId: string
    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.runCommand(
           `title @a actionbar X: ${Math.floor(entity.location.x)} | Y: ${Math.floor(entity.location.y)} | Z: ${Math.floor(
               entity.location.z
           )}`
       );
    });

    Methods

    • Parameters

      • horizontalForce: VectorXZ
      • verticalStrength: number

      Returns void

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

      This function can throw errors.

      InvalidEntityError

      minecraftcommon.UnsupportedFunctionalityError

      This function can't be called in early-execution mode.

      The following example (updated of the above - bounceSkeleton.ts) spawns several mobs, then applies a knockback to all skeletons.

      import { EntityQueryOptions, DimensionLocation } from "@minecraft/server";

      function bounceSkeletons(targetLocation: DimensionLocation) {
        const mobs = ["creeper", "skeleton", "sheep"];
        const horizontalForce = { x: 5, z: 4 }; // horizontal knockback strength - xz vector
        const verticalStrength = 0.3;           // upward knockback strength

        // Spawn 10 mobs in a pattern
        for (let i = 0; i < 10; i++) {
          targetLocation.dimension.spawnEntity(
            mobs[i % mobs.length],
            targetLocation
          );
        }

        const eqo: EntityQueryOptions = { type: "skeleton" };

        // Apply knockback to all skeletons in the area
        for (const entity of targetLocation.dimension.getEntities(eqo)) {
          entity.applyKnockback(horizontalForce, verticalStrength);
        }
      }

    • Returns void

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

      This function can throw errors.

      InvalidEntityError

      This function can't be called in early-execution mode.

      import { world } from "@minecraft/server";

      for (const entity of world.getDimension("overworld").getEntities()) {
      entity.clearDynamicProperties();
      }

    • Parameters

      • OptionaluseEffects: boolean

        Defaults to: true

      Returns boolean

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

      This function can throw errors.

      InvalidEntityError

      This function can't be called in early-execution mode.

    • Parameters

      Returns BlockRaycastHit

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

      This function can throw errors.

      InvalidEntityError

      This function can't be called in early-execution mode.

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

    • Type Parameters

      • T extends string

      Parameters

      • componentId: T

      Returns EntityComponentReturnType<T>

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

      This function can throw errors.

      InvalidEntityError

      This function can't be called in early-execution mode.

      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 EntityComponent[]

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

      This function can throw errors.

      InvalidEntityError

      This function can't be called in early-execution mode.

      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)}`);
      }

    • Parameters

      • identifier: string

      Returns string | number | boolean | Vector3

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

      This function can throw errors.

      InvalidEntityError

      This function can't be called in early-execution mode.

      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<string>(event.removedEntity.typeId, location);
      });
      });

    • Returns string[]

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

      This function can throw errors.

      InvalidEntityError

      This function can't be called in early-execution mode.

      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 number

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

      This function can throw errors.

      InvalidEntityError

      This function can't be called in early-execution mode.

      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}`);
      }
      });

    • Parameters

      Returns Effect

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

      This function can throw errors.

      minecraftcommon.InvalidArgumentError

      InvalidEntityError

      This function can't be called in early-execution mode.

      import { Player, world } from "@minecraft/server";

      /**
      @param {Player} player
      /
      function hasNightVision(player) {
      const nightVision = player.getEffect("night_vision");
      if (nightVision) {
         return true;
      } else return false;
      }

      for (const player of world.getAllPlayers()) {
      if (hasNightVision(player)) {
         player.sendMessage("You have night vision.");
      } else {
         player.sendMessage("You don't have night vision.");
      }
      }

    • Returns Effect[]

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

      This function can throw errors.

      InvalidEntityError

      This function can't be called in early-execution mode.

      import { world } from "@minecraft/server";

      for (const player of world.getAllPlayers()) {
      for (const effect of player.getEffects()) {
         player.sendMessage(
             `Effect: ${effect.displayName} | Duration: ${effect.duration} | Amplifier: ${effect.amplifier}`
         );
      }
      }

    • Parameters

      Returns EntityRaycastHit[]

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

      This function can throw errors.

      minecraftcommon.EngineError

      minecraftcommon.InvalidArgumentError

      InvalidEntityError

      minecraftcommon.UnsupportedFunctionalityError

      This function can't be called in early-execution mode.

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

    • Returns Vector3

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

      This function can throw errors.

      InvalidEntityError

      This function can't be called in early-execution mode.

      import { Player } from "@minecraft/server";

      function freezePlayerCamera(player: Player) {
      player.camera.setCamera("minecraft:free", {
         location: player.getHeadLocation(),
         rotation: player.getRotation(),
      });
      }

    • Parameters

      • identifier: string

      Returns string | number | boolean

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

      This function can throw errors.

      InvalidEntityError

      This function can't be called in early-execution mode.

      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 Vector2

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

      This function can throw errors.

      InvalidEntityError

      This function can't be called in early-execution mode.

      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}`);
      }
      });

    • Returns string[]

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

      This function can throw errors.

      InvalidEntityError

      This function can't be called in early-execution mode.

      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}`);
      }
      }

    • Parameters

      • componentId: string

      Returns boolean

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

      This function can throw errors.

      InvalidEntityError

      This function can't be called in early-execution mode.

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

    • Parameters

      Returns boolean

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

      This function can throw errors.

      minecraftcommon.InvalidArgumentError

      InvalidEntityError

      minecraftcommon.UnsupportedFunctionalityError

      This function can't be called in early-execution mode.

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

    • Returns void

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

      This function can throw errors.

      InvalidEntityError

      minecraftcommon.UnsupportedFunctionalityError

      This function can't be called in early-execution mode.

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

    • Parameters

      • tag: string

      Returns boolean

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

      This function can throw errors.

      InvalidEntityError

      This function can't be called in early-execution mode.

      import { world } from "@minecraft/server";

      for (const player of world.getAllPlayers()) {
      player.removeTag("admin");
      }

    • Parameters

      • commandString: string

      Returns CommandResult

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

      This function can throw errors.

      CommandError

      InvalidEntityError

      This function can't be called in early-execution mode.

      import { world } from "@minecraft/server";

      world.afterEvents.entityDie.subscribe((event) => {
      event.deadEntity.runCommand("say I am dead!");
      });

    • Parameters

      • identifier: string
      • Optionalvalue: string | number | boolean | Vector3

      Returns void

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

      This function can throw errors.

      minecraftcommon.ArgumentOutOfBoundsError

      InvalidEntityError

      This function can't be called in early-execution mode.

      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<string>(event.removedEntity.typeId, location);
      });
      });

    • Parameters

      • seconds: number
      • OptionaluseEffects: boolean

        Defaults to: true

      Returns boolean

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

      This function can throw errors.

      InvalidEntityError

      This function can't be called in early-execution mode.

    • Parameters

      • identifier: string
      • value: string | number | boolean

      Returns void

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

      This function can throw errors.

      minecraftcommon.ArgumentOutOfBoundsError

      minecraftcommon.InvalidArgumentError

      InvalidEntityError

      This function can't be called in early-execution mode.

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

    • Parameters

      Returns void

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

      This function can throw errors.

      InvalidEntityError

      minecraftcommon.UnsupportedFunctionalityError

      This function can't be called in early-execution mode.

      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 },
             }
         );
      }
      });

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Methods