HomeEngine API Reference - v2.20.0
    Preparing search index...

    Class JointComponentAlpha

    The JointComponent constrains the relative motion of two rigid bodies. The entity holding the joint component is not itself constrained - instead, its world transform defines the joint frame: the anchor point and axes that the constraint operates about. The constrained bodies are assigned via entityA and entityB, both of which must have a RigidBodyComponent. If entityB is null, entityA is constrained to a fixed point in world space.

    A joint's primary axis is the joint entity's local X axis: a hinge rotates about X, a slider translates along X and a ball joint twists about X. To aim a joint, rotate the joint entity. A common pattern is to parent the joint entity to entityA at the pivot point. For 6dof joints, each degree of freedom measures the offset of entityB (or of the world anchor when entityB is null) relative to entityA, along the joint's axes.

    The joint frames are captured when the underlying constraint is created - typically when the component is enabled and both bodies are present in the physics simulation. Moving the joint entity afterwards has no effect on an existing constraint. Call refreshFrames to re-capture the frames from the current world transforms. Entity scale is ignored, matching the behavior of rigid bodies.

    Many properties apply only to specific joint types; each one documents the types it affects, and properties without such a note (for example entityA, enableCollision and breakImpulse) apply to all types.

    To add a JointComponent to an Entity, use Entity#addComponent:

    // Create a door hinge: the joint entity's position is the hinge point and its
    // local X axis (rotated here to point up) is the hinge axis
    const hinge = new pc.Entity('hinge');
    hinge.setPosition(1, 1, 0);
    hinge.setEulerAngles(0, 0, 90);
    hinge.addComponent('joint', {
        type: pc.JOINTTYPE_HINGE,
        entityA: door,
        entityB: doorFrame,
        enableLimits: true,
        limits: new pc.Vec2(0, 110)
    });
    app.root.addChild(hinge);

    Hierarchy (View Summary)

    Index

    Properties

    entity system

    Accessors

    angularDamping angularEquilibrium angularLimitsX angularLimitsY angularLimitsZ angularMotionX angularMotionY angularMotionZ angularStiffness breakImpulse enableCollision enabled enableLimits entityA entityB isBroken limits linearDamping linearEquilibrium linearLimitsX linearLimitsY linearLimitsZ linearMotionX linearMotionY linearMotionZ linearStiffness maxMotorForce motorSpeed swingLimitY swingLimitZ twistLimit type

    Methods

    fire hasEvent off on onBeforeRemove once refreshFrames

    Events

    EVENT_BREAK

    Properties

    entity: Entity

    The Entity that this Component is attached to.

    system: ComponentSystem

    The ComponentSystem used to create this Component.

    Accessors

    • get angularStiffness(): Vec3
      Alpha

      Gets the stiffness of the springs acting on rotation about the joint's X, Y and Z axes.

      Returns Vec3

    • set angularStiffness(arg: Vec3): void
      Alpha

      Sets the stiffness of the springs acting on rotation about the joint's X, Y and Z axes. A spring acts on an axis when its stiffness component is greater than 0. Only used by 6dof joints. Defaults to [0, 0, 0] (no springs).

      Parameters

      Returns void

    • get breakImpulse(): number
      Alpha

      Gets the impulse threshold above which the joint breaks.

      Returns number

    • set breakImpulse(impulse: number): void
      Alpha

      Sets the impulse threshold, in Newton seconds, above which the joint breaks. A broken joint no longer constrains its bodies, fires the 'break' event and has isBroken set to true. As a rule of thumb, a steady force breaks the joint when force × simulation timestep exceeds this value. Defaults to Infinity (unbreakable).

      Parameters

      • impulse: number

      Returns void

    • get linearStiffness(): Vec3
      Alpha

      Gets the stiffness of the springs acting on translation along the joint's X, Y and Z axes.

      Returns Vec3

    • set linearStiffness(arg: Vec3): void
      Alpha

      Sets the stiffness of the springs acting on translation along the joint's X, Y and Z axes. A spring acts on an axis when its stiffness component is greater than 0. Only used by 6dof joints. Defaults to [0, 0, 0] (no springs).

      Parameters

      Returns void

    • get maxMotorForce(): number
      Alpha

      Gets the maximum force the joint's motor can apply.

      Returns number

    • set maxMotorForce(arg: number): void
      Alpha

      Sets the maximum force the motor can apply to reach motorSpeed. For hinge joints, this is a torque in Newton meters; for slider joints, a force in Newtons. The motor is disabled while this is 0, so set it greater than 0 to engage the motor. Only used by hinge and slider joints. Defaults to 0.

      Parameters

      • arg: number

      Returns void

    • get motorSpeed(): number
      Alpha

      Gets the target speed the motor drives towards.

      Returns number

    • set motorSpeed(arg: number): void
      Alpha

      Sets the target speed the motor drives towards. For hinge joints, this is an angular speed in degrees per second; for slider joints, a linear speed in meters per second. The motor is active only while maxMotorForce is greater than 0; with a target speed of 0 and a positive force the motor acts as a brake, holding the joint at rest. Only used by hinge and slider joints. Defaults to 0.

      Parameters

      • arg: number

      Returns void

    • get type(): "fixed" | "ball" | "hinge" | "slider" | "6dof"
      Alpha

      Gets the type of joint.

      Returns "fixed" | "ball" | "hinge" | "slider" | "6dof"

    • set type(type: "fixed" | "ball" | "hinge" | "slider" | "6dof"): void
      Alpha

      Sets the type of joint. Can be:

      • JOINTTYPE_FIXED: rigidly locks the bodies together.
      • JOINTTYPE_BALL: ball and socket - free rotation about the anchor point, with optional swing and twist limits.
      • JOINTTYPE_HINGE: rotation about the joint's X axis, with optional limits and motor.
      • JOINTTYPE_SLIDER: translation along the joint's X axis, with optional limits and motor.
      • JOINTTYPE_6DOF: each linear and angular axis is independently locked, limited or free, with optional springs.

      Defaults to JOINTTYPE_FIXED.

      Parameters

      • type: "fixed" | "ball" | "hinge" | "slider" | "6dof"

      Returns void

    Methods

    • Alpha

      Fire an event, all additional arguments are passed on to the event listener.

      Parameters

      • name: string

        Name of event to fire.

      • Optionalarg1: any

        First argument that is passed to the event handler.

      • Optionalarg2: any

        Second argument that is passed to the event handler.

      • Optionalarg3: any

        Third argument that is passed to the event handler.

      • Optionalarg4: any

        Fourth argument that is passed to the event handler.

      • Optionalarg5: any

        Fifth argument that is passed to the event handler.

      • Optionalarg6: any

        Sixth argument that is passed to the event handler.

      • Optionalarg7: any

        Seventh argument that is passed to the event handler.

      • Optionalarg8: any

        Eighth argument that is passed to the event handler.

      Returns EventHandler

      Self for chaining.

      obj.fire('test', 'This is the message');
    • Alpha

      Test if there are any handlers bound to an event name.

      Parameters

      • name: string

        The name of the event to test.

      Returns boolean

      True if the object has handlers bound to the specified event name.

      obj.on('test', () => {}); // bind an event to 'test'
      obj.hasEvent('test'); // returns true
      obj.hasEvent('hello'); // returns false
    • Alpha

      Detach an event handler from an event. If callback is not provided then all callbacks are unbound from the event, if scope is not provided then all events with the callback will be unbound.

      Parameters

      • Optionalname: string

        Name of the event to unbind.

      • Optionalcallback: HandleEventCallback

        Function to be unbound.

      • Optionalscope: any

        Scope that was used as the this when the event is fired.

      Returns EventHandler

      Self for chaining.

      const handler = () => {};
      obj.on('test', handler);

      obj.off(); // Removes all events
      obj.off('test'); // Removes all events called 'test'
      obj.off('test', handler); // Removes all handler functions, called 'test'
      obj.off('test', handler, this); // Removes all handler functions, called 'test' with scope this
    • Alpha

      Attach an event handler to an event.

      Parameters

      • name: string

        Name of the event to bind the callback to.

      • callback: HandleEventCallback

        Function that is called when event is fired. Note the callback is limited to 8 arguments.

      • Optionalscope: any = ...

        Object to use as 'this' when the event is fired, defaults to current this.

      Returns EventHandle

      Can be used for removing event in the future.

      obj.on('test', (a, b) => {
          console.log(a + b);
      });
      obj.fire('test', 1, 2); // prints 3 to the console

      const evt = obj.on('test', (a, b) => {
          console.log(a + b);
      });
      // some time later
      evt.off();
    • Alpha

      Attach an event handler to an event. This handler will be removed after being fired once.

      Parameters

      • name: string

        Name of the event to bind the callback to.

      • callback: HandleEventCallback

        Function that is called when event is fired. Note the callback is limited to 8 arguments.

      • Optionalscope: any = ...

        Object to use as 'this' when the event is fired, defaults to current this.

      Returns EventHandle

      Can be used for removing event in the future.

      obj.once('test', (a, b) => {
          console.log(a + b);
      });
      obj.fire('test', 1, 2); // prints 3 to the console
      obj.fire('test', 1, 2); // not going to get handled
    • Alpha

      Destroys and recreates the underlying constraint, re-capturing the joint frames from the current world transforms of the joint entity, entityA and entityB. Call this after moving the joint entity to re-anchor the joint, or to re-attach a joint that has broken.

      Returns void

    Events

    EVENT_BREAK: string = 'break'

    Fired when the applied impulse on the joint exceeds breakImpulse and the constraint breaks. The broken joint no longer constrains its bodies and isBroken becomes true. Call refreshFrames to re-attach it. Note that on ammo builds that expose no constraint state, breakage of 6dof joints cannot be detected, so this event does not fire for them - other joint types are unaffected.

    entity.joint.on('break', () => {
        console.log('The joint broke');
    });

    Settings

    Member Visibility

    On This Page

    Properties
    Accessors
    Methods
    Events