hytopia 0.2.11 → 0.3.0-dev.3

package/boilerplate/index.ts

@@ -26,8 +26,8 @@
 import {
   startServer,
   Audio,
-  GameServer,
   PlayerEntity,
+  PlayerEvent,
 } from 'hytopia';
 
 import worldMap from './assets/map.json';
@@ -65,14 +65,18 @@ startServer(world => {
   world.loadMap(worldMap);
 
   /**
-   * Handle player joining the game. The onPlayerJoin
-   * function is called when a new player connects to
+   * Handle player joining the game. The PlayerEvent.JOINED_WORLD
+   * event is emitted to the world when a new player connects to
    * the game. From here, we create a basic player
    * entity instance which automatically handles mapping
    * their inputs to control their in-game entity and
    * internally uses our player entity controller.
+   * 
+   * The HYTOPIA SDK is heavily driven by events, you
+   * can find documentation on how the event system works,
+   * here: https://dev.hytopia.com/sdk-guides/events
    */
-  world.onPlayerJoin = player => {
+  world.on(PlayerEvent.JOINED_WORLD, ({ player }) => {
     const playerEntity = new PlayerEntity({
       player,
       name: 'Player',
@@ -89,11 +93,11 @@ startServer(world => {
     world.chatManager.sendPlayerMessage(player, 'Press space to jump.');
     world.chatManager.sendPlayerMessage(player, 'Hold shift to sprint.');
     world.chatManager.sendPlayerMessage(player, 'Press \\ to enter or exit debug view.');
-  };
+  });
 
   /**
-   * Handle player leaving the game. The onPlayerLeave
-   * function is called when a player leaves the game.
+   * Handle player leaving the game. The PlayerEvent.LEFT_WORLD
+   * event is emitted to the world when a player leaves the game.
    * Because HYTOPIA is not opinionated on join and
    * leave game logic, we are responsible for cleaning
    * up the player and any entities associated with them
@@ -101,10 +105,14 @@ startServer(world => {
    * getting all the known PlayerEntity instances for
    * the player who left by using our world's EntityManager
    * instance.
+   * 
+   * The HYTOPIA SDK is heavily driven by events, you
+   * can find documentation on how the event system works,
+   * here: https://dev.hytopia.com/sdk-guides/events
    */
-  world.onPlayerLeave = player => {
+  world.on(PlayerEvent.LEFT_WORLD, ({ player }) => {
     world.entityManager.getPlayerEntitiesByPlayer(player).forEach(entity => entity.despawn());
-  };
+  });
 
   /**
    * A silly little easter egg command. When a player types

package/docs/server.audio.md

@@ -9,14 +9,20 @@ Represents a audio playback in a world.
 **Signature:**
 
 ```typescript
-export default class Audio implements protocol.Serializable 
+export default class Audio extends EventRouter implements protocol.Serializable 
 ```
+**Extends:** [EventRouter](./server.eventrouter.md)
+
 **Implements:** protocol.Serializable
 
 ## Remarks
 
 Audio instances are created directly as instances. They support a variety of configuration options through the [AudioOptions](./server.audiooptions.md) constructor argument.
 
+<h2>Events</h2>
+
+This class is an EventRouter, and instances of it emit events with payloads listed under [AudioEventPayloads](./server.audioeventpayloads.md)
+
 ## Example
 
 

package/docs/{server.audioeventtype.md → server.audioevent.md}

@@ -1,15 +1,15 @@
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
-[Home](./index.md) &gt; [server](./server.md) &gt; [AudioEventType](./server.audioeventtype.md)
+[Home](./index.md) &gt; [server](./server.md) &gt; [AudioEvent](./server.audioevent.md)
 
-## AudioEventType enum
+## AudioEvent enum
 
-Event types an Audio instance can emit.
+Event types an Audio instance can emit. See [AudioEventPayloads](./server.audioeventpayloads.md) for the payloads.
 
 **Signature:**
 
 ```typescript
-export declare enum AudioEventType 
+export declare enum AudioEvent 
 ```
 
 ## Enumeration Members

package/docs/server.audioeventpayloads._audio.pause_.md

@@ -0,0 +1,15 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [server](./server.md) &gt; [AudioEventPayloads](./server.audioeventpayloads.md) &gt; ["AUDIO.PAUSE"](./server.audioeventpayloads._audio.pause_.md)
+
+## AudioEventPayloads."AUDIO.PAUSE" property
+
+Emitted when the audio is paused.
+
+**Signature:**
+
+```typescript
+[AudioEvent.PAUSE]: {
+        audio: Audio;
+    };
+```

package/docs/server.audioeventpayloads._audio.play_.md

@@ -0,0 +1,15 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [server](./server.md) &gt; [AudioEventPayloads](./server.audioeventpayloads.md) &gt; ["AUDIO.PLAY"](./server.audioeventpayloads._audio.play_.md)
+
+## AudioEventPayloads."AUDIO.PLAY" property
+
+Emitted when the audio is played.
+
+**Signature:**
+
+```typescript
+[AudioEvent.PLAY]: {
+        audio: Audio;
+    };
+```

package/docs/server.audioeventpayloads._audio.play_restart_.md

@@ -0,0 +1,15 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [server](./server.md) &gt; [AudioEventPayloads](./server.audioeventpayloads.md) &gt; ["AUDIO.PLAY\_RESTART"](./server.audioeventpayloads._audio.play_restart_.md)
+
+## AudioEventPayloads."AUDIO.PLAY\_RESTART" property
+
+Emitted when the audio is restarted.
+
+**Signature:**
+
+```typescript
+[AudioEvent.PLAY_RESTART]: {
+        audio: Audio;
+    };
+```

package/docs/server.audioeventpayloads._audio.set_attached_to_entity_.md

@@ -0,0 +1,16 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [server](./server.md) &gt; [AudioEventPayloads](./server.audioeventpayloads.md) &gt; ["AUDIO.SET\_ATTACHED\_TO\_ENTITY"](./server.audioeventpayloads._audio.set_attached_to_entity_.md)
+
+## AudioEventPayloads."AUDIO.SET\_ATTACHED\_TO\_ENTITY" property
+
+Emitted when the audio is attached to an entity.
+
+**Signature:**
+
+```typescript
+[AudioEvent.SET_ATTACHED_TO_ENTITY]: {
+        audio: Audio;
+        entity: Entity | undefined;
+    };
+```

package/docs/server.audioeventpayloads._audio.set_detune_.md

@@ -0,0 +1,16 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [server](./server.md) &gt; [AudioEventPayloads](./server.audioeventpayloads.md) &gt; ["AUDIO.SET\_DETUNE"](./server.audioeventpayloads._audio.set_detune_.md)
+
+## AudioEventPayloads."AUDIO.SET\_DETUNE" property
+
+Emitted when the audio's detune is set.
+
+**Signature:**
+
+```typescript
+[AudioEvent.SET_DETUNE]: {
+        audio: Audio;
+        detune: number;
+    };
+```

package/docs/server.audioeventpayloads._audio.set_distortion_.md

@@ -0,0 +1,16 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [server](./server.md) &gt; [AudioEventPayloads](./server.audioeventpayloads.md) &gt; ["AUDIO.SET\_DISTORTION"](./server.audioeventpayloads._audio.set_distortion_.md)
+
+## AudioEventPayloads."AUDIO.SET\_DISTORTION" property
+
+Emitted when the audio's distortion is set.
+
+**Signature:**
+
+```typescript
+[AudioEvent.SET_DISTORTION]: {
+        audio: Audio;
+        distortion: number;
+    };
+```

package/docs/server.audioeventpayloads._audio.set_playback_rate_.md

@@ -0,0 +1,16 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [server](./server.md) &gt; [AudioEventPayloads](./server.audioeventpayloads.md) &gt; ["AUDIO.SET\_PLAYBACK\_RATE"](./server.audioeventpayloads._audio.set_playback_rate_.md)
+
+## AudioEventPayloads."AUDIO.SET\_PLAYBACK\_RATE" property
+
+Emitted when the audio's playback rate is set.
+
+**Signature:**
+
+```typescript
+[AudioEvent.SET_PLAYBACK_RATE]: {
+        audio: Audio;
+        playbackRate: number;
+    };
+```

package/docs/server.audioeventpayloads._audio.set_position_.md

@@ -0,0 +1,16 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [server](./server.md) &gt; [AudioEventPayloads](./server.audioeventpayloads.md) &gt; ["AUDIO.SET\_POSITION"](./server.audioeventpayloads._audio.set_position_.md)
+
+## AudioEventPayloads."AUDIO.SET\_POSITION" property
+
+Emitted when the audio's position is set.
+
+**Signature:**
+
+```typescript
+[AudioEvent.SET_POSITION]: {
+        audio: Audio;
+        position: Vector3Like;
+    };
+```

package/docs/server.audioeventpayloads._audio.set_reference_distance_.md

@@ -0,0 +1,16 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [server](./server.md) &gt; [AudioEventPayloads](./server.audioeventpayloads.md) &gt; ["AUDIO.SET\_REFERENCE\_DISTANCE"](./server.audioeventpayloads._audio.set_reference_distance_.md)
+
+## AudioEventPayloads."AUDIO.SET\_REFERENCE\_DISTANCE" property
+
+Emitted when the audio's reference distance is set.
+
+**Signature:**
+
+```typescript
+[AudioEvent.SET_REFERENCE_DISTANCE]: {
+        audio: Audio;
+        referenceDistance: number;
+    };
+```

package/docs/server.audioeventpayloads._audio.set_volume_.md

@@ -0,0 +1,16 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [server](./server.md) &gt; [AudioEventPayloads](./server.audioeventpayloads.md) &gt; ["AUDIO.SET\_VOLUME"](./server.audioeventpayloads._audio.set_volume_.md)
+
+## AudioEventPayloads."AUDIO.SET\_VOLUME" property
+
+Emitted when the audio's volume is set.
+
+**Signature:**
+
+```typescript
+[AudioEvent.SET_VOLUME]: {
+        audio: Audio;
+        volume: number;
+    };
+```

package/docs/server.audioeventpayloads.md

@@ -0,0 +1,228 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [server](./server.md) &gt; [AudioEventPayloads](./server.audioeventpayloads.md)
+
+## AudioEventPayloads interface
+
+Event payloads for Audio emitted events.
+
+**Signature:**
+
+```typescript
+export interface AudioEventPayloads 
+```
+
+## Properties
+
+<table><thead><tr><th>
+
+Property
+
+
+</th><th>
+
+Modifiers
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+["AUDIO.PAUSE"](./server.audioeventpayloads._audio.pause_.md)
+
+
+</td><td>
+
+
+</td><td>
+
+{ audio: [Audio](./server.audio.md)<!-- -->; }
+
+
+</td><td>
+
+Emitted when the audio is paused.
+
+
+</td></tr>
+<tr><td>
+
+["AUDIO.PLAY\_RESTART"](./server.audioeventpayloads._audio.play_restart_.md)
+
+
+</td><td>
+
+
+</td><td>
+
+{ audio: [Audio](./server.audio.md)<!-- -->; }
+
+
+</td><td>
+
+Emitted when the audio is restarted.
+
+
+</td></tr>
+<tr><td>
+
+["AUDIO.PLAY"](./server.audioeventpayloads._audio.play_.md)
+
+
+</td><td>
+
+
+</td><td>
+
+{ audio: [Audio](./server.audio.md)<!-- -->; }
+
+
+</td><td>
+
+Emitted when the audio is played.
+
+
+</td></tr>
+<tr><td>
+
+["AUDIO.SET\_ATTACHED\_TO\_ENTITY"](./server.audioeventpayloads._audio.set_attached_to_entity_.md)
+
+
+</td><td>
+
+
+</td><td>
+
+{ audio: [Audio](./server.audio.md)<!-- -->; entity: [Entity](./server.entity.md) \| undefined; }
+
+
+</td><td>
+
+Emitted when the audio is attached to an entity.
+
+
+</td></tr>
+<tr><td>
+
+["AUDIO.SET\_DETUNE"](./server.audioeventpayloads._audio.set_detune_.md)
+
+
+</td><td>
+
+
+</td><td>
+
+{ audio: [Audio](./server.audio.md)<!-- -->; detune: number; }
+
+
+</td><td>
+
+Emitted when the audio's detune is set.
+
+
+</td></tr>
+<tr><td>
+
+["AUDIO.SET\_DISTORTION"](./server.audioeventpayloads._audio.set_distortion_.md)
+
+
+</td><td>
+
+
+</td><td>
+
+{ audio: [Audio](./server.audio.md)<!-- -->; distortion: number; }
+
+
+</td><td>
+
+Emitted when the audio's distortion is set.
+
+
+</td></tr>
+<tr><td>
+
+["AUDIO.SET\_PLAYBACK\_RATE"](./server.audioeventpayloads._audio.set_playback_rate_.md)
+
+
+</td><td>
+
+
+</td><td>
+
+{ audio: [Audio](./server.audio.md)<!-- -->; playbackRate: number; }
+
+
+</td><td>
+
+Emitted when the audio's playback rate is set.
+
+
+</td></tr>
+<tr><td>
+
+["AUDIO.SET\_POSITION"](./server.audioeventpayloads._audio.set_position_.md)
+
+
+</td><td>
+
+
+</td><td>
+
+{ audio: [Audio](./server.audio.md)<!-- -->; position: [Vector3Like](./server.vector3like.md)<!-- -->; }
+
+
+</td><td>
+
+Emitted when the audio's position is set.
+
+
+</td></tr>
+<tr><td>
+
+["AUDIO.SET\_REFERENCE\_DISTANCE"](./server.audioeventpayloads._audio.set_reference_distance_.md)
+
+
+</td><td>
+
+
+</td><td>
+
+{ audio: [Audio](./server.audio.md)<!-- -->; referenceDistance: number; }
+
+
+</td><td>
+
+Emitted when the audio's reference distance is set.
+
+
+</td></tr>
+<tr><td>
+
+["AUDIO.SET\_VOLUME"](./server.audioeventpayloads._audio.set_volume_.md)
+
+
+</td><td>
+
+
+</td><td>
+
+{ audio: [Audio](./server.audio.md)<!-- -->; volume: number; }
+
+
+</td><td>
+
+Emitted when the audio's volume is set.
+
+
+</td></tr>
+</tbody></table>

package/docs/server.baseentitycontroller.md

@@ -9,151 +9,17 @@ A base class for entity controller implementations.
 **Signature:**
 
 ```typescript
-export default abstract class BaseEntityController 
+export default abstract class BaseEntityController extends EventRouter 
 ```
+**Extends:** [EventRouter](./server.eventrouter.md)
 
 ## Remarks
 
 The BaseEntityController should be extended by a more specific entity controller that you or a plugin implements. Entity controllers are intended to be used as one controller instance per entity, but are flexible enough for edge cases such as if you want to create niche behavior of one controller for many entities that behave in unison.
 
-## Properties
+<h2>Events</h2>
 
-<table><thead><tr><th>
-
-Property
-
-
-</th><th>
-
-Modifiers
-
-
-</th><th>
-
-Type
-
-
-</th><th>
-
-Description
-
-
-</th></tr></thead>
-<tbody><tr><td>
-
-[onAttach?](./server.baseentitycontroller.onattach.md)
-
-
-</td><td>
-
-
-</td><td>
-
-(entity: [Entity](./server.entity.md)<!-- -->) =&gt; void
-
-
-</td><td>
-
-_(Optional)_ A function that is called when the controller is attached to an entity. Useful for implementing attach logic without writing a new entity controller class.
-
-
-</td></tr>
-<tr><td>
-
-[onDespawn?](./server.baseentitycontroller.ondespawn.md)
-
-
-</td><td>
-
-
-</td><td>
-
-(entity: [Entity](./server.entity.md)<!-- -->) =&gt; void
-
-
-</td><td>
-
-_(Optional)_ A function that is called when the controlled entity is despawned. Useful for implementing despawn logic without writing a new entity controller class.
-
-
-</td></tr>
-<tr><td>
-
-[onDetach?](./server.baseentitycontroller.ondetach.md)
-
-
-</td><td>
-
-
-</td><td>
-
-(entity: [Entity](./server.entity.md)<!-- -->) =&gt; void
-
-
-</td><td>
-
-_(Optional)_ A function that is called when the controller is detached from an entity. Useful for implementing detach logic without writing a new entity controller class.
-
-
-</td></tr>
-<tr><td>
-
-[onSpawn?](./server.baseentitycontroller.onspawn.md)
-
-
-</td><td>
-
-
-</td><td>
-
-(entity: [Entity](./server.entity.md)<!-- -->) =&gt; void
-
-
-</td><td>
-
-_(Optional)_ A function that is called when the controlled entity is spawned. Useful for implementing spawn logic without writing a new entity controller class.
-
-
-</td></tr>
-<tr><td>
-
-[onTick?](./server.baseentitycontroller.ontick.md)
-
-
-</td><td>
-
-
-</td><td>
-
-(entity: [Entity](./server.entity.md)<!-- -->, deltaTimeMs: number) =&gt; void
-
-
-</td><td>
-
-_(Optional)_ A function that is called every tick. Useful for implementing tick logic without writing a new entity controller class.
-
-
-</td></tr>
-<tr><td>
-
-[onTickWithPlayerInput?](./server.baseentitycontroller.ontickwithplayerinput.md)
-
-
-</td><td>
-
-
-</td><td>
-
-(entity: [PlayerEntity](./server.playerentity.md)<!-- -->, input: [PlayerInput](./server.playerinput.md)<!-- -->, cameraOrientation: [PlayerCameraOrientation](./server.playercameraorientation.md)<!-- -->, deltaTimeMs: number) =&gt; void
-
-
-</td><td>
-
-_(Optional)_ A function that is called every tick with player input by a PlayerEntity with this controller attached. Useful for implementing tick logic without writing a new entity controller class.
-
-
-</td></tr>
-</tbody></table>
+This class is an EventRouter, and instances of it emit events with payloads listed under [BaseEntityControllerEventPayloads](./server.baseentitycontrollereventpayloads.md)
 
 ## Methods