Events

The HYTOPIA SDK is heavily designed around an event-driven architecture. This means that games, plugins, and even internal systems all make use of event emission and event listeners for when different things happen.

Events allow you to create in a highly flexible way by creating listeners that invoke a callback whenever something you subscribe to happens. For example..

• Did an entity collide with another specific entitiy?

• Did an entity despawn?

• Did a chunk get removed?

• Did a light despawn?

• Did some audio begin playing?

All of these examples cause events to be emitted when they happen. You can with a single line of code create logic that executes whenever any event you subscribe to happens. Many of these events also include contextually relevant data for the event as well!

Understanding Events & Event Emission

In the HYTOPIA SDK, nearly all instances of classes that you use are also an event emitter (aka an EventRouter within the SDK). This means that all instances of these classes can be specifically listened to for events that happen using common patterns like .on() .

When these instances emit events, they emit 2 copies of the event.

• One copy of an emitted event emits to any listeners specifically on the instance itself. For example if you have a listener assigned with myZombieEntity.on(EntityEvent.TICK, () ⇒ { ... }) , anytime that specific entity ticks, the TICK event listener you assigned will be invoked.

• The other copy of an emitted event emits through World instance that the emitting class instance belongs to. Per our previous example, lets assume myZombieEntity belongs to our world instance, so when it ticks, it emits a tick event through itself, and also through the World instance it belongs to. This allows you to do things like listen to all events of any type that emit by any instance of any class that is within a world. For example, we could add an event listener that is invoked every tick for every entity belonging to our world instance with world.on(EntityEvent.TICK, () ⇒ { ... }

This granular implementation of event routing allows you to optimally fine tune your game logic and behaviors based on whatever you need. This also makes it highly flexible to create your own Plugins for others to use as well!

Here's an example to better demonstrate this:

import {
  startServer,
  Entity
  EntityEvent,
} from 'hytopia'

startServer(world => {
  world.loadMap(worldMap);

  world.on(PlayerEvent.JOINED_WORLD, ({ player }) => {
    const playerEntity = new PlayerEntity({
      player,
      name: 'Player',
      modelUri: 'models/players/player.gltf',
      modelLoopedAnimations: [ 'idle' ],
      modelScale: 0.5,
    });
    
    // Callback is invoked only once when this specific playerEntity instance spawns.
    playerEntity.once(EntityEvent.SPAWN, payload => {
      console.log(`A player entity spawned for ${player.username}!`);
    });

    playerEntity.spawn(world, { x: 0, y: 10, z: 0 });
  });
 
  // Callback is invoked anytime ANY entity spawns in the world.
  world.on(EntityEvent.SPAWN, payload => {
    const entity = payload.entity;    
    console.log(`A new entity spawned with id ${entity.id} and name ${entity.name}!`);
  });
});

Event & Event Payload Documentation

The HYTOPIA SDK API Reference is the #1 place to find documentation and details on available events.

All classes that can emit events, will have an Events section within their documentation. For example, Entity events: https://github.com/hytopiagg/sdk/blob/main/docs/server.entity.md#events

This is true for other commonly used classes like Audio, BlockType, Light, and many others.

In this Events section within the documentation, you'll find a link to the exact events and payloads available for a given class. Additionally all events are available as enums through the SDK, rather than directly using a string for the event name. For example, all Entity events can be found and used through the EntityEvent enum.

Additionally, most modern IDEs with Typescript support will automatically be able to infer the expected payload for all event types and provide hints.

Supported Event Methods

All classes that can emit events will inherit from the EventRouter class. This means that all methods available through the EventRouterclass, will also be available to any class that inherits from it. This includes methods like .on(), .off(), .once() and more.

All Known SDK Events

If for any reason you need to reference all known SDK events, you can find them here: https://github.com/hytopiagg/sdk/blob/main/docs/server.eventpayloads.md