stingray.Joint object reference

Description

Interface to a physics joint.

A joint is a physical coupling between two actors or between an actor and the world.

For more background information about the concepts involved in physics joints, see also the PhysX documentation.

Constructors and accessors

stingray.PhysicsWorld.create_joint() stingray.Unit.create_custom_joint() stingray.Unit.create_joint()

Other related reference items

	stingray.PhysicsWorld.destroy_joint()
	Physics

Related help topics

Release Notes > Stingray 1.3 Release Notes

Enumerations

stingray.Joint.D6Axis Enumerates the degrees of freedom for a D6 joint.

stingray.Joint.D6Drive Enumerates drive modes for D6 joints.

stingray.Joint.D6Motion Enumerates the different modes available for each degree of freedom in a D6 joint.

stingray.Joint.DistanceFlag Flags that enable limits for DISTANCE joints.

stingray.Joint.RevoluteFlag Flags that enable limits for REVOLUTE joints.

stingray.Joint.Type Joint types.

Functions

d6_drive ( self, drive ) : number, number, number, boolean Returns the drive parameters for the specified D6 joint drive.

Parameters

self :	stingray.Joint	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
drive :	stingray.Joint.D6Drive	The degree of freedom for which the drive parameters should be retrieved. Is one of the D6Drive enum values: X, Y, Z, TWIST, SWING or SLERP.

Returns

number	The drive stiffness.
number	The drive damping.
number	The drive force limit.
boolean	Specify if the drive is an acceleration or a force/torque.

d6_drive_position ( self ) : stingray.Quaternion, stingray.Vector3 Returns the positional driving targets.

Parameters

self :

stingray.Joint

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

stingray.Quaternion	The orientation the drive is currently targeting for the second actor's frame, defined relative to the first actor's frame.
stingray.Vector3	The position the drive is currently targeting for the center of the second actor's frame, defined relative to the first actor's frame.

d6_drive_velocity ( self ) : stingray.Vector3, stingray.Vector3 Returns the linear & angular driving velocity targets.

Parameters

self :

stingray.Joint

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

stingray.Vector3	The drive target linear velocity.
stingray.Vector3	The drive target angular velocity.

d6_linear_limit_config ( self ) : table?

Parameters

self :

stingray.Joint

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

table?

Returns the linear limit for this D6 joint. D6 joints linear limits are configured with lower and upper limit values in meters. Like all other joint types, this table may also have the following shared parameters: restitution, bounceThreshold, stiffness, damping and contactDistance. The ? notation indicates that this type is optional: there may be zero or one instances of it.

d6_motion ( self, d6axis ) : stingray.Joint.D6Motion Returns the motion type of the specified degree of freedom for this joint.

Parameters

self :	stingray.Joint	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
d6axis :	stingray.Joint.D6Axis	The D6Axis (degree of freedom) for which the motion flag should be retrieved.

Returns

D6Motion

The D6Motion mode currently set for the specified DoF.

Other related reference items

stingray.Joint.limit_enabled()

d6_swing_limit_config ( self ) : table?

Parameters

self :

stingray.Joint

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

table?

Returns the swing limit parameter for this D6 joint. D6 joints swing limits are configured with yAngle and zAngle limit values in radians. Like all other joint types, this table may also have the following shared parameters: restitution, bounceThreshold, stiffness, damping and contactDistance. The ? notation indicates that this type is optional: there may be zero or one instances of it.

d6_swing_y_angle ( self ) : number Returns the current D6 Joint Y swing value.

Parameters

self :

stingray.Joint

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

number

The current D6 joint Y swing value, in radians.

d6_swing_z_angle ( self ) : number Returns the current D6 Joint Z swing value.

Parameters

self :

stingray.Joint

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

number

The current D6 joint Z swing value, in radians.

d6_twist ( self ) : number Returns the current D6 Joint twist value.

Parameters

self :

stingray.Joint

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

number

The current D6 joint twist value, in radians.

d6_twist_limit_config ( self ) : table?

Parameters

self :

stingray.Joint

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

table?

Returns the twist limit parameters for this D6 joint. D6 joints twist limits are configured with lower and upper limit values in radians. Like all other joint types, this table may also have the following shared parameters: restitution, bounceThreshold, stiffness, damping and contactDistance. The ? notation indicates that this type is optional: there may be zero or one instances of it.

distance_distance ( self ) : number Returns the current Joint distance.

Parameters

self :

stingray.Joint

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

number

The current joint distance, in meters.

distance_joint_flags ( self ) : number Returns the currently raised motion flags for this Distance joint.

Parameters

self :

stingray.Joint

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

number

The combination of DistanceFlag enum values that are currently raised.

distance_joint_flag_enabled ( self, flag ) : boolean Returns the specified motion flag activation status for this Distance joint.

Parameters

self :	stingray.Joint	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
flag :	stingray.Joint.DistanceFlag	One of the DistanceFlag enum values: MAX_DISTANCE_ENABLED, MIN_DISTANCE_ENABLED or SPRING_ENABLED.

Returns

boolean

The current status of the specified flag for this joint.

limit_config ( self ) : table? Gets the joint limit configuration.

Parameters

self :

stingray.Joint

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

table?

Returns the limit parameters for the joint. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Can be used for all joint types except D6 -- for D6 joints, use the d6_xxx_limit_config(...) functions.

The parameters in the returned table depend on the Joint type. See setup_limit() for details.

limit_enabled ( self ) : boolean Returns whether or not the limit is enabled for this joint.

Parameters

self :

stingray.Joint

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

boolean

The current limit activation status for this joint.

Suitable only for SPHERICAL, REVOLUTE & PRISMATIC joints. For D6 joints use d6_motion(), and for DISTANCE joints use [distance_joint_flag()].

prismatic_position ( self ) : number Returns the current PRISMATIC Joint distance along the X axis of the first actor's frame.

Parameters

self :

stingray.Joint

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

number

The current PRISMATIC Joint distance along the X axis, in meters.

prismatic_velocity ( self ) : number Returns the current PRISMATIC Joint velocity along the X axis of the first actor's frame.

Parameters

self :

stingray.Joint

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

number

The current PRISMATIC Joint velocity along the X axis, in meters per second.

revolute_angle ( self ) : number Returns the current REVOLUTE Joint angle value.

Parameters

self :

stingray.Joint

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

number

The current REVOLUTE Joint angle value, in radians.

revolute_drive_force_limit ( self ) : number Returns the drive force limit for this REVOLUTE joint.

Parameters

self :

stingray.Joint

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

number

The drive force limit for this revolute joint.

revolute_drive_gear_ratio ( self ) : number Returns the current drive gear ratio for this REVOLUTE joint.

Parameters

self :

stingray.Joint

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

number

The current drive gear ratio for this revolute joint.

revolute_drive_velocity ( self ) : number Returns the drive velocity target for this REVOLUTE joint.

Parameters

self :

stingray.Joint

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

number

The target velocity currently set for the drive on this revolute joint.

revolute_joint_flags ( self ) : number Returns the currently raised motion flags for this REVOLUTE joint.

Parameters

self :

stingray.Joint

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

number

The combination of RevoluteFlag enum values which are currently raised.

revolute_joint_flag_enabled ( self, flag ) : boolean Returns the specified motion flag activation status for this REVOLUTE joint.

Parameters

self :	stingray.Joint	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
flag :	stingray.Joint.RevoluteFlag	One of the RevoluteFlag enum values: LIMIT_ENABLED, DRIVE_ENABLED or DRIVE_FREESPIN.

Returns

boolean

The current status of the specified flag for this joint.

revolute_velocity ( self ) : number Returns the current REVOLUTE Joint angular velocity value.

Parameters

self :

stingray.Joint

Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.

Returns

number

The current REVOLUTE Joint angular velocity value, in radians per second.

setup_d6_linear_limit ( self, parameters ) Sets the linear limit for this D6 joint, but doesn't activate it.

Parameters

self :	stingray.Joint	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
parameters :	table	A (key, value) lua table defining the limit parameters.

Returns

This function does not return any values.

D6 joints linear limits are configured with lower and upper limit values in meters. Like all other joint types, you can also set up the following shared parameters: restitution, bounceThreshold, stiffness, damping and contactDistance.

setup_d6_swing_limit ( self, parameters ) Sets the swing limit parameter for this D6 joint, but doesn't activate it.

Parameters

self :	stingray.Joint	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
parameters :	table	A (key, value) lua table defining the limit parameters.

Returns

This function does not return any values.

D6 joints swing limits are configured with yAngle and zAngle limit values in radians. Like all other joint types, you can also set up the following shared parameters: restitution, bounceThreshold, stiffness, damping and contactDistance.

setup_d6_twist_limit ( self, parameters ) Sets the twist limit parameters for this D6 joint, but doesn't activate it.

Parameters

self :	stingray.Joint	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
parameters :	table	A (key, value) lua table defining the limit parameters.

Returns

This function does not return any values.

D6 joints twist limits are configured with lower and upper limit values in radians. Like all other joint types, you can also set up the following shared parameters: restitution, bounceThreshold, stiffness, damping and contactDistance.

setup_limit ( self, parameters ) Sets the limits for the joint, but doesn't activate them.

Parameters

self :	stingray.Joint	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
parameters :	table	A (key, value) lua table defining the limit parameters.

Returns

This function does not return any values.

This function is suitable for all joint types except D6 -- set up D6 joints using the set_d6_xxx_limit(...) functions.

The parameter set depends on the Joint type you are configuring.

• Linear limits for PRISMATIC joints are configured with lower and upper limit values in meters.
• Angular limits for REVOLUTE joints are configured with lower and upper limit values in radians.
• Cone limits for SPHERICAL joints are configured with yAngle and zAngle limit values in radians.
• Distance limits for DISTANCE joints are configured with minDistance and maxDistance limit values in meters.

All joint types also support the following shared parameters: restitution, bounceThreshold, stiffness, damping and contactDistance.

Other related reference items

stingray.Joint.limit_config()

set_break_force ( self, force, torque ) Sets the force and torque required to break a joint.

Parameters

self :	stingray.Joint	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
force :	number	Force required to break the joint.
torque :	number	Torque required to break the joint.

Returns

This function does not return any values.

set_d6_drive ( self, drive, stiffness, damping, force_limit, is_acceleration ) Setup the drive parameters for the given drive.

Parameters

self :	stingray.Joint	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
drive :	stingray.Joint.D6Drive	The degree of freedom on which the drive should be configured. Is one of the D6Drive enum values: X, Y, Z, TWIST, SWING or SLERP.
stiffness :	number	The drive stiffness.
damping :	number	The drive damping.
force_limit :	number	The drive force limit.
is_acceleration :	boolean?	Optional. Specify if the drive is an acceleration or a force/torque. Default is false, i.e. using force/torque. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

This function does not return any values.

set_d6_drive_position ( self, q, p ) Sets the positional driving target.

Parameters

self :	stingray.Joint	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
q :	stingray.Quaternion	The orientation to be targeted by the drives for the second actor's frame, defined relative to the first actor's frame.
p :	stingray.Vector3	The position to be targeted by the drives for the center of the second actor's frame, defined relative to the first actor's frame.

Returns

This function does not return any values.

set_d6_drive_velocity ( self, linear, angular ) Sets the velocity driving targets.

Parameters

self :	stingray.Joint	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
linear :	stingray.Vector3	The linear velocity target for drives.
angular :	stingray.Vector3	The angular velocity target for drives.

Returns

This function does not return any values.

set_d6_motion ( self, d6axis, motion ) Sets the motion type to the specified degree of freedom.

Parameters

self :	stingray.Joint	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
d6axis :	stingray.Joint.D6Axis	The D6Axis (degree of freedom) on which the motion flag should be set.
motion :	stingray.Joint.D6Motion	The D6Motion mode to apply on the specified DoF.

Returns

This function does not return any values.

Other related reference items

stingray.Joint.set_limit_enabled()

set_distance_joint_flags ( self, flags ) Sets the motion flags for this Distance joint.

Parameters

self :	stingray.Joint	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
flags :	number	Any combination of DistanceFlag enum values: MAX_DISTANCE_ENABLED, IN_DISTANCE_ENABLED and SPRING_ENABLED.

Returns

This function does not return any values.

set_distance_joint_flag_enabled ( self, flag, do_enable ) Setups the specified motion flag activation status for this Distance joint.

Parameters

self :	stingray.Joint	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
flag :	stingray.Joint.DistanceFlag	One of the DistanceFlag enum values: MAX_DISTANCE_ENABLED, MIN_DISTANCE_ENABLED or SPRING_ENABLED.
do_enable :	boolean	true to raise the flag, false to turn it down.

Returns

This function does not return any values.

set_limit_enabled ( self, do_enable ) Determines whether or not the limit should be enabled for this joint.

Parameters

self :	stingray.Joint	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
do_enable :	boolean	Use true to enable the limit for this Joint, or false to disable it.

Returns

This function does not return any values.

Suitable only for SPHERICAL, REVOLUTE & PRISMATIC joints. For D6 joints use set_d6_motion(), and for DISTANCE joints use [set_distance_joint_flag()].

set_revolute_drive_force_limit ( self, limit ) Sets the drive force limit for this REVOLUTE joint.

Parameters

self :	stingray.Joint	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
limit :	number	The drive force limit for this revolute joint.

Returns

This function does not return any values.

set_revolute_drive_gear_ratio ( self, ratio ) Sets the drive gear ratio for this REVOLUTE joint.

Parameters

self :	stingray.Joint	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
ratio :	number	The drive gear ratio for this revolute joint.

Returns

This function does not return any values.

set_revolute_drive_velocity ( self, velocity ) Sets the drive velocity target for this REVOLUTE joint.

Parameters

self :	stingray.Joint	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
velocity :	number	The drive velocity target for this revolute joint.

Returns

This function does not return any values.

set_revolute_joint_flags ( self, flags ) Sets the specified motion flags for this REVOLUTE joint.

Parameters

self :	stingray.Joint	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
flags :	number	Any combination of RevoluteFlag enum values: LIMIT_ENABLED, DRIVE_ENABLED and DRIVE_FREESPIN.

Returns

This function does not return any values.

set_revolute_joint_flag_enabled ( self, flag, do_enable ) Setups the specified motion flag activation status for this REVOLUTE joint.

Parameters

self :	stingray.Joint	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
flag :	stingray.Joint.RevoluteFlag	The flag to be raised or turn off. Must be one of the RevoluteFlag enum values: LIMIT_ENABLED, DRIVE_ENABLED or DRIVE_FREESPIN.
do_enable :	boolean	true to raise the flag, false to turn it down.

Returns

This function does not return any values.