A type that describes physics joints.
`PhysicsJoint` objects are transient and define physics joints properties.
``PhysicsJointsComponent`` stores physics joints when added to an entity.
Each `PhysicsJoint` references two entities at local poses (position and orientation) specified on each ``Entity``.
The two pins of a physics joint, ``pin0`` and ``pin1``, each reference poses on the entities that make up each point on a `PhysicsJoint`.
Use two unique entities that both have a ``PhysicsBodyComponent``,
and belong to the same physics simulation.
Joints specify linear and angular limits of motion, limiting the motion of the second pin (``pin1``)
relative to the first pin (``pin0``).
To become active, the `PhysicsJoint` needs to be added to a ``PhysicsJointsComponent`` This is achieved by either directly on the component,
or by calling ``addToSimulation()``.
Once you add the joint to the simulation context, you no longer need to reference `PhysicsJoint` directly in your code.
For example, a ``PhysicsRevoluteJoint`` that connects a window, `windowEntity`, to a window frame, `frameEntity`:
```swift
let parentSimulationEntity = Entity()
// Add PhysicsSimulationComponent to parentSimulationEntity...
let frameEntity = Entity()
let windowEntity = Entity()
// Add PhysicsBodyComponents to the entities...
// Create a hinge the references points on the entities.
let windowWidth: Float = 1
let framePin = frameEntity.pins.set(
named: "FrameHinge",
// In this example, center of the frame is the center of its bounding box,
// so the hinge is half its width to the negative x direction.
position: [-windowWidth / 2, 0, 0],
// This hinge rotates around the x-axis, but this window needs to
// rotate around the y-axis.
// This rotation modifies the pin's positive x-axis to the positive y-axis.
orientation: simd_quatf(from: [1, 0, 0], to: [0, 1, 0])
)
// Get a previously created GeometricPin from `windowEntity`,
// or a new one create one as above.
let windowPin = GeometricPin(entity: windowEntity, pinName: "WindowHinge")
let windowHingeJoint = PhysicsRevoluteJoint(
pin0: framePin,
pin1: windowPin,
// Allow the hinge to rotate up to 90º.
angularLimit: 0...Float.pi
)
try windowHingeJoint.addToSimulation()
```
**Best practices:**
- When creating a joint, make sure that the jointed entities are initially positioned so that they satisfy the joint.
If not done so, the physics solver may have difficulty bringing the entities together to satisfy the joint.
- When connecting a ``PhysicsBodyMode/kinematic`` and a ``PhysicsBodyMode/dynamic`` entities by a joint,
use ``pin0`` as the pin on the kinematic entity.\
If both are ``PhysicsBodyMode/dynamic``, set the heavier entity as ``pin0``.
- Aim to make the entities connected by joints similar in mass.
- Add a ``PhysicsSimulationComponent`` to a common ancestor when creating
`PhysicsJoint` instances, to make it clear which physics simulation is used to solve the joints.
- To improve the the solving of the joints, adjust the value of the ``PhysicsSimulationComponent/solverIterations-swift.property`` property.
Adds this joint to the simulation.
This method looks for an ancestral ``Entity`` that has ``PhysicsJointsComponent``
by traversing upwards from the entity referenced by ``pin0``.
If found, it adds the joint to that ancestor's ``PhysicsJointsComponent``.
The traversal stops when reaching an ``Entity`` with ``PhysicsSimulationComponent``,
or when it cannot traverse up anymore.
In the former case it adds the joint to ``PhysicsJointsComponent/joints``.
In the latter case it adds ``PhysicsJointsComponent``
to the first ``Entity`` referenced by the joint, and adds the joint to the newly created ``PhysicsJointsComponent``.
- Returns: The entity that owns the ``PhysicsJointsComponent``, which this joint has been added to.
- Throws: When the joint contains invalid data.
