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

package/src/engine-components/SpectatorCamera.ts

@@ -17,50 +17,77 @@ import { AvatarMarker } from "./webxr/WebXRAvatar.js";
 import { XRStateFlag } from "./webxr/XRFlag.js";
 
 
+/**
+ * Defines the viewing perspective in spectator mode
+ */
 export enum SpectatorMode {
+    /** View from the perspective of the followed player */
     FirstPerson = 0,
+    /** Freely view from a third-person perspective */
     ThirdPerson = 1,
 }
 
 const debug = getParam("debugspectator");
 
 /**
+ * Provides functionality to follow and spectate other users in a networked environment.
+ * Handles camera switching, following behavior, and network synchronization for spectator mode.
+ * 
+ * Debug mode can be enabled with the URL parameter `?debugspectator`, which provides additional console output.
+ * 
  * @category Networking
  * @group Components
  */
 export class SpectatorCamera extends Behaviour {
 
+    /** Reference to the Camera component on this GameObject */
     cam: Camera | null = null;
 
-    /** when enabled pressing F will send a request to all connected users to follow me, ESC to stop */
+    /** 
+     * When enabled, pressing F will send a request to all connected users to follow the local player.
+     * Pressing ESC will stop spectating.
+     */
     @serializable()
     useKeys: boolean = true;
 
     private _mode: SpectatorMode = SpectatorMode.FirstPerson;
 
+    /** Gets the current spectator perspective mode */
     get mode() { return this._mode; }
+    /** Sets the current spectator perspective mode */
     set mode(val: SpectatorMode) {
         this._mode = val;
     }
 
-    /** if this user is currently spectating someone else */
+    /** Returns whether this user is currently spectating another user */
     get isSpectating(): boolean {
         return this._handler?.currentTarget !== undefined;
     }
 
+    /**
+     * Checks if this instance is spectating the user with the given ID
+     * @param userId The user ID to check
+     * @returns True if spectating the specified user, false otherwise
+     */
     isSpectatingUser(userId: string): boolean {
         return this.target?.userId === userId;
     }
 
+    /**
+     * Checks if the user with the specified ID is following this user
+     * @param userId The user ID to check
+     * @returns True if the specified user is following this user, false otherwise
+     */
     isFollowedBy(userId: string): boolean {
         return this.followers?.includes(userId);
     }
 
-    /** list of other users that are following me */
+    /** List of user IDs that are currently following the user */
     get followers(): string[] {
         return this._networking.followers;
     }
 
+    /** Stops the current spectating session */
     stopSpectating() {
         if (this.context.isInXR) {
             this.followSelf();
@@ -69,11 +96,15 @@ export class SpectatorCamera extends Behaviour {
         this.target = undefined;
     }
 
+    /** Gets the local player's connection ID */
     private get localId() : string {
         return this.context.connection.connectionId ?? "local";
     }
 
-    /** player view to follow */
+    /** 
+     * Sets the player view to follow
+     * @param target The PlayerView to follow, or undefined to stop spectating
+     */
     set target(target: PlayerView | undefined) {
         if (this._handler) {
 
@@ -106,14 +137,17 @@ export class SpectatorCamera extends Behaviour {
         }
     }
 
+    /** Gets the currently followed player view */
     get target(): PlayerView | undefined {
         return this._handler?.currentTarget;
     }
 
+    /** Sends a network request for all users to follow this player */
     requestAllFollowMe() {
         this._networking.onRequestFollowMe();
     }
 
+    /** Determines if the camera is spectating the local player */
     private get isSpectatingSelf() {
         return this.isSpectating && this.target?.currentObject === this.context.players.getPlayerView(this.localId)?.currentObject;
     }
@@ -131,7 +165,6 @@ export class SpectatorCamera extends Behaviour {
     private _networking!: SpectatorCamNetworking;
 
     awake(): void {
-
         this._debug = new SpectatorSelectionController(this.context, this);
         this._networking = new SpectatorCamNetworking(this.context, this);
         this._networking.awake();
@@ -144,7 +177,6 @@ export class SpectatorCamera extends Behaviour {
             return;
         }
 
-
         if (!this._handler && this.cam)
             this._handler = new SpectatorHandler(this.context, this.cam, this);
 
@@ -157,6 +189,10 @@ export class SpectatorCamera extends Behaviour {
         this._networking?.destroy();
     }
 
+    /**
+     * Checks if the current platform supports spectator mode
+     * @returns True if the platform is supported, false otherwise
+     */
     private isSupportedPlatform() {
         const ua = window.navigator.userAgent;
         const standalone = /Windows|MacOS/.test(ua);
@@ -164,12 +200,19 @@ export class SpectatorCamera extends Behaviour {
         return standalone && !isHololens;
     }
 
+    /**
+     * Called before entering WebXR mode
+     * @param _evt The WebXR event
+     */
     onBeforeXR(_evt) {
         if (!this.isSupportedPlatform()) return;
         GameObject.setActive(this.gameObject, true);
     }
 
-
+    /**
+     * Called when entering WebXR mode
+     * @param _evt The WebXR event
+     */
     onEnterXR(_evt) {
         if (!this.isSupportedPlatform()) return;
         if (debug) console.log(this.context.mainCamera);
@@ -178,6 +221,10 @@ export class SpectatorCamera extends Behaviour {
         }
     }
 
+    /**
+     * Called when exiting WebXR mode
+     * @param _evt The WebXR event
+     */
     onLeaveXR(_evt) {
         this.context.removeCamera(this.cam as ICamera);
         GameObject.setActive(this.gameObject, false);
@@ -188,7 +235,9 @@ export class SpectatorCamera extends Behaviour {
             this.stopSpectating();
     }
 
-
+    /**
+     * Sets the target to follow the local player
+     */
     private followSelf() {
         this.target = this.context.players.getPlayerView(this.context.connection.connectionId);
         if (!this.target) {
@@ -201,6 +250,9 @@ export class SpectatorCamera extends Behaviour {
     // TODO: only show Spectator cam for DesktopVR;
     // don't show for AR, don't show on Quest
     // TODO: properly align cameras on enter/exit VR, seems currently spectator cam breaks alignment
+    /**
+     * Called after the main rendering pass to render the spectator view
+     */
     onAfterRender(): void {
         if (!this.cam) return;
 
@@ -278,6 +330,9 @@ export class SpectatorCamera extends Behaviour {
         this.resetAvatarFlags();
     }
 
+    /**
+     * Updates avatar visibility flags for rendering in spectator mode
+     */
     private setAvatarFlagsBeforeRender() {
         const isFirstPersonMode = this._mode === SpectatorMode.FirstPerson;
 
@@ -295,6 +350,9 @@ export class SpectatorCamera extends Behaviour {
         }
     }
 
+    /**
+     * Restores avatar visibility flags after spectator rendering
+     */
     private resetAvatarFlags() {
         for (const av of AvatarMarker.instances) {
             if (av.avatar && "flags" in av.avatar) {
@@ -313,6 +371,9 @@ export class SpectatorCamera extends Behaviour {
     }
 }
 
+/**
+ * Interface for handling spectator camera behavior
+ */
 interface ISpectatorHandler {
     context: Context;
     get currentTarget(): PlayerView | undefined;
@@ -322,6 +383,9 @@ interface ISpectatorHandler {
     destroy();
 }
 
+/**
+ * Handles the smooth following behavior for the spectator camera
+ */
 class SpectatorHandler implements ISpectatorHandler {
 
     readonly context: Context;
@@ -333,6 +397,7 @@ class SpectatorHandler implements ISpectatorHandler {
     private view?: PlayerView;
     private currentObject: Object3D | undefined;
 
+    /** Gets the currently targeted player view */
     get currentTarget(): PlayerView | undefined {
         return this.view;
     }
@@ -343,6 +408,10 @@ class SpectatorHandler implements ISpectatorHandler {
         this.spectator = spectator;
     }
 
+    /**
+     * Sets the target player view to follow
+     * @param view The PlayerView to follow
+     */
     set(view?: PlayerView): void {
         const followObject = view?.currentObject;
         if (!followObject) {
@@ -368,6 +437,7 @@ class SpectatorHandler implements ISpectatorHandler {
         else this.context.removeCamera(this.cam as ICamera);
     }
 
+    /** Disables the spectator following behavior */
     disable() {
         if (debug) console.log("STOP FOLLOW", this.currentObject);
         this.view = undefined;
@@ -377,12 +447,17 @@ class SpectatorHandler implements ISpectatorHandler {
             this.follow.enabled = false;
     }
 
+    /** Cleans up resources used by the handler */
     destroy() {
         this.target?.removeFromParent();
         if (this.follow)
             GameObject.destroy(this.follow);
     }
 
+    /**
+     * Updates the camera position and orientation based on the spectator mode
+     * @param mode The current spectator mode (first or third person)
+     */
     update(mode: SpectatorMode) {
         if (this.currentTarget?.isConnected === false || this.currentTarget?.removed === true) {
             if (debug) console.log("Target disconnected or timeout", this.currentTarget);
@@ -431,13 +506,13 @@ class SpectatorHandler implements ISpectatorHandler {
             target.quaternion.copy(_inverseYQuat);
         else target.quaternion.identity();
     }
-
-
 }
 
 const _inverseYQuat = new Quaternion().setFromAxisAngle(new Vector3(0, 1, 0), Math.PI);
 
-
+/**
+ * Handles user input for selecting targets to spectate
+ */
 class SpectatorSelectionController {
 
     private readonly context: Context;
@@ -468,6 +543,9 @@ class SpectatorSelectionController {
         });
     }
 
+    /**
+     * Attempts to select an avatar to spectate through raycasting
+     */
     private trySelectObject() {
         const opts = new RaycastOptions();
         opts.setMask(0xffffff);
@@ -491,17 +569,17 @@ class SpectatorSelectionController {
     }
 }
 
-
-
-
-
+/**
+ * Network model for communicating follower changes
+ */
 class SpectatorFollowerChangedEventModel implements IModel {
-    /** the user that is following */
+    /** The user ID that is following */
     guid: string;
     readonly dontSave: boolean = true;
 
-    /** the user being followed */
+    /** The user ID being followed */
     targetUserId: string | undefined;
+    /** Indicates if the user stopped following */
     stoppedFollowing: boolean;
 
     constructor(connectionId: string, userId: string | undefined, stoppedFollowing: boolean) {
@@ -511,6 +589,9 @@ class SpectatorFollowerChangedEventModel implements IModel {
     }
 }
 
+/**
+ * Network model for requesting users to follow a specific player
+ */
 class SpectatorFollowEventModel implements IModel {
     guid: string;
     userId: string | undefined;
@@ -521,11 +602,14 @@ class SpectatorFollowEventModel implements IModel {
     }
 }
 
+/**
+ * Handles network communication for spectator functionality
+ */
 class SpectatorCamNetworking {
 
+    /** List of user IDs currently following this player */
     readonly followers: string[] = [];
 
-
     private readonly context: Context;
     private readonly spectator: SpectatorCamera;
     private _followerEventMethod: Function;
@@ -540,6 +624,9 @@ class SpectatorCamNetworking {
         this._joinedRoomMethod = this.onUserJoinedRoom.bind(this);
     }
 
+    /**
+     * Initializes network event listeners
+     */
     awake() {
         this.context.connection.beginListen("spectator-follower-changed", this._followerEventMethod);
         this.context.connection.beginListen("spectator-request-follow", this._requestFollowMethod);
@@ -555,12 +642,20 @@ class SpectatorCamNetworking {
         });
     }
 
+    /**
+     * Removes network event listeners
+     */
     destroy() {
         this.context.connection.stopListen("spectator-follower-changed", this._followerEventMethod);
         this.context.connection.stopListen("spectator-request-follow", this._requestFollowMethod);
         this.context.connection.stopListen(RoomEvents.JoinedRoom, this._joinedRoomMethod);
     }
 
+    /**
+     * Notifies other users about spectating target changes
+     * @param target The new target being spectated
+     * @param _prevId The previous target's user ID
+     */
     onSpectatedObjectChanged(target: PlayerView | undefined, _prevId?: string) {
         if (debug)
             console.log(this.context.connection.connectionId, "onSpectatedObjectChanged", target, _prevId);
@@ -572,6 +667,10 @@ class SpectatorCamNetworking {
         }
     }
 
+    /**
+     * Requests other users to follow this player or stop following
+     * @param stop Whether to request users to stop following
+     */
     onRequestFollowMe(stop: boolean = false) {
         if (debug)
             console.log("Request follow", this.context.connection.connectionId);
@@ -583,12 +682,19 @@ class SpectatorCamNetworking {
         }
     }
 
+    /**
+     * Handles room join events
+     */
     private onUserJoinedRoom() {
         if (getParam("followme")) {
             this.onRequestFollowMe();
         }
     }
 
+    /**
+     * Processes follower status change events from the network
+     * @param evt The follower change event data
+     */
     private onFollowerEvent(evt: SpectatorFollowerChangedEventModel) {
         const userBeingFollowed = evt.targetUserId;
         const userThatIsFollowing = evt.guid;
@@ -615,6 +721,9 @@ class SpectatorCamNetworking {
         }
     }
 
+    /**
+     * Removes followers that are no longer connected to the room
+     */
     private removeDisconnectedFollowers() {
         for (let i = this.followers.length - 1; i >= 0; i--) {
             const id = this.followers[i];
@@ -626,6 +735,11 @@ class SpectatorCamNetworking {
 
     private _lastRequestFollowUser: SpectatorFollowEventModel | undefined;
 
+    /**
+     * Handles follow requests from other users
+     * @param evt The follow request event
+     * @returns True if the request was handled successfully
+     */
     private onRequestFollowEvent(evt: SpectatorFollowEventModel) {
         this._lastRequestFollowUser = evt;
 
@@ -652,6 +766,10 @@ class SpectatorCamNetworking {
     }
 
     private _enforceFollowInterval: any;
+    
+    /**
+     * Periodically retries following a user if the initial attempt failed
+     */
     private enforceFollow() {
         if (this._enforceFollowInterval) return;
         this._enforceFollowInterval = setInterval(() => {

package/src/engine-components/SyncedTransform.ts

@@ -19,7 +19,12 @@ registerBinaryType(SyncedTransformIdentifier, SyncedTransformModel.getRootAsSync
 
 const builder = new flatbuffers.Builder();
 
-/** Creates a flatbuffer model containing the transform data of a game object. Used by {@link SyncedTransform}
+/** 
+ * Creates a flatbuffer model containing the transform data of a game object. Used by {@link SyncedTransform}
+ * @param guid The unique identifier of the object to sync
+ * @param b The behavior component containing transform data
+ * @param fast Whether to use fast mode synchronization (syncs more frequently)
+ * @returns A Uint8Array containing the serialized transform data
  */
 export function createTransformModel(guid: string, b: Behaviour, fast: boolean = true): Uint8Array {
     builder.clear();
@@ -50,18 +55,28 @@ onUpdate((ctx) => {
 })
 
 /**
- * SyncedTransform is a behaviour that syncs the transform of a game object over the network.
+ * SyncedTransform synchronizes the position and rotation of a game object over the network.
+ * It handles ownership transfer, interpolation, and network state updates automatically.
  * @category Networking
  * @group Components
  */
 export class SyncedTransform extends Behaviour {
 
-
+    
     // public autoOwnership: boolean = true;
+    /** When true, overrides physics behavior when this object is owned by the local user */
     public overridePhysics: boolean = true
+    
+    /** Whether to smoothly interpolate position changes when receiving updates */
     public interpolatePosition: boolean = true;
+    
+    /** Whether to smoothly interpolate rotation changes when receiving updates */
     public interpolateRotation: boolean = true;
+    
+    /** When true, sends updates at a higher frequency, useful for fast-moving objects */
     public fastMode: boolean = false;
+    
+    /** When true, notifies other clients when this object is destroyed */
     public syncDestroy: boolean = false;
 
     // private _state!: SyncedTransformModel;
@@ -77,7 +92,10 @@ export class SyncedTransform extends Behaviour {
     private _receivedFastUpdate: boolean = false;
     private _shouldRequestOwnership: boolean = false;
 
-    /** Request ownership of an object - you need to be connected to a room */
+    /** 
+     * Requests ownership of this object on the network.
+     * You need to be connected to a room for this to work.
+     */
     public requestOwnership() {
         if (debug)
             console.log("Request ownership");
@@ -89,10 +107,18 @@ export class SyncedTransform extends Behaviour {
             this._model.requestOwnership();
     }
 
+    /**
+     * Checks if this client has ownership of the object
+     * @returns true if this client has ownership, false if not, undefined if ownership state is unknown
+     */
     public hasOwnership(): boolean | undefined {
         return this._model?.hasOwnership ?? undefined;
     }
 
+    /**
+     * Checks if the object is owned by any client
+     * @returns true if the object is owned, false if not, undefined if ownership state is unknown
+     */
     public isOwned(): boolean | undefined {
         return this._model?.isOwned;
     }
@@ -140,6 +166,9 @@ export class SyncedTransform extends Behaviour {
         this.context.connection.stopListenBinary(SyncedTransformIdentifier, this.receivedDataCallback);
     }
 
+    /**
+     * Attempts to retrieve and apply the last known network state for this transform
+     */
     private tryGetLastState() {
         const model = this.context.connection.tryGetState(this.guid) as unknown as SyncedTransformModel;
         if (model) this.onReceivedData(model);
@@ -147,6 +176,10 @@ export class SyncedTransform extends Behaviour {
 
     private tempEuler: Euler = new Euler();
 
+    /**
+     * Handles incoming network data for this transform
+     * @param data The model containing transform information
+     */
     private onReceivedData(data: SyncedTransformModel) {
         if (this.destroyed) return;
         if (typeof data.guid === "function" && data.guid() === this.guid) {
@@ -183,7 +216,10 @@ export class SyncedTransform extends Behaviour {
         }
     }
 
-    /** @internal */
+    /** 
+     * @internal 
+     * Initializes tracking of position and rotation when component is enabled
+     */
     onEnable(): void {
         this.lastWorldPos.copy(this.worldPosition);
         this.lastWorldRotation.copy(this.worldQuaternion);
@@ -194,7 +230,10 @@ export class SyncedTransform extends Behaviour {
         }
     }
 
-    /** @internal */
+    /** 
+     * @internal 
+     * Releases ownership when component is disabled
+     */
     onDisable(): void {
         if (this._model)
             this._model.freeOwnership();
@@ -205,7 +244,11 @@ export class SyncedTransform extends Behaviour {
     private lastWorldPos!: Vector3;
     private lastWorldRotation!: Quaternion;
 
-    /** @internal */
+    /** 
+     * @internal 
+     * Handles transform synchronization before each render frame
+     * Sends updates when owner, receives and applies updates when not owner
+     */
     onBeforeRender() {
         if (!this.activeAndEnabled || !this.context.connection.isConnected) return;
         // console.log("BEFORE RENDER", this.destroyed, this.guid, this._model?.isOwned, this.name, this.gameObject);

package/src/engine-components/TransformGizmo.ts

@@ -8,27 +8,43 @@ import { OrbitControls } from "./OrbitControls.js";
 import { SyncedTransform } from "./SyncedTransform.js";
 
 /**
- * TransformGizmo is a component that displays a gizmo for transforming the object in the scene.
+ * TransformGizmo displays manipulation controls for translating, rotating, and scaling objects in the scene.
+ * It wraps three.js {@link TransformControls} and provides keyboard shortcuts for changing modes and settings.
  * @category Helpers
  * @group Components
  */
 export class TransformGizmo extends Behaviour {
 
+    /**
+     * When true, this is considered a helper gizmo and will only be shown if showGizmos is enabled in engine parameters.
+     */
     @serializable()
     public isGizmo: boolean = false;
 
+    /**
+     * Specifies the translation grid snap value in world units.
+     * Applied when holding Shift while translating an object.
+     */
     @serializable()
     public translationSnap: number = 1;
 
+    /**
+     * Specifies the rotation snap angle in degrees.
+     * Applied when holding Shift while rotating an object.
+     */
     @serializable()
     public rotationSnapAngle: number = 15;
 
+    /**
+     * Specifies the scale snapping value.
+     * Applied when holding Shift while scaling an object.
+     */
     @serializable()
     public scaleSnap: number = .25;
 
     /**
-     * Get the underlying three.js TransformControls instance.
-     * @returns The TransformControls instance.
+     * Gets the underlying three.js {@link TransformControls} instance.
+     * @returns The TransformControls instance or undefined if not initialized.
      */
     get control() {
         return this._control;
@@ -81,6 +97,10 @@ export class TransformGizmo extends Behaviour {
         window.removeEventListener('keyup', this.windowKeyUpListener);
     }
 
+    /**
+     * Enables grid snapping for transform operations according to set snap values.
+     * This applies the translationSnap, rotationSnapAngle, and scaleSnap properties to the controls.
+     */
     enableSnapping() {
         if (this._control) {
             this._control.setTranslationSnap(this.translationSnap);
@@ -89,6 +109,10 @@ export class TransformGizmo extends Behaviour {
         }
     }
 
+    /**
+     * Disables grid snapping for transform operations.
+     * Removes all snapping constraints from the transform controls.
+     */
     disableSnapping() {
         if (this._control) {
             this._control.setTranslationSnap(null);
@@ -97,6 +121,11 @@ export class TransformGizmo extends Behaviour {
         }
     }
 
+    /**
+     * Event handler for when dragging state changes.
+     * Disables orbit controls during dragging and requests ownership of the transform if it's synchronized.
+     * @param event The drag change event
+     */
     private onControlChangedEvent = (event) => {
         const orbit = this.orbit;
         if (orbit) orbit.enabled = !event.value;
@@ -109,7 +138,18 @@ export class TransformGizmo extends Behaviour {
         }
     }
 
-
+    /**
+     * Handles keyboard shortcuts for transform operations:
+     * - Q: Toggle local/world space
+     * - W: Translation mode
+     * - E: Rotation mode
+     * - R: Scale mode
+     * - Shift: Enable snapping (while held)
+     * - +/-: Adjust gizmo size
+     * - X/Y/Z: Toggle visibility of respective axis
+     * - Spacebar: Toggle controls enabled state
+     * @param event The keyboard event
+     */
     private windowKeyDownListener = (event) => {
         if (!this.enabled) return;
         if (!this._control) return;
@@ -162,6 +202,11 @@ export class TransformGizmo extends Behaviour {
         }
     }
 
+    /**
+     * Handles keyboard key release events.
+     * Currently only handles releasing Shift key to disable snapping.
+     * @param event The keyboard event
+     */
     private windowKeyUpListener = (event) => {
         if (!this.enabled) return;
         switch (event.keyCode) {