Class World

Readonly afterEvents

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

Readonly beforeEvents

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

/**
 * @param {number} ticks
 */
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);
});
Copy

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

Readonly gameRules

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

Readonly isHardcore

// Script by WavePlayz

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

// Subscribe to the `playerSpawn` event, which is triggered when the world is initialized
world.afterEvents.playerSpawn.subscribe(() => {
    // Check if the world is in hardcore mode
    // Notify players about the current mode
    if (world.isHardcore) {
        world.sendMessage(
            "Welcome to Hardcore mode! Be careful, as death is permanent."
        );
    } else {
        world.sendMessage("This world is not in Hardcore mode. Play safely!");
    }
});
Copy

Readonly scoreboard

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

Readonly structureManager

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

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

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

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

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

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

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}`
  );
  Copy

getDimension

• getDimension(dimensionId): 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");
  Copy

  Example

  getOverworld.js

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

  Example

  getTheEnd.js

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

getDynamicProperty

• getDynamicProperty(identifier): 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');
  Copy

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

  Example

  retrieve.js

  // Script by WavePlayz
  
  import { world } from "@minecraft/server";
  
  // Subscribe to the `playerJoin` event, which is triggered when a player joins the world
  world.afterEvents.playerJoin.subscribe((eventData) => {
      // Extract the player entity from the event data
      const player = eventData.player;
  
      // Attempt to retrieve a custom dynamic property
      const playersCount = world.getDynamicProperty("playersCount");
  
      // If the property doesn't exist
      playersCount ??= 0;
  
      // set a default value
      player.setDynamicProperty("playersCount", playersCount + 1);
  });
  Copy

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

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

getEntity

• getEntity(id): 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
  Copy

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.");
  }
  Copy

getPlayers

• getPlayers(options?): Player[]

• Parameters

  • Optional options: EntityQueryOptions

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

    Optional

  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"] });
  Copy

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

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}`);
      }
  });
  Copy

playMusic

• playMusic(trackId, musicOptions?): void

• Parameters

  • trackId: string

  • Optional musicOptions: MusicOptions

    Optional

  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';
  import { MinecraftDimensionTypes } from '@minecraft/vanilla-data';
  
  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,
  };
  const overworld = world.getDimension(MinecraftDimensionTypes.Overworld);
  overworld.playSound('ambient.weather.thunder', targetLocation, worldSoundOptions);
  
  const playerSoundOptions: PlayerSoundOptions = {
      pitch: 1.0,
      volume: 1.0,
  };
  
  players[0].playSound('bucket.fill_water', playerSoundOptions);
  Copy

  Example

  music.js

  // Script by WavePlayz
  
  import { world } from "@minecraft/server";
  
  // Subscribe to the `playerJoin` event, which is triggered when a player joins the world
  world.afterEvents.playerJoin.subscribe((eventData) => {
      const player = eventData.player;
  
      // Play a music track for the player when they join the world
      player.playMusic("minecraft:music.game", {
          volume: 1.0, // Volume level of the music (1.0 is normal)
          fade: 0.5, // Fade in/out time in seconds
      });
  
      player.sendMessage("Welcome! Enjoy the music while you play.");
  });
  Copy

playSound

• playSound(soundId, location, soundOptions?): void

• Parameters

  • soundId: string

  • location: Vector3

  • Optional soundOptions: WorldSoundOptions

    Optional

  Returns void

  Remarks

  Plays a sound for all players. DEPRECATED: Use Dimension.playSound.

  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';
  import { MinecraftDimensionTypes } from '@minecraft/vanilla-data';
  
  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,
  };
  const overworld = world.getDimension(MinecraftDimensionTypes.Overworld);
  overworld.playSound('ambient.weather.thunder', targetLocation, worldSoundOptions);
  
  const playerSoundOptions: PlayerSoundOptions = {
      pitch: 1.0,
      volume: 1.0,
  };
  
  players[0].playSound('bucket.fill_water', playerSoundOptions);
  Copy

  Example

  sound.js

  // Script by WavePlayz
  
  import { world } from "@minecraft/server";
  
  // Subscribe to the `playerUseItemOn` event, which is triggered when a player uses an item on a block
  world.afterEvents.playerUseItemOn.subscribe((eventData) => {
      const player = eventData.source;
  
      // Play a sound effect when the player uses an item on a block
      player.playSound("minecraft:block.anvil.use", {
          volume: 0.8, // Volume level of the sound (1.0 is normal)
          pitch: 1.2, // Pitch of the sound (1.0 is normal)
          position: player.location, // Position where the sound should be played
      });
  
      player.sendMessage("You used an item on a block. Sound played!");
  });
  Copy

queueMusic

• queueMusic(trackId, musicOptions?): void

• Parameters

  • trackId: string

    Identifier of the music track to play.

  • Optional musicOptions: MusicOptions

    Additional options for the music track.

    Optional

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

sendMessage

• sendMessage(message): 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);
  Copy

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

  Example

  simpleString.ts

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

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

  Example

  message.js

  // Script by WavePlayz
  
  import { world } from "@minecraft/server";
  
  // Subscribe to the `playerSpawn` event, which is triggered when a player joins the world
  world.afterEvents.playerSpawn.subscribe((eventData) => {
      // ignore if player respawns
      if (!eventData.initialSpawn) return;
  
      const player = eventData.player;
  
      // Construct a welcome message for the player who just joined
      const welcomeMessage = `Welcome ${player.name}! Have fun in the world of Minecraft!`;
  
      // Use world.sendMessage to broadcast the message to all players in the world
      world.sendMessage(welcomeMessage);
  
      // Notify the player specifically with a different message
      player.sendMessage("Feel free to explore and build your adventure!");
  });
  Copy

setAbsoluteTime

• setAbsoluteTime(absoluteTime): 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);
  Copy

setDefaultSpawnLocation

• setDefaultSpawnLocation(spawnLocation): 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,
  });
  Copy

setDynamicProperty

• setDynamicProperty(identifier, value?): void

• Parameters

  • identifier: string

    The property identifier.

  • Optional value: string | number | boolean | Vector3

    Data value of the property to set.

    Optional

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

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

  Example

  assign.js

  // Script by WavePlayz
  
  import { world } from "@minecraft/server";
  
  // Subscribe to the `playerJoin` event, which is triggered when a player joins the world
  world.afterEvents.playerJoin.subscribe((eventData) => {
      // Extract the player entity from the event data
      const player = eventData.player;
  
      // Attempt to retrieve a custom dynamic property
      const playersCount = world.getDynamicProperty("playersCount");
  
      // If the property doesn't exist
      playersCount ??= 0;
  
      // set a default value
      player.setDynamicProperty("playersCount", playersCount + 1);
  });
  Copy

setTimeOfDay

• setTimeOfDay(timeOfDay): 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);
  Copy

  Example

  setTimeToMidnight.ts

  import { TimeOfDay, world } from "@minecraft/server";
  
  world.setTimeOfDay(TimeOfDay.Midnight);
  Copy

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