@antha/multiplayer-core 0.0.1 → 0.0.2

package/dist/multiplayer-api/multiplayer-controller.d.ts

@@ -5,6 +5,7 @@ import { ListenTarget } from 'typed-event-target';
 import { type ClientId, type RoomId } from '../multiplayer-id.js';
 import { type RoomInput } from '../webrtc/webrtc-multiplayer-controller.js';
 import { RoomRejectionError } from './errors.js';
+import { type MultiplayerClientRooms } from './multiplayer-api.js';
 import { type MultiplayerApiClient } from './multiplayer-client.js';
 /**
  * Connection state for {@link MultiplayerRoomController}.
@@ -173,13 +174,20 @@ declare const ControllerRoomListEvent_base: (new (eventInitDict: {
     hasRoomPassword: boolean;
 }>>>, "controller-room-list">, "type">;
 /**
- * This is called whenever the room list updates, even if there were no changes to the room list.
- * Note that room list updates are paused while the controller is connected to an actual room.
+ * This is called whenever the room list updates, even if there were no changes to the room list. By
+ * default, room list updates are off. Use `MultiplayerRoomController.startRoomUpdates` to start
+ * room list updates.
  *
  * @category Events
  */
 export declare class ControllerRoomListEvent extends ControllerRoomListEvent_base {
 }
+/**
+ * Callback fired whenever the room list is fetched from the multiplayer API.
+ *
+ * @category Internal
+ */
+export type ControllerRoomListListener = (rooms: Readonly<MultiplayerClientRooms>) => MaybePromise<void>;
 declare const ControllerClientEvent_base: (new (eventInitDict: {
     bubbles?: boolean;
     cancelable?: boolean;
@@ -334,11 +342,7 @@ export declare class MultiplayerRoomController<Message extends JsonCompatibleVal
     readonly knownErrors: {
         RoomRejectionError: typeof RoomRejectionError;
     };
-    /**
-     * Set to `false` to disable room updates, even when still not connected to a room in
-     * multiplayer mode.
-     */
-    enableRoomUpdates: boolean;
+    protected isListeningToRoomUpdates: boolean;
     /** Currently joined room id. If a room has not been joined yet, this will be empty. */
     readonly roomId: RoomId | undefined;
     /** The current connection state of the controller's connection to a backend API. */
@@ -357,11 +361,7 @@ export declare class MultiplayerRoomController<Message extends JsonCompatibleVal
      * playing in single player.
      */
     multiplayerApiClient: Readonly<MultiplayerApiClient> | undefined;
-    /**
-     * Used to keep track of the room update interval. This will be set when the controller is
-     * constructed in multiplayer mode or when a room is left. This will be cleared when a room is
-     * joined or if the controller is destroyed.
-     */
+    /** Used to keep track of the room update interval. */
     protected roomUpdateIntervalId: ReturnType<typeof globalThis.setInterval> | undefined;
     /** This is populated when `.initMultiplayer` is called. */
     protected multiplayerParams: Readonly<MultiplayerInitParams> | undefined;
@@ -389,10 +389,17 @@ export declare class MultiplayerRoomController<Message extends JsonCompatibleVal
     constructor(params: MultiplayerRoomControllerParams<Message>);
     /**
      * Start multiplayer mode. This initializes
-     * {@link MultiplayerRoomController.multiplayerApiClient} and
-     * {@link MultiplayerRoomController.roomUpdateIntervalId}.
+     * {@link MultiplayerRoomController.multiplayerApiClient}.
      */
     initMultiplayer(params: Readonly<MultiplayerInitParams>): Promise<void>;
+    /**
+     * Listen for room list updates, including while connected to a room.
+     *
+     * If a callback is provided, it is called each time the room list is updated.
+     */
+    startRoomUpdates(callback?: ControllerRoomListListener | undefined): import("typed-event-target").RemoveListenerCallback;
+    /** Turn off room list updates and remove callbacks added via `startRoomUpdates`. */
+    stopRoomUpdates(): void;
     /** Send a generic message to the current room. */
     sendMessage(message: Readonly<Message>): void;
     /** Detects if this controller is the room host or not. */
@@ -411,6 +418,8 @@ export declare class MultiplayerRoomController<Message extends JsonCompatibleVal
     leaveRoom(): void;
     /** Set the current connection state and fire listeners. */
     protected updateConnectionState(state: Partial<ApiAndRoomConnectionState>): void;
+    /** Stop polling the multiplayer server for room updates. */
+    protected stopRoomInterval(): void;
     /** Starts polling the multiplayer server for room updates and fires listeners. */
     protected startRoomInterval(): void;
 }

package/dist/multiplayer-api/multiplayer-controller.js

@@ -42,8 +42,9 @@ export class ControllerMessageEvent extends defineTypedCustomEvent()('controller
     }
 }
 /**
- * This is called whenever the room list updates, even if there were no changes to the room list.
- * Note that room list updates are paused while the controller is connected to an actual room.
+ * This is called whenever the room list updates, even if there were no changes to the room list. By
+ * default, room list updates are off. Use `MultiplayerRoomController.startRoomUpdates` to start
+ * room list updates.
  *
  * @category Events
  */
@@ -89,11 +90,7 @@ export class MultiplayerRoomController extends ListenTarget {
         RoomRejectionError,
     };
     knownErrors = MultiplayerRoomController.knownErrors;
-    /**
-     * Set to `false` to disable room updates, even when still not connected to a room in
-     * multiplayer mode.
-     */
-    enableRoomUpdates = true;
+    isListeningToRoomUpdates = false;
     /** Currently joined room id. If a room has not been joined yet, this will be empty. */
     roomId;
     /** The current connection state of the controller's connection to a backend API. */
@@ -112,11 +109,7 @@ export class MultiplayerRoomController extends ListenTarget {
      * playing in single player.
      */
     multiplayerApiClient;
-    /**
-     * Used to keep track of the room update interval. This will be set when the controller is
-     * constructed in multiplayer mode or when a room is left. This will be cleared when a room is
-     * joined or if the controller is destroyed.
-     */
+    /** Used to keep track of the room update interval. */
     roomUpdateIntervalId;
     /** This is populated when `.initMultiplayer` is called. */
     multiplayerParams;
@@ -153,8 +146,7 @@ export class MultiplayerRoomController extends ListenTarget {
     }
     /**
      * Start multiplayer mode. This initializes
-     * {@link MultiplayerRoomController.multiplayerApiClient} and
-     * {@link MultiplayerRoomController.roomUpdateIntervalId}.
+     * {@link MultiplayerRoomController.multiplayerApiClient}.
      */
     async initMultiplayer(params) {
         if (this.currentConnection) {
@@ -185,7 +177,23 @@ export class MultiplayerRoomController extends ListenTarget {
             });
             throw error;
         }
+    }
+    /**
+     * Listen for room list updates, including while connected to a room.
+     *
+     * If a callback is provided, it is called each time the room list is updated.
+     */
+    startRoomUpdates(callback) {
+        this.isListeningToRoomUpdates = true;
         this.startRoomInterval();
+        return this.listen(ControllerRoomListEvent, async (event) => {
+            await callback?.(event.detail);
+        });
+    }
+    /** Turn off room list updates and remove callbacks added via `startRoomUpdates`. */
+    stopRoomUpdates() {
+        this.isListeningToRoomUpdates = false;
+        this.stopRoomInterval();
     }
     /** Send a generic message to the current room. */
     sendMessage(message) {
@@ -210,7 +218,7 @@ export class MultiplayerRoomController extends ListenTarget {
             api: MultiplayerConnectionState.Disconnected,
         });
         this.currentConnection?.destroy();
-        globalThis.clearInterval(this.roomUpdateIntervalId);
+        this.stopRoomUpdates();
     }
     /**
      * Join or create a room.
@@ -257,7 +265,6 @@ export class MultiplayerRoomController extends ListenTarget {
         });
         if (connectionResult.connected) {
             makeWritable(this).roomId = room.roomId;
-            globalThis.clearInterval(this.roomUpdateIntervalId);
             this.updateConnectionState({
                 room: MultiplayerConnectionState.Connected,
             });
@@ -281,7 +288,6 @@ export class MultiplayerRoomController extends ListenTarget {
         makeWritable(this).roomId = undefined;
         this.currentConnection.destroy();
         this.currentConnection = undefined;
-        this.startRoomInterval();
         this.updateConnectionState({
             room: MultiplayerConnectionState.Disconnected,
         });
@@ -301,18 +307,22 @@ export class MultiplayerRoomController extends ListenTarget {
             },
         }));
     }
+    /** Stop polling the multiplayer server for room updates. */
+    stopRoomInterval() {
+        globalThis.clearInterval(this.roomUpdateIntervalId);
+        this.roomUpdateIntervalId = undefined;
+    }
     /** Starts polling the multiplayer server for room updates and fires listeners. */
     startRoomInterval() {
-        if (this.multiplayerApiClient) {
+        this.stopRoomInterval();
+        if (this.isListeningToRoomUpdates && this.multiplayerApiClient) {
             const roomUpdateMs = this.multiplayerParams?.roomUpdateInterval
                 ? convertDuration(this.multiplayerParams.roomUpdateInterval, {
                     milliseconds: true,
                 }).milliseconds
                 : 10_000;
             this.roomUpdateIntervalId = globalThis.setInterval(async () => {
-                if (this.currentConnection ||
-                    !this.multiplayerApiClient ||
-                    !this.enableRoomUpdates) {
+                if (!this.isListeningToRoomUpdates || !this.multiplayerApiClient) {
                     return;
                 }
                 const output = await this.multiplayerApiClient.fetch(multiplayerRoomsEndpoint).GET({

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@antha/multiplayer-core",
-    "version": "0.0.1",
+    "version": "0.0.2",
     "description": "Core functionalities for Antha multiplayer mods.",
     "keywords": [
         "vir",