Dimension

Class in @minecraft/server

The world’s one dimension: Basalt has only the overworld.

import { Dimension } from '@minecraft/server';

Example

TypeScript JavaScript

import { world, type Vector3 } from '@minecraft/server';

const overworld = world.getDimension('overworld');
const spot: Vector3 = { x: 0, y: 80, z: 0 };

// Place a block, read it back, then spawn a mob on top of it.
overworld.setBlockType(spot, 'minecraft:gold_block');
console.log(overworld.getBlock(spot)?.typeId);
overworld.spawnEntity('minecraft:cow', { x: 0, y: 81, z: 0 });

import { world } from '@minecraft/server';

const overworld = world.getDimension('overworld');
const spot = { x: 0, y: 80, z: 0 };

// Place a block, read it back, then spawn a mob on top of it.
overworld.setBlockType(spot, 'minecraft:gold_block');
console.log(overworld.getBlock(spot)?.typeId);
overworld.spawnEntity('minecraft:cow', { x: 0, y: 81, z: 0 });

Properties

id

read-only

readonly id: string;

minecraft:overworld.

heightRange

read-only

readonly heightRange: { readonly min: number; readonly max: number };

The lowest and highest block heights: -64 and 319 in the overworld.

localizationKey

read-only

readonly localizationKey: string;

The block’s name key in the language files.

Methods

getBlock

getBlock(location: Vector3): Block | undefined;

The block at a place, or undefined if its chunk isn’t loaded.

Parameters

location

Vector3

Returns

Block | undefined

Types

Vector3Block

setBlockType

setBlockType(location: Vector3, blockType: string | { id: string }): void;

Puts a block there in its default state, as minecraft:stone.

Parameters

location

Vector3

blockType

string | { id: string }

Types

Vector3

setBlockPermutation

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

Puts a block there in exactly this state.

Parameters

location

Vector3

permutation

BlockPermutation

Types

Vector3BlockPermutation

fillBlocks

fillBlocks(volume: BlockVolume, block: BlockPermutation | string, options?: unknown): number;

Fills a box with a block (capped server-side like /fill); returns how many were set.

Parameters

volume

BlockVolume

block

BlockPermutation | string

optionsoptional

unknown

Returns

number

Types

BlockVolumeBlockPermutation

getEntities

getEntities(options?: EntityFilterOptions): Entity[];

Entities in loaded chunks, players among them, optionally filtered.

Parameters

optionsoptional

EntityFilterOptions

Returns

Entity[]

Types

EntityFilterOptionsEntity

getPlayers

getPlayers(options?: EntityQueryOptions & EntityFilterOptions): Player[];

The players in it, narrowed by the options as getEntities is.

Parameters

optionsoptional

EntityQueryOptions & EntityFilterOptions

Returns

Player[]

Types

EntityQueryOptionsEntityFilterOptionsPlayer

spawnEntity

spawnEntity(identifier: string, location: Vector3): Entity;

Brings a mob, or minecraft:xp_orb, into the world.

Parameters

identifier

string

location

Vector3

Returns

Entity

Throws

• If there’s no such entity.

Types

Vector3Entity

spawnItem

spawnItem(itemStack: ItemStack, location: Vector3): ItemEntity;

Sets an item down at a place.

Parameters

itemStack

ItemStack

location

Vector3

Returns

ItemEntity

Types

ItemStackVector3ItemEntity

createExplosion

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

Sets off an explosion of this power.

Parameters

location

Vector3

radius

number

explosionOptionsoptional

ExplosionOptions

Returns

boolean

Types

Vector3ExplosionOptions

playSound

playSound(soundId: string, location: Vector3, soundOptions?: { volume?: number; pitch?: number }): void;

Plays a sound to every player.

Parameters

soundId

string

location

Vector3

soundOptionsoptional

{ volume?: number; pitch?: number }

Types

Vector3

spawnParticle

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

Shows every player a particle effect.

Parameters

effectName

string

location

Vector3

molangVariablesoptional

MolangVariableMap

Types

Vector3MolangVariableMap

stopSound

stopSound(soundId: string): void;

Stops a sound for every player.

Parameters

soundId

string

stopAllSounds

stopAllSounds(): void;

Stops every sound for every player.

getBlockAbove

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

The first block above a place that isn’t air, or undefined if there’s none or its chunk isn’t loaded.

Parameters

location

Vector3

optionsoptional

BlockRaycastOptions

Returns

Block | undefined

Types

Vector3BlockRaycastOptionsBlock

getBlockBelow

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

The first block below a place that isn’t air.

Parameters

location

Vector3

optionsoptional

BlockRaycastOptions

Returns

Block | undefined

Types

Vector3BlockRaycastOptionsBlock

getEntitiesAtBlockLocation

getEntitiesAtBlockLocation(location: Vector3): Entity[];

The entities and players inside a block.

Parameters

location

Vector3

Returns

Entity[]

Types

Vector3Entity

getWeather

getWeather(): WeatherType;

Whether it’s clear, raining or thundering.

Returns

WeatherType

Types

WeatherType

setWeather

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

For duration ticks, or vanilla’s random length.

Parameters

weatherType

WeatherType

durationoptional

number

Types

WeatherType

isChunkLoaded

isChunkLoaded(location: Vector3): boolean;

Whether the chunk holding a block location is loaded.

Parameters

location

Vector3

Returns

boolean

Types

Vector3

getChunk

getChunk(location: Vector3): ChunkInfo;
getChunk(x: number, y: number, z: number): ChunkInfo;
getChunk(chunkX: number, chunkZ: number): ChunkInfo;

A chunk, named by the location of a block in it ({ x, y, z }, or x, y, z), or by chunk coordinates (chunkX, chunkZ).

Types

Vector3ChunkInfo

loadChunk

loadChunk(location: Vector3): void;
loadChunk(x: number, y: number, z: number): void;
loadChunk(chunkX: number, chunkZ: number): void;

Loads a chunk, generating it if new, and keeps it until Dimension.unloadChunk. Named as in Dimension.getChunk.

Types

Vector3

unloadChunk

unloadChunk(location: Vector3): void;
unloadChunk(x: number, y: number, z: number): void;
unloadChunk(chunkX: number, chunkZ: number): void;

Lets a chunk go, at once if no player is near. Named as in Dimension.getChunk.

Types

Vector3

runCommand

runCommand(commandString: string): CommandResult;

Runs a command with the server’s permission, ~ counting from the world spawn.

Parameters

commandString

string

Returns

CommandResult

Throws

• If the command fails or the server hasn’t started.

Types

CommandResult

getBlockFromRay

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

The first block a ray from a point hits.

Parameters

location

Vector3

direction

Vector3

optionsoptional

BlockRaycastOptions

Returns

BlockRaycastHit | undefined

Types

Vector3BlockRaycastOptionsBlockRaycastHit

getEntitiesFromRay

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

The entities a ray from a point crosses, nearest first.

Parameters

location

Vector3

direction

Vector3

optionsoptional

EntityRaycastOptions

Returns

EntityRaycastHit[]

Types

Vector3EntityRaycastOptionsEntityRaycastHit

getTopmostBlock

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

The highest non-air block over an x/z, or undefined.

Parameters

locationXZ

VectorXZ

minHeightoptional

number

Returns

Block | undefined

Types

VectorXZBlock

getLightLevel

getLightLevel(location: Vector3): number;

The light reaching a place.

Parameters

location

Vector3

Returns

number

Types

Vector3

getSkyLightLevel

getSkyLightLevel(location: Vector3): number;

The skylight reaching a place.

Parameters

location

Vector3

Returns

number

Types

Vector3

containsBlock

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

Whether a box holds a block matching the filter.

Parameters

volume

BlockVolumeBase

filter

BlockFilter

allowUnloadedChunksoptional

boolean

Returns

boolean

Types

BlockVolumeBaseBlockFilter

getBlocks

getBlocks(volume: BlockVolumeBase, options: BlockQueryOptions, allowUnloadedChunks?: boolean): ListBlockVolume;

The blocks in a box matching the query.

Parameters

volume

BlockVolumeBase

options

BlockQueryOptions

allowUnloadedChunksoptional

boolean

Returns

ListBlockVolume

Types

BlockVolumeBaseBlockQueryOptionsListBlockVolume

cloneBlocks

cloneBlocks(beginLocation: Vector3, endLocation: Vector3, destination: Vector3, cloneMode: CloneMode, filter?: BlockFilter): void;

Copies a box of blocks to another place.

Parameters

beginLocation

Vector3

endLocation

Vector3

destination

Vector3

cloneMode

CloneMode

filteroptional

BlockFilter

Types

Vector3CloneModeBlockFilter

spawnXp

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

Drops experience orbs worth amount.

Parameters

location

Vector3

amount

number

Types

Vector3

getBiome

getBiome(location: Vector3): BiomeType;

The biome at a place.

Parameters

location

Vector3

Returns

BiomeType

Types

Vector3BiomeType

containsBiomes

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

Whether a box holds the biomes the filter wants.

Parameters

volume

BlockVolumeBase

biomeFilter

BiomeFilter

isSuperset

boolean

Returns

boolean

Types

BlockVolumeBaseBiomeFilter

calculateClosestBiomeFromSeed

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

The nearest matching biome from the seed, searched from a point.

Parameters

pos

Vector3

biomeToFind

BiomeType | string

optionsoptional

BiomeSearchOptions

Returns

Vector3 | undefined

Types

Vector3BiomeTypeBiomeSearchOptions

placeFeature

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

Places a named world-generation feature.

Parameters

featureName

string

location

Vector3

shouldThrowoptional

boolean

Returns

boolean

Types

Vector3

placeFeatureRule

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

Places a named feature rule.

Parameters

featureRuleName

string

location

Vector3

Returns

boolean

Types

Vector3

Used by

DimensionLocation.dimension, TeleportOptions.dimension, Block.dimension, Entity.dimension, StructureManager.place, StructureManager.createFromWorld, BlockExplodeAfterEvent.dimension, ExplosionBeforeEvent.dimension, ExplosionAfterEvent.dimension, ProjectileHitBlockAfterEvent.dimension, ButtonPushAfterEvent.dimension, LeverActionAfterEvent.dimension, PistonActivateAfterEvent.dimension, PressurePlatePushAfterEvent.dimension, PressurePlatePopAfterEvent.dimension, TargetBlockHitAfterEvent.dimension, TripWireTripAfterEvent.dimension, ProjectileHitEntityAfterEvent.dimension, World.getDimension, BlockEvent.dimension, PlayerDimensionChangeAfterEvent.fromDimension, PlayerDimensionChangeAfterEvent.toDimension, PrimitiveShape.dimension, PrimitiveShapesManager.addText and 2 more