View source for JointEntity

[[File:Gyroscope.gif|thumb|A gyroscope created with HingeJoints and collision boxes]]

Joints can be used in a multitude of ways to allow different kinds of rotations and translations around and on different axes. Some uses include:
* a single object rotating about one of it's axes (X/Y/ZHingeJoint)
* two objects rotating freely to any direction in relation to each other (SphericalJoint)
* a single object being attached to something and not allowed to move in any way (X/Y/Z/HingeJoint with RotationLimitAngles = 0)
* two objects attached to each other and allowed to translate a discrete amount on one axis (PrismaticJoint)

These are just a few examples of possible uses of joints. Many imaginative ways of movement and rotation are possible with a clever combination of joints.

A detailed explanation of each joint can be found from [https://developer.nvidia.com/sites/default/files/akamai/physx/Manual/Joints.html NVIDIA PhysX SDK Documentation about joints]

== Properties of joints ==
Joints can be found from InstanceBase->Entity->JointEntity.
=== HingeJoint ===
HingeJoint can be used as a fixed joint that doesn't allow a dynamic object to move or as a joint that allows rotation around one specific axis. Note, that the rotation axis is defined in the '''local coordinates''' of the joint, not in the global coordinates of the scene. This means that the rotation axis ''on the scene'' can be chosen freely, if the joint is rotated.
[[File:Joints.png|thumb|HingeJointEntity and it's properties]]
[[File:Softlimits.gif|thumb|Soft limit on the rotation of a HingeJoint]]
[[File:Hardlimit.gif|thumb|Hard limit on the rotation of a HingeJoint]]

Most of the properties between different joints are the same, but there are a few exceptions. Here's a list of the most important properties of HingeJoints (HingeJointEntity, XHingeJoint, YHingeJoint and ZHingeJoint) and a short explanation of what they affect and what's their purpose (again, a more in depth explanation can be found from [https://developer.nvidia.com/sites/default/files/akamai/physx/Manual/Joints.html PhysX documentation]). If the same properties are found on other joints, the reader is referred back to this list.

* Component0
** This and the next property control which objects the joints are attached to. At least one component needs to be set to an object on the scene, otherwise it gives and error. In the picture on the right, neither Component0 or Component1 are set (they both read "GUID_NONE"), which gives the following error: " --- ERROR --- bool validJoint, Joint isn't valid, component0 is invalid or UH_NONE. If component1 is defined, it may be invalid UH. --- HingeJointComponent GUID('0x60280F25','0xBBCE0013','0xDC77030A','0x00003353')"
* Component1
** It's possible to set only Component0 to some object on the scene and leave Component1 to it's default value (or the other way around). In this case, the object that the lone Component0/1 points to is "attached to the wall" on the scene. This means, that the object rotates or moves according to the joint used at the location of the joint. Conversely, if both components point to a different object, then these objects behave according to the joint in relation to each other and not in relation to the scene.
* Enabled
** Self-explanatory.
* RotationLimitLowAngle
** How many degrees is the joint allowed to rotate to the negative direction (negative according to the [https://en.wikipedia.org/wiki/Right-hand_rule right-hand rule]).
* RotationLimitHighAngle
** How many degrees is the joint allowed to rotate to the positive direction (positive according to the [https://en.wikipedia.org/wiki/Right-hand_rule right-hand rule]). Note, that the sum of the absolute values of the RotationLimitLow/HighAngles should be 360, if the joint needs to rotate a full circle.
* RotationLimitSpring
** According to [https://developer.nvidia.com/sites/default/files/akamai/physx/Manual/Joints.html#limits PhysX documentation]"''Limits may be either hard or soft. When a hard limit is reached, relative motion will simply stop dead (or, if you configure the limit with non-zero restitution, it will bounce.) When a soft limit is violated, the solver will pull the joint back towards the limit using a spring specified by the limit's spring and damping parameters.''" RotationLimitSpring determines the stiffness of the spring for the soft limit, i.e. how strongly the object bounces back when it reaches the RotationLimitAngle.
* RotationLimitDamping
** Damping determines how fast the "bouncing between limits" will die down. High value of damping kills the oscillations fast.
* PositionLimitDistance
** A limit for the distance of translatory movement.
* PositionLimitSpring
** The same principle as with RotationLimitSpring, but for translatory movement.
* PositionLimitDamping
** See above.
* PositionLockX/Y/Z
** Does the joint allow translatory movement on some axis or not.
* BreakForce
** How much force is needed to break the joint. If enough force is applied, the joint breaks down and the objects bound by the joint are free. See "Broken" below.
* RotationDriveVelocity
** Rotation drive causes the joint to apply rotation to the objects by itself. RotationDriveVelocity determines the target velocity of the rotational motion.
* RotationDriveForce
** Maximum target force the drive is allowed to reach. The force applied by the drive to the joint is calculated with the following formula: ''force = spring * (targetPosition - position) + damping * (targetVelocity - velocity)''. If the force is small, the drive won't be able to reach high rotational velocities, even if target velocity and damping are very large.
* RotationDriveDamping
** A constant coefficient that determines how fast the maximum target force is reached and what's the contribution of velocity towards it.
* Broken
** Is the joint broken or not. See "BreakForce" above.
* HingeAxis
** Which axis (x = 0,y = 1 or z = 2) does the joint rotate about.

=== PrismaticJoint ===
[[File:Prismatic.gif|thumb|PrismaticJoint]]
Prismatic joints don't allow rotation, but allows translatory movement of the object(s). The most important properties of PrismaticJoints are:
* Component0
** See HingeJoint.
* Component1
** See HingeJoint.
* Enabled
** Self-explanatory.
* LocalPosition0
** Position of the joint relative to Component0.
* LocalRotation0
** Rotation of the joint relative to Component0. Note: If you want to use the prismatic joint on another axis than x-axis, use these properties to alter the angle. In other words, if you want to make a prismatic joint for the y-axis, you can rotate the joint 90 degrees about the z-axis '''with these properties'''. It's not enough to rotate the joint itself in the editor window with the rotate tool, this '''does not''' alter the direction of the movement, it only changes the rotation of the model component of the prismatic joint, which is only for visualization purposes and doesn't actually affect anything.
* LocalPosition1
** Position of the joint relative to Component1.
* LocalRotation1
** Rotation of the joint relative to Component1. Read LocalRotation0 above.
* MinDistance
** The distance the object(s) are allowed to move in the direction of the negative x-axis (before LocalRotations).
* MaxDistance
** The distance the object(s) are allowed to move in the direction of the positive x-axis (before LocalRotations).
* Spring
** When Min/MaxDistance is reached, this spring pushes the object back towards the centre. If this value is 0, the joint has a hard limit at both ends. See HingeJoint RotationLimitSpring for more info about hard and soft limits.
* SpringDamper
** How fast the oscillations die down at the Min/MaxDistance, if soft limit is in use.

=== SphericalJoint ===
[[File:Spherical_prismatic_hinge.gif|thumb|A simple system with three different joints.]]

SphericalJoint allows objects to rotate freely to any direction. It can also be used to create a more constrained spherical rotations.
SphericalJoint has just a few properties:
* Component0
** See HingeJoint.
* Component1
** See HingeJoint.
* Enabled
** Self-explanatory.
* RotationLimitSpring
** See HingeJoint.
* RotationLimitDamping
** See HingeJoint.
* AngleY
** The amount the object is allowed to rotate on the y-axis.
* AngleZ
** The amount the object is allowed to rotate on the z-axis. Note: Free spherical rotation is possible when both AngleY/Z are set to 180.

=== PulleyJoint ===
[[File:Pulley.gif|thumb|A simple counterweight system created with a PulleyJoint.]]
PulleyJoints are used in counterweight systems. They share most of the properties with other joints:

* Component0
** See HingeJoint.
* Component1
** See HingeJoint.
* Enabled
** Self-explanatory.
* LocalPosition0
** Position of the joint relative to Component0.
* LocalRotation0
** Rotation of the joint relative to Component0. (Not sure if this affects anything.)
* LocalPosition1
** Position of the joint relative to Component1.
* LocalRotation1
** Rotation of the joint relative to Component1. (Not sure if this affects anything.)
* Stiffness
** How stiff the pulley constraint is.
* Ratio
** This property ''should'' determine how much force is applied to object of Component1 in relation to object of Component0, but currently it doesn't work.

== Tips & Tricks ==
Here are some additional miscellaneous things you can do with joints.
* Using two HingeJoints for a rotating object:
** One with a soft limit and smaller RotationLimitAngles
** One with a hard limit and larger RotationLimitAngles