Edit

Dimension Class

  • Article

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

Warning

This property can throw errors when used.

id

read-only id: string;

Identifier of the dimension.

Type: string

Methods

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.

Caution

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

Warning

This function can throw errors.

Throws Error, UnloadedChunksError

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

    Radius, in blocks, of the explosion to create.

  • explosionOptions?: ExplosionOptions = null

    Additional configurable options for the explosion.

Returns boolean

Important

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

Warning

This function can throw errors.

Throws LocationInUnloadedChunkError, LocationOutOfWorldBoundariesError

Examples

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

fillBlocks

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

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

Parameters

Returns ListBlockVolume - Returns number of blocks placed.

Caution

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

Important

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

Warning

This function can throw errors.

Throws @minecraft/common.EngineError, Error, UnloadedChunksError

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.

Important

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

Warning

This function can throw errors.

Throws @minecraft/common.EngineError, Error

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.

Warning

This function can throw errors.

Throws LocationInUnloadedChunkError, LocationOutOfWorldBoundariesError

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

Warning

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.

Caution

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

Warning

This function can throw errors.

Throws Error, UnloadedChunksError

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.

Warning

This function can throw errors.

Examples

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

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

Warning

This function can throw errors.

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.

Warning

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.

Important

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

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.

Caution

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

Important

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

Warning

This function can throw errors.

An error will be thrown if volume is less than 0.0.

An error will be thrown if fade is less than 0.0.

An error will be thrown if pitch is less than 0.01.

An error will be thrown if volume is less than 0.0.

Examples

playMusicAndSound.ts
import { world, MusicOptions, WorldSoundOptions, PlayerSoundOptions, Vector3 } from '@minecraft/server';
import { MinecraftDimensionTypes } from '@minecraft/vanilla-data';

const players = world.getPlayers();
const targetLocation: Vector3 = {
    x: 0,
    y: 0,
    z: 0,
};

const musicOptions: MusicOptions = {
    fade: 0.5,
    loop: true,
    volume: 1.0,
};
world.playMusic('music.menu', musicOptions);

const worldSoundOptions: WorldSoundOptions = {
    pitch: 0.5,
    volume: 4.0,
};
const overworld = world.getDimension(MinecraftDimensionTypes.Overworld);
overworld.playSound('ambient.weather.thunder', targetLocation, worldSoundOptions);

const playerSoundOptions: PlayerSoundOptions = {
    pitch: 1.0,
    volume: 1.0,
};

players[0].playSound('bucket.fill_water', playerSoundOptions);

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.

Important

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

Warning

This function can throw errors.

Throws CommandError

runCommandAsync

runCommandAsync(commandString: string): Promise<CommandResult>

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.

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.

Warning

This function can throw errors.

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

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

Parameters

Caution

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

Important

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

Warning

This function can throw errors.

Throws LocationInUnloadedChunkError, LocationOutOfWorldBoundariesError

setBlockType

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

Parameters

Caution

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

Important

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

Warning

This function can throw errors.

Throws Error, LocationInUnloadedChunkError, LocationOutOfWorldBoundariesError

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

    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.

Important

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

Warning

This function can throw errors.

spawnEntity

spawnEntity(identifier: string, location: Vector3, options?: SpawnEntityOptions): Entity

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

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.

  • options?: SpawnEntityOptions = null

Returns Entity - Newly created entity at the specified location.

Important

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

Warning

This function can throw errors.

Throws LocationInUnloadedChunkError, LocationOutOfWorldBoundariesError

Examples

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

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.

Important

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

Warning

This function can throw errors.

Throws LocationInUnloadedChunkError, LocationOutOfWorldBoundariesError

Examples

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

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.

Important

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

Warning

This function can throw errors.

Throws LocationInUnloadedChunkError, LocationOutOfWorldBoundariesError

Examples

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