@needle-tools/engine/src/engine-components/Joints.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.js";
import { Behaviour } from "./Component.js";
import { Rigidbody } from "./RigidBody.js";

/**
 * Base class for physics joints that connect two {@link Rigidbody} components.
 * Joints constrain how two bodies can move relative to each other.
 *
 * The joint is created between:
 * - The {@link Rigidbody} on this GameObject (automatically found)
 * - The {@link connectedBody} Rigidbody you specify
 *
 * @summary Connect two Rigidbodies with physics constraints
 * @category Physics
 * @group Components
 * @see {@link FixedJoint} for rigid connections
 * @see {@link HingeJoint} for rotating connections
 * @see {@link Rigidbody} for physics bodies
 */
export abstract class Joint extends Behaviour {
    /** The other Rigidbody to connect to */
    @serializable(Rigidbody)
    connectedBody?: Rigidbody;

    get rigidBody(): Rigidbody | null {
        return this._rigidBody;
    }
    private _rigidBody: Rigidbody | null = null;


    onEnable() {
        if (!this._rigidBody) this._rigidBody = this.gameObject.getComponent(Rigidbody);
        if (this.rigidBody && this.connectedBody)
            this.startCoroutine(this.create());
    }

    private *create() {
        yield;
        if (this.rigidBody && this.connectedBody && this.activeAndEnabled) {
            this.createJoint(this.rigidBody, this.connectedBody)
        }
    }

    protected abstract createJoint(self: Rigidbody, other: Rigidbody);
}

/**
 * FixedJoint locks two {@link Rigidbody} components together, making them move as one rigid unit.
 * The bodies maintain their relative position and rotation at the time the joint is created.
 *
 * Use this for:
 * - Attaching objects together permanently
 * - Creating compound rigid bodies
 * - Welding broken pieces back together
 *
 * @example Attach a weapon to a character
 * ```ts
 * const joint = weapon.addComponent(FixedJoint);
 * joint.connectedBody = characterRigidbody;
 * ```
 *
 * @summary Lock two Rigidbodies together rigidly
 * @category Physics
 * @group Components
 * @see {@link Joint} base class
 * @see {@link HingeJoint} for rotating connections
 */
export class FixedJoint extends Joint {

    protected createJoint(self: Rigidbody, other: Rigidbody) {
        this.context.physics.engine?.addFixedJoint(self, other);
    }
}

/**
 * HingeJoint connects two {@link Rigidbody} components with a rotating constraint,
 * like a door hinge or wheel axle. Bodies can only rotate around the specified axis.
 *
 * Use this for:
 * - Doors and gates
 * - Wheels and axles
 * - Pendulums
 * - Any rotating mechanical connection
 *
 * @example Create a door hinge
 * ```ts
 * const hinge = door.addComponent(HingeJoint);
 * hinge.connectedBody = doorFrameRigidbody;
 * hinge.anchor = new Vector3(0, 0, 0); // Hinge position
 * hinge.axis = new Vector3(0, 1, 0);   // Rotate around Y axis
 * ```
 *
 * @summary Connect two Rigidbodies with a rotating hinge
 * @category Physics
 * @group Components
 * @see {@link Joint} base class
 * @see {@link FixedJoint} for rigid connections
 */
export class HingeJoint extends Joint {

    /** Local position of the hinge pivot point */
    @serializable(Vector3)
    anchor?: Vector3;

    /** Axis of rotation for the hinge (e.g., Vector3(0,1,0) for vertical axis) */
    @serializable(Vector3)
    axis?: Vector3;

    protected createJoint(self: Rigidbody, other: Rigidbody) {
        if (this.axis && this.anchor)
            this.context.physics.engine?.addHingeJoint(self, other, this.anchor, this.axis);
    }

}