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

package/lib/engine-components/AxesHelper.js

@@ -9,15 +9,30 @@ import * as params from "../engine/engine_default_parameters.js";
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import { Behaviour } from "./Component.js";
 /**
- * AxesHelper is a component that displays the axes of the object in the scene.
+ * Component that visualizes the axes of an object in the scene.
+ * Renders colored lines representing the X (red), Y (green) and Z (blue) axes.
  * @category Helpers
  * @group Components
  */
 export class AxesHelper extends Behaviour {
+    /**
+     * The length of each axis line in scene units.
+     */
     length = 1;
+    /**
+     * Whether the axes should be occluded by objects in the scene.
+     * When set to false, axes will always appear on top regardless of their depth.
+     */
     depthTest = true;
+    /**
+     * When true, this helper will only be visible if the debug flag `?gizmos` is enabled.
+     */
     isGizmo = false;
     _axes = null;
+    /**
+     * Creates and adds the axes visualization to the scene when the component is enabled.
+     * If marked as a gizmo, it will only be shown when gizmos are enabled in the global parameters.
+     */
     onEnable() {
         if (this.isGizmo && !params.showGizmos)
             return;
@@ -32,6 +47,9 @@ export class AxesHelper extends Behaviour {
                 mat.depthTest = this.depthTest;
         }
     }
+    /**
+     * Removes the axes visualization from the scene when the component is disabled.
+     */
     onDisable() {
         if (!this._axes)
             return;

package/lib/engine-components/AxesHelper.js.map

@@ -1 +1 @@
-{"version":3,"file":"AxesHelper.js","sourceRoot":"","sources":["../../src/engine-components/AxesHelper.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAE,UAAU,IAAI,WAAW,EAAE,MAAM,OAAO,CAAC;AAElD,OAAO,KAAK,MAAM,MAAM,wCAAwC,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,6CAA6C,CAAC;AAC3E,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;;;GAIG;AACH,MAAM,OAAO,UAAW,SAAQ,SAAS;IAE9B,MAAM,GAAW,CAAC,CAAC;IAEnB,SAAS,GAAY,IAAI,CAAC;IAE1B,OAAO,GAAY,KAAK,CAAC;IAExB,KAAK,GAAuB,IAAI,CAAC;IAEzC,QAAQ;QACJ,IAAI,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,UAAU;YAAE,OAAO;QAC/C,IAAI,CAAC,IAAI,CAAC,KAAK;YACX,IAAI,CAAC,KAAK,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC9C,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;QAC/B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAClC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAChC,MAAM,GAAG,GAAQ,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC;QACrC,IAAI,GAAG,EAAE;YACL,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS;gBAC3B,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;SACtC;IACL,CAAC;IAED,SAAS;QACL,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,OAAO;QACxB,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACvC,CAAC;CACJ;AA1BG;IADC,YAAY,EAAE;0CACW;AAE1B;IADC,YAAY,EAAE;6CACkB;AAEjC;IADC,YAAY,EAAE;2CACiB"}
+{"version":3,"file":"AxesHelper.js","sourceRoot":"","sources":["../../src/engine-components/AxesHelper.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAE,UAAU,IAAI,WAAW,EAAE,MAAM,OAAO,CAAC;AAElD,OAAO,KAAK,MAAM,MAAM,wCAAwC,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,6CAA6C,CAAC;AAC3E,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,OAAO,UAAW,SAAQ,SAAS;IACrC;;OAEG;IAEI,MAAM,GAAW,CAAC,CAAC;IAE1B;;;OAGG;IAEI,SAAS,GAAY,IAAI,CAAC;IAEjC;;OAEG;IAEI,OAAO,GAAY,KAAK,CAAC;IAExB,KAAK,GAAuB,IAAI,CAAC;IAEzC;;;OAGG;IACH,QAAQ;QACJ,IAAI,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,UAAU;YAAE,OAAO;QAC/C,IAAI,CAAC,IAAI,CAAC,KAAK;YACX,IAAI,CAAC,KAAK,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC9C,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;QAC/B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAClC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAChC,MAAM,GAAG,GAAQ,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC;QACrC,IAAI,GAAG,EAAE;YACL,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS;gBAC3B,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;SACtC;IACL,CAAC;IAED;;OAEG;IACH,SAAS;QACL,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,OAAO;QACxB,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACvC,CAAC;CACJ;AA1CG;IADC,YAAY,EAAE;0CACW;AAO1B;IADC,YAAY,EAAE;6CACkB;AAMjC;IADC,YAAY,EAAE;2CACiB"}

package/lib/engine-components/BoxHelperComponent.d.ts

@@ -1,21 +1,47 @@
 import { Box3, type ColorRepresentation, Object3D } from "three";
 import { Behaviour } from "./Component.js";
 /**
+ * A component that creates a bounding box around an object and provides intersection testing functionality.
+ *
+ * Debug mode can be enabled with the URL parameter `?debugboxhelper`, which will visualize intersection tests.
+ * Helper visualization can be enabled with the URL parameter `?gizmos`.
+ *
  * @category Helpers
  * @group Components
  */
 export declare class BoxHelperComponent extends Behaviour {
+    /** The bounding box for this component */
     private box;
     private static testBox;
     private _lastMatrixUpdateFrame;
     private static _position;
     private static _size;
     private static _emptyObjectSize;
+    /**
+     * Tests if an object intersects with this helper's bounding box
+     * @param obj The object to test for intersection
+     * @returns True if objects intersect, false if not, undefined if the provided object is invalid
+     */
     isInBox(obj: Object3D): boolean | undefined;
+    /**
+     * Tests if this helper's bounding box intersects with another box
+     * @param box The {@link Box3} to test for intersection
+     * @returns True if boxes intersect, false otherwise
+     */
     intersects(box: Box3): boolean;
+    /**
+     * Updates the helper's bounding box based on the gameObject's position and scale
+     * @param force Whether to force an update regardless of frame count
+     * @returns The updated {@link Box3}
+     */
     updateBox(force?: boolean): Box3;
     private _helper;
     private _color;
     awake(): void;
+    /**
+     * Creates and displays a visual wireframe representation of this box helper
+     * @param col Optional color for the wireframe. If not provided, uses default color
+     * @param force If true, shows the helper even if gizmos are disabled
+     */
     showHelper(col?: ColorRepresentation | null, force?: boolean): void;
 }

package/lib/engine-components/BoxHelperComponent.js

@@ -6,16 +6,27 @@ import { Behaviour } from "./Component.js";
 const gizmos = getParam("gizmos");
 const debug = getParam("debugboxhelper");
 /**
+ * A component that creates a bounding box around an object and provides intersection testing functionality.
+ *
+ * Debug mode can be enabled with the URL parameter `?debugboxhelper`, which will visualize intersection tests.
+ * Helper visualization can be enabled with the URL parameter `?gizmos`.
+ *
  * @category Helpers
  * @group Components
  */
 export class BoxHelperComponent extends Behaviour {
+    /** The bounding box for this component */
     box = null;
     static testBox = new Box3();
     _lastMatrixUpdateFrame = -1;
     static _position = new Vector3();
     static _size = new Vector3(.01, .01, .01);
     static _emptyObjectSize = new Vector3(.01, .01, .01);
+    /**
+     * Tests if an object intersects with this helper's bounding box
+     * @param obj The object to test for intersection
+     * @returns True if objects intersect, false if not, undefined if the provided object is invalid
+     */
     isInBox(obj) {
         if (!obj)
             return undefined;
@@ -35,11 +46,21 @@ export class BoxHelperComponent extends Behaviour {
         }
         return intersects;
     }
+    /**
+     * Tests if this helper's bounding box intersects with another box
+     * @param box The {@link Box3} to test for intersection
+     * @returns True if boxes intersect, false otherwise
+     */
     intersects(box) {
         if (!box)
             return false;
         return this.updateBox(false).intersectsBox(box);
     }
+    /**
+     * Updates the helper's bounding box based on the gameObject's position and scale
+     * @param force Whether to force an update regardless of frame count
+     * @returns The updated {@link Box3}
+     */
     updateBox(force = false) {
         if (!this.box) {
             this.box = new Box3();
@@ -61,6 +82,11 @@ export class BoxHelperComponent extends Behaviour {
         this._color = null;
         this.box = null;
     }
+    /**
+     * Creates and displays a visual wireframe representation of this box helper
+     * @param col Optional color for the wireframe. If not provided, uses default color
+     * @param force If true, shows the helper even if gizmos are disabled
+     */
     showHelper(col = null, force = false) {
         if (!gizmos && !force)
             return;

package/lib/engine-components/BoxHelperComponent.js.map

@@ -1 +1 @@
-{"version":3,"file":"BoxHelperComponent.js","sourceRoot":"","sources":["../../src/engine-components/BoxHelperComponent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAA2D,OAAO,EAAE,MAAM,OAAO,CAAC;AAE/F,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAClG,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAClC,MAAM,KAAK,GAAG,QAAQ,CAAC,gBAAgB,CAAC,CAAC;AAEzC;;;GAGG;AACH,MAAM,OAAO,kBAAmB,SAAQ,SAAS;IAErC,GAAG,GAAgB,IAAI,CAAC;IACxB,MAAM,CAAC,OAAO,GAAS,IAAI,IAAI,EAAE,CAAC;IAClC,sBAAsB,GAAW,CAAC,CAAC,CAAC;IACpC,MAAM,CAAC,SAAS,GAAY,IAAI,OAAO,EAAE,CAAC;IAC1C,MAAM,CAAC,KAAK,GAAY,IAAI,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IACnD,MAAM,CAAC,gBAAgB,GAAY,IAAI,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAE/D,OAAO,CAAC,GAAa;QACxB,IAAI,CAAC,GAAG;YAAE,OAAO,SAAS,CAAC;QAE3B,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE;YACX,IAAI,CAAC,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;SACzB;QAED,cAAc,CAAC,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAC;QAExE,IAAI,kBAAkB,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE;YACtC,MAAM,EAAE,GAAG,gBAAgB,CAAC,GAAG,EAAE,kBAAkB,CAAC,SAAS,CAAC,CAAC;YAC/D,kBAAkB,CAAC,OAAO,CAAC,oBAAoB,CAAC,EAAE,EAAE,kBAAkB,CAAC,gBAAgB,CAAC,CAAC;SAC5F;QAED,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,aAAa,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;QACvE,IAAI,UAAU,EAAE;YACZ,IAAI,KAAK;gBAAE,MAAM,CAAC,YAAY,CAAC,kBAAkB,CAAC,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;SAE3E;QACD,OAAO,UAAU,CAAC;IACtB,CAAC;IAEM,UAAU,CAAC,GAAS;QACvB,IAAI,CAAC,GAAG;YAAE,OAAO,KAAK,CAAC;QACvB,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IACpD,CAAC;IAEM,SAAS,CAAC,QAAiB,KAAK;QACnC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE;YACX,IAAI,CAAC,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;SACzB;QACD,IAAI,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,sBAAsB,EAAE;YACtE,MAAM,WAAW,GAAG,IAAI,CAAC,sBAAsB,GAAG,CAAC,CAAC;YACpD,IAAI,CAAC,sBAAsB,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC;YAC3D,MAAM,aAAa,GAAY,WAAW,CAAC,CAAC,0EAA0E;YACtH,MAAM,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,UAAU,EAAE,kBAAkB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;YAC1F,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,UAAU,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC;YACtE,IAAI,CAAC,GAAG,CAAC,oBAAoB,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;SAC3C;QACD,OAAO,IAAI,CAAC,GAAG,CAAC;IACpB,CAAC;IAGO,OAAO,GAAwB,IAAI,CAAC;IACpC,MAAM,GAAiB,IAAI,CAAC;IAEpC,KAAK;QACD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC;IACpB,CAAC;IAEM,UAAU,CAAC,MAAkC,IAAI,EAAE,QAAiB,KAAK;QAC5E,IAAI,CAAC,MAAM,IAAI,CAAC,KAAK;YAAE,OAAO;QAC9B,IAAI,IAAI,CAAC,OAAO,EAAE;YACd,IAAI,GAAG;gBACH,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;YAC1B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAClC,OAAO;SACV;QACD,IAAI,CAAC,OAAO,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC"}
+{"version":3,"file":"BoxHelperComponent.js","sourceRoot":"","sources":["../../src/engine-components/BoxHelperComponent.ts"],"names":[],"mappings":"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"}

package/lib/engine-components/Camera.d.ts

@@ -4,8 +4,11 @@ import { RenderTexture } from "../engine/engine_texture.js";
 import type { ICamera } from "../engine/engine_types.js";
 import { RGBAColor } from "../engine/js-extensions/index.js";
 import { Behaviour } from "./Component.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 declare enum ClearFlags {
+    /** Don't clear the background */
     None = 0,
     /** Clear the background with a skybox */
     Skybox = 1,
@@ -15,68 +18,124 @@ export declare enum ClearFlags {
     Uninitialized = 4
 }
 /**
+ * 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 declare class Camera extends Behaviour implements ICamera {
+    /**
+     * Returns whether this component is a camera
+     * @returns {boolean} Always returns true
+     */
     get isCamera(): boolean;
-    /** 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;
     set aspect(value: number);
-    /** 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;
     set fieldOfView(val: number | undefined);
-    /** 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;
     set nearClipPlane(val: number);
     private _nearClipPlane;
-    /** 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;
     set farClipPlane(val: number);
     private _farClipPlane;
     /**
-     * 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(): void;
-    /** 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.
+     */
     get clearFlags(): ClearFlags;
     set clearFlags(val: ClearFlags);
+    /**
+     * Determines if the camera should use orthographic projection instead of perspective.
+     */
     orthographic: boolean;
+    /**
+     * The size of the orthographic camera's view volume when in orthographic mode.
+     * Larger values show more of the scene.
+     */
     orthographicSize: number;
+    /**
+     * Controls the transparency level of the camera background in AR mode on supported devices.
+     * Value from 0 (fully transparent) to 1 (fully opaque).
+     */
     ARBackgroundAlpha: number;
     /**
-     * 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.
+     */
     set cullingMask(val: number);
     get cullingMask(): number;
     private _cullingMask;
-    /** 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
+     */
     set cullingLayer(val: number);
-    /** 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).
+     */
     set backgroundBlurriness(val: number | undefined);
     get backgroundBlurriness(): number | undefined;
     private _backgroundBlurriness?;
-    /** 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).
+     */
     set backgroundIntensity(val: number | undefined);
     get backgroundIntensity(): number | undefined;
     private _backgroundIntensity?;
-    /** 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.
+     */
     set backgroundRotation(val: Euler | undefined);
     get backgroundRotation(): Euler | undefined;
     private _backgroundRotation?;
-    /** The intensity of the environment map */
+    /**
+     * Gets or sets the intensity of the environment lighting.
+     * Controls how strongly the environment map affects scene lighting.
+     */
     set environmentIntensity(val: number | undefined);
     get environmentIntensity(): number | undefined;
     private _environmentIntensity?;
-    /** 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.
+     */
     get backgroundColor(): RGBAColor | null;
     set backgroundColor(val: RGBAColor | null);
-    /** 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.
+     */
     set targetTexture(rt: RenderTexture | null);
     get targetTexture(): RenderTexture | null;
     private _targetTexture;
@@ -86,29 +145,47 @@ export declare class Camera extends Behaviour implements ICamera {
     private _clearFlags;
     private _skybox?;
     /**
-     * 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
      */
     get cam(): PerspectiveCamera | OrthographicCamera;
     /**
-     * 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
      */
     get threeCamera(): PerspectiveCamera | OrthographicCamera;
     private static _origin;
     private static _direction;
+    /**
+     * 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
+     */
     screenPointToRay(x: number, y: number, ray?: Ray): Ray;
     private _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
      */
     getFrustum(): 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.
+     */
     updateFrustum(): void;
     /**
-     * @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
      */
     getProjectionScreenMatrix(target: Matrix4, forceUpdate?: boolean): Matrix4;
     private readonly _projScreenMatrix;
@@ -121,22 +198,34 @@ export declare class Camera extends Behaviour implements ICamera {
     /** @internal */
     onBeforeRender(): void;
     /**
-     * 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(): void;
+    /**
+     * Applies clear flags if this is the active main camera.
+     * @param opts Options for applying clear flags
+     */
     applyClearFlagsIfIsActiveCamera(opts?: {
         applySkybox: boolean;
     }): void;
-    /** 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;
     }): void;
     /**
-     * Apply the skybox to the scene
+     * Applies the skybox texture to the scene background.
      */
     applySceneSkybox(): void;
-    /** 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): boolean;
 }