Events

The HYTOPIA server internally creates an event router globally, and for each individual world instance of a game. You can use this event router for lower level behaviors requiring subscription to direct events, or for emission and subscription to your own custom events.

Using the global Event Router

The global event router for your game controls lower level events like a player joining or leaving your server, the game server starting or stopping.

The global event router is useful for shared custom events that you want to emit and listen for between multiple world instances.

You can access the global event router for your game server as follows.

import { EventRouter } from 'hytopia';

// other code ...
 
EventRouter.serverInstance // the global singleton for your server events 

Using A World's Event Router

Every world when created, including the default world created when your game starts, is assigned its own isolated Event Router. This event router is in charge of all events related to the world. This includes but is not limited to entity events, audio events, chat events, physics events, and much more.

You can use a world's event router to listen to low-level world events, as well as emit and listen to your own custom events specific to a world.

You can access a world's event router as follows.

world.eventRouter

Listen For An Events

The world event router handles a number of events, all of which you can find in the SDK's API reference. Here's how you can listen for an event.

import {
  EntityEventType,
  EntityEventPayload
}

// other code ...

// You can subscribe to events in 2 ways, depending on how you're wanting to use types

world.eventRouter.on('ENTITY.UPDATE_POSITION', payload => {
  // Handle the payload for the event
});

// OR....

world.eventRouter.on<EntityEventPayload.UpdatePosition>(
  EntityEventType.UPDATE_POSITION,
  (payload: EntityEventPayload.UpdatePosition) => {
    // Handle the payload for the event, with proper type
    // checking and assumptions for payload
  }
)

There are a variety of available event listener methods for different needs, such as .on(), .off(), .once(), .prependOn(), .prependOnce()

You can find a full documentation of the EventRouter class here.

Emitting Events

You can emit your own custom events as follows.

// other code ...

// You can emit events in 2 ways depending on how you're wanting to use types.

world.eventRouter.emit('MY_HEALTH_EVENT', { health: 10 });

// OR....

const MY_HEALTH_EVENT = 'MY_HEALTH_EVENT';
interface MyHealthEventPayload { health: number }

world.eventRouter.emit<MyHealthEventPayload>(
  MY_HEALTH_EVENT,
  { health: 10 }
)

Documented Events & Payloads

You can find a list of documented events and their payloads in the SDK's API Reference, here.

Diving Deeper

The EventRouter class is constantly evolving. You can find the latest EventRouter API Reference here.

If there are features that we don't currently support for the EventRouter that you'd like to see added to the HYTOPIA SDK, you can submit a feature request here.