Serenity

Serenity provides three methods for listening to events, which differ in their execution priority and ability to intercept the event loop:

1. before: The highest priority. These listeners run before any other listeners. A before listener can cancel the event loop for all subsequent listeners by returning false. Returning true allows the loop to continue.
2. on: Medium priority. These run on the same process tick immediately after before listeners. They cannot be canceled.
3. after: Lowest priority. These run on the next process tick after all other listeners have completed.

Use before when you need to intercept or block actions (like chat moderation), on for immediate reactions to game state changes, and after for logic that should only occur once the current event processing cycle is fully finalized.

// Example of canceling an event using 'before'
serenity.before(WorldEvent.PlayerChat, ({ player, message }) => {
  if (message === "cancel") return false;
  return true;
});

// Example of immediate reaction using 'on'
serenity.on(WorldEvent.PlayerPlaceBlock, ({ block, permutationBeingPlaced }) => {
  // Logic runs immediately after 'before' listeners
});

// Example of post-process reaction using 'after'
serenity.on(WorldEvent.PlayerPlaceBlock, ({ block, permutationBeingPlaced }) => {
  // Logic runs on the next process tick
});

Overloads allow a single command to support multiple different argument structures. You define them within the registry function using registry.overload(args, executor).

Argument Definition: Arguments are defined as an object where keys are the argument names. The value is an array containing:

1. The Argument Type (e.g., TargetEnum, CustomEnum, or a class extending CustomEnum).
2. A boolean indicating if the argument is optional (false means it is required).

Executor Context: The overload executor receives an object containing the results of the parsed arguments (e.g., { target, kit }).

import { TargetEnum, World } from "@serenityjs/core";

function register(world: World): void {
  world.commandPalette.register(
    "ping",
    "Ping the server to check if it's responsive.",
    (registry) => {
      registry.overload(
        {
          target: [TargetEnum, false] // Required argument
        },
        ({ target }) => {
          // target.result contains the parsed entities
          const value = target.result[0].isPlayer() 
            ? target.result[0].username 
            : target.result[0].type.identifier;

          return { message: `Pong, ${value}!` };
        }
      );
    },
    () => { return { message: "Pong!" }; }
  );
}

To create a custom block, instantiate the CustomBlockType class from @serenityjs/core. The constructor requires a unique block ID (e.g., "serenity:example_block") and an optional configuration object.

Once created, you can configure the block's base properties using the components property. Components assigned to the base type are inherited by all permutations unless explicitly overridden. Common component operations include:

• setLightEmission(level: number): Sets the light emission level.
• getGeometry().setModelIdentifier(id: string): Sets the geometry model identifier.
• getMaterialInstances().createMaterialInstance(name: string, options: object): Creates a material instance (e.g., for textures and render methods).
• setIsInteractable(value: boolean): Determines if the block can be interacted with.

import { CustomBlockType } from '@serenityjs/core';
import { MaterialRenderMethod } from '@serenityjs/protocol';

// 1. Define the base block type
const exampleBlockType = new CustomBlockType("serenity:example_block", { solid: true });

// 2. Configure base components
exampleBlockType.components.setLightEmission(15);

const geometry = exampleBlockType.components.getGeometry();
geometry.setModelIdentifier("geometry.example_block");

const materials = exampleBlockType.components.getMaterialInstances();
materials.createMaterialInstance("*", {
  texture: "example_block",
  render_method: MaterialRenderMethod.AlphaTest
});

// 3. Make it interactable for traits
exampleBlockType.components.setIsInteractable(true);

When registering a command, you can provide a registry function as the third argument. This function allows you to configure metadata and access control for the command via a registry object.

Key properties available on the registry object:

• permissions: An array of strings (e.g., ["example.ping"]) that restricts command execution to users with those specific permissions.
• debug: A boolean. If set to true, the command appears blue in the in-game command list (purely visual/informational).
• overload(args, executor): Used to define specific argument structures and their corresponding logic.

import { World } from "@serenityjs/core";

function register(world: World): void {
  world.commandPalette.register(
    "ping",
    "Ping the server to check if it's responsive.",
    (registry) => {
      registry.permissions = ["example.ping"];
      registry.debug = true;
    },
    () => {
      return { message: "Pong!" };
    }
  );
}

Block traits define custom behaviors for blocks (e.g., what happens when a block is interacted with). Traits are reusable across different block types.

To create a trait:

1. Extend the BlockTrait class from @serenityjs/core.
2. Define a unique public static readonly identifier.
3. Implement behavior methods (e.g., onInteract()). Inside these methods, you can access the block instance via this.block to get or set states using getState(key) and setState(key, value).

To use a trait:

• Register it to the block type using blockType.registerTrait(TraitClass).
• Register it to the world instance using world.blockPalette.registerTrait(TraitClass).

import { BlockTrait } from '@serenityjs/core';

class ExampleBlockTrait extends BlockTrait {
  public static readonly identifier = "serenity:example_block_trait";

  public onInteract(): void {
    // Access the state defined in a permutation
    const state = this.block.getState("powered");

    // Toggle the state
    this.block.setState("powered", !state);
  }
}

// Register with the block type
exampleBlockType.registerTrait(ExampleBlockTrait);