@needle-tools/engine
Version:
Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.
95 lines (94 loc) • 3.83 kB
TypeScript
import { Object3D } from "three";
import { Axes } from "../engine/engine_physics.types.js";
import { Behaviour } from "./Component.js";
/**
* [SmoothFollow](https://engine.needle.tools/docs/api/SmoothFollow) makes this GameObject smoothly follow another target object's position and/or rotation.
*
* **Position Following:**
* When enabled (`followFactor > 0`), this object will move towards the target's world position.
* The object interpolates from its current position to the target's position each frame.
* Use `positionAxes` to restrict following to specific axes (e.g., only horizontal movement).
*
* **Rotation Following:**
* When enabled (`rotateFactor > 0`), this object will rotate to match the target's world rotation.
* The object smoothly interpolates from its current rotation to the target's rotation each frame.
* This makes the object face the same direction as the target, not look at it (use {@link LookAt} for that).
*
* **Smoothing:**
* Both position and rotation use time-based interpolation (lerp/slerp).
* Higher factor values = faster following (less lag), lower values = slower following (more lag).
* Set a factor to 0 to disable that type of following entirely.
*
* **Common Use Cases:**
* - Camera following a player character
* - UI elements tracking world objects
* - Delayed motion effects (ghost trails, spring arms)
* - Smoothed object attachment
*
* @example Follow a target with smooth position
* ```ts
* const follower = myObject.addComponent(SmoothFollow);
* follower.target = playerObject;
* follower.followFactor = 5; // Higher = faster following
* follower.rotateFactor = 0; // Don't follow rotation
* ```
*
* @example Follow only on horizontal plane
* ```ts
* follower.positionAxes = Axes.X | Axes.Z; // Follow X and Z only (no vertical)
* ```
*
* @example Follow both position and rotation
* ```ts
* follower.target = targetObject;
* follower.followFactor = 3; // Smooth position following
* follower.rotateFactor = 2; // Smooth rotation following
* ```
*
* @summary Smoothly follows a target object's position and/or rotation
* @category Interactivity
* @group Components
* @see {@link LookAtConstraint} for making an object look at a target (different from rotation following)
* @see {@link Mathf} for the interpolation used
*/
export declare class SmoothFollow extends Behaviour {
/**
* The target to follow. If null, the GameObject will not move.
*/
target: Object3D | null;
/**
* Speed factor for position following.
* Controls how quickly this object moves to match the target's position.
* Higher values = faster/tighter following (less lag), lower = slower/looser (more lag).
* Set to 0 to disable position following entirely.
* @default 0.1
*/
followFactor: number;
/**
* Speed factor for rotation following.
* Controls how quickly this object rotates to match the target's rotation.
* Higher values = faster/tighter following (less lag), lower = slower/looser (more lag).
* Set to 0 to disable rotation following entirely.
* @default 0.1
*/
rotateFactor: number;
/**
* Which position axes to follow. Use bitwise OR to combine:
* `Axes.X | Axes.Y` follows only X and Y axes.
* @default Axes.All
*/
positionAxes: Axes;
/** When true, rotates 180° around Y axis (useful for mirrored setups) */
flipForward: boolean;
private static _invertForward;
private _firstUpdate;
/**
* Update the position and rotation of the GameObject to follow the target.
*/
onBeforeRender(): void;
/**
* Manually update the position/rotation to follow the target.
* @param hard If true, snaps instantly to target without smoothing
*/
updateNow(hard: boolean): void;
}