@needle-tools/engine/src/engine-components/AlignmentConstraint.ts

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.

import { Vector3 } from "three";

import { serializable } from "../engine/engine_serialization_decorator.js";
import * as utils from "./../engine/engine_three_utils.js";
import { Behaviour, GameObject } from "./Component.js";

/**
 * The [AlignmentConstraint](https://engine.needle.tools/docs/api/AlignmentConstraint) positions and scales this GameObject to span between two target objects.
 * The object is rotated to face `to` and scaled along Z to match the distance.  
 *
 * **Use cases:**  
 * - Dynamic beams or laser effects between objects  
 * - Stretchy connectors or ropes  
 * - Visual links between UI elements
 * - Debug lines between transforms
 *
 * **How it works:**  
 * - Position: Centered between `from` and `to` (or at `from` if not centered)
 * - Rotation: Looks at `to` from `from`
 * - Scale: Z-axis scales to match distance, X/Y use `width`
 *
 * @example Create a beam between two objects
 * ```ts
 * const beam = beamMesh.addComponent(AlignmentConstraint);
 * // Set targets via serialized properties in editor
 * // or via code if properties are exposed
 * ```
 *
 * @summary Aligns and scales object between two targets
 * @category Constraints
 * @group Components
 * @see {@link SmoothFollow} for following with smoothing
 **/
export class AlignmentConstraint extends Behaviour {

    @serializable(GameObject)
    private from: GameObject | undefined;
    @serializable(GameObject)
    private to: GameObject | undefined;

    private width: number = 0;
    private centered: boolean = true;
    private _centerPos!: Vector3;

    awake(): void {
        this._centerPos = new Vector3();
    }

    update() {
        if (!this.from || !this.to) return;
        
        const fromWorldPos = utils.getWorldPosition(this.from).clone();
        const toWorldPos = utils.getWorldPosition(this.to).clone();
        const dist = fromWorldPos.distanceTo(toWorldPos);
        
        this._centerPos.copy(fromWorldPos);
        this._centerPos.add(toWorldPos);
        this._centerPos.multiplyScalar(0.5);

        utils.setWorldPosition(this.gameObject, this.centered ? this._centerPos : fromWorldPos);
        this.gameObject.lookAt(utils.getWorldPosition(this.to).clone());
        this.gameObject.scale.set(this.width, this.width, dist);
    }
}