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

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 Known SDK Events

PreviousPlayer Controlled Entities NextInput & Controls

Last updated 1 month ago

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}!`); }); });