@needle-tools/engine 4.12.0-beta → 4.12.0-beta.1

package/src/engine-components/BasicIKConstraint.ts

@@ -3,6 +3,14 @@ import { Vector3 } from "three";
 import * as utils from "./../engine/engine_three_utils.js";
 import { Behaviour, GameObject } from "./Component.js";
 
+/**
+ * BasicIKConstraint positions the GameObject between two target GameObjects (`from` and `to`) with an optional `hint` GameObject to guide the bending direction.  
+ * This is useful for simple inverse kinematics setups, such as positioning a joint in a limb.
+ * 
+ * @summary Simple Inverse Kinematics Constraint
+ * @category Animation
+ * @group Components
+ */
 export class BasicIKConstraint extends Behaviour {
 
     private from!: GameObject;

package/src/engine-components/BoxHelperComponent.ts

@@ -14,6 +14,7 @@ const debug = getParam("debugboxhelper");
  * 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`.
  * 
+ * @summary Bounding box helper with intersection tests
  * @category Helpers
  * @group Components
  */

package/src/engine-components/Camera.ts

@@ -36,7 +36,7 @@ const debugscreenpointtoray = getParam("debugscreenpointtoray");
  * Supports both perspective and orthographic cameras with various rendering options.
  * Internally, this component uses {@link PerspectiveCamera} and {@link OrthographicCamera} three.js objects.
  * 
- * @summary Camera rendering scenes from a specific viewpoint
+ * @summary Rendering scenes from a specific viewpoint
  * @category Camera
  * @group Components
  */

package/src/engine-components/Collider.ts

@@ -22,7 +22,7 @@ import { Rigidbody } from "./RigidBody.js";
  * - Example: https://samples.needle.tools/physics-playground
  * - Example: https://samples.needle.tools/physics-&-animation 
  * 
- * 
+ * @summary Physics collider
  * @category Physics  
  * @group Components
  */

package/src/engine-components/ContactShadows.ts

@@ -53,7 +53,7 @@ type FitParameters = {
  * 
  * ContactShadows can also be enabled on the `<needle-engine>` web component directly by adding the `contactshadows` attribute. The value of the attribute will be used as opacity and darkness of the shadows: `<needle-engine contactshadows="0.7">`.
  * 
- * 
+ * @summary Display contact shadows on the ground
  * @category Rendering
  * @group Components
 */

package/src/engine-components/DragControls.ts

@@ -485,6 +485,8 @@ interface IDragHandler {
     onDragUpdate?(numberOfPointers: number): void;
 }
 
+
+// #region MultiTouchDragHandler
 /** 
  * Handles two touch points affecting one object. 
  * Enables multi-touch interactions that allow movement, scaling, and rotation of objects.
@@ -734,6 +736,7 @@ class MultiTouchDragHandler implements IDragHandler {
 }
 
 
+// #region DragPointerHandler
 /** 
  * Handles a single pointer on an object. 
  * DragPointerHandlers manage determining if a drag operation has started, tracking pointer movement,
@@ -1335,6 +1338,7 @@ class DragPointerHandler implements IDragHandler {
     }
 }
 
+// #region LegacyDragVisualsHelper
 /** 
  * Provides visual helper elements for DragControls.
  * Shows where objects will be placed and their relation to surfaces below them.

package/src/engine-components/Gizmos.ts

@@ -8,6 +8,8 @@ import { Behaviour } from "./Component.js";
 
 /**
  * BoxGizmo is a component that displays a box around the object in the scene. It can optionally expand to the object's bounds.
+ *
+ * @summary Display a box around the object
  * @category Helpers
  * @group Components
  */

package/src/engine-components/Joints.ts

@@ -4,6 +4,12 @@ import { serializable } from "../engine/engine_serialization.js";
 import { Behaviour } from "./Component.js";
 import { Rigidbody } from "./RigidBody.js";
 
+/**
+ * Base class for physics joints connecting two rigid bodies.
+ * @summary Connect two Rigidbodies
+ * @category Physics
+ * @group Components
+ */
 export abstract class Joint extends Behaviour {
     @serializable(Rigidbody)
     connectedBody?: Rigidbody;

package/src/engine-components/LODGroup.ts

@@ -41,7 +41,7 @@ declare class LODSetting {
 /**
  * LODGroup allows to create a group of LOD levels for an object.
  * 
- * @summary Level of Detail (LOD) Group Component
+ * @summary Level of Detail Group for optimizing rendering
  * @category Rendering
  * @group Components
  */

package/src/engine-components/Networking.ts

@@ -11,7 +11,7 @@ const debug = getParam("debugnet");
  * This component supplies websocket URLs for establishing connections.
  * It implements the {@link INetworkingWebsocketUrlProvider} interface.
  * 
- * @summary Networking configuration component
+ * @summary Networking configuration
  * @category Networking
  * @group Components
  */

package/src/engine-components/ShadowCatcher.ts

@@ -23,7 +23,7 @@ enum ShadowMode {
  * 
  * Note that ShadowCatcher meshes are not raycastable by default; if you want them to be raycastable, change the layers in `onEnable()`.
  * 
- * @summary Renders shadows or light on the object
+ * @summary Creates a shadow mask or a light occluder 
  * @category Rendering
  * @group Components
  */

package/src/engine-components/SpectatorCamera.ts

@@ -35,7 +35,7 @@ const debug = getParam("debugspectator");
  * 
  * Debug mode can be enabled with the URL parameter `?debugspectator`, which provides additional console output.
  * 
- * @summary Follow other users in a networked room
+ * @summary Spectator camera for following other users
  * @category Networking
  * @group Components
  */

package/src/engine-components/Voip.ts

@@ -14,7 +14,7 @@ const debugParam = getParam("debugvoip");
 /**
  * The Voice over IP component (VoIP) allows you to send and receive audio streams to other users in the same networked room.  
  * It requires a networking connection to be working (e.g. by having an active SyncedRoom component in the scene or by connecting to a room manually).  
- * @summary Voice over IP (VoIP) for networked audio communication
+ * @summary Voice over IP for networked audio communication
  * @category Networking
  * @group Components
  */

package/src/engine-components/export/gltf/GltfExport.ts

@@ -30,6 +30,11 @@ export class GltfExportBox extends BoxHelperComponent {
 }
 
 /**
+ * GltfExport is a component that enables exporting selected 3D objects from the scene to the glTF format.  
+ * You can specify whether to export in binary format (.glb) or JSON format (.gltf), and select specific objects to include in the export.
+ * The exported glTF file can be used in various 3D applications and engines that support the glTF standard.
+ * 
+ * @summary Export selected 3D objects to glTF format
  * @category Asset Management
  * @group Components
  */

package/src/engine-components/export/usdz/USDZExporter.ts

@@ -84,6 +84,7 @@ type BeforeLODExportArguments = {
  * usdz.autoExportAudioSources = true;
  * usdz.exportAsync();
  * ```
+ * @summary Export 3D objects as USDZ files for QuickLook
  * @category XR
  * @group Components
  */

package/src/engine-components/particlesystem/ParticleSystem.ts

@@ -692,7 +692,7 @@ class ParticlesEmissionState implements EmissionState {
  * 
  * Needle Engine uses [three.quarks](https://github.com/Alchemist0823/three.quarks) under the hood to handle particles.
  * 
- * @summary Particle System
+ * @summary Handles the motion and rendering of many individual particles
  * @category Rendering
  * @group Components
  */

package/src/engine-components/ui/Button.ts

@@ -64,7 +64,7 @@ class AnimationTriggers {
  * Button is a UI component that can be clicked by the user to perform an action.  
  * It supports different visual states such as normal, highlighted, pressed, and disabled.  
  * You can customize the button's appearance using colors or animations for each state.
- * @summary Button UI Component
+ * @summary UI Button that can be clicked to perform actions
  * @category User Interface
  * @group Components
  */

package/src/engine-components/ui/Canvas.ts

@@ -29,7 +29,7 @@ const debugLayout = getParam("debuguilayout");
  * It defines the area where UI elements are rendered and manages their layout and rendering settings.  
  * Canvases can be set to render in world space or screen space (overlay or camera).  
  * Multiple canvases can exist in a scene, each with its own settings and hierarchy of UI elements.
- * @summary Canvas UI Component
+ * @summary Root component for UI elements, managing layout and rendering settings
  * @category User Interface
  * @group Components
  */

package/src/engine-components/ui/CanvasGroup.ts

@@ -10,7 +10,7 @@ import { type ICanvasGroup, type IHasAlphaFactor } from "./Interfaces.js";
  * CanvasGroup is a UI component that allows you to control the transparency and interactivity of a group of UI elements.  
  * By adjusting the alpha property, you can fade in or out all child UI elements simultaneously.  
  * The interactable and blocksRaycasts properties let you enable or disable user interaction for the entire group.
- * @summary CanvasGroup UI Component
+ * @summary Group UI elements to control transparency and interactivity
  * @category User Interface
  * @group Components
  */

package/src/engine-components/ui/EventSystem.ts

@@ -37,7 +37,7 @@ onInitialized((ctx) => {
 
 /**
  * The EventSystem is responsible for managing and dispatching input events to UI components within the scene.
- * @summary UI Input Event System
+ * @summary Manages and dispatches input events to UI components
  * @category User Interface
  * @group Components
  */

package/src/engine-components/ui/Image.ts

@@ -15,7 +15,7 @@ class Sprite {
  * Image is a UI component that displays a sprite (2D image) in the user interface.  
  * You can set the image property to assign a texture to be displayed.  
  * The sprite can be customized with various properties such as color tinting and pixel density.
- * @summary Image UI Component
+ * @summary Display a 2D image in the UI
  * @category User Interface
  * @group Components
  */

package/src/engine-components/ui/InputField.ts

@@ -13,7 +13,7 @@ const debug = getParam("debuginputfield");
  * InputField is a UI component that allows users to enter and edit text.  
  * It provides a text input area where users can type, delete, and modify text.  
  * The InputField supports placeholder text, events for value changes, and end edit actions.
- * @summary Text Input Field UI Component
+ * @summary Text field for user input
  * @category User Interface
  * @group Components
  */

package/src/engine-components/ui/Outline.ts

@@ -7,7 +7,7 @@ import { Behaviour } from "../Component.js";
 /**
  * Outline is a UI component that adds an outline effect to UI elements.  
  * You can customize the outline color and distance to create a visual border around the UI element.
- * @summary Outline UI Component
+ * @summary Add an outline effect to UI elements
  * @category User Interface
  * @group Components
  */

package/src/engine-components/ui/SpatialHtml.ts

@@ -6,6 +6,13 @@ import { serializable } from '../../engine/engine_serialization.js';
 import { getWorldRotation, setWorldRotationXYZ } from '../../engine/engine_three_utils.js';
 import { Behaviour } from '../Component.js';
 
+/**
+ * SpatialHtml is a component that allows you to integrate HTML elements into a 3D scene.  
+ * By specifying the ID of an existing HTML element, you can render it as a 3D object within the scene.
+ * @summary Render HTML elements as 3D objects in the scene
+ * @category User Interface
+ * @group Components
+ */
 export class SpatialHtml extends Behaviour {
 
     @serializable()

package/src/engine-components/ui/Text.ts

@@ -41,6 +41,8 @@ export enum FontStyle {
 
 /**
  * Text is a UI component that displays text in the user interface.
+ * 
+ * @summary Display text in the UI
  * @category User Interface
  * @group Components
  */