@needle-tools/engine 4.13.0 → 4.13.1

package/lib/engine-components/splines/Spline.d.ts

@@ -1,53 +1,450 @@
 import { Curve, Quaternion, Vector3 } from "three";
 import { Behaviour } from "../Component.js";
+/**
+ * Represents a single knot (control point) in a spline curve.
+ *
+ * Each knot defines a point along the spline with its position, rotation, and tangent handles
+ * that control the curve's shape entering and leaving the knot.
+ *
+ * **Properties:**
+ * - **position**: The 3D position of this knot in local space
+ * - **rotation**: The orientation at this knot (useful for rotating objects along the spline)
+ * - **tangentIn**: The incoming tangent handle controlling the curve shape before this knot
+ * - **tangentOut**: The outgoing tangent handle controlling the curve shape after this knot
+ *
+ * @see {@link SplineContainer} for the container that holds and manages multiple knots
+ */
 export declare class SplineData {
+    /**
+     * The 3D position of this knot in local space relative to the SplineContainer.
+     */
     position: Vector3;
+    /**
+     * The orientation at this knot. Can be used to rotate objects following the spline.
+     */
     rotation: Quaternion;
+    /**
+     * The incoming tangent handle controlling the curve shape as it approaches this knot.
+     * The magnitude and direction affect the smoothness and curvature of the spline.
+     */
     tangentIn: Vector3;
+    /**
+     * The outgoing tangent handle controlling the curve shape as it leaves this knot.
+     * The magnitude and direction affect the smoothness and curvature of the spline.
+     */
     tangentOut: Vector3;
 }
 /**
- * Holds spline data and generates a spline curve. Use with SplineWalker to move objects along the spline or call getPointAt to sample points on the spline.
- * The spline is defined by an array of knots (SplineData) which define position, rotation and tangents.
+ * [SplineContainer](https://engine.needle.tools/docs/api/SplineContainer) manages spline curves defined by a series of knots (control points).
+ * This component stores spline data and generates smooth curves that can be used for animation paths, camera paths, racing tracks, or any curved path in 3D space.
+ *
+ * ![](https://cloud.needle.tools/-/media/XIHaiNFsA1IbMZVJepp1aQ.gif)
+ *
+ * **How It Works:**
+ * The spline is defined by an array of {@link SplineData} knots. Each knot contains:
+ * - **Position**: The location of the control point
+ * - **Rotation**: Orientation at that point (useful for banking/tilting objects along the path)
+ * - **Tangents**: Handles that control the curve's smoothness and shape
+ *
+ * The component uses Catmull-Rom interpolation to create smooth curves between knots. The curve is automatically
+ * rebuilt when knots are added, removed, or marked dirty, and all sampling methods return positions in world space.
+ *
+ * **Key Features:**
+ * - Smooth Catmull-Rom curve interpolation
+ * - Support for open and closed curves
+ * - Dynamic knot management (add/remove at runtime)
+ * - World-space sampling with {@link getPointAt} and {@link getTangentAt}
+ * - Automatic curve regeneration when modified
+ * - Built-in debug visualization
+ * - Integrates seamlessly with {@link SplineWalker}
+ *
+ * **Common Use Cases:**
+ * - Camera paths and cinematics
+ * - Object movement along curved paths
+ * - Racing game tracks and racing lines
+ * - Character patrol routes
+ * - Procedural road/path generation
+ * - Animation curves for complex motion
+ * - Cable/rope visualization
+ *
+ * @example Basic spline setup with knots
+ * ```ts
+ * const splineObj = new Object3D();
+ * const spline = splineObj.addComponent(SplineContainer);
+ *
+ * // Add knots to define the path
+ * spline.addKnot({ position: new Vector3(0, 0, 0) });
+ * spline.addKnot({ position: new Vector3(2, 1, 0) });
+ * spline.addKnot({ position: new Vector3(4, 0, 2) });
+ * spline.addKnot({ position: new Vector3(6, -1, 1) });
+ *
+ * // Sample a point halfway along the spline
+ * const midpoint = spline.getPointAt(0.5);
+ * console.log("Midpoint:", midpoint);
+ * ```
+ *
+ * @example Creating a closed loop spline
+ * ```ts
+ * const loopSpline = gameObject.addComponent(SplineContainer);
+ * loopSpline.closed = true; // Makes the spline loop back to the start
  *
- * You can create a SplineContainer from an array of points using the static method 'createFromPoints'.
+ * // Add circular path knots
+ * for (let i = 0; i < 8; i++) {
+ *   const angle = (i / 8) * Math.PI * 2;
+ *   const pos = new Vector3(Math.cos(angle) * 5, 0, Math.sin(angle) * 5);
+ *   loopSpline.addKnot({ position: pos });
+ * }
+ * ```
  *
- * @summary Holds spline data and generates a spline curve.
+ * @example Sampling points along a spline
+ * ```ts
+ * const spline = gameObject.getComponent(SplineContainer);
+ *
+ * // Sample 10 points along the spline
+ * const points: Vector3[] = [];
+ * for (let i = 0; i <= 10; i++) {
+ *   const t = i / 10; // 0 to 1
+ *   const point = spline.getPointAt(t);
+ *   points.push(point);
+ * }
+ *
+ * // Get tangent (direction) at 75% along the spline
+ * const tangent = spline.getTangentAt(0.75);
+ * console.log("Direction at 75%:", tangent);
+ * ```
+ *
+ * @example Dynamic knot manipulation
+ * ```ts
+ * const spline = gameObject.getComponent(SplineContainer);
+ *
+ * // Add a new knot dynamically
+ * const newKnot = new SplineData();
+ * newKnot.position.set(10, 5, 0);
+ * spline.addKnot(newKnot);
+ *
+ * // Remove the first knot
+ * spline.removeKnot(0);
+ *
+ * // Modify existing knot
+ * spline.spline[1].position.y += 2;
+ * spline.markDirty(); // Tell the spline to rebuild
+ * ```
+ *
+ * @example Using with SplineWalker for animation
+ * ```ts
+ * // Set up spline path
+ * const spline = pathObject.addComponent(SplineContainer);
+ * spline.addKnot({ position: new Vector3(0, 0, 0) });
+ * spline.addKnot({ position: new Vector3(5, 2, 5) });
+ * spline.addKnot({ position: new Vector3(10, 0, 0) });
+ *
+ * // Make object follow the spline
+ * const walker = movingObject.addComponent(SplineWalker);
+ * walker.spline = spline;
+ * walker.speed = 2; // Units per second
+ * walker.loop = true;
+ * ```
+ *
+ * **Debug Visualization:**
+ * Add `?debugsplines` to your URL to enable debug visualization, which draws the spline curve as a purple line.
+ * You can also enable it programmatically:
+ * ```ts
+ * spline.debug = true; // Show debug visualization
+ * ```
+ *
+ * @see {@link SplineWalker} - Component for moving objects along a spline path
+ * @see {@link SplineData} - The knot data structure used to define spline points
+ * @see {@link getPointAt} - Sample positions along the spline
+ * @see {@link getTangentAt} - Get direction vectors along the spline
+ * @see {@link addKnot} - Add control points to the spline
+ * @see {@link removeKnot} - Remove control points from the spline
+ *
+ * @summary Manages smooth spline curves defined by control point knots
  * @category Splines
  * @group Components
+ * @component
  */
 export declare class SplineContainer extends Behaviour {
     /**
-     * Adds a knot to the end of the spline.
+     * Adds a knot (control point) to the end of the spline.
+     *
+     * You can pass either a full {@link SplineData} object or a simple object with just a position.
+     * When passing a simple object, default values are used for rotation and tangents.
+     *
+     * The spline curve is automatically marked dirty and will be rebuilt on the next update.
+     *
+     * @param knot - Either a SplineData object or an object with at least a `position` property
+     * @returns This SplineContainer for method chaining
+     *
+     * @example Add knots with positions only
+     * ```ts
+     * spline.addKnot({ position: new Vector3(0, 0, 0) })
+     *       .addKnot({ position: new Vector3(5, 0, 0) })
+     *       .addKnot({ position: new Vector3(5, 0, 5) });
+     * ```
+     *
+     * @example Add a full SplineData knot
+     * ```ts
+     * const knot = new SplineData();
+     * knot.position.set(10, 2, 5);
+     * knot.rotation.setFromEuler(new Euler(0, Math.PI / 4, 0));
+     * spline.addKnot(knot);
+     * ```
      */
     addKnot(knot: SplineData | {
         position: Vector3;
     }): SplineContainer;
     /**
-     * Removes a knot by index or by reference.
+     * Removes a knot (control point) from the spline.
+     *
+     * You can remove a knot either by its numeric index in the spline array or by passing
+     * a reference to the SplineData object itself.
+     *
+     * The spline curve is automatically marked dirty and will be rebuilt on the next update.
+     *
+     * @param index - Either the numeric index of the knot to remove, or the SplineData object reference
+     * @returns This SplineContainer for method chaining
+     *
+     * @example Remove knot by index
+     * ```ts
+     * spline.removeKnot(0); // Remove first knot
+     * spline.removeKnot(spline.spline.length - 1); // Remove last knot
+     * ```
+     *
+     * @example Remove knot by reference
+     * ```ts
+     * const knotToRemove = spline.spline[2];
+     * spline.removeKnot(knotToRemove);
+     * ```
      */
     removeKnot(index: number | SplineData): SplineContainer;
     /**
-     * Gets a point on the spline in world space.
+     * Samples a point on the spline at a given parametric position (in world space).
+     *
+     * The parameter `t` ranges from 0 to 1, where:
+     * - `0` = start of the spline
+     * - `0.5` = middle of the spline
+     * - `1` = end of the spline
+     *
+     * The returned position is in world space, accounting for the SplineContainer's transform.
+     * Values outside 0-1 are clamped to the valid range.
+     *
+     * @param t - Parametric position along the spline (0 to 1)
+     * @param target - Optional Vector3 to store the result (avoids allocation)
+     * @returns The world-space position at parameter `t`
+     *
+     * @example Sample multiple points along the spline
+     * ```ts
+     * // Sample 20 evenly-spaced points
+     * const points: Vector3[] = [];
+     * for (let i = 0; i <= 20; i++) {
+     *   const t = i / 20;
+     *   points.push(spline.getPointAt(t));
+     * }
+     * ```
+     *
+     * @example Using a target vector for efficiency
+     * ```ts
+     * const reusableVector = new Vector3();
+     * for (let i = 0; i < 100; i++) {
+     *   const point = spline.getPointAt(i / 100, reusableVector);
+     *   // Use point...
+     * }
+     * ```
+     *
+     * @see {@link getTangentAt} to get the direction at a point
      */
     getPointAt(t: number, target?: Vector3): Vector3;
     /**
-     * Marks the spline as dirty, causing it to be rebuilt on the next update.
+     * Marks the spline as dirty, causing it to be rebuilt on the next update frame.
+     *
+     * Call this method whenever you manually modify the spline data (knot positions, rotations, or tangents)
+     * to ensure the curve is regenerated. This is done automatically when using {@link addKnot} or {@link removeKnot}.
+     *
+     * @example Modifying knots and marking dirty
+     * ```ts
+     * // Modify existing knot positions
+     * spline.spline[0].position.y += 2;
+     * spline.spline[1].position.x -= 1;
+     *
+     * // Tell the spline to rebuild
+     * spline.markDirty();
+     * ```
+     *
+     * @example Animating knot positions
+     * ```ts
+     * update() {
+     *   const time = this.context.time.time;
+     *   // Animate knot positions
+     *   for (let i = 0; i < spline.spline.length; i++) {
+     *     spline.spline[i].position.y = Math.sin(time + i) * 2;
+     *   }
+     *   spline.markDirty(); // Rebuild curve each frame
+     * }
+     * ```
      */
     markDirty(): void;
     /**
-     * Gets the tangent vector on the spline in world space.
+     * Samples the tangent (direction) vector on the spline at a given parametric position (in world space).
+     *
+     * The tangent represents the forward direction of the curve at point `t`. This is useful for:
+     * - Orienting objects along the spline (facing the direction of travel)
+     * - Calculating banking/tilting for vehicles on the path
+     * - Understanding the curve's direction at any point
+     *
+     * The parameter `t` ranges from 0 to 1 (same as {@link getPointAt}).
+     * The returned vector is normalized and in world space, accounting for the SplineContainer's rotation.
+     *
+     * @param t - Parametric position along the spline (0 to 1)
+     * @param target - Optional Vector3 to store the result (avoids allocation)
+     * @returns The normalized tangent vector in world space at parameter `t`
+     *
+     * @example Orient an object along the spline
+     * ```ts
+     * const position = spline.getPointAt(0.5);
+     * const tangent = spline.getTangentAt(0.5);
+     *
+     * object.position.copy(position);
+     * object.lookAt(position.clone().add(tangent)); // Face along the spline
+     * ```
+     *
+     * @example Calculate velocity direction for a moving object
+     * ```ts
+     * let t = 0;
+     * update() {
+     *   t += this.context.time.deltaTime * 0.2; // Speed
+     *   if (t > 1) t = 0; // Loop
+     *
+     *   const pos = spline.getPointAt(t);
+     *   const direction = spline.getTangentAt(t);
+     *
+     *   movingObject.position.copy(pos);
+     *   movingObject.quaternion.setFromUnitVectors(
+     *     new Vector3(0, 0, 1),
+     *     direction
+     *   );
+     * }
+     * ```
+     *
+     * @see {@link getPointAt} to get the position at a point
      */
     getTangentAt(t: number, target?: Vector3): Vector3;
+    /**
+     * Whether the spline forms a closed loop.
+     *
+     * **When `true`:**
+     * - The spline connects the last knot back to the first knot, forming a continuous loop
+     * - Perfect for racing tracks, patrol routes, or any circular path
+     * - Parameter `t=1` will smoothly connect back to `t=0`
+     *
+     * **When `false` (default):**
+     * - The spline is open, with distinct start and end points
+     * - Suitable for one-way paths, camera movements, or linear progressions
+     *
+     * Changing this property marks the spline as dirty and triggers a rebuild.
+     *
+     * @example Create a circular patrol route
+     * ```ts
+     * const patrol = gameObject.addComponent(SplineContainer);
+     * patrol.closed = true; // Loop back to start
+     *
+     * // Add points in a circle
+     * for (let i = 0; i < 8; i++) {
+     *   const angle = (i / 8) * Math.PI * 2;
+     *   patrol.addKnot({
+     *     position: new Vector3(Math.cos(angle) * 10, 0, Math.sin(angle) * 10)
+     *   });
+     * }
+     * ```
+     *
+     * @default false
+     */
     set closed(value: boolean);
     get closed(): boolean;
     private _closed;
-    /** Spline data. Call 'markDirty' if modified */
+    /**
+     * Array of knots (control points) that define the spline curve.
+     *
+     * Each element is a {@link SplineData} object containing position, rotation, and tangent information.
+     * You can directly access and modify this array, but remember to call {@link markDirty} afterwards
+     * to trigger a curve rebuild.
+     *
+     * **Best practices:**
+     * - Use {@link addKnot} and {@link removeKnot} methods for automatic dirty marking
+     * - If modifying knots directly, always call {@link markDirty} afterwards
+     * - The order of knots determines the path direction
+     *
+     * @example Direct array access
+     * ```ts
+     * console.log(`Spline has ${spline.spline.length} knots`);
+     *
+     * // Access first knot
+     * const firstKnot = spline.spline[0];
+     * console.log("Start position:", firstKnot.position);
+     *
+     * // Modify and mark dirty
+     * spline.spline[2].position.y += 5;
+     * spline.markDirty();
+     * ```
+     *
+     * @see {@link SplineData} for the knot data structure
+     * @see {@link addKnot} for adding knots (auto marks dirty)
+     * @see {@link removeKnot} for removing knots (auto marks dirty)
+     * @see {@link markDirty} to trigger rebuild after manual modifications
+     */
     spline: SplineData[];
-    /** Enable to render the spline curve for debugging */
+    /**
+     * Enables visual debug rendering of the spline curve.
+     *
+     * When enabled, the spline is rendered as a purple line in the scene, making it easy to
+     * visualize the path during development. The debug line automatically updates when the spline is modified.
+     *
+     * **Debug visualization:**
+     * - Purple line showing the complete curve path
+     * - Automatically rebuilds when spline changes
+     * - Line resolution based on number of knots (10 segments per knot)
+     *
+     * **Tip:** You can also enable debug visualization globally for all splines by adding `?debugsplines`
+     * to your URL.
+     *
+     * @example Enable debug visualization
+     * ```ts
+     * const spline = gameObject.addComponent(SplineContainer);
+     * spline.debug = true; // Show purple debug line
+     *
+     * // Add some knots to see the visualization
+     * spline.addKnot({ position: new Vector3(0, 0, 0) });
+     * spline.addKnot({ position: new Vector3(5, 2, 0) });
+     * spline.addKnot({ position: new Vector3(10, 0, 5) });
+     * ```
+     */
     set debug(debug: boolean);
-    /** Gets the spline curve generated from the 'spline' data */
+    /**
+     * The Three.js Curve object generated from the spline knots.
+     *
+     * This is the underlying curve implementation (typically a CatmullRomCurve3) that's used for
+     * all position and tangent sampling. The curve is automatically regenerated when the spline
+     * is marked dirty.
+     *
+     * **Note:** This curve is in local space relative to the SplineContainer. Use {@link getPointAt}
+     * and {@link getTangentAt} methods to get world-space results.
+     *
+     * @returns The generated Three.js Curve, or null if not yet built
+     */
     get curve(): Curve<Vector3> | null;
+    /**
+     * Whether the spline needs to be rebuilt due to modifications.
+     *
+     * The spline is marked dirty when:
+     * - Knots are added via {@link addKnot}
+     * - Knots are removed via {@link removeKnot}
+     * - {@link markDirty} is called manually
+     * - The {@link closed} property is changed
+     *
+     * The curve is automatically rebuilt on the next update frame when dirty.
+     *
+     * @returns `true` if the spline needs rebuilding, `false` otherwise
+     */
     get isDirty(): boolean;
     private _isDirty;
     private _curve;