@needle-tools/engine 4.3.0-alpha → 4.3.0-alpha.3

package/src/engine-components-experimental/networking/PlayerSync.ts

@@ -12,6 +12,7 @@ import { EventList } from "../../engine-components/EventList.js";
 
 const debug = getParam("debugplayersync");
 
+/** Type definition for a PlayerSync instance with a guaranteed asset property */
 declare type PlayerSyncWithAsset = PlayerSync & Required<Pick<PlayerSync, "asset">>;
 
 /**
@@ -23,7 +24,10 @@ export class PlayerSync extends Behaviour {
 
     /**
      * This API is experimental and may change or be removed in the future.
-     * Create a PlayerSync instance at runtime from a given URL
+     * Creates a PlayerSync instance at runtime from a given URL and sets it up for networking
+     * @param url Path to the asset that should be instantiated for each player
+     * @param init Optional initialization parameters for the PlayerSync component
+     * @returns Promise resolving to a PlayerSync instance with a guaranteed asset property
      * @example
      * ```typescript
      * const res = await PlayerSync.setupFrom("/assets/demo.glb");
@@ -47,15 +51,22 @@ export class PlayerSync extends Behaviour {
         return ps as PlayerSyncWithAsset;
     }
 
-    /** when enabled PlayerSync will automatically load and instantiate the assigned asset when joining a networked room */
+    /** 
+     * When enabled, PlayerSync will automatically load and instantiate the assigned asset when joining a networked room
+     */
     @serializable()
     autoSync: boolean = true;
 
-    /** This asset will be loaded and instantiated when PlayerSync becomes active and joins a networked room */
+    /** 
+     * The asset that will be loaded and instantiated when PlayerSync becomes active and joins a networked room
+     */
     @serializable(AssetReference)
     asset?: AssetReference;
 
-    /** Event called when an instance is spawned */
+    /** 
+     * Event invoked when a player instance is spawned with the spawned {@link Object3D} as parameter
+     * @serializable
+     */
     @serializable(EventList)
     onPlayerSpawned?: EventList<Object3D>;
 
@@ -86,6 +97,10 @@ export class PlayerSync extends Behaviour {
         if (this.autoSync) this.getInstance();
     }
 
+    /**
+     * Gets or creates an instance of the assigned asset for the local player
+     * @returns Promise resolving to the instantiated player object or null if creation failed
+     */
     async getInstance() {
         if (this._localInstance) return this._localInstance;
 
@@ -123,6 +138,9 @@ export class PlayerSync extends Behaviour {
         return this._localInstance;
     }
 
+    /**
+     * Destroys the current player instance and cleans up networking state
+     */
     destroyInstance = () => {
         this._localInstance?.then(go => {
             if (debug) console.log("PlayerSync.destroyInstance", go);
@@ -131,8 +149,9 @@ export class PlayerSync extends Behaviour {
         this._localInstance = undefined;
     }
 
-
-
+    /**
+     * Sets up visibility change listeners to handle player cleanup when browser tab visibility changes
+     */
     private watchTabVisible() {
         window.addEventListener("visibilitychange", _ => {
             if (document.visibilityState === "visible") {
@@ -147,32 +166,50 @@ export class PlayerSync extends Behaviour {
     }
 }
 
+/**
+ * Enum defining events that can be triggered by PlayerState
+ */
 export enum PlayerStateEvent {
+    /** Triggered when a PlayerState's owner property changes */
     OwnerChanged = "ownerChanged",
 }
 
+/** Arguments passed when a PlayerState's owner changes */
 export declare interface PlayerStateOwnerChangedArgs {
+    /** The PlayerState instance that changed */
     playerState: PlayerState;
+    /** Previous owner's connection ID */
     oldValue: string;
+    /** New owner's connection ID */
     newValue: string;
 }
 
+/** Callback type for PlayerState events */
 export declare type PlayerStateEventCallback = (args: CustomEvent<PlayerStateOwnerChangedArgs>) => void;
 
+/**
+ * Represents a player instance in the networked environment.
+ * Handles ownership, synchronization, and lifecycle management of player objects.
+ */
 export class PlayerState extends Behaviour {
 
     private static _all: PlayerState[] = [];
-    /** all instances for all players */
+    /** All PlayerState instances for all players in the scene */
     static get all(): PlayerState[] {
         return PlayerState._all;
     };
 
     private static _local: PlayerState[] = [];
-    /** all instances for the local player */
+    /** All PlayerState instances that belong to the local player */
     static get local(): PlayerState[] {
         return PlayerState._local;
     }
 
+    /**
+     * Gets the PlayerState component for a given object or component
+     * @param obj Object3D or Component to find the PlayerState for
+     * @returns The PlayerState component if found, undefined otherwise
+     */
     static getFor(obj: Object3D | Component) {
         if (obj instanceof Object3D) {
             return GameObject.getComponentInParent(obj, PlayerState);
@@ -183,22 +220,34 @@ export class PlayerState extends Behaviour {
         return undefined;
     }
 
-    //** use to check if a component or gameobject is part of a instance owned by the local player */
+    /**
+     * Checks if a given object or component belongs to the local player
+     * @param obj Object3D or Component to check
+     * @returns True if the object belongs to the local player, false otherwise
+     */
     static isLocalPlayer(obj: Object3D | Component): boolean {
         const state = PlayerState.getFor(obj);
         return state?.isLocalPlayer ?? false;
     }
 
-    // static Callback
     private static _callbacks: { [key: string]: PlayerStateEventCallback[] } = {};
     /**
-     * Add a callback for a PlayerStateEvent
+     * Registers a callback for a specific PlayerState event
+     * @param event The event to listen for
+     * @param cb Callback function that will be invoked when the event occurs
+     * @returns The provided callback function for chaining
      */
     static addEventListener(event: PlayerStateEvent, cb: PlayerStateEventCallback) {
         if (!this._callbacks[event]) this._callbacks[event] = [];
         this._callbacks[event].push(cb);
         return cb;
     }
+
+    /**
+     * Removes a previously registered event callback
+     * @param event The event type to remove the callback from
+     * @param cb The callback function to remove
+     */
     static removeEventListener(event: PlayerStateEvent, cb: PlayerStateEventCallback) {
         if (!this._callbacks[event]) return;
         const index = this._callbacks[event].indexOf(cb);
@@ -212,20 +261,39 @@ export class PlayerState extends Behaviour {
     }
 
 
+    /** Event triggered when the owner of this PlayerState changes */
     public onOwnerChangeEvent = new EventList();
+    
+    /** Event triggered the first time an owner is assigned to this PlayerState */
     public onFirstOwnerChangeEvent = new EventList();
+    
+    /** Indicates if this PlayerState has an owner assigned */
     public hasOwner = false;
 
+    /**
+     * The connection ID of the player who owns this PlayerState instance
+     * @syncField Synchronized across the network
+     */
     @syncField(PlayerState.prototype.onOwnerChange)
     owner?: string;
 
-    /** when enabled PlayerSync will not destroy itself when not connected anymore */
+    /** 
+     * When enabled, PlayerState will not destroy itself when the owner is not connected anymore 
+     */
     dontDestroy: boolean = false;
 
+    /**
+     * Indicates if this PlayerState belongs to the local player
+     */
     get isLocalPlayer(): boolean {
         return this.owner === this.context.connection.connectionId;
     }
 
+    /**
+     * Handles owner change events and updates relevant state
+     * @param newOwner The new owner's connection ID
+     * @param oldOwner The previous owner's connection ID
+     */
     private onOwnerChange(newOwner: string, oldOwner: string) {
         if (debug) console.log(`PlayerSync.onOwnerChange: ${oldOwner} → ${newOwner} (me: ${this.context.connection.connectionId})`);
 
@@ -300,7 +368,7 @@ export class PlayerState extends Behaviour {
         }
     }
 
-    /** this tells the server that this client has been destroyed and the networking message for the instantiate will be removed */
+    /** Tells the server that this client has been destroyed, and the networking message for the instantiate will be removed      */
     doDestroy() {
         if (debug) console.log("PlayerSync.doDestroy → syncDestroy", this.name);
         syncDestroy(this.gameObject, this.context.connection, true, { saveInRoom: false });
@@ -319,6 +387,10 @@ export class PlayerState extends Behaviour {
         }
     }
 
+    /**
+     * Handler for when a user leaves the networked room
+     * @param model Object containing the ID of the user who left
+     */
     private onUserLeftRoom = (model: { userId: string }) => {
         if (model.userId === this.owner) {
             if (debug)