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

Parameter	Type	Description
id	string	The message identifier.
value	string	The 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

Parameter	Type	Description
dimensionId	string	The 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

Parameter	Type	Description
identifier	string	The 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

Parameter	Type	Description
id	string	The 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

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

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

Parameter	Type
trackId	string
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

Parameter	Type
soundId	string
location	Vector3
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

Parameter	Type	Description
trackId	string	Identifier of the music track to play.
musicOptions?	MusicOptions	Additional 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

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

Parameter	Type	Description
absoluteTime	number	The 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

Parameter	Type	Description
spawnLocation	Vector3	Location 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

Parameter	Type	Description
identifier	string	The property identifier.
value?	string | number | boolean | Vector3	Data 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

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