Class System

ReadonlyafterEvents

// Script by WavePlayz

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

// Subscribe to the scriptEventReceive event, which is triggered when a custom script event is received
system.afterEvents.scriptEventReceive.subscribe((event) => {
    const { message, sourceEntity } = event;

    // Check if the source entity is a player
    if (sourceEntity instanceof Player) {
        // If the received message is "hi"
        if (message === "hi") {
            // Get the player's name
            let playerName = sourceEntity.name;

            // Send a greeting message back to the player
            sourceEntity.sendMessage(`hello ${playerName}`);
        }
    }
});

/*
  Usage:
  Run the following command in Minecraft to trigger this script event:

  /scriptevent foo:bar hi

  This will cause the script to detect the event and respond with a message
  "hello [playerName]", where [playerName] is the name of the player who ran the command.
*/
Copy

ReadonlycurrentTick

// Script by WavePlayz

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

// A function that will be executed periodically
function looper() {
    // Send a message to all players in the world with the current game tick count
    world.sendMessage(`Current tick: ${system.currentTick}`);
}

// Define constants for time intervals in ticks
const TICKS_IN_SEC = 20; // 20 ticks per second (Minecraft runs at 20 ticks per second)
const TICKS_IN_20_SECS = TICKS_IN_SEC * 20; // 20 seconds in ticks (20 ticks/second * 20 seconds = 400 ticks)

// Set up the looper function to run every 20 seconds in the game
system.runInterval(looper, TICKS_IN_20_SECS);

/*
  Usage:
  This script sends a message to all players in the game every 20 seconds,
  displaying the current tick count in the Minecraft world.

  The message will appear as:
  "Current tick: [currentTick]"
  where [currentTick] is the current game tick at the time the message is sent.
*/
Copy

clearJob

• clearJob(jobId: number): void

• Parameters

  • jobId: number

    The job ID returned from System.runJob.

  Returns void

  Remarks

  Cancels the execution of a job queued via System.runJob.

  Example: stopPlayerSneakAlert.js

  // Script by WavePlayz
  
  import { system, world } from "@minecraft/server";
  
  // Variable to hold the job reference for later management
  let job;
  
  // A generator function to continuously monitor if any players are sneaking
  function* generatorFunction() {
      // Infinite loop to create a long-running task
      while (true) {
          // Retrieve the list of all players currently in the world
          let worldPlayers = world.getAllPlayers();
  
          // If no players are found, stop the job and exit the function
          if (worldPlayers.length === 0) {
              system.clearJob(job); // Clear the running job
              return; // Exit the generator function
          }
  
          // Iterate over each player in the world
          for (let worldPlayer of worldPlayers) {
              // Check if the player is sneaking
              if (worldPlayer.isSneaking) {
                  // Display an alert message on the player's action bar
                  worldPlayer.onScreenDisplay.setActionBar(
                      "[Alert] You are now sneaking"
                  );
              }
  
              // Pause the generator function until the next game tick
              yield;
          }
      }
  }
  
  // Create an instance of the generator function
  const generator = generatorFunction();
  
  // Start the generator function as a periodic job in the game system
  job = system.runJob(generator);
  Copy

clearRun

• clearRun(runId: number): void

• Parameters

  • runId: number

  Returns void

  Remarks

  Cancels the execution of a function run that was previously scheduled via System.run.

  Example: clearRun.js

  import { system } from "@minecraft/server";
  
  const runId = system.run(() => {
      console.log("Running callback function...");
  });
  
  // Clear the run, so it will not run again.
  system.clearRun(runId);
  Copy

  Example: stopPlayerSneakAlert.js

  // by WavePlayz
  
  import { system, world } from "@minecraft/server";
  
  let interval;
  
  // A function to check if any player in the world is sneaking
  function looper() {
      // Retrieve all players currently in the world
      let worldPlayers = world.getAllPlayers();
  
      // If no players are found, stop the job and exit the function
      if (worldPlayers.length === 0) {
          system.clearRun(interval); // Clear the running job
          return; // Exit the generator function
      }
  
      // Iterate over each player in the world
      for (let worldPlayer of worldPlayers) {
          // If the player is sneaking, display an alert on their action bar
          if (worldPlayer.isSneaking) {
              worldPlayer.onScreenDisplay.setActionBar(
                  "[Alert] You are now sneaking"
              );
          }
      }
  }
  
  // Run the generator function as a periodic job in the game system
  interval = system.runInterval(looper);
  Copy

run

• run(callback: () => void): number

• Parameters

  • callback: () => void

    Function callback to run at the next game tick.

  Returns number

  An opaque identifier that can be used with the clearRun function to cancel the execution of this run.

  Remarks

  Runs a specified function at the next available future time. This is frequently used to implement delayed behaviors and game loops. When run within the context of an event handler, this will generally run the code at the end of the same tick where the event occurred. When run in other code (a system.run callout), this will run the function in the next tick. Note, however, that depending on load on the system, running in the same or next tick is not guaranteed.

  Example: trapTick.ts

  import { system, world } from '@minecraft/server';
  
  function printEveryMinute() {
      try {
          // Minecraft runs at 20 ticks per second.
          if (system.currentTick % 1200 === 0) {
              world.sendMessage('Another minute passes...');
          }
      } catch (e) {
          console.warn('Error: ' + e);
      }
  
      system.run(printEveryMinute);
  }
  
  printEveryMinute();
  Copy

  Example: run.js

  import { system } from "@minecraft/server";
  
  const runId = system.run(() => {
      console.log("Running callback function...");
  });
  Copy

runInterval

• runInterval(callback: () => void, tickInterval?: number): number

• Parameters

  • callback: () => void

    Functional code that will run when this interval occurs.
  • OptionaltickInterval: number

    An interval of every N ticks that the callback will be called upon.

  Returns number

  An opaque handle that can be used with the clearRun method to stop the run of this function on an interval.

  Remarks

  Runs a set of code on an interval.

  Example: every30Seconds.ts

  import { system, world } from '@minecraft/server';
  
  const intervalRunIdentifier = Math.floor(Math.random() * 10000);
  
  system.runInterval(() => {
      world.sendMessage('This is an interval run ' + intervalRunIdentifier + ' sending a message every 30 seconds.');
  }, 600);
  Copy

  Example: playerSneakAlert.js

  // by WavePlayz
  
  import { system, world } from "@minecraft/server";
  
  // A function to check if any player in the world is sneaking
  function looper() {
      // Retrieve all players currently in the world
      let worldPlayers = world.getAllPlayers();
  
      // Iterate over each player in the world
      for (let worldPlayer of worldPlayers) {
          // If the player is sneaking, display an alert on their action bar
          if (worldPlayer.isSneaking) {
              worldPlayer.onScreenDisplay.setActionBar(
                  "[Alert] You are now sneaking"
              );
          }
      }
  }
  
  // Attach the looper function as interval in the game system
  system.runInterval(looper);
  Copy

runJob

• runJob(generator: Generator<void, void, void>): number

• Parameters

  • generator: Generator<void, void, void>

    The instance of the generator to run.

  Returns number

  An opaque handle that can be used with System.clearJob to stop the run of this generator.

  Remarks

  Queues a generator to run until completion. The generator will be given a time slice each tick, and will be run until it yields or completes.

  Example: cubeGenerator.ts

  import { BlockPermutation, DimensionLocation, world, ButtonPushAfterEvent, system } from '@minecraft/server';
  
  // A simple generator that places blocks in a cube at a specific location
  // with a specific size, yielding after every block place.
  function* blockPlacingGenerator(blockPerm: BlockPermutation, startingLocation: DimensionLocation, size: number) {
      for (let x = startingLocation.x; x < startingLocation.x + size; x++) {
          for (let y = startingLocation.y; y < startingLocation.y + size; y++) {
              for (let z = startingLocation.z; z < startingLocation.z + size; z++) {
                  const block = startingLocation.dimension.getBlock({ x: x, y: y, z: z });
                  if (block) {
                      block.setPermutation(blockPerm);
                  }
                  yield;
              }
          }
      }
  }
  
  // When a button is pushed, we will place a 15x15x15 cube of cobblestone 10 blocks above it
  world.afterEvents.buttonPush.subscribe((buttonPushEvent: ButtonPushAfterEvent) => {
      const cubePos = buttonPushEvent.block.location;
      cubePos.y += 10;
  
      const blockPerm = BlockPermutation.resolve('minecraft:cobblestone');
  
      system.runJob(blockPlacingGenerator(blockPerm, { dimension: buttonPushEvent.dimension, ...cubePos }, 15));
  });
  Copy

  Example: playerSneakAlert.js

  // by WavePlayz
  
  import { system, world } from "@minecraft/server";
  
  // A generator function to check if any player in the world is sneaking
  function* generatorFunction() {
      // Long running task
      while (true) {
          // Retrieve all players currently in the world
          let worldPlayers = world.getAllPlayers();
  
          // Iterate over each player in the world
          for (let worldPlayer of worldPlayers) {
              // If the player is sneaking, display an alert on their action bar
              if (worldPlayer.isSneaking) {
                  worldPlayer.onScreenDisplay.setActionBar(
                      "[Alert] You are now sneaking"
                  );
              }
  
              // Pause the generator function until the next game tick
              yield;
          }
      }
  }
  
  // Create an instance of the generator function
  const generator = generatorFunction();
  
  // Run the generator function as a periodic job in the game system
  system.runJob(generator);
  Copy

runTimeout

• runTimeout(callback: () => void, tickDelay?: number): number

• Parameters

  • callback: () => void

    Functional code that will run when this timeout occurs.
  • OptionaltickDelay: number

    Amount of time, in ticks, before the interval will be called.

  Returns number

  An opaque handle that can be used with the clearRun method to stop the run of this function on an interval.

  Remarks

  Runs a set of code at a future time specified by tickDelay.

  Example: runTimeout.js

  import { TicksPerSecond, system } from "@minecraft/server";
  
  system.runTimeout(() => {
      console.log("Running callback function after delay...");
  }, TicksPerSecond * 5); // Tick delay of 5 seconds
  Copy

waitTicks

• waitTicks(ticks: number): Promise<void>

• Parameters

  • ticks: number

  Returns Promise<void>

  Throws

  This function can throw errors.

  minecraftcommon.EngineError

  Example: heal.js

  // Script by WavePlayz
  
  import { system, world } from "@minecraft/server";
  
  // Subscribe to the entityHurt event, which triggers whenever an entity takes damage
  world.afterEvents.entityHurt.subscribe(async (eventData) => {
      // Extract the hurt entity and damage amount from the event data
      const { hurtEntity, damage } = eventData;
  
      // Wait for a number of game ticks equal to the damage value before proceeding
      await system.waitTick(damage);
  
      // Attempt to get the health component of the hurt entity
      const health = hurtEntity.getComponent("health");
  
      // If the entity has a health component, reset its health to the maximum value
      if (health != null) {
          health.resetToMaxValue(); // Reset the entity's health to full
  
          // Send a message to the entity (if it supports receiving messages)
          hurtEntity.sendMessage?.("Health reset");
      }
  });
  Copy