Class World

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

Properties

`Readonly`afterEvents

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.

Example: triggerEventOnce.js

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

const callback = world.afterEvents.itemUseOn.subscribe((event) => {
    if (event.itemStack.typeId == "minecraft:water_bucket") {
        event.source.sendMessage("You used water bucket once.");

        // Unsubscribe callback after first use
        world.afterEvents.itemUseOn.unsubscribe(callback);
    }
});

`Readonly`beforeEvents

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.

Example: fixRequiredPrivilegesError.js

// Check out how BeforeEvents privilege system work:
// https://wiki.bedrock.dev/scripting/script-server.html#beforeevents-privilege-system
import { world, system, TimeOfDay } from "@minecraft/server";

// Use system.run()
world.beforeEvents.chatSend.subscribe((event) => {
    event.cancel = true;
    // setTime changes world state, must be run after its execution by a tick
    system.run(() => {
        world.setTimeOfDay(TimeOfDay.Night);
    });
});

function sleep(ticks) {
    return new Promise((resolve) => {
        system.runTimeout(() => resolve(), ticks);
    });
}

// Or execute function at a later tick using async functions
world.beforeEvents.chatSend.subscribe(async (event) => {
    // synchronous code
    event.cancel = true;

    // asynchronous code
    await sleep(10); // Pretend you have a sleep function that returns a promise that resolves in 10 ticks
    world.setTimeOfDay(TimeOfDay.Night);
});

Example: triggerBeforeEventOnce.js

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

const callback = world.beforeEvents.itemUseOn.subscribe((event) => {
    if (event.itemStack.typeId == "minecraft:water_bucket") {
        event.source.sendMessage(
            "You cannot use water bucket at this time, please try again."
        );
        event.cancel = true;

        // Unsubscribe callback after first use
        system.run(() => world.beforeEvents.itemUseOn.unsubscribe(callback));
    }
});

`Readonly`gameRules

gameRules: GameRules

Remarks

The game rules that apply to the world.

Example: disableGamerules.ts

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

world.gameRules.doDayLightCycle = false;
world.gameRules.doEntityDrops = false;
world.gameRules.doFireTick = false;
world.gameRules.doWeatherCycle = false;
world.gameRules.doMobSpawning = false;

`Readonly`scoreboard

scoreboard: Scoreboard

Remarks

Returns the general global scoreboard that applies to the world.

Example: getScoreboard.js

import { world } from "@minecraft/server";
const money = world.scoreboard.getObjective("money");

`Readonly`structureManager

structureManager: StructureManager

Remarks

Returns the manager for Structure related APIs.

Example: getAllDiskStructures.ts

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

world.structureManager.getWorldStructureIds().forEach((id) => {
    const structure = world.structureManager.get(id);
    structure.isValid();
});

Methods

clearDynamicProperties

clearDynamicProperties(): void
Returns void
Remarks
Clears the set of dynamic properties declared for this behavior pack within the world.
Example: clearProperties.ts
```
import { world } from "@minecraft/server";

world.clearDynamicProperties();
```

getAbsoluteTime

getAbsoluteTime(): number

Returns number

Remarks

Returns the absolute time since the start of the world.

Example: gametime.ts

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

const gametime = world.getAbsoluteTime();
world.sendMessage("Current gametime: " + gametime);

getAllPlayers

getAllPlayers(): Player[]

Returns Player[]

Remarks

Returns an array of all active players within the world.

Throws

This function can throw errors.

Example: displayActionBar.ts

import { EntityHealthComponent, system, world } from "@minecraft/server";

system.runInterval(() => {
    for (const player of world.getPlayers()) {
        const health = player.getComponent(EntityHealthComponent.componentId);
        player.onScreenDisplay.setActionBar(
            `Name: ${
                player.name
            } | Health: ${health.currentValue.toFixed()} / ${
                health.effectiveMax
            }`
        );
    }
}, 5000);

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.
Example: broadcastDay.ts
```
import { world } from "@minecraft/server";

world.sendMessage("Day " + world.getDay());
```

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.
Example: printSpawnLocation.ts
```
import { world } from "@minecraft/server";

const spawnLocation = world.getDefaultSpawnLocation();
world.sendMessage(
    `Spawn location: ${spawnLocation.x}, ${spawnLocation.y}, ${spawnLocation.z}`
);
```

getDimension

getDimension(dimensionId: string): Dimension
Parameters
- 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
Example: getNether.js
```
import { world } from "@minecraft/server";

world.getDimension("nether");
```
Example: getOverworld.js
```
import { world } from "@minecraft/server";

world.getDimension("overworld");
```
Example: getTheEnd.js
```
import { world } from "@minecraft/server";

world.getDimension("the_end");
```

getDynamicProperty

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

Parameters

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.

Example: incrementDynamicProperty.ts

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

Example: incrementDynamicPropertyInJsonBlob.ts

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.

Example: listPropertiesAndValues.ts

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

world.getDynamicPropertyIds().forEach((id) => {
    const value = world.getDynamicProperty(id)!;
    world.sendMessage(`Dynamic property ${id} has value ${value}`);
});
world.sendMessage(
    "There are " + world.getDynamicPropertyIds().length + " dynamic properties"
);

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.
Example: getByteCount.ts
```
import { world } from "@minecraft/server";

world.getDynamicPropertyTotalByteCount();
```

getEntity

getEntity(id: string): Entity

Parameters

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.

Example: getNpc.js

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

// Entity::id - format: '-451021564564561'
const entityId = world
    .getDimension("overworld")
    .spawnEntity(
        "minecraft:npc",
        { x: 0, y: 70, z: 0 },
        { initialPersistence: true }
    ).id;
world.getEntity(entityId).typeId; // minecraft:npc

getMoonPhase

getMoonPhase(): MoonPhase

Returns MoonPhase

Remarks

Returns the MoonPhase for the current time.

Example: sayMoonPhase.ts

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

// Get the current moon phase
const moonPhase: MoonPhase = world.getMoonPhase();

// Display a message based on the current moon phase
switch (moonPhase) {
    case MoonPhase.FullMoon:
        world.sendMessage("It's full moon!");
        break;
    case MoonPhase.WaningGibbous:
        world.sendMessage("It's waning gibbous moon!");
        break;
    // Add cases for other moon phases as needed
    default:
        world.sendMessage("It's another phase of the moon.");
}

getPlayers

getPlayers(options?: EntityQueryOptions): Player[]

Parameters

Optionaloptions: 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.

Example: getFamily.js

import { world } from "@minecraft/server";
world.getPlayers({ families: ["player"] });

Example: getFilteredPlayers.ts

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

const entityQueryOptions: EntityQueryOptions = {
    minLevel: 10,
    maxLevel: 30,
    tags: ["team_red"],
    excludeNames: ["Admin"],
};

const filteredPlayers = world.getPlayers(entityQueryOptions);
console.log(
    "Filtered Players:",
    filteredPlayers.map((player) => player.name)
);

getTimeOfDay

getTimeOfDay(): number

Returns number

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

Remarks

Returns the time of day.

Example: broadcastTimeOfDay.ts

import { TimeOfDay, system, world } from "@minecraft/server";

function GetWorldTime() {
    const daytime = world.getTimeOfDay() + 6000;
    const datetime = new Date(daytime * 3.6 * 1000);
    const hours =
        datetime.getHours() < 10
            ? "0" + datetime.getHours()
            : datetime.getHours();
    const minutes =
        datetime.getMinutes() < 10
            ? "0" + datetime.getMinutes()
            : datetime.getMinutes();

    return { hours, minutes };
}

system.runInterval(() => {
    const { hours, minutes } = GetWorldTime();
    for (const player of world.getAllPlayers()) {
        player.onScreenDisplay.setActionBar(`Time - ${hours}:${minutes}`);
    }
});

playMusic

playMusic(trackId: string, musicOptions?: MusicOptions): void

Parameters

trackId: string
OptionalmusicOptions: 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: playMusicAndSound.ts

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: string,
    location: Vector3,
    soundOptions?: WorldSoundOptions,
): void

Parameters

soundId: string
location: Vector3
OptionalsoundOptions: 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: playMusicAndSound.ts

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: string, musicOptions?: MusicOptions): void
Parameters
- trackId: string
  Identifier of the music track to play.
- OptionalmusicOptions: 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.
Example: queueMusicForAll.ts
```
import { world } from "@minecraft/server";

world.queueMusic("music.game.swamp_music", { loop: true });
```

sendMessage

sendMessage(message: string | RawMessage | (string | RawMessage)[]): void

Parameters

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.

Example: nestedTranslation.ts

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

Example: scoreWildcard.ts

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

Example: simpleString.ts

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

// Displays "Hello, world!"
world.sendMessage('Hello, world!');

Example: translation.ts

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: number): void
Parameters
- absoluteTime: number
  The world time, in ticks.
Returns void
Remarks
Sets the world time.

This function can't be called in read-only mode.
Example: setDay.js
```
import { TimeOfDay, world } from "@minecraft/server";
world.setAbsoluteTime(TimeOfDay.Noon);
```

setDefaultSpawnLocation

setDefaultSpawnLocation(spawnLocation: Vector3): void
Parameters
- 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
Example: setWorldSpawn.js
```
import { world } from "@minecraft/server";

world.setDefaultSpawnLocation({
    x: 0,
    y: -64,
    z: 0,
});
```

setDynamicProperty

setDynamicProperty(
identifier: string,
value?: string | number | boolean | Vector3,
): void

Parameters

identifier: string
The property identifier.
Optionalvalue: 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.

Example: incrementDynamicProperty.ts

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

Example: incrementDynamicPropertyInJsonBlob.ts

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: number): void
Parameters
- 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.
Example: setTimeToDay.ts
```
import { TimeOfDay, world } from "@minecraft/server";

world.setTimeOfDay(TimeOfDay.Day);
```
Example: setTimeToMidnight.ts
```
import { TimeOfDay, world } from "@minecraft/server";

world.setTimeOfDay(TimeOfDay.Midnight);
```

stopMusic

stopMusic(): void
Returns void
Remarks
Stops any music tracks from playing.

This function can't be called in read-only mode.
Example: stopMusicForAll.ts
```
import { world } from "@minecraft/server";

world.stopMusic();
```

Class World

Index

Properties

Methods

Properties

ReadonlyafterEvents

Remarks

Example: triggerEventOnce.js

ReadonlybeforeEvents

Remarks

Example: fixRequiredPrivilegesError.js

Example: triggerBeforeEventOnce.js

ReadonlygameRules

Remarks

Example: disableGamerules.ts

Readonlyscoreboard

Remarks

Example: getScoreboard.js

ReadonlystructureManager

Remarks

Example: getAllDiskStructures.ts

Methods

clearDynamicProperties

Returns void

Remarks

Example: clearProperties.ts

getAbsoluteTime

Returns number

Remarks

Example: gametime.ts

getAllPlayers

Returns Player[]

Remarks

Throws

Example: displayActionBar.ts

getDay

Returns number

Remarks

Example: broadcastDay.ts

getDefaultSpawnLocation

Returns Vector3

Remarks

Example: printSpawnLocation.ts

getDimension

Parameters

Returns Dimension

Remarks

Throws

Example: getNether.js

Example: getOverworld.js

Example: getTheEnd.js

getDynamicProperty

Parameters

Returns string | number | boolean | Vector3

Remarks

Throws

Example: incrementDynamicProperty.ts

Example: incrementDynamicPropertyInJsonBlob.ts

getDynamicPropertyIds

Returns string[]

Remarks

Example: listPropertiesAndValues.ts

getDynamicPropertyTotalByteCount

Returns number

Remarks

Example: getByteCount.ts

getEntity

Parameters

Returns Entity

Remarks

Throws

Example: getNpc.js

getMoonPhase

Returns MoonPhase

Remarks

Example: sayMoonPhase.ts

getPlayers

Parameters

Returns Player[]

Remarks

`Readonly`afterEvents

`Readonly`beforeEvents

`Readonly`gameRules

`Readonly`scoreboard

`Readonly`structureManager