Joint

Associated namespace: sm.joint

A userdata object representing a joint (bearing, piston, etc.) in the game.

Values:

• angle [ number ]
  

  • Get: The bearing's angle.

• angularVelocity [ number ]
  

  • Get: The bearing's angular velocity.

• appliedImpulse [ number ]
  

  • Get: The bearing's applied impulse.

• color [ Color ]
  

  • Get: The joint's color.

• id [ int ]
  

  • Get: The joint's id.

• length [ number ]
  

  • Get: The piston's current length in blocks.

• localPosition [ Vec3 ]
  

  • Get: The joint's local position.

• localRotation [ Quat ]
  

  • Get: The joint's local rotation.

• reversed [ bool ]
  

  • Get: Whether the bearing is reversed (counterclockwise) or not.

• shapeA [ Shape ]
  

  • Get: The joint's parent shape. This shape always exists.

• shapeB [ Shape ]
  

  • Get: The joint's child shape or nil if no shape is attached.

• type [ string ]
  

  • Get: The joint's type.

• uuid [ Uuid ]
  

  • Get: The joint's uuid.

• worldPosition [ Vec3 ]
  

  • Get: The joint's world position.

• xAxis [ Vec3 ]
  

  • Get: The joint's local x-axis vector.

• yAxis [ Vec3 ]
  

  • Get: The joint's local y-axis vector.

• zAxis [ Vec3 ]
  

  • Get: The joint's local z-axis vector.

Operations:

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

Functions

createBlock

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

Server-Only

Creates a block on the joint.

Arguments:

• joint [ Joint ]: The joint.
• uuid [ Uuid ]: The shape uuid.
• size [ Vec3 ]: The shape size.
• position [ Vec3 ]: The shape's local position.
• forceCreate [ bool ]: Whether to force creating the shape or not. Defaults to true.

---

createPart

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

Server-Only

Creates a part on the joint.

Arguments:

• joint [ Joint ]: The joint.
• uuid [ Uuid ]: The shape uuid.
• position [ Vec3 ]: The shape's local position.
• zAxis [ Vec3 ]: The shape's local z direction.
• xAxis [ Vec3 ]: The shape's local x direction.
• forceCreate [ bool ]: Whether to force creating the shape or not. Defaults to true.

---

getAngle

bearing:getAngle()

Returns the bearing's angle.

Arguments:

• bearing [ Joint ]: The bearing.

Returns:

• [ number ]: The bearing's angle (-math.pi - +math.pi).

---

getAngularVelocity

bearing:getAngularVelocity()

Returns the bearing's angular velocity.

This velocity can be set using setMotorVelocity or setTargetAngle.

Arguments:

• bearing [ Joint ]: The bearing.

Returns:

• [ number ]: The bearing's angular velocity.

---

getAppliedImpulse

bearing:getAppliedImpulse()

Returns the bearing's applied impulse.

The applied impulse can be set using setMotorVelocity or setTargetAngle.

Arguments:

• bearing [ Joint ]: The bearing.

Returns:

• [ number ]: The bearing's applied impulse.

---

getBoundingBox

joint:getBoundingBox()

Returns the joint's bounding box - the dimensions that it occupies when building.

Arguments:

• joint [ Joint ]: The joint.

Returns:

• [ Vec3 ]: The joint's bounding box.

---

getColor

joint:getColor()

Returns the joint's color.

Arguments:

• joint [ Joint ]: The joint.

Returns:

• [ Color ]: The joint's color.

---

setColor

joint:setColor( color )

Server-Only

Sets the joint's color.

Arguments:

• joint [ Joint ]: The joint.
• color [ Color ]: The color.

---

getId

joint:getId()

Returns the joint's id.

Arguments:

• joint [ Joint ]: The joint.

Returns:

• [ int ]: The joint's id.

---

getLength

piston:getLength()

Returns the piston's current length in blocks.

Arguments:

• piston [ Joint ]: The piston.

Returns:

• [ number ]: The joint's id.

---

getLocalPosition

joint:getLocalPosition()

Returns the joint's local position.

Arguments:

• joint [ Joint ]: The joint.

Returns:

• [ Vec3 ]: The joint's local position.

---

getLocalRotation

joint:getLocalRotation()

Returns the joint's local rotation.

Arguments:

• joint [ Joint ]: The joint.

Returns:

• [ Quat ]: The joint's local rotation.

---

getShapeA

joint:getShapeA()

Returns the joint's parent shape.
This is the shape that the joint is attached to.
This shape always exists.

Arguments:

• joint [ Joint ]: The joint.

Returns:

• [ Shape ]: The joint's parent shape.

---

getShapeB

joint:getShapeB()

Returns the joint's child shape.
This is the shape that is attached to the joint.

Arguments:

• joint [ Joint ]: The joint.

Returns:

• [ Shape ]: The joint's child shape.

---

getShapeUuid

joint:getShapeUuid()

Returns the joint's uuid.

Arguments:

• joint [ Joint ]: The joint.

Returns:

• [ 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.

Arguments:

• joint [ Joint ]: The joint.

Returns:

• [ Vec3 ]: The negative sticky directions.
• [ Vec3 ]: The positive sticky directions.

---

getType

joint:getType()

Returns the joint's type.

For details, see sm.joint.types.

Arguments:

• joint [ Joint ]: The joint.

Returns:

• [ string ]: The joint's type.

---

getWorldPosition

joint:getWorldPosition()

Returns the joint's world position.

Arguments:

• joint [ Joint ]: The joint.

Returns:

• [ Vec3 ]: The joint's world position.

---

getWorldRotation

joint:getWorldRotation()

Returns the joint's world rotation.

Arguments:

• joint [ Joint ]: The joint.

Returns:

• [ Quat ]: The joint's world rotation.

---

getXAxis

joint:getXAxis()

Returns the joint's local x-axis vector.

Arguments:

• joint [ Joint ]: The joint.

Returns:

• [ Vec3 ]: The joint's x-axis vector.

---

getYAxis

joint:getYAxis()

Returns the joint's local y-axis vector.

Arguments:

• joint [ Joint ]: The joint.

Returns:

• [ Vec3 ]: The joint's y-axis vector.

---

getZAxis

joint:getZAxis()

Returns the joint's local z-axis vector.

Arguments:

• joint [ Joint ]: The joint.

Returns:

• [ Vec3 ]: The joint's z-axis vector.

---

isReversed

bearing:isReversed()

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

Arguments:

• bearing [ Joint ]: The bearing.

Returns:

• [ bool ]: Whether the bearing was reversed or not.

---

setMotorVelocity

bearing: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.

Arguments:

• bearing [ Joint ]: The bearing.
• targetVelocity [ number ]: The target velocity.
• maxImpulse [ number ]: The max impulse.

---

setTargetAngle

bearing: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.

Arguments:

• bearing [ Joint ]: The bearing.
• targetAngle [ number ]: The target angle.
• targetVelocity [ number ]: The target velocity.
• maxImpulse [ number ]: The max impulse.

---

setTargetLength

piston: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.

Arguments:

• piston [ Joint ]: The piston.
• targetLength [ number ]: The target length.
• targetVelocity [ number ]: The target velocity.
• maxImpulse [ number ]: The max impulse.

---