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

package/src/engine-components/Camera.ts

@@ -13,8 +13,11 @@ import { RGBAColor } from "../engine/js-extensions/index.js";
 import { Behaviour, GameObject } from "./Component.js";
 import { OrbitControls } from "./OrbitControls.js";
 
-/**  The ClearFlags enum is used to determine how the camera clears the background */
+/**  
+ * The ClearFlags enum is used to determine how the camera clears the background 
+ */
 export enum ClearFlags {
+    /** Don't clear the background */
     None = 0,
     /** Clear the background with a skybox */
     Skybox = 1,
@@ -28,16 +31,28 @@ const debug = getParam("debugcam");
 const debugscreenpointtoray = getParam("debugscreenpointtoray");
 
 /**
+ * Camera component that handles rendering from a specific viewpoint in the scene.
+ * Supports both perspective and orthographic cameras with various rendering options.
+ * Internally, this component uses {@link PerspectiveCamera} and {@link OrthographicCamera} three.js objects.
+ * 
  * @category Camera Controls
  * @group Components
  */
 export class Camera extends Behaviour implements ICamera {
 
+    /**
+     * Returns whether this component is a camera
+     * @returns {boolean} Always returns true
+     */
     get isCamera() {
         return true;
     }
 
-    /** The camera's aspect ratio (width divided by height) if it is a perspective camera */
+    /** 
+     * Gets or sets the camera's aspect ratio (width divided by height).
+     * For perspective cameras, this directly affects the camera's projection matrix.
+     * When set, automatically updates the projection matrix.
+     */
     get aspect(): number {
         if (this._cam instanceof PerspectiveCamera) return this._cam.aspect;
         return (this.context.domWidth / this.context.domHeight);
@@ -51,7 +66,11 @@ export class Camera extends Behaviour implements ICamera {
             }
         }
     }
-    /** The camera's field of view in degrees if it is a perspective camera. Calls updateProjectionMatrix when set */
+    
+    /**
+     * Gets or sets the camera's field of view in degrees for perspective cameras.
+     * When set, automatically updates the projection matrix.
+     */
     get fieldOfView(): number | undefined {
         if (this._cam instanceof PerspectiveCamera) {
             return this._cam.fov;
@@ -74,7 +93,11 @@ export class Camera extends Behaviour implements ICamera {
         }
     }
 
-    /** The camera's near clipping plane. Calls updateProjectionMatrix when set */
+    /**
+     * Gets or sets the camera's near clipping plane distance.
+     * Objects closer than this distance won't be rendered.
+     * When set, automatically updates the projection matrix.
+     */
     get nearClipPlane(): number { return this._nearClipPlane; }
     @serializable()
     set nearClipPlane(val) {
@@ -87,7 +110,11 @@ export class Camera extends Behaviour implements ICamera {
     }
     private _nearClipPlane: number = 0.1;
 
-    /** The camera's far clipping plane. Calls updateProjectionMatrix when set */
+    /**
+     * Gets or sets the camera's far clipping plane distance.
+     * Objects farther than this distance won't be rendered.
+     * When set, automatically updates the projection matrix.
+     */
     get farClipPlane(): number { return this._farClipPlane; }
     @serializable()
     set farClipPlane(val) {
@@ -101,7 +128,8 @@ export class Camera extends Behaviour implements ICamera {
     private _farClipPlane: number = 1000;
 
     /**
-     * Applys both the camera's near and far plane and calls updateProjectionMatrix on the camera.
+     * Applies both the camera's near and far clipping planes and updates the projection matrix.
+     * This ensures rendering occurs only within the specified distance range.
      */
     applyClippingPlane() {
         if (this._cam) {
@@ -111,7 +139,10 @@ export class Camera extends Behaviour implements ICamera {
         }
     }
 
-    /** The camera's clear flags - determines if the background is a skybox or a solid color or transparent */
+    /**
+     * Gets or sets the camera's clear flags that determine how the background is rendered.
+     * Options include skybox, solid color, or transparent background.
+     */
     @serializable()
     public get clearFlags(): ClearFlags {
         return this._clearFlags;
@@ -121,18 +152,31 @@ export class Camera extends Behaviour implements ICamera {
         this._clearFlags = val;
         this.applyClearFlagsIfIsActiveCamera();
     }
+    
+    /**
+     * Determines if the camera should use orthographic projection instead of perspective.
+     */
     @serializable()
     public orthographic: boolean = false;
+    
+    /**
+     * The size of the orthographic camera's view volume when in orthographic mode.
+     * Larger values show more of the scene.
+     */
     @serializable()
     public orthographicSize: number = 5;
 
+    /**
+     * Controls the transparency level of the camera background in AR mode on supported devices.
+     * Value from 0 (fully transparent) to 1 (fully opaque).
+     */
     @serializable()
     public ARBackgroundAlpha: number = 0;
 
     /** 
-     * The [`mask`](https://threejs.org/docs/#api/en/core/Layers.mask) value of the three camera object layers 
-     * If you want to just see objects on one layer (e.g. layer 2) then you can use `cullingLayer = 2` on this camera component instead 
-    */
+     * Gets or sets the layers mask that determines which objects this camera will render.
+     * Uses the {@link https://threejs.org/docs/#api/en/core/Layers.mask|three.js layers mask} convention.
+     */
     @serializable()
     public set cullingMask(val: number) {
         this._cullingMask = val;
@@ -146,14 +190,19 @@ export class Camera extends Behaviour implements ICamera {
     }
     private _cullingMask: number = 0xffffffff;
 
-    /** Set only a specific layer active to be rendered by the camera.   
-     * This is equivalent to calling `layers.set(val)` 
-     **/
+    /**
+     * Sets only a specific layer to be active for rendering by this camera.
+     * This is equivalent to calling `layers.set(val)` on the three.js camera object.
+     * @param val The layer index to set active
+     */
     public set cullingLayer(val: number) {
         this.cullingMask = (1 << val | 0) >>> 0;
     }
 
-    /** The blurriness of the background texture (when using a skybox) */
+    /**
+     * Gets or sets the blurriness of the skybox background.
+     * Values range from 0 (sharp) to 1 (maximum blur).
+     */
     @serializable()
     public set backgroundBlurriness(val: number | undefined) {
         if (val === this._backgroundBlurriness) return;
@@ -168,7 +217,10 @@ export class Camera extends Behaviour implements ICamera {
     }
     private _backgroundBlurriness?: number = undefined;
 
-    /** The intensity of the background texture (when using a skybox) */
+    /**
+     * Gets or sets the intensity of the skybox background.
+     * Values range from 0 (dark) to 10 (very bright).
+     */
     @serializable()
     public set backgroundIntensity(val: number | undefined) {
         if (val === this._backgroundIntensity) return;
@@ -183,7 +235,10 @@ export class Camera extends Behaviour implements ICamera {
     }
     private _backgroundIntensity?: number = undefined;
 
-    /** the rotation of the background texture (when using a skybox) */
+    /**
+     * Gets or sets the rotation of the skybox background.
+     * Controls the orientation of the environment map.
+     */
     @serializable(Euler)
     public set backgroundRotation(val: Euler | undefined) {
         if (val === this._backgroundRotation) return;
@@ -198,7 +253,10 @@ export class Camera extends Behaviour implements ICamera {
     }
     private _backgroundRotation?: Euler = undefined;
 
-    /** The intensity of the environment map */
+    /**
+     * Gets or sets the intensity of the environment lighting.
+     * Controls how strongly the environment map affects scene lighting.
+     */
     @serializable()
     public set environmentIntensity(val: number | undefined) {
         this._environmentIntensity = val;
@@ -208,7 +266,10 @@ export class Camera extends Behaviour implements ICamera {
     }
     private _environmentIntensity?: number = undefined;
 
-    /** The background color of the camera when {@link ClearFlags} are set to `SolidColor` */
+    /**
+     * Gets or sets the background color of the camera when {@link ClearFlags} is set to {@link ClearFlags.SolidColor}.
+     * The alpha component controls transparency.
+     */
     @serializable(RGBAColor)
     public get backgroundColor(): RGBAColor | null {
         return this._backgroundColor ?? null;
@@ -225,9 +286,10 @@ export class Camera extends Behaviour implements ICamera {
         this.applyClearFlagsIfIsActiveCamera();
     }
 
-    /** The texture that the camera should render to 
-     * It can be used to render to a {@link Texture} instead of the screen.
-    */
+    /**
+     * Gets or sets the texture that the camera should render to instead of the screen.
+     * Useful for creating effects like mirrors, portals or custom post processing.
+     */
     @serializable(RenderTexture)
     public set targetTexture(rt: RenderTexture | null) {
         this._targetTexture = rt;
@@ -244,16 +306,17 @@ export class Camera extends Behaviour implements ICamera {
     private _skybox?: CameraSkybox;
 
     /**
-     * Get the three.js camera object. This will create a camera if it does not exist yet.
-     * @returns {PerspectiveCamera | OrthographicCamera} the three camera
-     * @deprecated use {@link threeCamera} instead
+     * Gets the three.js camera object. Creates one if it doesn't exist yet.
+     * @returns {PerspectiveCamera | OrthographicCamera} The three.js camera object
+     * @deprecated Use {@link threeCamera} instead
      */
     public get cam(): PerspectiveCamera | OrthographicCamera {
         return this.threeCamera;
     }
+    
     /**
-     * Get the three.js camera object. This will create a camera if it does not exist yet.
-     * @returns {PerspectiveCamera | OrthographicCamera} the three camera
+     * Gets the three.js camera object. Creates one if it doesn't exist yet.
+     * @returns {PerspectiveCamera | OrthographicCamera} The three.js camera object
      */
     public get threeCamera(): PerspectiveCamera | OrthographicCamera {
         if (this.activeAndEnabled)
@@ -263,6 +326,16 @@ export class Camera extends Behaviour implements ICamera {
 
     private static _origin: Vector3 = new Vector3();
     private static _direction: Vector3 = new Vector3();
+    
+    /**
+     * Converts screen coordinates to a ray in world space.
+     * Useful for implementing picking or raycasting from screen to world.
+     * 
+     * @param x The x screen coordinate
+     * @param y The y screen coordinate
+     * @param ray Optional ray object to reuse instead of creating a new one
+     * @returns {Ray} A ray originating from the camera position pointing through the screen point
+     */
     public screenPointToRay(x: number, y: number, ray?: Ray): Ray {
         const cam = this.threeCamera;
         const origin = Camera._origin;
@@ -285,9 +358,12 @@ export class Camera extends Behaviour implements ICamera {
     }
 
     private _frustum?: Frustum;
+    
     /**
-     * Get a frustum - it will be created the first time this method is called and updated every frame in onBeforeRender when it exists.  
-     * You can also manually update it using the updateFrustum method.
+     * Gets the camera's view frustum for culling and visibility checks.
+     * Creates the frustum if it doesn't exist and returns it.
+     * 
+     * @returns {Frustum} The camera's view frustum
      */
     public getFrustum(): Frustum {
         if (!this._frustum) {
@@ -296,13 +372,22 @@ export class Camera extends Behaviour implements ICamera {
         }
         return this._frustum;
     }
-    /** Force frustum update - note that this also happens automatically every frame in onBeforeRender */
+    
+    /**
+     * Forces an update of the camera's frustum.
+     * This is automatically called every frame in onBeforeRender.
+     */
     public updateFrustum() {
         if (!this._frustum) this._frustum = new Frustum();
         this._frustum.setFromProjectionMatrix(this.getProjectionScreenMatrix(this._projScreenMatrix, true), this.context.renderer.coordinateSystem);
     }
+    
     /**
-     * @returns {Matrix4} this camera's projection screen matrix.
+     * Gets this camera's projection-screen matrix.
+     * 
+     * @param target Matrix4 object to store the result in
+     * @param forceUpdate Whether to force recalculation of the matrix
+     * @returns {Matrix4} The requested projection screen matrix
      */
     public getProjectionScreenMatrix(target: Matrix4, forceUpdate?: boolean) {
         if (forceUpdate) {
@@ -313,7 +398,6 @@ export class Camera extends Behaviour implements ICamera {
     }
     private readonly _projScreenMatrix = new Matrix4();
 
-
     /** @internal */
     awake() {
         if (debugscreenpointtoray) {
@@ -382,8 +466,9 @@ export class Camera extends Behaviour implements ICamera {
     }
 
     /** 
-     * Creates a {@link PerspectiveCamera} if it does not exist yet and set the camera's properties. This is internally also called when accessing the {@link cam} property.
-     **/
+     * Creates a three.js camera object if it doesn't exist yet and sets its properties.
+     * This is called internally when accessing the {@link threeCamera} property.
+     */
     buildCamera() {
         if (this._cam) return;
 
@@ -428,13 +513,21 @@ export class Camera extends Behaviour implements ICamera {
         }
     }
 
+    /**
+     * Applies clear flags if this is the active main camera.
+     * @param opts Options for applying clear flags
+     */
     applyClearFlagsIfIsActiveCamera(opts?: { applySkybox: boolean }) {
         if (this.context.mainCameraComponent === this) {
             this.applyClearFlags(opts);
         }
     }
 
-    /** Apply this camera's clear flags and related settings to the renderer */
+    /**
+     * Applies this camera's clear flags and related settings to the renderer.
+     * This controls how the background is rendered (skybox, solid color, transparent).
+     * @param opts Options for applying clear flags
+     */
     applyClearFlags(opts?: { applySkybox: boolean }) {
         if (!this._cam) {
             if (debug) console.log("Camera does not exist (apply clear flags)")
@@ -503,7 +596,7 @@ export class Camera extends Behaviour implements ICamera {
     }
 
     /**
-     * Apply the skybox to the scene
+     * Applies the skybox texture to the scene background.
      */
     applySceneSkybox() {
         if (!this._skybox)
@@ -511,9 +604,12 @@ export class Camera extends Behaviour implements ICamera {
         this._skybox.apply();
     }
 
-    /** Used to determine if the background should be transparent when in pass through AR
-     * @returns true when in XR on a pass through device where the background shouldbe invisible 
-     **/
+    /**
+     * Determines if the background should be transparent when in passthrough AR mode.
+     * 
+     * @param context The current rendering context
+     * @returns {boolean} True when in XR on a pass through device where the background should be invisible
+     */
     static backgroundShouldBeTransparent(context: Context) {
         const session = context.renderer.xr?.getSession();
         if (!session) return false;
@@ -543,7 +639,10 @@ export class Camera extends Behaviour implements ICamera {
     }
 }
 
-
+/**
+ * Helper class for managing skybox textures for cameras.
+ * Handles retrieving and applying skybox textures to the scene.
+ */
 class CameraSkybox {
 
     private _camera: Camera;
@@ -555,6 +654,10 @@ class CameraSkybox {
         this._camera = camera;
     }
 
+    /**
+     * Applies the skybox texture to the scene background.
+     * Retrieves the texture based on the camera's source ID.
+     */
     apply() {
         this._skybox = this.context.lightmaps.tryGetSkybox(this._camera.sourceId) as Texture;
         if (!this._skybox) {
@@ -572,13 +675,16 @@ class CameraSkybox {
     }
 }
 
-
+/**
+ * Adds orbit controls to the camera if the freecam URL parameter is enabled.
+ * 
+ * @param cam The camera to potentially add orbit controls to
+ */
 function handleFreeCam(cam: Camera) {
     const isFreecam = getParam("freecam");
     if (isFreecam) {
         if (cam.context.mainCameraComponent === cam) {
             GameObject.getOrAddComponent(cam.gameObject, OrbitControls);
         }
-
     }
 }

package/src/engine-components/CameraUtils.ts

@@ -13,6 +13,13 @@ import { OrbitControls } from "./OrbitControls.js";
 
 const debug = getParam("debugmissingcamera");
 
+/**
+ * Handler for missing camera events. Creates a default fallback camera when no camera is found in the scene.
+ * Sets up camera properties based on the context and HTML element attributes.
+ * 
+ * @param evt The context event containing scene and configuration information
+ * @returns The created camera component
+ */
 ContextRegistry.registerCallback(ContextEvent.MissingCamera, (evt) => {
     if (debug) console.warn("Creating missing camera")
     const scene = evt.context.scene;
@@ -57,6 +64,12 @@ ContextRegistry.registerCallback(ContextEvent.MissingCamera, (evt) => {
     return cam;
 });
 
+/**
+ * Handler for context creation events. Checks if camera controls should be added
+ * to the main camera when the context is created.
+ * 
+ * @param evt The context creation event containing the context information
+ */
 ContextRegistry.registerCallback(ContextEvent.ContextCreated, (evt) => {
     if (!evt.context.mainCamera) {
         if (debug) console.log("Will not auto-fit because a default camera exists");
@@ -77,6 +90,13 @@ ContextRegistry.registerCallback(ContextEvent.ContextCreated, (evt) => {
     }
 })
 
+/**
+ * Creates default orbit camera controls for the specified camera.
+ * Configures auto-rotation and auto-fit settings based on HTML attributes.
+ * 
+ * @param context The rendering context
+ * @param cam Optional camera component to attach controls to (uses main camera if not specified)
+ */
 function createDefaultCameraControls(context: IContext, cam?: ICamera) {
 
     cam = cam ?? context.mainCameraComponent;