Bedrock API Reference

Appearance

@minecraft/server

@minecraft/server / World

Class: World ​

Defined in: @minecraft/server/index.d.ts:21211

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

Properties ​

afterEvents ​

readonly afterEvents: WorldAfterEvents

Defined in: @minecraft/server/index.d.ts:21222

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.

This property can be read in early-execution mode.

beforeEvents ​

readonly beforeEvents: WorldBeforeEvents

Defined in: @minecraft/server/index.d.ts:21259

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.

This property can be read in early-execution mode.

Example ​

customCommand.ts

typescript
import { world, DimensionLocation } from '@minecraft/server';

function customCommand(targetLocation: DimensionLocation) {
  const chatCallback = world.beforeEvents.chatSend.subscribe(eventData => {
    if (eventData.message.includes('cancel')) {
      // Cancel event if the message contains "cancel"
      eventData.cancel = true;
    } else {
      const args = eventData.message.split(' ');

      if (args.length > 0) {
        switch (args[0].toLowerCase()) {
          case 'echo':
            // Send a modified version of chat message
            world.sendMessage(`Echo '${eventData.message.substring(4).trim()}'`);
            break;
          case 'help':
            world.sendMessage(`Available commands: echo <message>`);
            break;
        }
      }
    }
  });
}

gameRules ​

readonly gameRules: GameRules

Defined in: @minecraft/server/index.d.ts:21265

Remarks ​

The game rules that apply to the world.

isHardcore ​

readonly isHardcore: boolean

Defined in: @minecraft/server/index.d.ts:21266

primitiveShapesManager ​

readonly primitiveShapesManager: PrimitiveShapesManager

Defined in: @minecraft/server/index.d.ts:21273

Remarks ​

Manager for adding and removing primitive text objects in the world.

scoreboard ​

readonly scoreboard: Scoreboard

Defined in: @minecraft/server/index.d.ts:21280

Remarks ​

Returns the general global scoreboard that applies to the world.

seed ​

readonly seed: string

Defined in: @minecraft/server/index.d.ts:21286

Remarks ​

The world seed.

structureManager ​

readonly structureManager: StructureManager

Defined in: @minecraft/server/index.d.ts:21292

Remarks ​

Returns the manager for Structure related APIs.

tickingAreaManager ​

readonly tickingAreaManager: TickingAreaManager

Defined in: @minecraft/server/index.d.ts:21299

Remarks ​

Manager for adding, removing and querying pack specific ticking areas.

Methods ​

clearDynamicProperties() ​

clearDynamicProperties(): void

Defined in: @minecraft/server/index.d.ts:21306

Returns ​

void

Remarks ​

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

getAbsoluteTime() ​

getAbsoluteTime(): number

Defined in: @minecraft/server/index.d.ts:21312

Returns ​

number

Remarks ​

Returns the absolute time since the start of the world.

getAimAssist() ​

getAimAssist(): AimAssistRegistry

Defined in: @minecraft/server/index.d.ts:21319

Returns ​

AimAssistRegistry

Remarks ​

The aim-assist presets and categories that can be used in the world.

getAllPlayers() ​

getAllPlayers(): Player[]

Defined in: @minecraft/server/index.d.ts:21330

Returns ​

Player[]

Remarks ​

Returns an array of all active players within the world.

Throws ​

This function can throw errors.

CommandError

minecraftcommon.InvalidArgumentError

getDay() ​

getDay(): number

Defined in: @minecraft/server/index.d.ts:21339

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

Defined in: @minecraft/server/index.d.ts:21349

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.

getDifficulty() ​

getDifficulty(): Difficulty

Defined in: @minecraft/server/index.d.ts:21357

Returns ​

Difficulty

Returns the world difficulty.

Remarks ​

Gets the difficulty from the world.

getDimension() ​

getDimension(dimensionId): Dimension

Defined in: @minecraft/server/index.d.ts:21370

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

getDynamicProperty() ​

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

Defined in: @minecraft/server/index.d.ts:21447

Parameters ​

identifier ​

string

The property identifier.

Returns ​

string | number | boolean | Vector3 | undefined

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 ​

incrementDynamicProperty.ts

typescript
import { world, DimensionLocation } from '@minecraft/server';

function incrementDynamicProperty(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  let number = 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;
  }

  world.setDynamicProperty('samplelibrary:number', number + 1);
}

incrementDynamicPropertyInJsonBlob.ts

typescript
import { world, DimensionLocation } from '@minecraft/server';

function incrementDynamicPropertyInJsonBlob(
  log: (message: string, status?: number) => void,
  targetLocation: DimensionLocation
) {
  let paintStr = 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
  world.setDynamicProperty('samplelibrary:longerjson', paintStr);
}

getDynamicPropertyIds() ​

getDynamicPropertyIds(): string[]

Defined in: @minecraft/server/index.d.ts:21456

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

Defined in: @minecraft/server/index.d.ts:21464

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 | undefined

Defined in: @minecraft/server/index.d.ts:21476

Parameters ​

id ​

string

The id of the entity.

Returns ​

Entity | undefined

The requested entity object.

Remarks ​

Returns an entity based on the provided id.

Throws ​

Throws if the given entity id is invalid.

getLootTableManager() ​

getLootTableManager(): LootTableManager

Defined in: @minecraft/server/index.d.ts:21486

Returns ​

LootTableManager

A loot table manager with a variety of loot generation methods.

Remarks ​

Returns a manager capable of generating loot from an assortment of sources.

getMoonPhase() ​

getMoonPhase(): MoonPhase

Defined in: @minecraft/server/index.d.ts:21492

Returns ​

MoonPhase

Remarks ​

Returns the MoonPhase for the current time.

getPackSettings() ​

getPackSettings(): Record<string, boolean | number | string>

Defined in: @minecraft/server/index.d.ts:21500

Returns ​

Record<string, boolean | number | string>

Remarks ​

Returns a map of pack setting name and value pairs.

This function can be called in early-execution mode.

getPlayers() ​

getPlayers(options?): Player[]

Defined in: @minecraft/server/index.d.ts:21518

Parameters ​

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.

CommandError

minecraftcommon.InvalidArgumentError

getTimeOfDay() ​

getTimeOfDay(): number

Defined in: @minecraft/server/index.d.ts:21526

Returns ​

number

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

Remarks ​

Returns the time of day.

playMusic() ​

playMusic(trackId, musicOptions?): void

Defined in: @minecraft/server/index.d.ts:21565

Parameters ​

trackId ​

string

musicOptions? ​

MusicOptions

Returns ​

void

Remarks ​

Plays a particular music track for all players.

This function can't be called in restricted-execution mode.

Throws ​

This function can throw errors.

minecraftcommon.PropertyOutOfBoundsError

Example ​

playMusicAndSound.ts

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

function playMusicAndSound(targetLocation: DimensionLocation) {
  const players = world.getPlayers();

  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

Defined in: @minecraft/server/index.d.ts:21584

Parameters ​

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 restricted-execution 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.

minecraftcommon.PropertyOutOfBoundsError

sendMessage() ​

sendMessage(message): void

Defined in: @minecraft/server/index.d.ts:21596

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.

setAbsoluteTime() ​

setAbsoluteTime(absoluteTime): void

Defined in: @minecraft/server/index.d.ts:21606

Parameters ​

absoluteTime ​

number

The world time, in ticks.

Returns ​

void

Remarks ​

Sets the world time.

This function can't be called in restricted-execution mode.

setDefaultSpawnLocation() ​

setDefaultSpawnLocation(spawnLocation): void

Defined in: @minecraft/server/index.d.ts:21623

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 restricted-execution mode.

Throws ​

Throws if the provided spawn location is out of bounds.

Error

LocationOutOfWorldBoundariesError

setDifficulty() ​

setDifficulty(difficulty): void

Defined in: @minecraft/server/index.d.ts:21633

Parameters ​

difficulty ​

Difficulty

The difficulty we want to set the world to.

Returns ​

void

Remarks ​

Sets the worlds difficulty.

This function can't be called in restricted-execution mode.

setDynamicProperties() ​

setDynamicProperties(values): void

Defined in: @minecraft/server/index.d.ts:21646

Parameters ​

values ​

Record<string, boolean | number | string | Vector3 | undefined>

A Record of key value pairs of the dynamic properties to set. If the data value is null, it will remove that property instead.

Returns ​

void

Remarks ​

Sets multiple dynamic properties with specific values.

Throws ​

This function can throw errors.

minecraftcommon.ArgumentOutOfBoundsError

setDynamicProperty() ​

setDynamicProperty(identifier, value?): void

Defined in: @minecraft/server/index.d.ts:21725

Parameters ​

identifier ​

string

The property identifier.

value? ​

string | number | boolean | Vector3

Data value of the property to set. If the value is null, it will remove the property instead.

Returns ​

void

Remarks ​

Sets a specified property to a value.

Throws ​

Throws if the given dynamic property identifier is not defined.

minecraftcommon.ArgumentOutOfBoundsError

Examples ​

incrementDynamicProperty.ts

typescript
import { world, DimensionLocation } from '@minecraft/server';

function incrementDynamicProperty(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
  let number = 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;
  }

  world.setDynamicProperty('samplelibrary:number', number + 1);
}

incrementDynamicPropertyInJsonBlob.ts

typescript
import { world, DimensionLocation } from '@minecraft/server';

function incrementDynamicPropertyInJsonBlob(
  log: (message: string, status?: number) => void,
  targetLocation: DimensionLocation
) {
  let paintStr = 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
  world.setDynamicProperty('samplelibrary:longerjson', paintStr);
}

setTimeOfDay() ​

setTimeOfDay(timeOfDay): void

Defined in: @minecraft/server/index.d.ts:21738

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 restricted-execution mode.

Throws ​

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

stopMusic() ​

stopMusic(): void

Defined in: @minecraft/server/index.d.ts:21746

Returns ​

void

Remarks ​

Stops any music tracks from playing.

This function can't be called in restricted-execution mode.