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

Hierarchy

  • Dimension

Constructors

Properties

heightRange: NumberRange

Remarks

Height range of the dimension.

Throws

This property can throw when used.

id: string

Remarks

Identifier of the dimension.

Methods

  • Beta

    Parameters

    • volume: BlockVolumeBase

      Volume of blocks that will be checked.

    • filter: BlockFilter

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

    • Optional allowUnloadedChunks: boolean

      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.

      Optional

    Returns boolean

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

    Remarks

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

    Throws

    This function can throw errors.

    Error

    UnloadedChunksError

  • Parameters

    • location: Vector3

      The location of the explosion.

    • radius: number

      Radius, in blocks, of the explosion to create.

    • Optional explosionOptions: ExplosionOptions

      Additional configurable options for the explosion.

      Optional

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

  • Beta

    Parameters

    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

    Example

    fillBlockPermutation.js

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

    // Command: /fill 0 10 0 20 30 40 tnt["allow_underwater_bit"=true] replace air
    const overworld = world.getDimension("overworld");
    const volume = new BlockVolume({ x: 0, y: 10, z: 0 }, { x: 20, y: 30, z: 40 });
    const tnt = BlockPermutation.resolve("minecraft:tnt", {
    allow_underwater_bit: true,
    });
    overworld.fillBlocks(volume, tnt, {
    blockFilter: { excludeTypes: ["minecraft:air"] },
    });

    Example

    fillBlockType.ts

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

    function fillBlockType(
    dimension: Dimension,
    from: Vector3,
    to: Vector3,
    block: string
    ): void {
    const volume = new BlockVolume(from, to);
    dimension.fillBlocks(volume, block);
    }

    // Command: /fill 0 10 0 20 30 40 diamond_block
    const overworld = world.getDimension("overworld");
    fillBlockType(
    overworld,
    { x: 0, y: 10, z: 0 },
    { x: 20, y: 30, z: 40 },
    "minecraft:diamond_block"
    );

  • Beta

    Parameters

    • pos: Vector3

      Starting location to look for a biome to find.

    • biomeToFind: string | BiomeType

      Identifier of the biome to look for.

    • Optional options: BiomeSearchOptions

      Additional selection criteria for a biome search.

      Optional

    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

    Example

    playerGetBiome.ts

    import { BiomeTypes, Player } from "@minecraft/server";

    const biomeTypes = BiomeTypes.getAll();

    // Finds which biome player is in currently
    function getBiome(player: Player): string {
    for (const currentBiome of biomeTypes) {
    const biome = player.dimension.findClosestBiome(
    player.location,
    currentBiome,
    { boundingSize: { x: 64, y: 64, z: 64 } }
    );
    if (biome !== undefined) {
    return currentBiome.id;
    }
    }
    throw new Error("Player is not in any biome");
    }

  • 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

  • Beta

    Parameters

    Returns Block

    Remarks

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

    Throws

    This function can throw errors.

  • Beta

    Parameters

    Returns Block

    Remarks

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

    Throws

    This function can throw errors.

  • Parameters

    • location: Vector3

      Location from where to initiate the ray check.

    • direction: Vector3

      Vector direction to cast the ray.

    • Optional options: BlockRaycastOptions

      Additional options for processing this raycast query.

      Optional

    Returns BlockRaycastHit

    Remarks

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

    Throws

    This function can throw errors.

  • Beta

    Parameters

    • volume: BlockVolumeBase

      Volume of blocks that will be checked.

    • filter: BlockFilter

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

    • Optional allowUnloadedChunks: boolean

      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.

      Optional

    Returns ListBlockVolume

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

    Remarks

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

    Throws

    This function can throw errors.

    Error

    UnloadedChunksError

    Example

    cobblestoneTerrain.js

    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

    • Optional options: EntityQueryOptions

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

      Optional

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

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

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

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

  • Parameters

    Returns EntityRaycastHit[]

    Remarks

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

    Throws

    This function can throw errors.

  • Parameters

    • Optional options: EntityQueryOptions

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

      Optional

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

  • Parameters

    • locationXZ: VectorXZ

      Location to retrieve the topmost block for.

    • Optional minHeight: number

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

      Optional

    Returns Block

    Remarks

    Returns the highest block at the given XZ location.

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

    Throws

    This function can throw errors.

  • Beta

    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.

  • Parameters

    • soundId: string

      Identifier of the sound.

    • location: Vector3

      Location of the sound.

    • Optional soundOptions: WorldSoundOptions

      Additional options for configuring additional effects for the sound.

      Optional

    Returns void

    Remarks

    Plays a sound for all players.

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

    Throws

    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.

    Example

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

  • 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

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

  • Parameters

    • location: Vector3

      The location within the dimension to set the block.

    • permutation: BlockPermutation

      The block permutation to set.

    Returns void

    Remarks

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

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

    Throws

    Throws if the location is within an unloaded chunk or outside of the world bounds.

    LocationInUnloadedChunkError

    LocationOutOfWorldBoundariesError

  • Parameters

    • location: Vector3

      The location within the dimension to set the block.

    • blockType: string | BlockType

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

    Returns void

    Remarks

    Sets a block at a given location within the dimension.

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

    Throws

    Throws if the location is within an unloaded chunk or outside of the world bounds.

    Error

    LocationInUnloadedChunkError

    LocationOutOfWorldBoundariesError

  • Parameters

    • weatherType: WeatherType

      Set the type of weather to apply.

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

      Optional

    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.

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

    • Optional options: SpawnEntityOptions
      Optional

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

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

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

  • Parameters

    • effectName: string

      Identifier of the particle to create.

    • location: Vector3

      The location at which to create the particle emitter.

    • Optional molangVariables: MolangVariableMap

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

      Optional

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