Class: Dimension

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

Constructors

new Dimension()

private new Dimension(): Dimension

Returns

Dimension

Properties

heightRange

readonly heightRange: NumberRange

Remarks

Height range of the dimension.

Throws

This property can throw when used.

---

id

readonly id: string

Remarks

Identifier of the dimension.

Methods

containsBlock()

Beta

containsBlock(volume, filter, allowUnloadedChunks?): boolean

Parameters

Parameter	Type
volume	BlockVolumeBase
filter	BlockFilter
allowUnloadedChunks?	boolean

Returns

boolean

Throws

This function can throw errors.

Error

UnloadedChunksError

---

createExplosion()

createExplosion(location, radius, explosionOptions?): boolean

Parameters

Parameter	Type	Description
location	Vector3	The location of the explosion.
radius	number	Radius, in blocks, of the explosion to create.
explosionOptions?	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

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

---

fillBlocks()

Beta

fillBlocks(volume, block, options?): ListBlockVolume

Parameters

Parameter	Type	Description
volume	BlockVolumeBase | CompoundBlockVolume	-
block	string | BlockPermutation | BlockType	Type of block to fill the volume with.
options?	BlockFillOptions	A set of additional options, such as a matching block to potentially replace this fill block with.

Returns

ListBlockVolume

Returns number of blocks placed.

Remarks

Fills an area between begin and end with block of type block.

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

Throws

This function can throw errors.

minecraftcommon.EngineError

Error

UnloadedChunksError

---

findClosestBiome()

Beta

findClosestBiome(pos, biomeToFind, options?): Vector3

Parameters

Parameter	Type	Description
pos	Vector3	Starting location to look for a biome to find.
biomeToFind	string | BiomeType	Identifier of the biome to look for.
options?	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.

Remarks

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.

Throws

This function can throw errors.

minecraftcommon.EngineError

Error

---

getBlock()

getBlock(location): Block

Parameters

Parameter	Type	Description
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

---

getBlockAbove()

Beta

getBlockAbove(location, options?): Block

Parameters

Parameter	Type
location	Vector3
options?	BlockRaycastOptions

Returns

Block

Remarks

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

Throws

This function can throw errors.

---

getBlockBelow()

Beta

getBlockBelow(location, options?): Block

Parameters

Parameter	Type
location	Vector3
options?	BlockRaycastOptions

Returns

Block

Remarks

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

Throws

This function can throw errors.

---

getBlockFromRay()

getBlockFromRay(location, direction, options?): BlockRaycastHit

Parameters

Parameter	Type	Description
location	Vector3	Location from where to initiate the ray check.
direction	Vector3	Vector direction to cast the ray.
options?	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.

---

getBlocks()

Beta

getBlocks(volume, filter, allowUnloadedChunks?): ListBlockVolume

Parameters

Parameter	Type
volume	BlockVolumeBase
filter	BlockFilter
allowUnloadedChunks?	boolean

Returns

ListBlockVolume

Throws

This function can throw errors.

Error

UnloadedChunksError

---

getEntities()

getEntities(options?): Entity[]

Parameters

Parameter	Type	Description
options?	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.

Examples

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

---

getEntitiesAtBlockLocation()

getEntitiesAtBlockLocation(location): Entity[]

Parameters

Parameter	Type	Description
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, direction, options?): EntityRaycastHit[]

Parameters

Parameter	Type	Description
location	Vector3	-
direction	Vector3	-
options?	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?): Player[]

Parameters

Parameter	Type	Description
options?	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.

---

getTopmostBlock()

Beta

getTopmostBlock(locationXZ, minHeight?): Block

Parameters

Parameter	Type
locationXZ	VectorXZ
minHeight?	number

Returns

Block

Remarks

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

Throws

This function can throw errors.

---

getWeather()

Beta

getWeather(): WeatherType

Returns

WeatherType

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

Remarks

Returns the current weather.

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

---

playSound()

Beta

playSound(soundId, location, soundOptions?): void

Parameters

Parameter	Type
soundId	string
location	Vector3
soundOptions?	WorldSoundOptions

Returns

void

Remarks

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

Throws

This function can throw errors.

---

runCommand()

runCommand(commandString): CommandResult

Parameters

Parameter	Type	Description
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): Promise ↗️ <CommandResult>

Parameters

Parameter	Type	Description
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.

---

setBlockPermutation()

Beta

setBlockPermutation(location, permutation): void

Parameters

Parameter	Type
location	Vector3
permutation	BlockPermutation

Returns

void

Remarks

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

Throws

This function can throw errors.

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

---

setBlockType()

Beta

setBlockType(location, blockType): void

Parameters

Parameter	Type
location	Vector3
blockType	string | BlockType

Returns

void

Remarks

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

Throws

This function can throw errors.

Error

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

---

setWeather()

setWeather(weatherType, duration?): void

Parameters

Parameter	Type	Description
weatherType	WeatherType	Set the type of weather to apply.
duration?	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, location, options?): Entity

Parameters

Parameter	Type	Description
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.
options?	SpawnEntityOptions	-

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

Examples

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

---

spawnItem()

spawnItem(itemStack, location): Entity

Parameters

Parameter	Type	Description
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

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

---

spawnParticle()

spawnParticle(effectName, location, molangVariables?): void

Parameters

Parameter	Type	Description
effectName	string	Identifier of the particle to create.
location	Vector3	The location at which to create the particle emitter.
molangVariables?	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

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