attachChild

From Bohemia Interactive Community
Hover & click on the images for description
Only available in Development branch(es) until its release with Arma 3 patch v2.22.

Description

Description:
🏗
This article is a work in progress!

Attaches a child object to a parent, similar to attachTo but instead of a rigid/forced attachment its using a PhysX joint.

For more information see NVIDIA docs.
Does NOT behave well in Multiplayer!
Note that the joint parameters XYZ orientations, are according to the localFrame of the joint. swingZ/swingY/twist being Yaw/Roll/Pitch, can be changed if the joint itself is rotated, because the joint rotation moves the whole axis.
Groups:
PhysX

Syntax

Syntax:
[parent, child] attachChild [jointType, localFrameParent, localFrameChild, miscFlags, jointDescription]
Parameters:
parent: Object - The parent object that another object is attached to. Must be a Transport vehicle like Car/Tank (Maybe helicopter/airplane works?).
child: Object - The object being attached onto the parent. Must be a Transport vehicle like Car/Tank (Maybe helicopter/airplane works?).
jointType: String - Currently only "6DOFJoint" and "RevoluteJoint" and "FixedJoint"
6DOFJoint
Allows to configure all axis (XYZ translation, Pitch/Yaw/Roll rotation) limits and drives.
RevoluteJoint
Only allows rotation around the X axis, a Revolute joint can also be implemented with a 6DOFJoint and the appropriate limits (internally it is implemented exactly like that)
FixedJoint
Limited in all axis, it essentially works like a PhysX based attachTo.
localFrameParent: Array - The Position and orientation, in parent's model-space of where the joint will be placed.
An Array of 3 elements [position, upPos, dirPos]
Each element can either be a Vector (3-element array of Number) or a Memory point name (String).


An important Caveat when using Vectors is that dir and up are not direction vectors, but positions.
Essentially, upPos/dirPos would be the model-space coordinates of where the memory point would be.
For example:
_jointPos = [0,0,0]; _vectorDir = [0,1,0]; _vectorUp = [0,0,1]; [_jointPos, _jointPos vectorAdd _vectorDir, _jointPos vectorAdd _vectorUp];
localFrameChild: Array - The Position and orientation, in child's model-space of where the joint will be placed.
miscFlags: Array - [(collisionEnabled, breakForce)]
collisionEnabled: Boolean (Optional, Default: false) - When false, disables collision between the two joint-ed objects
breakForce: Number (Optional, Default: -1)
limitsAreForces?
jointDescription: Array - This specifies the behavior/limits of the joint.
[(linearLimit, swingLimit, twistLimit, drives)]

Note that all are optional. Passing an empty array is equivalent to using a "FixedJoint" type

linearLimit
Array - Linear limit specifies the joints permitted translation along the XYZ axis.
There are three types of linear limits, fully locked, per-axis limit and distance limit.

Fully Locked:
[]
Empty array, will completely lock the XYZ translational axes, only allowing rotational movement (If allowed in the swing/twist limits)
Per axis:
[limitX, limitY, limitZ]
limit*:
Array - [lowerLimit, upperLimit, springParameters]
lowerLimit:
Number - The minimum permitted offset on the axis
upperLimit:
Number - The maximum permitted offset on the axis
upperLimit must be larger than lowerLimit
springParameters:
Array - [(restitution, spring, damping)]
All spring parameters are optional, but for the linear limits, atleast an empty array must be provided.
restitiution:
Number (Optional, Default: 0) - Must be between 0-1.
Controls the amount of bounce when the joint hits a limit.
A restitution value of 1.0 causes the joint to bounce back with the velocity which it hit the limit.
A value of zero causes the joint to stop dead.
NVIDIA docs
spring:
Number (Optional, Default: 0) - Must be 0 or greater.
if greater than zero, the limit is soft, i.e. a spring pulls the joint back to the limit
damping:
Number (Optional, Default: 0) - Must be 0 or greater. if spring is greater than zero, this is the damping of the limit spring
Distance Limit
[xLocked, yLocked, zLocked, distanceLimit, springParameters]
*Locked:
Boolean - Whether the axis is completely locked and no translation is allowed along it
distanceLimit:
Number - Distance on meters, as a radius/sphere around the joint.
swingLimit:
Array - [(swingX, swingZ, springParameters)]
All parameters are optional, the default is both swing axis being locked
Swing limit comes in two types, cone and pyramid. Which variant is used depends on the datatype inside the swing parameter
Note that cone cannot be combined with pyramid, either both are cone or both are pyramid.
If the swing limit is pi, the rotation around that axis is fully unlocked/free.
Cone limit:
swingZ: Number (Optional, Default 0/locked) - The rotation around the Z (up) axis, thus the yaw. Rotation in radians, between pi and pi.
swingY: Number (Optional, Default 0/locked) - The rotation around the Y (front/dir) axis, thus the roll. Rotation in radians, between pi and pi.
Pyramid limit:
swingZ: Array - [(min, max)] - Same rotation in radians as the cone limit, but it can be asymmetrical.
swingY: Array - [(min, max)] - Same rotation in radians as the cone limit, but it can be asymmetrical.
twistLimit:
Array - [(twistLower, twistUpper, springParameters)]
Twist is rotation about the X (right) axis, thus the pitch.
Left and right twist limits can be configured independently.
twist*:
Number (Optional, Default: 0) - Rotation limit in radians, between -2pi and 2pi
0 means twist is locked, and 2*pi means its completely unlocked
drives:
Array - [(angularSwingDrive, angularTwistDrive, angularSlerpDrive, linearXDrive, linearYDrive, linearZDrive, limitsAreForces)]
Drives allow to apply force into the joint on any of the axes.
Each drive is a spring, one end being on the joint, and the other end being on the target specified by the commands:
setJointDrivePosition setJointDriveOrientation setJointDriveLinearVelocity setJointDriveAngularVelocity
For rotational drives there are two variants, Swing+Twist or SLERP (Spherical Linear Interpolation)
See NVIDIA docs
*Drive:
Array - [type, spring, damping, forceLimit]
type:
Number - MUST be 0 (#TODO acceleration drive implementation?)
spring:
Number - Same as springParameters above
damping:
Number - Same as springParameters above
forceLimit:
Number - The maximum force this drive c an apply to the joint
limitsAreForces:
Boolean (Optional, Default: true) - NOT IMPLEMENTED #TODO?
Return Value:
Nothing - Do NOT depend on this staying nothing, it might change to be something.

Examples

Example 1:
Attach a Quad (varname towbar) to a HEMTT (varName vParent) and another HEMTT (varName vChild) to the Quad. Essentially using the Quad as a "towbar"
_parentPos = [0,-5,0]; // position on the hemtt _childPos = [0,1,-0.2]; // position on the quad _jointDescription = [ // Limits // Linear [], // Default is locked // Swing // [swing1 yaw, swing2 roll, springParams] [ rad 45, // yaw 0 // roll ], // Twist pitch // [twistLower, twistUpper, springParams] [rad -20, rad 20], // Default is locked // Drives [] // Default are none ]; _params = [ "6DOFJoint", // From [pos,dir,up] [_parentPos, _parentPos vectorAdd [0, 1, 0], _parentPos vectorAdd [0, 0, 1]], // To [pos,dir,up] [_childPos, _childPos vectorAdd [0, 1, 0], _childPos vectorAdd [0, 0, 1]], // misc [collisions enabled] [false], _jointDescription ]; [vParent, towBar] attachChild _params; _parentPos = [0,-1,-0.2]; // Position on the quad _childPos = [0,5,0]; // Position on the hemtt _params = [ "6DOFJoint", // From [pos,dir,up] [_parentPos, _parentPos vectorAdd [0, 1, 0], _parentPos vectorAdd[0, 0, 1]], // To [pos,dir,up] [_childPos, _childPos vectorAdd [0, 1, 0], _childPos vectorAdd [0, 0, 1]], // misc [collisions enabled] [false], _jointDescription ]; [towBar, vChild] attachChild _params;
Example 2:
Attach a Quad (varname towbar) to a HEMTT (varName vParent) and another HEMTT (varName vChild) to the Quad. But we rotate the axis so that Swing's are Pitch/Yaw and Twist is roll
_parentPos = [0,-5,0]; // position on the hemtt _childPos = [0,1,-0.2]; // position on the quad _jointDescription = [ // Limits // Linear [], // Default is locked // Swing // [swing1 pitch, swing2 yaw, springParams] [ rad 20, // pitch rad 45 // yaw ], // Twist roll // [twistLower, twistUpper, springParams] [], // Default is locked // Drives [] // Default are none ]; _params = [ "6DOFJoint", // From [pos,dir,up] [_parentPos, _parentPos vectorAdd [0, 0, 1], _parentPos vectorAdd [1, 0, 0]], // Note how the up is pointing right and forward is pointing down, we are rotating the whole joint // To [pos,dir,up] [_childPos, _childPos vectorAdd [0, 0, 1], _childPos vectorAdd [1, 0, 0]], // misc [collisions enabled] [false], _jointDescription ]; [vParent, towBar] attachChild _params; _parentPos = [0,-1,-0.2]; // Position on the quad _childPos = [0,5,0]; // Position on the hemtt _params = [ "6DOFJoint", // From [pos,dir,up] [_parentPos, _parentPos vectorAdd [0, 0, 1], _parentPos vectorAdd [1, 0, 0]], // To [pos,dir,up] [_childPos, _childPos vectorAdd [0, 0, 1], _childPos vectorAdd [1, 0, 0]], // misc [collisions enabled] [false], _jointDescription ]; [towBar, vChild] attachChild _params;
Example 3:
-no SQF code provided-
Example 4:
-no SQF code provided-
Example 5:
-no SQF code provided-

Additional Information

See also:
detachChild setJointDrivePosition setJointDriveOrientation setJointDriveLinearVelocity setJointDriveAngularVelocity childAttached parentAttached

Notes

Report bugs on the Feedback Tracker and/or discuss them on the Arma Discord or on the Forums.
Only post proven facts here! Add Note