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

    A class that represents a particular dimension (e.g., The End) within a world.

    Index

    Properties

    heightRange: NumberRange

    Height range of the dimension.

    This property can throw when used.

    id: string

    Identifier of the dimension.

    Methods

    • 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

      Creates an explosion at the specified location.

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

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

      Parameters

      • pos: Vector3

        Starting location to look for a biome to find.

      • biomeToFind: string | BiomeType

        Identifier of the biome to look for.

      • Optionaloptions: BiomeSearchOptions

        Additional selection criteria for a biome search.

      Returns Vector3

      Returns a location of the biome, or undefined if a biome could not be found.

      Finds the location of the closest biome of a particular type. Note that the findClosestBiome operation can take some time to complete, so avoid using many of these calls within a particular tick.

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

      This function can throw errors.

      minecraftcommon.EngineError

      Error

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

      Returns a block instance at the given location.

      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

    • 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

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

      This function can throw errors.

    • Beta

      Parameters

      Returns ListBlockVolume

      This function can throw errors.

      Error

      UnloadedChunksError

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

      // Get every non-air block location at chunk (0, 0)
      const overworld = world.getDimension("overworld");
      const volume = new BlockVolume(
      { x: 0, y: overworld.heightRange.min, z: 0 },
      { x: 15, y: overworld.heightRange.max, z: 15 }
      );
      const locations = overworld.getBlocks(
      volume,
      { excludeTypes: ["minecraft:air"] },
      false
      );

      // A simple generator that replace non-air blocks to cobblestone at chunk (0, 0),
      // yielding after each block placement.
      function* blockPlacingGenerator() {
      for (const location of locations.getBlockLocationIterator()) {
      const block = overworld.getBlock(location);
      block.setPermutation(BlockPermutation.resolve("minecraft:cobblestone"));
      yield;
      }
      }

      system.runJob(blockPlacingGenerator());
    • Parameters

      • Optionaloptions: EntityQueryOptions

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

      Returns Entity[]

      An entity array.

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

      This function can throw errors.

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

      • location: Vector3

        The location at which to return entities.

      Returns Entity[]

      Zero or more entities at the specified location.

      Returns a set of entities at a particular location.

    • Parameters

      • Optionaloptions: EntityQueryOptions

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

      Returns Player[]

      A player array.

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

      This function can throw errors.

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

      Parameters

      • locationXZ: VectorXZ
      • OptionalminHeight: number

      Returns Block

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

      This function can throw errors.

    • Beta

      Returns WeatherType

      Returns a WeatherType that explains the broad category of weather that is currently going on.

      Returns the current weather.

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

    • Parameters

      Returns void

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

      This function can throw errors.

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

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

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

      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

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

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

    • 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

      Sets the current weather within the dimension

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

      This function can throw errors.

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

      • Optionaloptions: SpawnEntityOptions

      Returns Entity

      Newly created entity at the specified location.

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

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

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

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

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

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

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

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