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

Properties

afterEvents: WorldAfterEvents

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.

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

const callback = world.beforeEvents.itemUse.subscribe((event) => {}); // your event
world.beforeEvents.itemUse.unsubscribe(callback); // unsubscribe
beforeEvents: WorldBeforeEvents

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.

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

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);
});
});
import { world } from "@minecraft/server";

const callback = world.afterEvents.buttonPush.subscribe((event) => {}); // event
world.afterEvents.buttonPush.unsubscribe(callback); // unsubscribe
scoreboard: Scoreboard

Returns the general global scoreboard that applies to the world.

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

Methods

  • Returns void

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

  • Returns number

    Returns the absolute time since the start of the world.

  • Returns Player[]

    Returns an array of all active players within the world.

    This function can throw errors.

  • Returns number

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

    Returns the current day.

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

    Returns the default Overworld spawn location.

  • Parameters

    • dimensionId: string

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

    Returns Dimension

    The requested dimension

    Returns a dimension object.

    Throws if the given dimension name is invalid

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

    world.getDimension("nether");
    import { world } from "@minecraft/server";

    world.getDimension("overworld");
    import { world } from "@minecraft/server";

    world.getDimension("the_end");
  • 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.

    Returns a property value.

    Throws if the given dynamic property identifier is not defined.

    let number = mc.world.getDynamicProperty("samplelibrary:number");

    log("Current value is: " + number);

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

    if (typeof number !== "number") {
    log("Number is of an unexpected type.");
    return -1;
    }

    mc.world.setDynamicProperty("samplelibrary:number", number + 1);
    let paintStr = mc.world.getDynamicProperty("samplelibrary:longerjson");
    let paint: { color: string; intensity: number } | undefined = undefined;

    log("Current value is: " + paintStr);

    if (paintStr === undefined) {
    paint = {
    color: "purple",
    intensity: 0,
    };
    } else {
    if (typeof paintStr !== "string") {
    log("Paint is of an unexpected type.");
    return -1;
    }

    try {
    paint = JSON.parse(paintStr);
    } catch (e) {
    log("Error parsing serialized struct.");
    return -1;
    }
    }

    if (!paint) {
    log("Error parsing serialized struct.");
    return -1;
    }

    paint.intensity++;
    paintStr = JSON.stringify(paint); // be very careful to ensure your serialized JSON str cannot exceed limits
    mc.world.setDynamicProperty("samplelibrary:longerjson", paintStr);
  • Returns string[]

    A string array of active dynamic property identifiers.

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

  • Returns number

    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.

  • Parameters

    • id: string

      The id of the entity.

    Returns Entity

    The requested entity object.

    Returns an entity based on the provided id.

    Throws if the given entity id is invalid.

  • Returns MoonPhase

    Returns the MoonPhase for the current time.

  • Parameters

    • Optionaloptions: EntityQueryOptions

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

    Returns Player[]

    A player array.

    Returns a set of players based on a set of conditions defined via the EntityQueryOptions set of filter criteria.

    Throws if the provided EntityQueryOptions are invalid.

    import { world } from "@minecraft/server";
    world.getPlayers({ families: ["player"] });
    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)
    );
  • Returns number

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

    Returns the time of day.

  • Parameters

    Returns void

    Plays a particular music track for all players.

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

    This function can throw errors.

    let players = mc.world.getPlayers();

    const musicOptions: mc.MusicOptions = {
    fade: 0.5,
    loop: true,
    volume: 1.0,
    };
    mc.world.playMusic("music.menu", musicOptions);

    const worldSoundOptions: mc.WorldSoundOptions = {
    pitch: 0.5,
    volume: 4.0,
    };
    mc.world.playSound("ambient.weather.thunder", targetLocation, worldSoundOptions);

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

    players[0].playSound("bucket.fill_water", playerSoundOptions);
  • Parameters

    Returns void

    Plays a sound for all players.

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

    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.

    let players = mc.world.getPlayers();

    const musicOptions: mc.MusicOptions = {
    fade: 0.5,
    loop: true,
    volume: 1.0,
    };
    mc.world.playMusic("music.menu", musicOptions);

    const worldSoundOptions: mc.WorldSoundOptions = {
    pitch: 0.5,
    volume: 4.0,
    };
    mc.world.playSound("ambient.weather.thunder", targetLocation, worldSoundOptions);

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

    players[0].playSound("bucket.fill_water", playerSoundOptions);
  • Parameters

    • trackId: string

      Identifier of the music track to play.

    • OptionalmusicOptions: MusicOptions

      Additional options for the music track.

    Returns void

    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.

    An error will be thrown if volume is less than 0.0. An error will be thrown if fade is less than 0.0.

  • Parameters

    Returns void

    Sends a message to all players.

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

    // Displays "Apple or Coal"
    let rawMessage = {
    translate: "accessibility.list.or.two",
    with: { rawtext: [{ translate: "item.apple.name" }, { translate: "item.coal.name" }] },
    };
    world.sendMessage(rawMessage);
    // Displays the player's score for objective "obj". Each player will see their own score.
    const rawMessage = { score: { name: "*", objective: "obj" } };
    world.sendMessage(rawMessage);
    // Displays "Hello, world!"
    world.sendMessage("Hello, world!");
    // Displays "First or Second"
    const rawMessage = { translate: "accessibility.list.or.two", with: ["First", "Second"] };
    world.sendMessage(rawMessage);
  • Parameters

    • absoluteTime: number

      The world time, in ticks.

    Returns void

    Sets the world time.

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

    import { TimeOfDay, world } from "@minecraft/server";
    world.setAbsoluteTime(TimeOfDay.Noon);
  • Parameters

    • spawnLocation: Vector3

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

    Returns void

    Sets a default spawn location for all players.

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

    Throws if the provided spawn location is out of bounds.

    Error

    LocationOutOfWorldBoundariesError

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

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

    • identifier: string

      The property identifier.

    • Optionalvalue: string | number | boolean | Vector3

      Data value of the property to set.

    Returns void

    Sets a specified property to a value.

    Throws if the given dynamic property identifier is not defined.

    let number = mc.world.getDynamicProperty("samplelibrary:number");

    log("Current value is: " + number);

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

    if (typeof number !== "number") {
    log("Number is of an unexpected type.");
    return -1;
    }

    mc.world.setDynamicProperty("samplelibrary:number", number + 1);
    let paintStr = mc.world.getDynamicProperty("samplelibrary:longerjson");
    let paint: { color: string; intensity: number } | undefined = undefined;

    log("Current value is: " + paintStr);

    if (paintStr === undefined) {
    paint = {
    color: "purple",
    intensity: 0,
    };
    } else {
    if (typeof paintStr !== "string") {
    log("Paint is of an unexpected type.");
    return -1;
    }

    try {
    paint = JSON.parse(paintStr);
    } catch (e) {
    log("Error parsing serialized struct.");
    return -1;
    }
    }

    if (!paint) {
    log("Error parsing serialized struct.");
    return -1;
    }

    paint.intensity++;
    paintStr = JSON.stringify(paint); // be very careful to ensure your serialized JSON str cannot exceed limits
    mc.world.setDynamicProperty("samplelibrary:longerjson", paintStr);
  • Parameters

    • timeOfDay: number

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

    Returns void

    Sets the time of day.

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

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

  • Returns void

    Stops any music tracks from playing.

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