SM Docs
Docs›Game›Userdata›Joint

Joint

Availability
Server + Client
Serializable
Yes
Associated namespace
sm.joint

A userdata object representing a joint in the game.

Values:

  • angle [ number ]

    • Get: The bearing's angle. The angle ranges between -math.pi and +math.pi.

  • angularVelocity [ number ]

  • appliedImpulse [ number ]

  • color [ Color ]

    • Get: Returns the color of a joint.
    • Set: (Server-Only) Sets the color of a joint.

  • id [ integer ]

    • Get: Returns the id of a joint.

  • length [ number ]

    • Get: Returns the current length of a piston. The length is measured in blocks.

  • localPosition [ Vec3 ]

    • Get: Returns the local position of a joint.

  • localRotation [ Quat ]

    • Get: Returns the local rotation of a joint.

  • reversed [ boolean ]

    • Get: Returns whether a bearing has been reversed using the Connect Tool. A reversed bearing rotates counterclockwise.

  • shapeA [ Shape ]

    • Get: Returns the Shape a joint is attached to. This shape does always exist.
      Result: The joint's first shape.

  • shapeB [ Shape ]

    • Get: Returns the Shape that is attached to a joint on another Body. This method returns nil if there is no shape attached to the joint.
      Result: The joint's second shape.

  • shapeUuid [ Uuid ]

    • Get: Returns the uuid string unique to a joint type.

  • type [ string ]

    • Get: One of the joint's type found in (sm.joint.types).

  • uuid [ Uuid ]

    • Get: Returns the uuid string unique to a joint type.

  • worldPosition [ Vec3 ]

    • Get: Returns the world position of a joint.

  • xAxis [ Vec3 ]

    • Get: Returns the local x-axis vector of a joint.

  • yAxis [ Vec3 ]

    • Get: Returns the local y-axis vector of a joint.

  • zAxis [ Vec3 ]

    • Get: Returns the local z-axis vector of a joint.

Operations:

Operation Returns Description
Joint == Joint boolean Checks if two instances of Joint refer to the same Joint.

Server + Client

getAngle

joint:getAngle(  )

Returns the angle of a bearing.

Parameters:

Name Type Description
bearing Joint The bearing.

Returns:

Type Description
number The bearing's angle. The angle ranges between -math.pi and +math.pi.

getAngularVelocity

joint:getAngularVelocity(  )

Returns the angular velocity of a bearing.

The angular velocity can be set using setMotorVelocity or setTargetAngle.

Parameters:

Name Type Description
bearing Joint The bearing.

Returns:

Type Description
number The bearing's angular velocity.

getAngularVelocityVector

joint:getAngularVelocityVector(  )

Returns the angular velocity of a generic joint.

Parameters:

Name Type Description
joint Joint The joint.

Returns:

Type Description
Vec3 The joint's angular velocities.

getAppliedImpulse

joint:getAppliedImpulse(  )

Returns the applied impulse of a bearing.

The applied impulse can be set using setMotorVelocity or setTargetAngle.

Parameters:

Name Type Description
bearing Joint The bearing.

Returns:

Type Description
number The bearing's applied impulse.

getBearingEnabled

joint:getBearingEnabled(  )

Returns whether a joint has a bearing enabled.

Parameters:

Name Type Description
joint Joint The joint.

Returns:

Type Description
boolean Whether the joint has a bearing enabled. Springs return whether their bearing is enabled, bearings always return true, pistons always return false.

getBoundingBox

joint:getBoundingBox(  )

Returns the bounding box of a joint – the dimensions that a joint occupies when building.

Parameters:

Name Type Description
joint Joint The joint.

Returns:

Type Description
Vec3 The size of the joint's bounding box.

getColor

joint:getColor(  )

Returns the color of a joint.

Parameters:

Name Type Description
joint Joint The joint.

Returns:

Type Description
Color The joint's color.

getId

joint:getId(  )

Returns the id of a joint.

Parameters:

Name Type Description
joint Joint The joint.

Returns:

Type Description
integer The joint's id.

getLength

joint:getLength(  )

Returns the current length of a piston. The length is measured in blocks.

Parameters:

Name Type Description
piston Joint The piston.

Returns:

Type Description
number The piston's current length in blocks.

getLocalPosition

joint:getLocalPosition(  )

Returns the local position of a joint.

Parameters:

Name Type Description
joint Joint The joint.

Returns:

Type Description
Vec3 The joint's local position.

getLocalRotation

joint:getLocalRotation(  )

Returns the local rotation of a joint.

Parameters:

Name Type Description
joint Joint The joint.

Returns:

Type Description
Quat The joint's local rotation.

getMultiShapeJoints

joint:getMultiShapeJoints(  )

Parameters:

Name Type Description
joint Joint A Join that is part of a multishape

Returns:

Type Description
table A table of joints contained in the multishape (returns nil if joint wasn't a multishape)

getMultiShapeShapes

joint:getMultiShapeShapes(  )

Parameters:

Name Type Description
joint Joint A joint that is part of a multishape

Returns:

Type Description
table A table of shapes contained in the multishape (returns nil if joint wasn't a multishape)

getShapeA

joint:getShapeA(  )

Returns the Shape a joint is attached to. This shape does always exist.

Parameters:

Name Type Description
joint Joint The joint.

Returns:

Type Description
Shape The joint's first shape.

getShapeB

joint:getShapeB(  )

Returns the Shape that is attached to a joint on another Body. This method returns nil if there is no shape attached to the joint.

Parameters:

Name Type Description
joint Joint The joint.

Returns:

Type Description
Shape The joint's second shape.

getShapeUuid

joint:getShapeUuid(  )

Returns the uuid string unique to a joint type.

Parameters:

Name Type Description
joint Joint The joint.

Returns:

Type Description
Uuid The joint's uuid.

getSticky

joint:getSticky(  )

Returns the sticky directions of the joint for positive xyz and negative xyz.

A value of 1 means that the direction is sticky and a value of 0 means that the direction is not sticky.

Parameters:

Name Type Description
joint Joint The joint.

Returns:

Type Description
Vec3
Vec3		 The negative xyz sticky and the positive xyz sticky.

getType

joint:getType(  )

Returns the joint type of a joint.

Parameters:

Name Type Description
joint Joint The joint.

Returns:

Type Description
string One of the joint's type found in (sm.joint.types).

getWorldPosition

joint:getWorldPosition(  )

Returns the world position of a joint.

Parameters:

Name Type Description
joint Joint The joint.

Returns:

Type Description
Vec3 The joint's world position.

getWorldRotation

joint:getWorldRotation(  )

Returns the world rotation of a joint.

Parameters:

Name Type Description
joint Joint The joint.

Returns:

Type Description
Quat The joint's world rotation.

getXAxis

joint:getXAxis(  )

Returns the local x-axis vector of a joint.

Parameters:

Name Type Description
joint Joint The joint.

Returns:

Type Description
Vec3 The joint's x-axis.

getYAxis

joint:getYAxis(  )

Returns the local y-axis vector of a joint.

Parameters:

Name Type Description
joint Joint The joint.

Returns:

Type Description
Vec3 The joint's y-axis.

getZAxis

joint:getZAxis(  )

Returns the local z-axis vector of a joint.

Parameters:

Name Type Description
joint Joint The joint.

Returns:

Type Description
Vec3 The joint's z-axis.

isReversed

joint:isReversed(  )

Returns whether a bearing has been reversed using the Connect Tool. A reversed bearing rotates counterclockwise.

Parameters:

Name Type Description
bearing Joint The bearing.

Returns:

Type Description
boolean Whether the bearing is reversed (rotating counterclockwise).

setMotorVelocity

joint:setMotorVelocity( targetVelocity, maxImpulse )

Sets the motor velocity for a bearing. The bearing will try to maintain the target velocity with the given amount of impulse/strength.

In Scrap Mechanic, the Gas Engine increases both velocity and impulse with every gear. The Electric Engine increases velocity, but maintains the same impulse for every gear, making it sturdier.

This method cancels the effects of setTargetAngle.

Parameters:

Name Type Description
bearing Joint The bearing.
targetVelocity number The target velocity.
maxImpulse number The max impulse.

setTargetAngle

joint:setTargetAngle( targetAngle, targetVelocity, maxImpulse )

Sets the target angle for a bearing. The bearing will try to reach the target angle with the target velocity and the given amount of impulse/strength.

The target angle is set to range between -math.pi and +math.pi. The bearing will always try to rotate in the direction closest to the target angle.

This method cancels the effects of setMotorVelocity.

Parameters:

Name Type Description
bearing Joint The bearing.
targetAngle number The target angle.
targetVelocity number The target velocity.
maxImpulse number The max impulse.

Server-only

createBlock

joint:createBlock( uuid, size, position, forceCreate )

Create a block on joint.

Parameters:

Name Type Description
joint Joint The parent joint.
uuid Uuid The uuid of the shape.
size Vec3 The shape's size.
position Vec3 The shape's local position.
forceCreate (optional) boolean Set true to force create the shape. (Defaults to true)

createPart

joint:createPart( uuid, position, zAxis, xAxis, forceCreate )

Create a part on joint.

Parameters:

Name Type Description
joint Joint The parent joint.
uuid Uuid The uuid of the shape.
position Vec3 The shape's local position.
zAxis Vec3 The shape's local z direction.
xAxis Vec3 The shape's local x direction.
forceCreate (optional) boolean Set true to force create the shape. (Defaults to true)

setColor

joint:setColor( color )

Sets the color of a joint.

Parameters:

Name Type Description
joint Joint The joint.
color Color The new color.

setTargetLength

joint:setTargetLength( targetLength, targetVelocity, maxImpulse )

Sets the target length for a piston. The piston will try to reach the target length with the target velocity and the given amount of impulse/strength.

The target length is measured in blocks.

This method cancels the effects of setMotorVelocity.

Parameters:

Name Type Description
bearing Joint The bearing.
targetLength number The target length.
targetVelocity number The target velocity.
maxImpulse (optional) number The max impulse. (Defaults to impulse used in game)