@needle-tools/engine 4.13.0 → 4.13.1

package/lib/engine/engine_networking.d.ts

@@ -74,13 +74,81 @@ export declare enum OwnershipEvent {
 }
 type OwnershipEventNamesIncoming = Exclude<`${OwnershipEvent}`, "request-has-owner" | "request-is-owner" | "request-ownership" | "remove-ownership">;
 declare type WebsocketSendType = IModel | object | boolean | null | string | number;
-/** Class for abstracting the concept of ownership regarding a networked object or component.
- * A component that is owned by another user can not be modified through networking (the server will reject changes) */
+/**
+ * Manages ownership of networked objects or components.
+ *
+ * In multiplayer scenarios, ownership determines which client has authority to modify an object.
+ * The networking server rejects changes from clients that don't own an object. This prevents conflicts
+ * when multiple users try to manipulate the same object simultaneously.
+ *
+ * **Ownership states:**
+ * - `hasOwnership`: This client owns the object and can modify it
+ * - `isOwned`: Some client (could be local or remote) owns the object
+ * - `undefined`: Ownership state is unknown (not yet queried)
+ *
+ * **Typical workflow:**
+ * 1. Request ownership before modifying an object
+ * 2. Make your changes while you have ownership
+ * 3. Free ownership when done (or keep it if still interacting)
+ *
+ * @example Basic usage
+ * ```ts
+ * export class MyComponent extends Behaviour {
+ *   private ownership?: OwnershipModel;
+ *
+ *   awake() {
+ *     this.ownership = new OwnershipModel(this.context.connection, this.guid);
+ *   }
+ *
+ *   onClick() {
+ *     // Request ownership before modifying the object
+ *     this.ownership.requestOwnership();
+ *   }
+ *
+ *   update() {
+ *     if (this.ownership.hasOwnership) {
+ *       // Safe to modify and sync the object
+ *       this.gameObject.position.y += 0.01;
+ *     }
+ *   }
+ *
+ *   onDisable() {
+ *     // Release ownership when done
+ *     this.ownership.freeOwnership();
+ *     this.ownership.destroy();
+ *   }
+ * }
+ * ```
+ *
+ * @example Async ownership
+ * ```ts
+ * async modifyObject() {
+ *   try {
+ *     await this.ownership.requestOwnershipAsync();
+ *     // Now guaranteed to have ownership
+ *     this.transform.position.x = 5;
+ *   } catch(e) {
+ *     console.log("Failed to gain ownership");
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link SyncedTransform} for a complete example of ownership in action
+ * @link https://engine.needle.tools/docs/networking.html
+ */
 export declare class OwnershipModel {
+    /** The unique identifier (GUID) of the object this ownership model manages */
     guid: string;
     private connection;
+    /**
+     * Checks if the local client has ownership of this object.
+     * @returns `true` if this client owns the object and can modify it, `false` otherwise
+     */
     get hasOwnership(): boolean;
-    /** @returns true of anyone has ownership */
+    /**
+     * Checks if anyone (local or remote client) has ownership of this object.
+     * @returns `true` if someone owns the object, `false` if no one owns it, `undefined` if unknown
+     */
     get isOwned(): boolean | undefined;
     /**
      * Checks if Needle Engine networking is connected to a websocket. Note that this is **not equal** to being connected to a *room*. If you want to check if Needle Engine is connected to a networking room use the `isInRoom` property.
@@ -94,13 +162,50 @@ export declare class OwnershipModel {
     private _hasOwnerResponse;
     constructor(connection: NetworkConnection, guid: string);
     private _isWaitingForOwnershipResponseCallback;
+    /**
+     * Queries the server to update the `isOwned` state.
+     * Call this to check if anyone currently has ownership.
+     */
     updateIsOwned(): void;
     private onHasOwnerResponse;
+    /**
+     * Requests ownership only if the object is not currently owned by anyone.
+     * Internally checks ownership state first, then requests ownership if free.
+     * @returns this OwnershipModel instance for method chaining
+     */
     requestOwnershipIfNotOwned(): OwnershipModel;
     private waitForHasOwnershipRequestResponse;
+    /**
+     * Requests ownership and waits asynchronously until ownership is granted or timeout occurs.
+     * @returns Promise that resolves with this OwnershipModel when ownership is gained
+     * @throws Rejects with "Timeout" if ownership is not gained within ~1 second
+     * @example
+     * ```ts
+     * try {
+     *   await ownership.requestOwnershipAsync();
+     *   // Ownership granted, safe to modify object
+     * } catch(e) {
+     *   console.warn("Could not gain ownership:", e);
+     * }
+     * ```
+     */
     requestOwnershipAsync(): Promise<OwnershipModel>;
+    /**
+     * Requests ownership of this object from the networking server.
+     * Ownership may not be granted immediately - check `hasOwnership` property or use `requestOwnershipAsync()`.
+     * @returns this OwnershipModel instance for method chaining
+     */
     requestOwnership(): OwnershipModel;
+    /**
+     * Releases ownership of this object, allowing others to take control.
+     * Call this when you're done modifying an object to allow other users to interact with it.
+     * @returns this OwnershipModel instance for method chaining
+     */
     freeOwnership(): OwnershipModel;
+    /**
+     * Cleans up event listeners and resources.
+     * Call this when the OwnershipModel is no longer needed (e.g., in `onDestroy()`).
+     */
     destroy(): void;
     private onGainedOwnership;
     private onLostOwnership;
@@ -108,10 +213,46 @@ export declare class OwnershipModel {
 export declare type BinaryCallback = {
     (data: any | flatbuffers.ByteBuffer): void;
 };
-/** Main class to communicate with the networking backend
- * @link https://engine.needle.tools/docs/networking.html
+/**
+ * Main class for multiuser networking. Access via `this.context.connection` from any component.
+ *
+ * **About GUIDs:**
+ * In Needle Engine networking, GUIDs (Globally Unique Identifiers) are used to identify objects and components across the network.
+ * Every GameObject and Component has a unique `guid` property that remains consistent across all clients.
+ * GUIDs are automatically assigned (e.g. during export from Unity/Blender) and are essential for:
+ * - Object ownership management (see {@link OwnershipModel})
+ * - State synchronization (storing and retrieving object state)
+ * - Identifying which object received a network message
+ *
+ * When working with networking, you'll typically use `this.guid` to identify your component or `this.gameObject.guid` for the GameObject.
  *
-*/
+ * @example Joining a room
+ * ```ts
+ * this.context.connection.connect();
+ * this.context.connection.joinRoom("my-room");
+ * ```
+ * @example Listening to events
+ * ```ts
+ * this.context.connection.beginListen("my-event", (data) => {
+ *   console.log("Received:", data);
+ * });
+ * ```
+ * @example Sending data
+ * ```ts
+ * this.context.connection.send("my-event", { message: "Hello" });
+ * ```
+ * @example Using GUIDs for object identification
+ * ```ts
+ * // Get state for a specific object by its GUID
+ * const state = this.context.connection.tryGetState(this.guid);
+ *
+ * // Delete remote state for an object
+ * this.context.connection.sendDeleteRemoteState(this.guid);
+ * ```
+ * @see {@link RoomEvents} for room lifecycle events
+ * @see {@link OwnershipModel} for object ownership
+ * @link https://engine.needle.tools/docs/how-to-guides/networking/
+ */
 export declare class NetworkConnection implements INetworkConnection {
     private context;
     private _peer;
@@ -119,7 +260,18 @@ export declare class NetworkConnection implements INetworkConnection {
     /** Experimental: networking via peerjs */
     get peer(): PeerNetworking;
     /**
-     * Returns the state of a given guid.
+     * Returns the cached network state for a given GUID.
+     * The state is stored locally whenever network updates are received for that object.
+     * @param guid The unique identifier of the object whose state you want to retrieve
+     * @returns The cached state object, or `null` if no state exists for this GUID
+     * @example
+     * ```ts
+     * // Get the last known state for this component
+     * const myState = this.context.connection.tryGetState(this.guid);
+     * if (myState) {
+     *   console.log("Found cached state:", myState);
+     * }
+     * ```
      */
     tryGetState(guid: string): IModel | null;
     /** The connection id of the local user - it is given by the networking backend and can not be changed */
@@ -129,7 +281,7 @@ export declare class NetworkConnection implements INetworkConnection {
      */
     get isDebugEnabled(): boolean;
     /**
-     * Checks if Needle Engine networking is connected to a websocket. Note that this is **not equal** to being connected to a *room*. If you want to check if Needle Engine is connected to a networking room use the `isInRoom` property.
+     * Checks if Needle Engine networking is connected to a websocket. Note that this is **not equal** to being connected to a *room*. If you want to check if Needle Engine is connected to a networking room use the `{@link isInRoom}` property.
      * @returns true if connected to the websocket.
      */
     get isConnected(): boolean;
@@ -162,13 +314,24 @@ export declare class NetworkConnection implements INetworkConnection {
     private _usersInRoomCopy;
     /** Returns a list of all user ids in the current room */
     usersInRoom(target?: string[] | null): string[];
-    /** Joins a networked room. If you don't want to manage a connection yourself you can use a `SyncedRoom` component as well */
+    /** Joins a networked room. If you don't want to manage a connection yourself you can use a `{@link SyncedRoom}` component as well */
     joinRoom(room: string, viewOnly?: boolean): boolean;
     /** 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 broadcasted to all connected users in the same room by default */
     send<T extends WebsocketSendType>(key: string | OwnershipEvent, data?: T | null, queue?: SendQueue): void;
-    /** Use to delete state for a given guid on the server */
+    /**
+     * 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.
+     * @param guid The unique identifier of the object whose state should be deleted
+     * @example
+     * ```ts
+     * // When destroying a networked object, clean up its server state
+     * onDestroy() {
+     *   this.context.connection.sendDeleteRemoteState(this.guid);
+     * }
+     * ```
+     */
     sendDeleteRemoteState(guid: string): void;
     /** Use to delete all state in the currently connected room on the server */
     sendDeleteRemoteStateAll(): void;
@@ -178,7 +341,7 @@ export declare class NetworkConnection implements INetworkConnection {
     private _defaultMessagesBufferArray;
     sendBufferedMessagesNow(): void;
     /** Use to start listening to networking events.
-     * To unsubscribe from events use the `stopListen` method.
+     * To unsubscribe from events use the `{@link stopListen}` method.
      * See the example below for typical usage:
      *
      * ### Component Example
@@ -203,7 +366,7 @@ export declare class NetworkConnection implements INetworkConnection {
     /**@deprecated please use stopListen instead (2.65.2-pre) */
     stopListening(key: (string & {}) | OwnershipEvent | OwnershipEventNamesIncoming | RoomEventsIncoming | RoomEvents, callback: Function | null): void;
     /** Use to stop listening to networking events
-     * To subscribe to events use the `beginListen` method.
+     * To subscribe to events use the `{@link beginListen}` method.
      * See the example below for typical usage:
      *
      * ### Component Example
@@ -228,9 +391,13 @@ export declare class NetworkConnection implements INetworkConnection {
     /** Use to stop listening to networking binary events */
     stopListenBinary(identifier: string, callback: any): void;
     private netWebSocketUrlProvider?;
-    /** Use to override the networking server backend url. This is what the `Networking` component uses to modify the backend url */
+    /** Use to override the networking server backend url.
+     * This is what the `{@link Networking}` component uses to modify the backend url.
+     **/
     registerProvider(prov: INetworkingWebsocketUrlProvider): void;
-    /** Used to connect to the networking server */
+    /** 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.
+    */
     connect(url?: string): Promise<boolean>;
     /** Disconnect from the networking backend + reset internal state */
     disconnect(): void;

package/lib/engine/engine_networking.js

@@ -67,16 +67,84 @@ export var OwnershipEvent;
     OwnershipEvent["GainedOwnershipBroadcast"] = "gained-ownership-broadcast";
     OwnershipEvent["LostOwnershipBroadcast"] = "lost-ownership-broadcast";
 })(OwnershipEvent || (OwnershipEvent = {}));
-/** Class for abstracting the concept of ownership regarding a networked object or component.
- * A component that is owned by another user can not be modified through networking (the server will reject changes) */
+/**
+ * Manages ownership of networked objects or components.
+ *
+ * In multiplayer scenarios, ownership determines which client has authority to modify an object.
+ * The networking server rejects changes from clients that don't own an object. This prevents conflicts
+ * when multiple users try to manipulate the same object simultaneously.
+ *
+ * **Ownership states:**
+ * - `hasOwnership`: This client owns the object and can modify it
+ * - `isOwned`: Some client (could be local or remote) owns the object
+ * - `undefined`: Ownership state is unknown (not yet queried)
+ *
+ * **Typical workflow:**
+ * 1. Request ownership before modifying an object
+ * 2. Make your changes while you have ownership
+ * 3. Free ownership when done (or keep it if still interacting)
+ *
+ * @example Basic usage
+ * ```ts
+ * export class MyComponent extends Behaviour {
+ *   private ownership?: OwnershipModel;
+ *
+ *   awake() {
+ *     this.ownership = new OwnershipModel(this.context.connection, this.guid);
+ *   }
+ *
+ *   onClick() {
+ *     // Request ownership before modifying the object
+ *     this.ownership.requestOwnership();
+ *   }
+ *
+ *   update() {
+ *     if (this.ownership.hasOwnership) {
+ *       // Safe to modify and sync the object
+ *       this.gameObject.position.y += 0.01;
+ *     }
+ *   }
+ *
+ *   onDisable() {
+ *     // Release ownership when done
+ *     this.ownership.freeOwnership();
+ *     this.ownership.destroy();
+ *   }
+ * }
+ * ```
+ *
+ * @example Async ownership
+ * ```ts
+ * async modifyObject() {
+ *   try {
+ *     await this.ownership.requestOwnershipAsync();
+ *     // Now guaranteed to have ownership
+ *     this.transform.position.x = 5;
+ *   } catch(e) {
+ *     console.log("Failed to gain ownership");
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link SyncedTransform} for a complete example of ownership in action
+ * @link https://engine.needle.tools/docs/networking.html
+ */
 export class OwnershipModel {
+    /** The unique identifier (GUID) of the object this ownership model manages */
     guid;
     connection;
+    /**
+     * Checks if the local client has ownership of this object.
+     * @returns `true` if this client owns the object and can modify it, `false` otherwise
+     */
     get hasOwnership() {
         return this._hasOwnership;
     }
     // TODO: server should just send id to everyone
-    /** @returns true of anyone has ownership */
+    /**
+     * Checks if anyone (local or remote client) has ownership of this object.
+     * @returns `true` if someone owns the object, `false` if no one owns it, `undefined` if unknown
+     */
     get isOwned() {
         return this._isOwned;
     }
@@ -103,6 +171,10 @@ export class OwnershipModel {
         connection.beginListen(OwnershipEvent.ResponseHasOwner, this._hasOwnerResponse);
     }
     _isWaitingForOwnershipResponseCallback = null;
+    /**
+     * Queries the server to update the `isOwned` state.
+     * Call this to check if anyone currently has ownership.
+     */
     updateIsOwned() {
         this.connection.send(OwnershipEvent.RequestHasOwner, { guid: this.guid });
     }
@@ -111,6 +183,11 @@ export class OwnershipModel {
             this._isOwned = res.value;
         }
     }
+    /**
+     * Requests ownership only if the object is not currently owned by anyone.
+     * Internally checks ownership state first, then requests ownership if free.
+     * @returns this OwnershipModel instance for method chaining
+     */
     requestOwnershipIfNotOwned() {
         if (this._isWaitingForOwnershipResponseCallback !== null)
             return this;
@@ -134,6 +211,20 @@ export class OwnershipModel {
             }
         }
     }
+    /**
+     * Requests ownership and waits asynchronously until ownership is granted or timeout occurs.
+     * @returns Promise that resolves with this OwnershipModel when ownership is gained
+     * @throws Rejects with "Timeout" if ownership is not gained within ~1 second
+     * @example
+     * ```ts
+     * try {
+     *   await ownership.requestOwnershipAsync();
+     *   // Ownership granted, safe to modify object
+     * } catch(e) {
+     *   console.warn("Could not gain ownership:", e);
+     * }
+     * ```
+     */
     requestOwnershipAsync() {
         return new Promise((resolve, reject) => {
             this.requestOwnership();
@@ -151,12 +242,22 @@ export class OwnershipModel {
             waitForOwnership();
         });
     }
+    /**
+     * Requests ownership of this object from the networking server.
+     * Ownership may not be granted immediately - check `hasOwnership` property or use `requestOwnershipAsync()`.
+     * @returns this OwnershipModel instance for method chaining
+     */
     requestOwnership() {
         if (debugOwner)
             console.log("Request ownership", this.guid);
         this.connection.send(OwnershipEvent.RequestOwnership, { guid: this.guid });
         return this;
     }
+    /**
+     * Releases ownership of this object, allowing others to take control.
+     * Call this when you're done modifying an object to allow other users to interact with it.
+     * @returns this OwnershipModel instance for method chaining
+     */
     freeOwnership() {
         // TODO: abort "requestOwnershipIfNotOwned"
         this.connection.send(OwnershipEvent.RemoveOwnership, { guid: this.guid });
@@ -166,6 +267,10 @@ export class OwnershipModel {
         }
         return this;
     }
+    /**
+     * Cleans up event listeners and resources.
+     * Call this when the OwnershipModel is no longer needed (e.g., in `onDestroy()`).
+     */
     destroy() {
         this.connection.stopListen(OwnershipEvent.GainedOwnership, this._gainSubscription);
         this.connection.stopListen(OwnershipEvent.LostOwnership, this._lostSubscription);
@@ -197,10 +302,46 @@ export class OwnershipModel {
         }
     }
 }
-/** Main class to communicate with the networking backend
- * @link https://engine.needle.tools/docs/networking.html
+/**
+ * Main class for multiuser networking. Access via `this.context.connection` from any component.
+ *
+ * **About GUIDs:**
+ * In Needle Engine networking, GUIDs (Globally Unique Identifiers) are used to identify objects and components across the network.
+ * Every GameObject and Component has a unique `guid` property that remains consistent across all clients.
+ * GUIDs are automatically assigned (e.g. during export from Unity/Blender) and are essential for:
+ * - Object ownership management (see {@link OwnershipModel})
+ * - State synchronization (storing and retrieving object state)
+ * - Identifying which object received a network message
+ *
+ * When working with networking, you'll typically use `this.guid` to identify your component or `this.gameObject.guid` for the GameObject.
  *
-*/
+ * @example Joining a room
+ * ```ts
+ * this.context.connection.connect();
+ * this.context.connection.joinRoom("my-room");
+ * ```
+ * @example Listening to events
+ * ```ts
+ * this.context.connection.beginListen("my-event", (data) => {
+ *   console.log("Received:", data);
+ * });
+ * ```
+ * @example Sending data
+ * ```ts
+ * this.context.connection.send("my-event", { message: "Hello" });
+ * ```
+ * @example Using GUIDs for object identification
+ * ```ts
+ * // Get state for a specific object by its GUID
+ * const state = this.context.connection.tryGetState(this.guid);
+ *
+ * // Delete remote state for an object
+ * this.context.connection.sendDeleteRemoteState(this.guid);
+ * ```
+ * @see {@link RoomEvents} for room lifecycle events
+ * @see {@link OwnershipModel} for object ownership
+ * @link https://engine.needle.tools/docs/how-to-guides/networking/
+ */
 export class NetworkConnection {
     context;
     _peer = null;
@@ -215,7 +356,18 @@ export class NetworkConnection {
         return this._peer;
     }
     /**
-     * Returns the state of a given guid.
+     * Returns the cached network state for a given GUID.
+     * The state is stored locally whenever network updates are received for that object.
+     * @param guid The unique identifier of the object whose state you want to retrieve
+     * @returns The cached state object, or `null` if no state exists for this GUID
+     * @example
+     * ```ts
+     * // Get the last known state for this component
+     * const myState = this.context.connection.tryGetState(this.guid);
+     * if (myState) {
+     *   console.log("Found cached state:", myState);
+     * }
+     * ```
      */
     tryGetState(guid) {
         if (guid === "invalid")
@@ -233,7 +385,7 @@ export class NetworkConnection {
         return debugNet;
     }
     /**
-     * Checks if Needle Engine networking is connected to a websocket. Note that this is **not equal** to being connected to a *room*. If you want to check if Needle Engine is connected to a networking room use the `isInRoom` property.
+     * Checks if Needle Engine networking is connected to a websocket. Note that this is **not equal** to being connected to a *room*. If you want to check if Needle Engine is connected to a networking room use the `{@link isInRoom}` property.
      * @returns true if connected to the websocket.
      */
     get isConnected() {
@@ -292,7 +444,7 @@ export class NetworkConnection {
             target.push(user);
         return target;
     }
-    /** Joins a networked room. If you don't want to manage a connection yourself you can use a `SyncedRoom` component as well */
+    /** Joins a networked room. If you don't want to manage a connection yourself you can use a `{@link SyncedRoom}` component as well */
     joinRoom(room, viewOnly = false) {
         if (!room) {
             console.error("Missing room name, can not join: \"" + room + "\"");
@@ -340,7 +492,18 @@ export class NetworkConnection {
         // this.sendGeckosIo(key, data);
         return this.sendWithWebsocket(key, data, queue);
     }
-    /** Use to delete state for a given guid on the server */
+    /**
+     * 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.
+     * @param guid The unique identifier of the object whose state should be deleted
+     * @example
+     * ```ts
+     * // When destroying a networked object, clean up its server state
+     * onDestroy() {
+     *   this.context.connection.sendDeleteRemoteState(this.guid);
+     * }
+     * ```
+     */
     sendDeleteRemoteState(guid) {
         this.send("delete-state", { guid: guid, dontSave: true });
         delete this._state[guid];
@@ -382,7 +545,7 @@ export class NetworkConnection {
         this._ws?.send(message);
     }
     /** Use to start listening to networking events.
-     * To unsubscribe from events use the `stopListen` method.
+     * To unsubscribe from events use the `{@link stopListen}` method.
      * See the example below for typical usage:
      *
      * ### Component Example
@@ -412,7 +575,7 @@ export class NetworkConnection {
     /**@deprecated please use stopListen instead (2.65.2-pre) */
     stopListening(key, callback) { return this.stopListen(key, callback); }
     /** Use to stop listening to networking events
-     * To subscribe to events use the `beginListen` method.
+     * To subscribe to events use the `{@link beginListen}` method.
      * See the example below for typical usage:
      *
      * ### Component Example
@@ -458,11 +621,15 @@ export class NetworkConnection {
         }
     }
     netWebSocketUrlProvider;
-    /** Use to override the networking server backend url. This is what the `Networking` component uses to modify the backend url */
+    /** Use to override the networking server backend url.
+     * This is what the `{@link Networking}` component uses to modify the backend url.
+     **/
     registerProvider(prov) {
         this.netWebSocketUrlProvider = prov;
     }
-    /** Used to connect to the networking server */
+    /** 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.
+    */
     async connect(url) {
         if (this.connected && url && url !== networkingServerUrl) {
             return Promise.reject("Can not connect to different server url. Please disconnect first.");