@needle-tools/engine 5.1.0-canary.fbdfce3 → 5.1.0-experimental.03e8105

package/lib/engine/engine_networking.d.ts

@@ -1,7 +1,8 @@
 import * as flatbuffers from 'flatbuffers';
 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 { Context } from './engine_setup.js';
+import type { DisposeFn } from "./engine_disposable.js";
 export declare const debugNet: boolean;
 export declare const debugOwner: boolean;
 export interface INetworkingWebsocketUrlProvider {
@@ -75,7 +76,7 @@ declare type OwnershipResponse = {
     guid: string;
     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.
  */
@@ -365,7 +366,7 @@ export declare class NetworkConnection implements INetworkConnection {
     /** Use to leave a room that you are currently connected to (use `leaveRoom()` to disconnect from the currently active room but you can also specify a room name) */
     leaveRoom(room?: string | null): boolean;
     /** Send a message to the networking backend - it will be broadcasted to all connected users (except yourself) in the same room by default */
-    send<K extends NetworkEventKey>(key: K, data?: (K extends keyof NetworkEventMap ? NetworkEventData<K> : WebsocketSendType) | null, queue?: SendQueue): void;
+    send<K extends NetworkEventKey>(key: K, data?: (K extends keyof NetworkEventMap ? NetworkEventData<K> : WebsocketSendType), queue?: SendQueue): void;
     /**
      * Deletes the network state for a specific object on the server.
      * This removes the object's state from the room, preventing it from being sent to newly joining users.
@@ -387,61 +388,69 @@ export declare class NetworkConnection implements INetworkConnection {
     private _defaultMessagesBufferArray;
     sendBufferedMessagesNow(): void;
     /** Use to start listening to networking events.
-     * To unsubscribe from events use the `{@link stopListen}` method.
+     * 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 Custom event example
+     * @example With autoCleanup (recommended)
      * ```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);
-     * });
+     * 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 Listening to room events
+     * @example Manual unsubscribe
+     * ```ts
+     * const unsub = this.context.connection.beginListen("joined-room", () => { });
+     * // Later:
+     * unsub(); // removes the listener
+     * ```
+     *
+     * @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
      *
     */
-    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;
+    beginListen<K extends NetworkEventKey>(key: K, callback: K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void): DisposeFn;
     /**@deprecated please use stopListen instead (2.65.2-pre) */
     stopListening<K extends NetworkEventKey>(key: K, callback: (K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void) | null): void;
-    /** Use to stop listening to networking events
+    /** 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.
-     * See the example below for typical usage:
      *
-     * ### Component Example
+     * @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
      * ```
      */
-    stopListen<K extends NetworkEventKey>(key: K, callback: (K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void) | null): void;
-    /** Use to start listening to networking binary events */
-    beginListenBinary(identifier: string, callback: BinaryCallback): BinaryCallback;
-    /** Use to stop listening to networking binary events */
+    private static _didLogStopListenHint;
+    stopListen<K extends NetworkEventKey>(key: K, callback: (K extends keyof NetworkEventMap ? NetworkEventMap[K] : (...args: any[]) => void) | Function | null): void;
+    /** 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}.
+     */
+    beginListenBinary(identifier: string, callback: BinaryCallback): DisposeFn;
+    /** Use to stop listening to networking binary events.
+     * Accepts either the original callback or the unsubscribe function returned by {@link beginListenBinary}.
+     */
     stopListenBinary(identifier: string, callback: any): void;
     private netWebSocketUrlProvider?;
     /** Use to override the networking server backend url.
@@ -450,16 +459,19 @@ export declare class NetworkConnection implements INetworkConnection {
     registerProvider(prov: INetworkingWebsocketUrlProvider): void;
     /** 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.
     */
-    connect(url?: string): Promise<boolean>;
+    connect(url?: string, transport?: INetworkTransport): Promise<boolean>;
     /** Disconnect from the networking backend + reset internal state */
     disconnect(): void;
+    /** 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. */
+    dispose(): void;
     private _listeners;
     private _listenersBinary;
     private connected;
-    private channelId;
     private _connectionId;
-    private _ws;
+    private _transport;
     private _waitingForSocket;
     private _isInRoom;
     private _currentRoomName;
@@ -469,6 +481,8 @@ export declare class NetworkConnection implements INetworkConnection {
     private _state;
     private _currentDelay;
     private _connectingToWebsocketPromise;
+    /** Wire up a transport's event callbacks and start it */
+    private connectTransport;
     private connectWebsocket;
     private onMessage;
     private handleIncomingBinaryMessage;

package/lib/engine/engine_networking.js

@@ -6,8 +6,11 @@ import { isDevEnvironment } from './debug/index.js';
 import { Telemetry } from './engine_license.js';
 import { PeerNetworking } from './engine_networking_peer.js';
 import { SendQueue } from './engine_networking_types.js';
+import { WebsocketTransport } from './engine_networking.transport.websocket.js';
 import { isHostedOnGlitch } from './engine_networking_utils.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");
@@ -442,8 +445,7 @@ export class NetworkConnection {
      * The current server url that the networking backend is connected to (e.g. the url of the websocket server)
      */
     get currentServerUrl() {
-        // @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 */
     sendPing() {
@@ -494,20 +496,11 @@ export class NetworkConnection {
         this.send(RoomEvents.Leave, { room: room });
         return true;
     }
-    send(key, data = null, queue = SendQueue.Queued) {
-        //@ts-ignore
-        if (data === null)
-            data = {};
+    send(key, data, queue = 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);
     }
     /**
@@ -535,12 +528,12 @@ export class NetworkConnection {
     sendBinary(bin) {
         if (debugnetBin)
             console.log("<< send binary", this.context.time.frame, (bin.length / 1024) + " KB");
-        this._ws?.send(bin);
+        this._transport?.send(bin);
     }
     _defaultMessagesBuffer = [];
     _defaultMessagesBufferArray = [];
     sendBufferedMessagesNow() {
-        if (!this._ws)
+        if (!this._transport)
             return;
         this._defaultMessagesBufferArray.length = 0;
         const count = Object.keys(this._defaultMessagesBuffer).length;
@@ -560,31 +553,42 @@ export class NetworkConnection {
         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.
+     * 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 Custom event example
+     * @example With autoCleanup (recommended)
      * ```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);
-     * });
+     * 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 Listening to room events
+     * @example Manual unsubscribe
+     * ```ts
+     * const unsub = this.context.connection.beginListen("joined-room", () => { });
+     * // Later:
+     * unsub(); // removes the listener
+     * ```
+     *
+     * @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");
      *   }
      * }
      * ```
@@ -595,33 +599,62 @@ export class NetworkConnection {
         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;
+        const unsub = () => this.stopListen(key, callback);
+        unsub[$originalCallback] = callback;
+        return unsub;
     }
     /**@deprecated please use stopListen instead (2.65.2-pre) */
     stopListening(key, callback) { return this.stopListen(key, callback); }
+    /** 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
+     * // Both patterns work:
+     * this.context.connection.stopListen("joined-room", this.onJoinedRoom); // original callback
+     * this.context.connection.stopListen("joined-room", unsub);             // unsubscribe fn from beginListen
+     * ```
+     */
+    static _didLogStopListenHint = false;
     stopListen(key, callback) {
         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[$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 */
+    /** 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}.
+     */
     beginListenBinary(identifier, callback) {
         if (!this._listenersBinary[identifier])
             this._listenersBinary[identifier] = [];
         this._listenersBinary[identifier].push(callback);
-        return callback;
+        const unsub = () => this.stopListenBinary(identifier, callback);
+        unsub[$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}.
+     */
     stopListenBinary(identifier, callback) {
         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);
         }
@@ -635,14 +668,18 @@ export class NetworkConnection {
     }
     /** 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.
     */
-    async connect(url) {
+    async connect(url, transport) {
         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();
@@ -657,10 +694,19 @@ export class NetworkConnection {
     ;
     /** Disconnect from the networking backend + reset internal state */
     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;
@@ -668,14 +714,23 @@ export class NetworkConnection {
         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. */
+    dispose() {
+        this.disconnect();
+        this._listeners = {};
+        this._listenersBinary = {};
+        this._waitingForSocket = {};
+        this._peer = null;
     }
     _listeners = {};
     _listenersBinary = {};
     connected = false;
-    channelId;
     _connectionId = null;
-    // Websocket ------------------------------------------------------------
-    _ws;
+    // Transport ------------------------------------------------------------
+    _transport;
     _waitingForSocket = {};
     _isInRoom = false;
     _currentRoomName = null;
@@ -685,10 +740,11 @@ export class NetworkConnection {
     _state = {};
     _currentDelay = -1;
     _connectingToWebsocketPromise = null;
-    connectWebsocket() {
+    /** Wire up a transport's event callbacks and start it */
+    connectTransport(transport) {
         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) => {
                 if (didResolve)
@@ -696,63 +752,57 @@ export class NetworkConnection {
                 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) {
-                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(() => {
+            transport.onOpen = () => {
                 this._connectingToWebsocketPromise = null;
-                this._ws = ws;
+                this._transport = transport;
                 this.connected = true;
                 if (isDevEnvironment() || debugNet)
-                    console.log("Connected to networking backend\n" + networkingServerUrl);
+                    console.log("Connected to networking backend\n" + (transport.url ?? ""));
                 else
-                    console.debug("Connected to networking backend", networkingServerUrl);
+                    console.debug("Connected to networking backend", transport.url ?? "");
                 resolve(true);
                 this.onSendQueued(SendQueue.OnConnection);
-            })
-                .onClose((_evt) => {
+            };
+            transport.onClose = () => {
                 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\"?`;
+                if (!transport.url?.includes("/socket"))
+                    msg += ` Do you perhaps mean to connect to "/socket"?`;
                 console.error(msg);
-            })
-                .onError((_e) => {
+            };
+            transport.onError = () => {
                 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);
-            });
+            };
+            transport.onMessage = (data) => {
+                this.onMessage(data);
+            };
+            transport.start();
         });
     }
-    onMessage(_, ev) {
-        const msg = ev.data;
+    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);
+    }
+    onMessage(data) {
+        const msg = data;
         try {
             if (typeof msg !== "string") {
                 if (msg.size) {
@@ -927,7 +977,7 @@ export class NetworkConnection {
     }
     sendWithWebsocket(key, data, queue = 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;
@@ -937,7 +987,7 @@ export class NetworkConnection {
         const str = JSON.stringify(this.toMessage(key, data));
         if (debugNet)
             console.log(">>", key);
-        this._ws.send(str);
+        this._transport.send(str);
     }
     onSendQueued(queue) {
         const queued = this._waitingForSocket[queue];