LogoLogo
  • Get Started
  • Getting Started
    • Initial Setup
    • Create Your First Game
    • API Reference
    • Build Your First World Map
    • Multiplayer Testing
    • Use Templates & Examples
    • Styling & Assets
      • Modeling Guidelines
      • Texturing Guidelines
      • Default Assets
  • Build Faster With AI Tools
  • SDK Guides
    • Assets
    • Audio & SFX
      • Audio Manager
    • Blocks & Chunks
      • Block Types
      • Block Type Registry
      • Chunks
      • Chunk Lattice
    • Camera
    • Chat & Commands
    • Debugging
    • Entities
      • Animations
      • Block Entities
      • Colliders & Hitbox
      • Child Entities
      • Entity Controllers
        • Base Entity Controller
        • Pathfinding Entity Controller
        • DefaultPlayer Entity Controller
        • Simple Entity Controller
      • Entity Manager
      • Model Entities
      • Movement & Pathfinding
      • Player Controlled Entities
    • Events
    • Input & Controls
    • Lighting
      • Ambient Light
      • Light Manager
      • Point Lights
      • Spot Lights
      • Sun Light (Directional)
    • Mobile
    • Persisted Data
    • Players
      • Player Manager
      • Persisted Player Data
    • Plugins
    • Physics
      • Colliders
      • Collision Groups
      • Debugging
      • Gravity
      • Raycasts
      • Rigid Bodies
    • User Interface
      • Overlay UI
      • Scene UIs
      • Scene UI Manager
    • Worlds
      • Map Data Format
  • Helpful Resources
    • HYTOPIA Architecture & Platform Overview
    • Useful Third-Party Tools
Powered by GitBook
On this page
  • Understanding Events & Event Emission
  • Event & Event Payload Documentation
  • Supported Event Methods
  • All Known SDK Events
Export as PDF
  1. SDK Guides

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 DefaultPlayerEntity({
      player,
      name: 'Player',
    });
    
    // 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 EntitiesNextInput & Controls

Last updated 9 days ago

The 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:

This is true for other commonly used classes like , , , 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 .

All classes that can emit events will inherit from the . 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.

If for any reason you need to reference all known SDK events, you can find them here:

HYTOPIA SDK API Reference
https://github.com/hytopiagg/sdk/blob/main/docs/server.entity.md#events
Audio
BlockType
Light
EntityEvent enum
EventRouter class
https://github.com/hytopiagg/sdk/blob/main/docs/server.eventpayloads.md