@needle-tools/engine 5.1.0-alpha.3 → 5.1.0-alpha.5

package/src/engine/engine_networking.ts

@@ -2,7 +2,6 @@ const defaultNetworkingBackendUrlProvider = "https://urls.needle.tools/default-n
 let networkingServerUrl: string | undefined = "wss://networking-2.needle.tools/socket";
 
 import * as flatbuffers from 'flatbuffers';
-import { type Websocket } from 'websocket-ts';
 
 import type { Networking } from "../engine-components/Networking.js";
 import type { SyncedRoom } from "../engine-components/SyncedRoom.js";
@@ -10,11 +9,16 @@ import * as schemes from "../engine-schemes/schemes.js";
 import { isDevEnvironment } from './debug/index.js';
 import { Telemetry } from './engine_license.js';
 import { PeerNetworking } from './engine_networking_peer.js';
-import { type IModel, type INetworkConnection, SendQueue } from './engine_networking_types.js';
+import { type IModel, type INetworkConnection, type INetworkTransport, SendQueue } from './engine_networking_types.js';
+import { WebsocketTransport } from './engine_networking.transport.websocket.js';
 import { isHostedOnGlitch } from './engine_networking_utils.js';
 import { Context } from './engine_setup.js';
+import type { DisposeFn } from "./engine_disposable.js";
 import * as utils from "./engine_utils.js";
 
+/** @internal Symbol used to attach the original callback to unsubscribe functions returned by beginListen/beginListenBinary */
+const $originalCallback = Symbol("originalCallback");
+
 export const debugNet = utils.getParam("debugnet") ? true : false;
 export const debugOwner = debugNet || utils.getParam("debugowner") ? true : false;
 const debugnetBin = utils.getParam("debugnetbin");
@@ -58,16 +62,6 @@ export enum RoomEvents {
     /** When a user joins a room, the server sends the entire room state. Afterwards, the server sends the room-state-sent event. */
     RoomStateSent = "room-state-sent",
 }
-/**
- * See {@link RoomEvents} for all event names and docs.
- * - `joined-room`: When the local user has joined a room
- * - `left-room`: When the local user has left a room
- * - `user-joined-room`: When a other user has joined the room
- * - `user-left-room`: When a other user has left the room
- * - `room-state-sent`: When the server has sent the room state to the client
- */
-type RoomEventsIncoming = Exclude<`${RoomEvents}`, "join-room" | "leave-room">;
-
 /** Received when listening to `RoomEvents.JoinedRoom` event */
 export class JoinedRoomResponse {
     room!: string; // room name
@@ -100,8 +94,6 @@ export enum OwnershipEvent {
     GainedOwnershipBroadcast = 'gained-ownership-broadcast',
     LostOwnershipBroadcast = 'lost-ownership-broadcast',
 }
-type OwnershipEventNamesIncoming = Exclude<`${OwnershipEvent}`, "request-has-owner" | "request-is-owner" | "request-ownership" | "remove-ownership">;
-
 declare type GainedOwnershipBroadcastResponse = {
     guid: string;
     owner: string;
@@ -116,7 +108,7 @@ declare type OwnershipResponse = {
     value: boolean;
 }
 
-declare type WebsocketSendType = IModel | object | boolean | null | string | number;
+declare type WebsocketSendType = IModel | object | boolean | string | number;
 
 /** Maps known networking event keys to their callback signatures.
  * Used by {@link NetworkConnection.beginListen} and {@link NetworkConnection.stopListen} for type-safe event handling.
@@ -559,8 +551,7 @@ export class NetworkConnection implements INetworkConnection {
      * The current server url that the networking backend is connected to (e.g. the url of the websocket server)
      */
     public get currentServerUrl(): string | null {
-        // @ts-ignore (in ts-websocket 2.x this property is exposed)
-        return this._ws?.url ?? null;
+        return this._transport?.url ?? null;
     }
 
     /** A ping is sent to the server at a regular interval while the browser tab is active. This method can be used to send additional ping messages when needed so that the user doesn't get disconnected from the networking backend */
@@ -620,25 +611,16 @@ export class NetworkConnection implements INetworkConnection {
     /** Send a message to the networking backend - it will be broadcasted to all connected users (except yourself) in the same room by default */
     public send<K extends NetworkEventKey>(
         key: K,
-        data?: (K extends keyof NetworkEventMap ? NetworkEventData<K> : WebsocketSendType) | null,
+        data?: (K extends keyof NetworkEventMap ? NetworkEventData<K> : WebsocketSendType),
         queue?: SendQueue,
     ): void
-    public send(key: string, data: WebsocketSendType | null = null, queue: SendQueue = SendQueue.Queued) {
-
-        //@ts-ignore
-        if (data === null) data = {};
+    public send(key: string, data?: WebsocketSendType, queue: SendQueue = SendQueue.Queued) {
 
         if (queue === SendQueue.Queued) {
             this._defaultMessagesBuffer.push({ key: key, value: data });
             return;
         }
 
-        // if (!this.connected) return;
-        // if (this.channelId)
-        //     data["__id"] = this.channelId;
-        // else if (this.connectionId)
-        //     data["__id"] = this.connectionId;
-        // this.sendGeckosIo(key, data);
         return this.sendWithWebsocket(key, data, queue);
     }
 
@@ -668,13 +650,13 @@ export class NetworkConnection implements INetworkConnection {
     /** Send a binary message to the server (broadcasted to all connected users) */
     public sendBinary(bin: Uint8Array) {
         if (debugnetBin) console.log("<< send binary", this.context.time.frame, (bin.length / 1024) + " KB");
-        this._ws?.send(bin);
+        this._transport?.send(bin);
     }
 
     private _defaultMessagesBuffer: Array<{ key: string, value: any }> = [];
     private _defaultMessagesBufferArray: Array<{ key: string, data: any }> = [];
     public sendBufferedMessagesNow() {
-        if (!this._ws) return;
+        if (!this._transport) return;
         this._defaultMessagesBufferArray.length = 0;
         const count = Object.keys(this._defaultMessagesBuffer).length;
         for (const key in this._defaultMessagesBuffer) {
@@ -692,47 +674,59 @@ export class NetworkConnection implements INetworkConnection {
             console.log("SEND BUFFERED", this._defaultMessagesBufferArray.length);
         if (this._defaultMessagesBufferArray.length <= 0) return;
         const message = JSON.stringify(this._defaultMessagesBufferArray);
-        this._ws?.send(message);
+        this._transport?.send(message);
     }
 
-    /** Use to start listening to networking events.   
-     * To unsubscribe from events use the `{@link stopListen}` method.   
-     * 
-     * @example Custom event example
+    /** Use to start listening to networking events.
+     * Returns an unsubscribe function that removes the listener when called.
+     * The returned function can also be passed to {@link stopListen} or {@link Component.autoCleanup} for automatic lifecycle management.
+     *
+     * @example With autoCleanup (recommended)
+     * ```ts
+     * export class MyComponent extends Behaviour {
+     *   onEnable() {
+     *     this.autoCleanup(this.context.connection.beginListen("joined-room", () => {
+     *       console.log("I joined a networked room");
+     *     }));
+     *   }
+     *   // Automatically unsubscribed on disable — no manual cleanup needed!
+     * }
+     * ```
+     *
+     * @example Manual unsubscribe
      * ```ts
-     * // Listen to a custom event sent by the server
-     * this.context.connection.beginListen<MyDataType>("my-custom-event", (data) => {
-     *   console.log("Received custom event:", data);
-     * });
+     * const unsub = this.context.connection.beginListen("joined-room", () => { });
+     * // Later:
+     * unsub(); // removes the listener
      * ```
      *
-     * @example Listening to room events
+     * @example With stopListen (legacy pattern, still supported)
      * ```ts
-     * // Make sure to unsubscribe from events when the component is disabled
      * export class MyComponent extends Behaviour {
      *   onEnable() {
-     *     this.connection.beginListen("joined-room", this.onJoinedRoom)
+     *     this.context.connection.beginListen("joined-room", this.onJoinedRoom);
      *   }
      *   onDisable() {
-     *     this.connection.stopListen("joined-room", this.onJoinedRoom)
+     *     this.context.connection.stopListen("joined-room", this.onJoinedRoom);
      *   }
      *   onJoinedRoom = () => {
-     *      console.log("I joined a networked room")
+     *     console.log("I joined a networked room");
      *   }
      * }
      * ```
      * @link https://engine.needle.tools/docs/networking.html
-     * 
+     *
     */
     public beginListen<K extends NetworkEventKey>(
         key: K,
         callback: K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void,
-    ): K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void {
+    ): DisposeFn {
         if (!this._listeners[key])
             this._listeners[key] = [];
         this._listeners[key].push(callback);
-        // TODO: for a breaking change it would be easier to return a function to unsubscribe directly
-        return callback as any;
+        const unsub = () => this.stopListen(key, callback as any);
+        (unsub as any)[$originalCallback] = callback;
+        return unsub;
     }
 
     /**@deprecated please use stopListen instead (2.65.2-pre) */
@@ -741,51 +735,59 @@ export class NetworkConnection implements INetworkConnection {
         callback: (K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void) | null,
     ) { return this.stopListen(key, callback as any); }
 
-    /** Use to stop listening to networking events  
-     * To subscribe to events use the `{@link beginListen}` method.   
-     * See the example below for typical usage:
-     * 
-     * ### Component Example
+    /** Use to stop listening to networking events.
+     * Accepts either the original callback or the unsubscribe function returned by {@link beginListen}.
+     * To subscribe to events use the `{@link beginListen}` method.
+     *
+     * @example
      * ```ts
-     * // Make sure to unsubscribe from events when the component is disabled
-     * export class MyComponent extends Behaviour {
-     *   onEnable() {
-     *     this.connection.beginListen("joined-room", this.onJoinedRoom)
-     *   }
-     *   onDisable() {
-     *     this.connection.stopListen("joined-room", this.onJoinedRoom)
-     *   }
-     *   onJoinedRoom = () => {
-     *      console.log("I joined a networked room")
-     *   }
-     * }
+     * // Both patterns work:
+     * this.context.connection.stopListen("joined-room", this.onJoinedRoom); // original callback
+     * this.context.connection.stopListen("joined-room", unsub);             // unsubscribe fn from beginListen
      * ```
      */
+    private static _didLogStopListenHint = false;
     public stopListen<K extends NetworkEventKey>(
         key: K,
-        callback: (K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void) | null,
+        callback: (K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void) | Function | null,
     ): void
     public stopListen(key: string, callback: Function | null) {
         if (!callback) return;
         if (!this._listeners[key]) return;
-        const index = this._listeners[key].indexOf(callback);
+        // Backwards compat: if an unsubscribe function returned by beginListen was passed to stopListen,
+        // resolve it to the original callback via symbol so the listener can be found and removed.
+        const original = (callback as any)[$originalCallback] ?? callback;
+        if (original !== callback && isDevEnvironment() && !NetworkConnection._didLogStopListenHint) {
+            NetworkConnection._didLogStopListenHint = true;
+            console.warn("[Needle Engine] Tip: beginListen() returns an unsubscribe function — you can call it directly instead of using stopListen().");
+        }
+        const index = this._listeners[key].indexOf(original);
         if (index >= 0) {
             this._listeners[key].splice(index, 1);
         }
     }
 
-    /** Use to start listening to networking binary events */
-    public beginListenBinary(identifier: string, callback: BinaryCallback): BinaryCallback {
+    /** Use to start listening to networking binary events.
+     * Returns an unsubscribe function that removes the listener when called.
+     * The returned function can also be passed to {@link stopListenBinary} or {@link Component.autoCleanup}.
+     */
+    public beginListenBinary(identifier: string, callback: BinaryCallback): DisposeFn {
         if (!this._listenersBinary[identifier])
             this._listenersBinary[identifier] = [];
         this._listenersBinary[identifier].push(callback);
-        return callback;
+        const unsub = () => this.stopListenBinary(identifier, callback);
+        (unsub as any)[$originalCallback] = callback;
+        return unsub;
     }
 
-    /** Use to stop listening to networking binary events */
+    /** Use to stop listening to networking binary events.
+     * Accepts either the original callback or the unsubscribe function returned by {@link beginListenBinary}.
+     */
     public stopListenBinary(identifier: string, callback: any) {
         if (!this._listenersBinary[identifier]) return;
-        const index = this._listenersBinary[identifier].indexOf(callback);
+        // Backwards compat: resolve unsubscribe function to original callback via symbol
+        const original = callback?.[$originalCallback] ?? callback;
+        const index = this._listenersBinary[identifier].indexOf(original);
         if (index >= 0) {
             this._listenersBinary[identifier].splice(index, 1);
         }
@@ -802,14 +804,18 @@ export class NetworkConnection implements INetworkConnection {
 
     /** Used to connect to the networking server
      * @param url Optional url to connect to. If not provided, it will use the url from the registered `INetworkingWebsocketUrlProvider` or the default backend networking url. If you want to change the url after connecting, you need to disconnect first and then connect again with the new url.
+     * @param transport Optional custom transport to use instead of the default websocket. Useful for testing or alternative transports.
     */
-    public async connect(url?: string) {
+    public async connect(url?: string, transport?: INetworkTransport) {
         if (this.connected && url && url !== networkingServerUrl) {
             return Promise.reject("Can not connect to different server url. Please disconnect first.");
         }
         if (this.connected) {
             return Promise.resolve(true);
         }
+        if (transport) {
+            return this.connectTransport(transport);
+        }
         if (url)
             console.debug("Connecting to user provided url " + url);
         const overrideUrl = url || this.netWebSocketUrlProvider?.getWebsocketUrl();
@@ -824,11 +830,20 @@ export class NetworkConnection implements INetworkConnection {
 
     /** Disconnect from the networking backend + reset internal state */
     public disconnect() {
-        this._ws?.close();
-        this._ws = undefined;
+        if (this._transport) {
+            // Clear callbacks before closing so the onClose handler doesn't fire
+            this._transport.onOpen = null;
+            this._transport.onClose = null;
+            this._transport.onError = null;
+            this._transport.onMessage = null;
+            this._transport.close();
+            this._transport = undefined;
+        }
         networkingServerUrl = undefined;
 
-        // Reset all state
+        // Reset all state synchronously so callers can rely on isConnected/isInRoom immediately
+        this.connected = false;
+        this._connectionId = null;
         this._currentRoomAllowEditing = true;
         this._currentRoomName = null;
         this._currentRoomViewId = null;
@@ -836,16 +851,26 @@ export class NetworkConnection implements INetworkConnection {
         this._currentInRoom.length = 0;
         this._state = {};
         this._currentDelay = -1;
+        this._connectingToWebsocketPromise = null;
+    }
+
+    /** Full teardown: disconnect, clear all listeners, and release all resources.
+     * Called when the owning Context is destroyed. After dispose(), this instance should not be reused. */
+    public dispose() {
+        this.disconnect();
+        this._listeners = {};
+        this._listenersBinary = {};
+        this._waitingForSocket = {};
+        this._peer = null;
     }
 
     private _listeners: { [key: string]: Function[] } = {};
     private _listenersBinary: { [key: string]: BinaryCallback[] } = {};
     private connected: boolean = false;
-    private channelId: string | undefined;
     private _connectionId: string | null = null;
 
-    // Websocket ------------------------------------------------------------
-    private _ws: Websocket | undefined;
+    // Transport ------------------------------------------------------------
+    private _transport: INetworkTransport | undefined;
     private _waitingForSocket: { [key: string]: Array<Function> } = {};
     private _isInRoom: boolean = false;
     private _currentRoomName: string | null = null;
@@ -857,71 +882,70 @@ export class NetworkConnection implements INetworkConnection {
 
     private _connectingToWebsocketPromise: Promise<boolean> | null = null;
 
-    private connectWebsocket() {
+    /** Wire up a transport's event callbacks and start it */
+    private connectTransport(transport: INetworkTransport): Promise<boolean> {
         if (this._connectingToWebsocketPromise) return this._connectingToWebsocketPromise;
-        return this._connectingToWebsocketPromise = new Promise(async (res, _) => {
+        return this._connectingToWebsocketPromise = new Promise((res) => {
             let didResolve = false;
             const resolve = (val: boolean) => {
                 if (didResolve) return;
                 didResolve = true;
                 res(val);
-            }
-            if (networkingServerUrl === undefined) {
-                console.log("Fetch default backend url: " + defaultNetworkingBackendUrlProvider);
-                const failed = false;
-                const defaultUrlResponse = await fetch(defaultNetworkingBackendUrlProvider);
-                networkingServerUrl = await defaultUrlResponse.text();
-                if (failed) return;
-            }
-
-            if (networkingServerUrl === undefined) {
+            };
+
+            transport.onOpen = () => {
+                this._connectingToWebsocketPromise = null;
+                this._transport = transport;
+                this.connected = true;
+                if (isDevEnvironment() || debugNet) console.log("Connected to networking backend\n" + (transport.url ?? ""));
+                else console.debug("Connected to networking backend", transport.url ?? "");
+                resolve(true);
+                this.onSendQueued(SendQueue.OnConnection);
+            };
+            transport.onClose = () => {
+                this._connectingToWebsocketPromise = null;
+                this.connected = false;
+                this._isInRoom = false;
                 resolve(false);
-                return;
-            }
-
-            console.debug("Connecting to networking backend on\n" + networkingServerUrl)
-            const pkg = await import('websocket-ts');
-            // @ts-ignore
-            const WebsocketBuilder = pkg.default?.WebsocketBuilder ?? pkg.WebsocketBuilder;
-            const ExponentialBackoff = pkg.default?.ExponentialBackoff ?? pkg.ExponentialBackoff;
-            const ws = new WebsocketBuilder(networkingServerUrl)
-                .withMaxRetries(10)
-                .withBackoff(new ExponentialBackoff(2000, 4))
-                .onOpen(() => {
-                    this._connectingToWebsocketPromise = null;
-                    this._ws = ws;
-                    this.connected = true;
-                    if (isDevEnvironment() || debugNet) console.log("Connected to networking backend\n" + networkingServerUrl);
-                    else console.debug("Connected to networking backend", networkingServerUrl);
-                    resolve(true);
-                    this.onSendQueued(SendQueue.OnConnection);
-                })
-                .onClose((_evt) => {
-                    this._connectingToWebsocketPromise = null;
-                    this.connected = false;
-                    this._isInRoom = false;
-                    resolve(false);
-                    let msg = "Websocket connection closed...";
-                    if (!networkingServerUrl?.includes("/socket")) msg += ` Do you perhaps mean to connect to \"/socket\"?`;
-                    console.error(msg);
-                })
-                .onError((_e) => {
-                    console.error("Websocket connection failed...");
-                    resolve(false);
-                    Telemetry.sendEvent(this.context, "networking", {
-                        event: "connection_error",
-                    });
-                })
-                .onRetry(() => { console.log("Retry connecting to networking websocket") })
-                .build();
-            ws.addEventListener(pkg.WebsocketEvent.message, (socket, msg) => {
-                this.onMessage(socket, msg);
-            });
+                let msg = "Websocket connection closed...";
+                if (!transport.url?.includes("/socket")) msg += ` Do you perhaps mean to connect to "/socket"?`;
+                console.error(msg);
+            };
+            transport.onError = () => {
+                console.error("Websocket connection failed...");
+                resolve(false);
+                Telemetry.sendEvent(this.context, "networking", {
+                    event: "connection_error",
+                });
+            };
+            transport.onMessage = (data) => {
+                this.onMessage(data);
+            };
+
+            transport.start();
         });
     }
 
-    private onMessage(_, ev) {
-        const msg = ev.data;
+    private async connectWebsocket() {
+        if (this._connectingToWebsocketPromise) return this._connectingToWebsocketPromise;
+
+        if (networkingServerUrl === undefined) {
+            console.log("Fetch default backend url: " + defaultNetworkingBackendUrlProvider);
+            const defaultUrlResponse = await fetch(defaultNetworkingBackendUrlProvider);
+            networkingServerUrl = await defaultUrlResponse.text();
+        }
+
+        if (networkingServerUrl === undefined) {
+            return false;
+        }
+
+        console.debug("Connecting to networking backend on\n" + networkingServerUrl);
+        const transport = new WebsocketTransport(networkingServerUrl);
+        return this.connectTransport(transport);
+    }
+
+    private onMessage(data: string | Blob) {
+        const msg = data;
         try {
             if (typeof msg !== "string") {
                 if (msg.size) {
@@ -1098,9 +1122,9 @@ export class NetworkConnection implements INetworkConnection {
         };
     }
 
-    private sendWithWebsocket(key: string, data: IModel | object | boolean | string | number, queue: SendQueue = SendQueue.OnRoomJoin) {
+    private sendWithWebsocket(key: string, data: WebsocketSendType | undefined, queue: SendQueue = SendQueue.OnRoomJoin) {
         // console.log(key);
-        if (!this._ws) {
+        if (!this._transport) {
             const arr = this._waitingForSocket[queue] || [];
             arr.push(() => this.sendWithWebsocket(key, data, queue));
             this._waitingForSocket[queue] = arr;
@@ -1109,7 +1133,7 @@ export class NetworkConnection implements INetworkConnection {
         }
         const str = JSON.stringify(this.toMessage(key, data));
         if (debugNet) console.log(">>", key);
-        this._ws.send(str);
+        this._transport.send(str);
     }
 
     private onSendQueued(queue: SendQueue) {

package/src/engine/engine_networking_instantiate.ts

@@ -498,8 +498,8 @@ export function beginListenInstantiate(context: Context) {
     });
 
     return () => {
-        context.connection.stopListen(InstantiateEvent.NewInstanceCreated, cb1);
-        context.connection.stopListen("left-room", cb2);
+        cb1();
+        cb2();
     }
 }
 

package/src/engine/engine_networking_types.ts

@@ -11,15 +11,55 @@ export declare interface IModel {
 }
 
 
+/** Controls when a network message is actually sent to the server.
+ * @see {@link NetworkConnection.send}
+ */
 export enum SendQueue {
+    /** Hold the message until the transport connection opens, then send it. Use for messages that must arrive as soon as the socket is ready (e.g. join-room). */
     OnConnection,
+    /** Hold the message until the client has joined a room, then send it. Use for messages that require room context. */
     OnRoomJoin,
+    /** Buffer the message and send it on the next `sendBufferedMessagesNow()` call (typically once per frame). This is the default for `send()`. */
     Queued,
+    /** Send the message to the server immediately without buffering. */
     Immediate,
 }
 
 export declare interface INetworkConnection {
     get isConnected(): boolean;
     get isInRoom(): boolean;
-    send(key: string, data: IModel | object | boolean | null | string | number, queue: SendQueue): unknown;
+    send(key: string, data?: IModel | object | boolean | string | number, queue?: SendQueue): unknown;
+}
+
+/**
+ * @experimental
+ * Interface for a network transport layer used by {@link NetworkConnection}.
+ * The default implementation wraps a websocket via `websocket-ts`.
+ * Custom implementations can be injected into {@link NetworkConnection.connect}
+ * for testing or alternative transports.
+ *
+ * **Lifecycle:** After creating a transport and passing it to `connect()`,
+ * `NetworkConnection` sets the four event callbacks (`onOpen`, `onClose`,
+ * `onError`, `onMessage`) and then calls {@link start}. The transport
+ * should call `onOpen` when the connection is ready.
+ */
+export interface INetworkTransport {
+    /** Start the connection. Called by NetworkConnection after event callbacks are set.
+     * May return a promise if setup is async (e.g. dynamic imports). */
+    start(): void | Promise<void>;
+    /** Send data (string for JSON messages, Uint8Array for binary) */
+    send(data: string | Uint8Array): void;
+    /** Close the transport */
+    close(): void | Promise<void>;
+    /** The URL this transport is connected to, if applicable */
+    readonly url: string | undefined;
+
+    /** Called when the transport connection opens */
+    onOpen: (() => void) | null;
+    /** Called when the transport connection closes */
+    onClose: (() => void) | null;
+    /** Called when an error occurs */
+    onError: ((err: any) => void) | null;
+    /** Called when a message is received. Data is either a string (JSON) or Blob (binary). */
+    onMessage: ((data: string | Blob) => void) | null;
 }