Skip to main content

Class: World

A class that wraps the state of a world - a set of dimensions and the environment of Minecraft.

Constructors​

new World()​

private new World(): World

Returns​

World

Properties​

afterEvents​

readonly afterEvents: WorldAfterEvents

Remarks​

Contains a set of events that are applicable to the entirety of the world. Event callbacks are called in a deferred manner. Event callbacks are executed in read-write mode.

beforeEvents​

readonly beforeEvents: WorldBeforeEvents

Remarks​

Contains a set of events that are applicable to the entirety of the world. Event callbacks are called immediately. Event callbacks are executed in read-only mode.

gameRules​

Beta

readonly gameRules: GameRules

Remarks​

The game rules that apply to the world.

scoreboard​

readonly scoreboard: Scoreboard

Remarks​

Returns the general global scoreboard that applies to the world.

structureManager​

readonly structureManager: StructureManager

Remarks​

Returns the manager for Structure related APIs.

Methods​

broadcastClientMessage()​

Beta

broadcastClientMessage(id, value): void

Parameters​

ParameterTypeDescription
idstringThe message identifier.
valuestringThe message.

Returns​

void

Remarks​

A method that is internal-only, used for broadcasting specific messages between client and server.

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

clearDynamicProperties()​

clearDynamicProperties(): void

Returns​

void

Remarks​

Clears the set of dynamic properties declared for this behavior pack within the world.

getAbsoluteTime()​

getAbsoluteTime(): number

Returns​

number

Remarks​

Returns the absolute time since the start of the world.

getAllPlayers()​

getAllPlayers(): Player[]

Returns​

Player[]

Remarks​

Returns an array of all active players within the world.

Throws​

This function can throw errors.

getDay()​

getDay(): number

Returns​

number

The current day, determined by the world time divided by the number of ticks per day. New worlds start at day 0.

Remarks​

Returns the current day.

getDefaultSpawnLocation()​

getDefaultSpawnLocation(): Vector3

Returns​

Vector3

The default Overworld spawn location. By default, the Y coordinate is 32767, indicating a player's spawn height is not fixed and will be determined by surrounding blocks.

Remarks​

Returns the default Overworld spawn location.

getDimension()​

getDimension(dimensionId): Dimension

Parameters​

ParameterTypeDescription
dimensionIdstringThe name of the dimension. For example, "overworld",
"nether" or "the_end".

Returns​

Dimension

The requested dimension

Remarks​

Returns a dimension object.

Throws​

Throws if the given dimension name is invalid

getDynamicProperty()​

getDynamicProperty(identifier): string | number | boolean | Vector3

Parameters​

ParameterTypeDescription
identifierstringThe property identifier.

Returns​

string | number | boolean | Vector3

Returns the value for the property, or undefined if the property has not been set.

Remarks​

Returns a property value.

Throws​

Throws if the given dynamic property identifier is not defined.

Examples​

import * as mc from '@minecraft/server';

function incrementProperty(propertyName: string): boolean {
    let number = mc.world.getDynamicProperty(propertyName);

    console.warn('Current value is: ' + number);

    if (number === undefined) {
        number = 0;
    }

    if (typeof number !== 'number') {
        console.warn('Number is of an unexpected type.');
        return false;
    }

    mc.world.setDynamicProperty(propertyName, number + 1);
    return true;
}

incrementProperty('samplelibrary:number');
import * as mc from '@minecraft/server';

function updateWorldProperty(propertyName: string): boolean {
    let paintStr = mc.world.getDynamicProperty(propertyName);
    let paint: { color: string; intensity: number } | undefined = undefined;

    console.log('Current value is: ' + paintStr);

    if (paintStr === undefined) {
        paint = {
            color: 'purple',
            intensity: 0,
        };
    } else {
        if (typeof paintStr !== 'string') {
            console.warn('Paint is of an unexpected type.');
            return false;
        }

        try {
            paint = JSON.parse(paintStr);
        } catch (e) {
            console.warn('Error parsing serialized struct.');
            return false;
        }
    }

    if (!paint) {
        console.warn('Error parsing serialized struct.');
        return false;
    }

    paint.intensity++;
    paintStr = JSON.stringify(paint); // be very careful to ensure your serialized JSON str cannot exceed limits
    mc.world.setDynamicProperty(propertyName, paintStr);

    return true;
}

updateWorldProperty('samplelibrary:longerjson');

getDynamicPropertyIds()​

getDynamicPropertyIds(): string[]

Returns​

string[]

A string array of active dynamic property identifiers.

Remarks​

Gets a set of dynamic property identifiers that have been set in this world.

getDynamicPropertyTotalByteCount()​

getDynamicPropertyTotalByteCount(): number

Returns​

number

Remarks​

Gets the total byte count of dynamic properties. This could potentially be used for your own analytics to ensure you're not storing gigantic sets of dynamic properties.

getEntity()​

getEntity(id): Entity

Parameters​

ParameterTypeDescription
idstringThe id of the entity.

Returns​

Entity

The requested entity object.

Remarks​

Returns an entity based on the provided id.

Throws​

Throws if the given entity id is invalid.

getMoonPhase()​

getMoonPhase(): MoonPhase

Returns​

MoonPhase

Remarks​

Returns the MoonPhase for the current time.

getPlayers()​

getPlayers(options?): Player[]

Parameters​

ParameterTypeDescription
options?EntityQueryOptionsAdditional 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​

Throws if the provided EntityQueryOptions are invalid.

getTimeOfDay()​

getTimeOfDay(): number

Returns​

number

The time of day, in ticks, between 0 and 24000.

Remarks​

Returns the time of day.

playMusic()​

playMusic(trackId, musicOptions?): void

Parameters​

ParameterType
trackIdstring
musicOptions?MusicOptions

Returns​

void

Remarks​

Plays a particular music track for all players.

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

Throws​

This function can throw errors.

Example​

import { world, MusicOptions, WorldSoundOptions, PlayerSoundOptions, Vector3 } from '@minecraft/server';

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,
};
world.playSound('ambient.weather.thunder', targetLocation, worldSoundOptions);

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

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

playSound()​

playSound(soundId, location, soundOptions?): void

Parameters​

ParameterType
soundIdstring
locationVector3
soundOptions?WorldSoundOptions

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​

import { world, MusicOptions, WorldSoundOptions, PlayerSoundOptions, Vector3 } from '@minecraft/server';

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,
};
world.playSound('ambient.weather.thunder', targetLocation, worldSoundOptions);

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

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

queueMusic()​

queueMusic(trackId, musicOptions?): void

Parameters​

ParameterTypeDescription
trackIdstringIdentifier of the music track to play.
musicOptions?MusicOptionsAdditional options for the music track.

Returns​

void

Remarks​

Queues an additional music track for players. If a track is not playing, a music track will play.

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.

sendMessage()​

sendMessage(message): void

Parameters​

ParameterTypeDescription
messagestring | RawMessage | (string | RawMessage)[]The message to be displayed.

Returns​

void

Remarks​

Sends a message to all players.

Throws​

This method can throw if the provided RawMessage is in an invalid format. For example, if an empty name string is provided to score.

Examples​

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

// Displays "Apple or Coal"
const rawMessage = {
    translate: 'accessibility.list.or.two',
    with: { rawtext: [{ translate: 'item.apple.name' }, { translate: 'item.coal.name' }] },
};
world.sendMessage(rawMessage);
import { world } from '@minecraft/server';

// Displays the player's score for objective "obj". Each player will see their own score.
const rawMessage = { score: { name: '*', objective: 'obj' } };
world.sendMessage(rawMessage);
import { world } from '@minecraft/server';

// Displays "Hello, world!"
world.sendMessage('Hello, world!');
import { world } from '@minecraft/server';

// Displays "First or Second"
const rawMessage = { translate: 'accessibility.list.or.two', with: ['First', 'Second'] };
world.sendMessage(rawMessage);

setAbsoluteTime()​

setAbsoluteTime(absoluteTime): void

Parameters​

ParameterTypeDescription
absoluteTimenumberThe world time, in ticks.

Returns​

void

Remarks​

Sets the world time.

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

setDefaultSpawnLocation()​

setDefaultSpawnLocation(spawnLocation): void

Parameters​

ParameterTypeDescription
spawnLocationVector3Location of the spawn point. Note that this is assumed to be
within the overworld dimension.

Returns​

void

Remarks​

Sets a default spawn location for all players.

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

Throws​

Throws if the provided spawn location is out of bounds.

Error

LocationOutOfWorldBoundariesError

setDynamicProperty()​

setDynamicProperty(identifier, value?): void

Parameters​

ParameterTypeDescription
identifierstringThe property identifier.
value?string | number | boolean | Vector3Data value of the property to set.

Returns​

void

Remarks​

Sets a specified property to a value.

Throws​

Throws if the given dynamic property identifier is not defined.

Examples​

import * as mc from '@minecraft/server';

function incrementProperty(propertyName: string): boolean {
    let number = mc.world.getDynamicProperty(propertyName);

    console.warn('Current value is: ' + number);

    if (number === undefined) {
        number = 0;
    }

    if (typeof number !== 'number') {
        console.warn('Number is of an unexpected type.');
        return false;
    }

    mc.world.setDynamicProperty(propertyName, number + 1);
    return true;
}

incrementProperty('samplelibrary:number');
import * as mc from '@minecraft/server';

function updateWorldProperty(propertyName: string): boolean {
    let paintStr = mc.world.getDynamicProperty(propertyName);
    let paint: { color: string; intensity: number } | undefined = undefined;

    console.log('Current value is: ' + paintStr);

    if (paintStr === undefined) {
        paint = {
            color: 'purple',
            intensity: 0,
        };
    } else {
        if (typeof paintStr !== 'string') {
            console.warn('Paint is of an unexpected type.');
            return false;
        }

        try {
            paint = JSON.parse(paintStr);
        } catch (e) {
            console.warn('Error parsing serialized struct.');
            return false;
        }
    }

    if (!paint) {
        console.warn('Error parsing serialized struct.');
        return false;
    }

    paint.intensity++;
    paintStr = JSON.stringify(paint); // be very careful to ensure your serialized JSON str cannot exceed limits
    mc.world.setDynamicProperty(propertyName, paintStr);

    return true;
}

updateWorldProperty('samplelibrary:longerjson');

setTimeOfDay()​

setTimeOfDay(timeOfDay): void

Parameters​

ParameterTypeDescription
timeOfDaynumberThe time of day, in ticks, between 0 and 24000.

Returns​

void

Remarks​

Sets the time of day.

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

Throws​

Throws if the provided time of day is not within the valid range.

stopMusic()​

stopMusic(): void

Returns​

void

Remarks​

Stops any music tracks from playing.

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