Class Dimension

ReadonlyheightRange

Readonlyid

createExplosion

• createExplosion(
      location: Vector3,
      radius: number,
      explosionOptions?: ExplosionOptions,
  ): boolean

• Parameters

  • location: Vector3

    The location of the explosion.
  • radius: number

    Radius, in blocks, of the explosion to create.
  • OptionalexplosionOptions: ExplosionOptions

    Additional configurable options for the explosion.

  Returns boolean

  Remarks

  Creates an explosion at the specified location.

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

  Throws

  This function can throw errors.

  LocationInUnloadedChunkError

  LocationOutOfWorldBoundariesError

  Example: createExplosions.ts

  // Creates an explosion of radius 15 that does not break blocks
  import { DimensionLocation } from '@minecraft/server';
  
  function createExplosions(location: DimensionLocation) {
      // Creates an explosion of radius 15 that does not break blocks
      location.dimension.createExplosion(location, 15, { breaksBlocks: false });
  
      // Creates an explosion of radius 15 that does not cause fire
      location.dimension.createExplosion(location, 15, { causesFire: true });
  
      // Creates an explosion of radius 10 that can go underwater
      location.dimension.createExplosion(location, 10, { allowUnderwater: true });
  }
  Copy

getBlock

• getBlock(location: Vector3): Block

• Parameters

  • location: Vector3

    The location at which to return a block.

  Returns Block

  Block at the specified location, or 'undefined' if asking for a block at an unloaded chunk.

  Remarks

  Returns a block instance at the given location.

  Throws

  PositionInUnloadedChunkError: Exception thrown when trying to interact with a Block object that isn't in a loaded and ticking chunk anymore

  PositionOutOfWorldBoundariesError: Exception thrown when trying to interact with a position outside of dimension height range

  LocationInUnloadedChunkError

  LocationOutOfWorldBoundariesError

getBlockFromRay

• getBlockFromRay(
      location: Vector3,
      direction: Vector3,
      options?: BlockRaycastOptions,
  ): BlockRaycastHit

• Parameters

  • location: Vector3

    Location from where to initiate the ray check.
  • direction: Vector3

    Vector direction to cast the ray.
  • Optionaloptions: BlockRaycastOptions

    Additional options for processing this raycast query.

  Returns BlockRaycastHit

  Remarks

  Gets the first block that intersects with a vector emanating from a location.

  Throws

  This function can throw errors.

getEntities

• getEntities(options?: EntityQueryOptions): Entity[]

• Parameters

  • Optionaloptions: EntityQueryOptions

    Additional options that can be used to filter the set of entities returned.

  Returns Entity[]

  An entity array.

  Remarks

  Returns a set of entities based on a set of conditions defined via the EntityQueryOptions set of filter criteria.

  Throws

  This function can throw errors.

  Example: checkFeatherNearby.ts

  import { DimensionLocation, EntityComponentTypes } from "@minecraft/server";
  
  // Returns true if a feather item entity is within 'distance' blocks of 'location'.
  function isFeatherNear(location: DimensionLocation, distance: number): boolean {
      const items = location.dimension.getEntities({
          location: location,
          maxDistance: 20,
      });
  
      for (const item of items) {
          const itemComp = item.getComponent(EntityComponentTypes.Item);
  
          if (itemComp) {
              if (itemComp.itemStack.typeId.endsWith('feather')) {
                  return true;
              }
          }
      }
  
      return false;
  }
  Copy

  Example: tagsQuery.ts

  import { EntityQueryOptions, DimensionLocation } from '@minecraft/server';
  
  function mobParty(targetLocation: DimensionLocation) {
      const mobs = ['creeper', 'skeleton', 'sheep'];
  
      // create some sample mob data
      for (let i = 0; i < 10; i++) {
          const mobTypeId = mobs[i % mobs.length];
          const entity = targetLocation.dimension.spawnEntity(mobTypeId, targetLocation);
          entity.addTag('mobparty.' + mobTypeId);
      }
  
      const eqo: EntityQueryOptions = {
          tags: ['mobparty.skeleton'],
      };
  
      for (const entity of targetLocation.dimension.getEntities(eqo)) {
          entity.kill();
      }
  }
  Copy

  Example: getFilteredEntities.ts

  import { EntityQueryOptions, GameMode, world } from "@minecraft/server";
  
  const options: EntityQueryOptions = {
      families: ["mob", "animal"],
      excludeTypes: ["cow"],
      maxDistance: 50,
      excludeGameModes: [GameMode.creative, GameMode.spectator],
  };
  
  const filteredEntities = world.getDimension("overworld").getEntities(options);
  console.log(
      "Filtered Entities:",
      filteredEntities.map((entity) => entity.typeId)
  );
  Copy

getEntitiesAtBlockLocation

• getEntitiesAtBlockLocation(location: Vector3): Entity[]

• Parameters

  • location: Vector3

    The location at which to return entities.

  Returns Entity[]

  Zero or more entities at the specified location.

  Remarks

  Returns a set of entities at a particular location.

getEntitiesFromRay

• getEntitiesFromRay(
      location: Vector3,
      direction: Vector3,
      options?: EntityRaycastOptions,
  ): EntityRaycastHit[]

• Parameters

  • location: Vector3
  • direction: Vector3
  • Optionaloptions: EntityRaycastOptions

    Additional options for processing this raycast query.

  Returns EntityRaycastHit[]

  Remarks

  Gets entities that intersect with a specified vector emanating from a location.

  Throws

  This function can throw errors.

getPlayers

• getPlayers(options?: EntityQueryOptions): Player[]

• Parameters

  • Optionaloptions: EntityQueryOptions

    Additional options that can be used to filter the set of players returned.

  Returns Player[]

  A player array.

  Remarks

  Returns a set of players based on a set of conditions defined via the EntityQueryOptions set of filter criteria.

  Throws

  This function can throw errors.

  Example: getFilteredPlayersInOverworld.ts

  import { EntityQueryOptions, world } from "@minecraft/server";
  
  const entityQueryOptions: EntityQueryOptions = {
      maxDistance: 100,
      scoreOptions: [
          { objective: "kills", minScore: 10 },
          { objective: "deaths", maxScore: 5 },
      ],
  };
  
  const filteredPlayers = world
      .getDimension("overworld")
      .getPlayers(entityQueryOptions);
  console.log(
      "Filtered Players in Overworld:",
      filteredPlayers.map((player) => player.name)
  );
  Copy

playSound

• playSound(
      soundId: string,
      location: Vector3,
      soundOptions?: WorldSoundOptions,
  ): void

• Parameters

  • soundId: string
  • location: Vector3
  • OptionalsoundOptions: WorldSoundOptions

  Returns void

  Remarks

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

  Throws

  This function can throw errors.

runCommand

• runCommand(commandString: string): CommandResult

• Parameters

  • commandString: string

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

  Returns CommandResult

  Returns a command result with a count of successful values from the command.

  Remarks

  Runs a command synchronously using the context of the broader dimenion.

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

  Throws

  Throws an exception if the command fails due to incorrect parameters or command syntax, or in erroneous cases for the command. Note that in many cases, if the command does not operate (e.g., a target selector found no matches), this method will not throw an exception.

  CommandError

runCommandAsync

• runCommandAsync(commandString: string): Promise<CommandResult>

• 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 CommandResult with an indicator of command results.

  Remarks

  Runs a particular command asynchronously from the context of the broader dimension. Note that there is a maximum queue of 128 asynchronous commands that can be run in a given tick.

  Throws

  Throws an exception if the command fails due to incorrect parameters or command syntax, or in erroneous cases for the command. Note that in many cases, if the command does not operate (e.g., a target selector found no matches), this method will not throw an exception.

setWeather

• setWeather(weatherType: WeatherType, duration?: number): void

• Parameters

  • weatherType: WeatherType

    Set the type of weather to apply.
  • Optionalduration: number

    Sets the duration of the weather (in ticks). If no duration is provided, the duration will be set to a random duration between 300 and 900 seconds.

  Returns void

  Remarks

  Sets the current weather within the dimension

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

  Throws

  This function can throw errors.

spawnEntity

• spawnEntity(identifier: string, location: Vector3): Entity

• Parameters

  • identifier: string

    Identifier of the type of entity to spawn. If no namespace is specified, 'minecraft:' is assumed.
  • location: Vector3

    The location at which to create the entity.

  Returns Entity

  Newly created entity at the specified location.

  Remarks

  Creates a new entity (e.g., a mob) at the specified location.

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

  Throws

  This function can throw errors.

  LocationInUnloadedChunkError

  LocationOutOfWorldBoundariesError

  Example: createOldHorse.ts

  // Spawns an adult horse
  import { DimensionLocation } from '@minecraft/server';
  
  function spawnAdultHorse(location: DimensionLocation) {
      // Create a horse and triggering the 'ageable_grow_up' event, ensuring the horse is created as an adult
      location.dimension.spawnEntity('minecraft:horse<minecraft:ageable_grow_up>', location);
  }
  Copy

  Example: quickFoxLazyDog.ts

  // Spawns a fox over a dog
  import { DimensionLocation } from '@minecraft/server';
  import { MinecraftEntityTypes } from '@minecraft/vanilla-data';
  
  function spawnAdultHorse(location: DimensionLocation) {
      // Create fox (our quick brown fox)
      const fox = location.dimension.spawnEntity(MinecraftEntityTypes.Fox, {
          x: location.x,
          y: location.y + 2,
          z: location.z,
      });
  
      fox.addEffect('speed', 10, {
          amplifier: 2,
      });
  
      // Create wolf (our lazy dog)
      const wolf = location.dimension.spawnEntity(MinecraftEntityTypes.Wolf, location);
      wolf.addEffect('slowness', 10, {
          amplifier: 2,
      });
      wolf.isSneaking = true;
  }
  Copy

spawnItem

• spawnItem(itemStack: ItemStack, location: Vector3): Entity

• Parameters

  • itemStack: ItemStack
  • location: Vector3

    The location at which to create the item stack.

  Returns Entity

  Newly created item stack entity at the specified location.

  Remarks

  Creates a new item stack as an entity at the specified location.

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

  Throws

  This function can throw errors.

  LocationInUnloadedChunkError

  LocationOutOfWorldBoundariesError

  Example: spawnFeatherItem.ts

  // Spawns a feather at a location
  import { ItemStack, DimensionLocation } from '@minecraft/server';
  import { MinecraftItemTypes } from '@minecraft/vanilla-data';
  
  function spawnFeather(location: DimensionLocation) {
      const featherItem = new ItemStack(MinecraftItemTypes.Feather, 1);
      location.dimension.spawnItem(featherItem, location);
  }
  Copy

spawnParticle

• spawnParticle(
      effectName: string,
      location: Vector3,
      molangVariables?: MolangVariableMap,
  ): void

• 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

  Remarks

  Creates a new particle emitter at a specified location in the world.

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

  Throws

  This function can throw errors.

  LocationInUnloadedChunkError

  LocationOutOfWorldBoundariesError

  Example: spawnParticle.ts

  // A function that spawns a particle at a random location near the target location for all players in the server
  import { world, MolangVariableMap, DimensionLocation, Vector3 } 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);
      }
  }
  Copy