Edit

Dimension Class

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

Properties

heightRange

read-only heightRange: minecraftcommon.NumberRange;

Height range of the dimension.

Type: @minecraft/common.NumberRange

Notes:

  • This property can throw errors when used.

id

read-only id: string;

Identifier of the dimension.

Type: string

localizationKey

read-only localizationKey: string;

Key for the localization of a dimension's name used by language files.

Type: string

Methods

containsBiomes

containsBiomes(volume: BlockVolumeBase, biomeFilter: BiomeFilter, isSuperset: boolean): boolean

Checks if an area contains the specified biomes. If the area is partially inside world boundaries, only the area that is in bounds will be searched. This operation takes longer proportional to both the area of the volume and the number of biomes to check.

Parameters

  • volume: BlockVolumeBase

    Area to check biomes in.

  • biomeFilter: BiomeFilter

    A list of biomes to include and exclude. A list of tags to include and exclude. Will return false if a biome is found in the area that is in the excluded list or contains any of the excluded tags.

  • isSuperset: boolean

    Superset is used to determine the strictness of the filter. If superset is set to true then the area must contain one or more biomes in the included list or that contains all of the included tags. If superset is set to false then the area must contain only biomes in the included list and that contain all of the included tags

Returns boolean - Returns true if the biomes in the area match the filter settings passed in. Otherwise, returns false.

Notes:

containsBlock

containsBlock(volume: BlockVolumeBase, filter: BlockFilter, allowUnloadedChunks?: boolean): boolean

Searches the block volume for a block that satisfies the block filter.

Parameters

  • volume: BlockVolumeBase

    Volume of blocks that will be checked.

  • filter: BlockFilter

    Block filter that will be checked against each block in the volume.

  • allowUnloadedChunks?: boolean = false

    If set to true will suppress the UnloadedChunksError if some or all of the block volume is outside of the loaded chunks. Will only check the block locations that are within the loaded chunks in the volume.

Returns boolean - Returns true if at least one block in the volume satisfies the filter, false otherwise.

Notes:

createExplosion

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

Creates an explosion at the specified location.

Parameters

  • location: Vector3

    The location of the explosion.

  • radius: number

    • Bounds: [0, 1000]

    Radius, in blocks, of the explosion to create.

  • explosionOptions?: ExplosionOptions = null

    Additional configurable options for the explosion.

Returns boolean

Notes:

Examples

createExplosion.ts
import { DimensionLocation } from '@minecraft/server';

function createExplosion(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  log('Creating an explosion of radius 10.');
  targetLocation.dimension.createExplosion(targetLocation, 10);
}

(preview) Work with this sample on the MCTools.dev code sandbox.

createNoBlockExplosion.ts
import { DimensionLocation } from '@minecraft/server';
import { Vector3Utils } from '@minecraft/math';

function createNoBlockExplosion(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  const explodeNoBlocksLoc = Vector3Utils.floor(Vector3Utils.add(targetLocation, { x: 1, y: 2, z: 1 }));

  log('Creating an explosion of radius 15 that does not break blocks.');
  targetLocation.dimension.createExplosion(explodeNoBlocksLoc, 15, { breaksBlocks: false });
}

(preview) Work with this sample on the MCTools.dev code sandbox.

createExplosions.ts
import { DimensionLocation } from '@minecraft/server';
import { Vector3Utils } from '@minecraft/math';

function createExplosions(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  const explosionLoc = Vector3Utils.add(targetLocation, { x: 0.5, y: 0.5, z: 0.5 });

  log('Creating an explosion of radius 15 that causes fire.');
  targetLocation.dimension.createExplosion(explosionLoc, 15, { causesFire: true });

  const belowWaterLoc = Vector3Utils.add(targetLocation, { x: 3, y: 1, z: 3 });

  log('Creating an explosion of radius 10 that can go underwater.');
  targetLocation.dimension.createExplosion(belowWaterLoc, 10, { allowUnderwater: true });
}

(preview) Work with this sample on the MCTools.dev code sandbox.

fillBlocks

fillBlocks(volume: BlockVolumeBase, block: BlockPermutation | BlockType | string, options?: BlockFillOptions): ListBlockVolume

Fills an area of blocks with a specific block type.

Parameters

  • volume: BlockVolumeBase

    Volume of blocks to be filled.

  • block: BlockPermutation | BlockType | string

    Type of block to fill the volume with.

  • options?: BlockFillOptions = null

    A set of additional options, such as a block filter which can be used to include / exclude specific blocks in the fill.

Returns ListBlockVolume - Returns a ListBlockVolume which contains all the blocks that were placed.

Notes:

findClosestBiome

findClosestBiome(pos: Vector3, biomeToFind: BiomeType | string, options?: BiomeSearchOptions): Vector3 | undefined

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.

Parameters

  • pos: Vector3

    Starting location to look for a biome to find.

  • biomeToFind: BiomeType | string

    Identifier of the biome to look for.

  • options?: BiomeSearchOptions = null

    Additional selection criteria for a biome search.

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

Caution

This function is still in pre-release. Its signature may change or it may be removed in future releases.

Notes:

getBiome

getBiome(location: Vector3): BiomeType

Returns the biome type at the specified location.

Parameters

  • location: Vector3

    Location at which to check the biome.

Returns BiomeType

Notes:

getBlock

getBlock(location: Vector3): Block | undefined

Returns a block instance at the given location.

Parameters

  • location: Vector3

    The location at which to return a block.

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

Notes:

getBlockAbove

getBlockAbove(location: Vector3, options?: BlockRaycastOptions): Block | undefined

Gets the first block found above a given block location based on the given options (by default will find the first solid block above).

Parameters

  • location: Vector3

    Location to retrieve the block above from.

  • options?: BlockRaycastOptions = null

    The options to decide if a block is a valid result.

Returns Block | undefined

Notes:

  • This function can throw errors.

getBlockBelow

getBlockBelow(location: Vector3, options?: BlockRaycastOptions): Block | undefined

Gets the first block found below a given block location based on the given options (by default will find the first solid block below).

Parameters

  • location: Vector3

    Location to retrieve the block below from.

  • options?: BlockRaycastOptions = null

    The options to decide if a block is a valid result.

Returns Block | undefined

Notes:

  • This function can throw errors.

getBlockFromRay

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

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

Parameters

  • location: Vector3

    Location from where to initiate the ray check.

  • direction: Vector3

    Vector direction to cast the ray.

  • options?: BlockRaycastOptions = null

    Additional options for processing this raycast query.

Returns BlockRaycastHit | undefined

Notes:

  • This function can throw errors.

getBlocks

getBlocks(volume: BlockVolumeBase, filter: BlockFilter, allowUnloadedChunks?: boolean): ListBlockVolume

Gets all the blocks in a volume that satisfy the filter.

Parameters

  • volume: BlockVolumeBase

    Volume of blocks that will be checked.

  • filter: BlockFilter

    Block filter that will be checked against each block in the volume.

  • allowUnloadedChunks?: boolean = false

    If set to true will suppress the UnloadedChunksError if some or all of the block volume is outside of the loaded chunks. Will only check the block locations that are within the loaded chunks in the volume.

Returns ListBlockVolume - Returns the ListBlockVolume that contains all the block locations that satisfied the block filter.

Notes:

getEntities

getEntities(options?: EntityQueryOptions): Entity[]

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

Parameters

  • options?: EntityQueryOptions = null

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

Returns Entity[] - An entity array.

Notes:

Examples

bounceSkeletons.ts
import { EntityQueryOptions, DimensionLocation } from '@minecraft/server';

function bounceSkeletons(targetLocation: DimensionLocation) {
  const mobs = ['creeper', 'skeleton', 'sheep'];

  // create some sample mob data
  for (let i = 0; i < 10; i++) {
    targetLocation.dimension.spawnEntity(mobs[i % mobs.length], targetLocation);
  }

  const eqo: EntityQueryOptions = {
    type: 'skeleton',
  };

  for (const entity of targetLocation.dimension.getEntities(eqo)) {
    entity.applyKnockback(0, 0, 0, 1);
  }
}

(preview) Work with this sample on the MCTools.dev code sandbox.

tagsQuery.ts
import { EntityQueryOptions, DimensionLocation } from '@minecraft/server';

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

(preview) Work with this sample on the MCTools.dev code sandbox.

testThatEntityIsFeatherItem.ts
import { EntityItemComponent, EntityComponentTypes, DimensionLocation } from '@minecraft/server';

function testThatEntityIsFeatherItem(
  log: (message: string, status?: number) => void,
  targetLocation: DimensionLocation
) {
  const items = targetLocation.dimension.getEntities({
    location: targetLocation,
    maxDistance: 20,
  });

  for (const item of items) {
    const itemComp = item.getComponent(EntityComponentTypes.Item) as EntityItemComponent;

    if (itemComp) {
      if (itemComp.itemStack.typeId.endsWith('feather')) {
        log('Success! Found a feather', 1);
      }
    }
  }
}

(preview) Work with this sample on the MCTools.dev code sandbox.

getEntitiesAtBlockLocation

getEntitiesAtBlockLocation(location: Vector3): Entity[]

Returns a set of entities at a particular location.

Parameters

  • location: Vector3

    The location at which to return entities.

Returns Entity[] - Zero or more entities at the specified location.

getEntitiesFromRay

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

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

Parameters

Returns EntityRaycastHit[]

Notes:

getGeneratedStructures

getGeneratedStructures(location: Vector3): (minecraftvanilladata.MinecraftFeatureTypes | string)[]

Returns a vector of generated structures that contain the specified location (ex: Pillager Outpost, Mineshaft, etc.). The vector will be empty if no structures are found.

Parameters

  • location: Vector3

    Location at which to check for structures.

Returns (minecraftvanilladata.MinecraftFeatureTypes | string)[]

Caution

This function is still in pre-release. Its signature may change or it may be removed in future releases.

Notes:

getLightLevel

getLightLevel(location: Vector3): number

Returns the total brightness level of light shining on a certain block position.

Parameters

  • location: Vector3

    Location of the block we want to check the brightness of.

Returns number - The brightness level on the block.

Notes:

getPlayers

getPlayers(options?: EntityQueryOptions): Player[]

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

Parameters

  • options?: EntityQueryOptions = null

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

Returns Player[] - A player array.

Notes:

getSkyLightLevel

getSkyLightLevel(location: Vector3): number

Returns the brightness level of light shining from the sky on a certain block position.

Parameters

  • location: Vector3

    Position of the block we want to check the brightness of.

Returns number - The brightness level on the block.

Notes:

getTopmostBlock

getTopmostBlock(locationXZ: VectorXZ, minHeight?: number): Block | undefined

Returns the highest block at the given XZ location.

Parameters

  • locationXZ: VectorXZ

    Location to retrieve the topmost block for.

  • minHeight?: number = null

    The Y height to begin the search from. Defaults to the maximum dimension height.

Returns Block | undefined

Notes:

  • This function can throw errors.

getWeather

getWeather(): WeatherType

Returns the current weather.

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

Caution

This function is still in pre-release. Its signature may change or it may be removed in future releases.

isChunkLoaded

isChunkLoaded(location: Vector3): boolean

Returns true if the chunk at the given location is loaded (and valid for use with scripting).

Parameters

  • location: Vector3

    Location to check if the chunk is loaded.

Returns boolean

placeFeature

placeFeature(featureName: string, location: Vector3, shouldThrow?: boolean): boolean

Places the given feature into the dimension at the specified location.

Parameters

  • featureName: string

    The string identifier for the feature.

  • location: Vector3

    Location to place the feature.

  • shouldThrow?: boolean = false

    Specifies if the function call will throw an error if the feature could not be placed.

    Note: The function call will always throw an error if using an unknown feature name or trying to place in a unloaded chunk.

Returns boolean

Notes:

placeFeatureRule

placeFeatureRule(featureRuleName: string, location: Vector3): boolean

Places the given feature rule into the dimension at the specified location.

Parameters

  • featureRuleName: string

    The string identifier for the feature rule.

  • location: Vector3

    Location to place the feature rule.

Returns boolean

Notes:

playSound

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

Plays a sound for all players.

Parameters

  • soundId: string

    Identifier of the sound.

  • location: Vector3

    Location of the sound.

  • soundOptions?: WorldSoundOptions = null

    Additional options for configuring additional effects for the sound.

Notes:

runCommand

runCommand(commandString: string): CommandResult

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

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.

Notes:

  • This function can't be called in restricted-execution mode.
  • This function can throw errors.

setBlockPermutation

setBlockPermutation(location: Vector3, permutation: BlockPermutation): void

Sets a block in the world using a BlockPermutation. BlockPermutations are blocks with a particular state.

Parameters

  • location: Vector3

    The location within the dimension to set the block.

  • permutation: BlockPermutation

    The block permutation to set.

Notes:

setBlockType

setBlockType(location: Vector3, blockType: BlockType | string): void

Sets a block at a given location within the dimension.

Parameters

  • location: Vector3

    The location within the dimension to set the block.

  • blockType: BlockType | string

    The type of block to set. This can be either a string identifier or a BlockType. The default block permutation is used.

Notes:

setWeather

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

Sets the current weather within the dimension

Parameters

  • weatherType: WeatherType

    Set the type of weather to apply.

  • duration?: number = null

    • Bounds: [1, 1000000]

    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.

Notes:

  • This function can't be called in restricted-execution mode.
  • This function can throw errors.

spawnEntity

spawnEntity(identifier: EntityIdentifierType<NoInfer<T>>, location: Vector3, options?: SpawnEntityOptions): Entity

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

Parameters

  • identifier: EntityIdentifierType<NoInfer<T>>

    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.

  • options?: SpawnEntityOptions

Returns Entity - Newly created entity at the specified location.

Notes:

Examples

spawnAdultHorse.ts
import { DimensionLocation } from '@minecraft/server';
import { Vector3Utils } from '@minecraft/math';

function spawnAdultHorse(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  log('Create a horse and triggering the ageable_grow_up event, ensuring the horse is created as an adult');
  targetLocation.dimension.spawnEntity(
    'minecraft:horse<minecraft:ageable_grow_up>',
    Vector3Utils.add(targetLocation, { x: 0, y: 1, z: 0 })
  );
}

(preview) Work with this sample on the MCTools.dev code sandbox.

quickFoxLazyDog.ts
import { DimensionLocation } from '@minecraft/server';
import { MinecraftEntityTypes, MinecraftEffectTypes } from '@minecraft/vanilla-data';

function quickFoxLazyDog(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  const fox = targetLocation.dimension.spawnEntity(MinecraftEntityTypes.Fox, {
    x: targetLocation.x + 1,
    y: targetLocation.y + 2,
    z: targetLocation.z + 3,
  });

  fox.addEffect(MinecraftEffectTypes.Speed, 10, {
    amplifier: 2,
  });
  log('Created a fox.');

  const wolf = targetLocation.dimension.spawnEntity(MinecraftEntityTypes.Wolf, {
    x: targetLocation.x + 4,
    y: targetLocation.y + 2,
    z: targetLocation.z + 3,
  });
  wolf.addEffect(MinecraftEffectTypes.Slowness, 10, {
    amplifier: 2,
  });
  wolf.isSneaking = true;
  log('Created a sneaking wolf.', 1);
}

(preview) Work with this sample on the MCTools.dev code sandbox.

triggerEvent.ts
import { DimensionLocation } from '@minecraft/server';
import { MinecraftEntityTypes } from '@minecraft/vanilla-data';

function triggerEvent(targetLocation: DimensionLocation) {
  const creeper = targetLocation.dimension.spawnEntity(MinecraftEntityTypes.Creeper, targetLocation);

  creeper.triggerEvent('minecraft:start_exploding_forced');
}

(preview) Work with this sample on the MCTools.dev code sandbox.

spawnItem

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

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

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.

Notes:

Examples

itemStacks.ts
import { ItemStack, DimensionLocation } from '@minecraft/server';
import { MinecraftItemTypes } from '@minecraft/vanilla-data';

function itemStacks(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  const oneItemLoc = { x: targetLocation.x + targetLocation.y + 3, y: 2, z: targetLocation.z + 1 };
  const fiveItemsLoc = { x: targetLocation.x + 1, y: targetLocation.y + 2, z: targetLocation.z + 1 };
  const diamondPickaxeLoc = { x: targetLocation.x + 2, y: targetLocation.y + 2, z: targetLocation.z + 4 };

  const oneEmerald = new ItemStack(MinecraftItemTypes.Emerald, 1);
  const onePickaxe = new ItemStack(MinecraftItemTypes.DiamondPickaxe, 1);
  const fiveEmeralds = new ItemStack(MinecraftItemTypes.Emerald, 5);

  log(`Spawning an emerald at (${oneItemLoc.x}, ${oneItemLoc.y}, ${oneItemLoc.z})`);
  targetLocation.dimension.spawnItem(oneEmerald, oneItemLoc);

  log(`Spawning five emeralds at (${fiveItemsLoc.x}, ${fiveItemsLoc.y}, ${fiveItemsLoc.z})`);
  targetLocation.dimension.spawnItem(fiveEmeralds, fiveItemsLoc);

  log(`Spawning a diamond pickaxe at (${diamondPickaxeLoc.x}, ${diamondPickaxeLoc.y}, ${diamondPickaxeLoc.z})`);
  targetLocation.dimension.spawnItem(onePickaxe, diamondPickaxeLoc);
}

(preview) Work with this sample on the MCTools.dev code sandbox.

spawnFeatherItem.ts
import { ItemStack, DimensionLocation } from '@minecraft/server';
import { MinecraftItemTypes } from '@minecraft/vanilla-data';

function spawnFeatherItem(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  const featherItem = new ItemStack(MinecraftItemTypes.Feather, 1);

  targetLocation.dimension.spawnItem(featherItem, targetLocation);
  log(`New feather created at ${targetLocation.x}, ${targetLocation.y}, ${targetLocation.z}!`);
}

(preview) Work with this sample on the MCTools.dev code sandbox.

spawnParticle

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

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

Parameters

  • effectName: string

    Identifier of the particle to create.

  • location: Vector3

    The location at which to create the particle emitter.

  • molangVariables?: MolangVariableMap = null

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

Notes:

Examples

spawnParticle.ts
import { MolangVariableMap, DimensionLocation } from '@minecraft/server';

function spawnParticle(targetLocation: 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 = {
      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,
    };
    targetLocation.dimension.spawnParticle('minecraft:colored_flame_particle', newLocation, molang);
  }
}

(preview) Work with this sample on the MCTools.dev code sandbox.

spawnXp

spawnXp(location: Vector3, amount: number): void

Spawns an experience orb at a specified location in the dimension.

Parameters

  • location: Vector3

    The location at which to spawn the experience orb.

  • amount: number

    • Bounds: [1, 12000]

    The amount of experience to give the experience orb.

Caution

This function is still in pre-release. Its signature may change or it may be removed in future releases.

Notes:

stopAllSounds

stopAllSounds(): void

Stops all sounds from playing for all players.

Caution

This function is still in pre-release. Its signature may change or it may be removed in future releases.

Notes:

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

stopSound

stopSound(soundId: string): void

Stops a sound from playing for all players.

Parameters

  • soundId: string

    Identifier of the sound.

Caution

This function is still in pre-release. Its signature may change or it may be removed in future releases.

Notes:

  • This function can't be called in restricted-execution mode.
  • Last updated on