Some HingeJoint stuff;

api/lovr/physics/DistanceJoint/getSpring.lua

@@ -18,6 +18,12 @@ return {
       description = 'The damping ratio of the spring.'
     }
   },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'frequency', 'damping' }
+    }
+  },
   notes = [[
     Higher frequencies make the spring more stiff.  When zero (the default), the spring is disabled
     and the limits will be as stiff as possible.

api/lovr/physics/DistanceJoint/setSpring.lua

@@ -18,6 +18,12 @@ return {
     }
   },
   returns = {},
+  variants = {
+    {
+      arguments = { 'frequency', 'damping' },
+      returns = {}
+    }
+  },
   notes = [[
     Higher frequencies make the spring more stiff.  When zero (the default), the spring is disabled
     and the limits will be as stiff as possible.

api/lovr/physics/HingeJoint/getAngle.lua

@@ -1,9 +1,6 @@
 return {
-  summary = 'Get the angle of the HingeJoint.',
-  description = [[
-    Get the angle between the two colliders attached to the HingeJoint.  When the joint is created
-    or when the anchor or axis is set, the current angle is the new "zero" angle.
-  ]],
+  summary = 'Get the current angle of the HingeJoint.',
+  description = 'Returns the current angle of the HingeJoint, relative to the rest position.',
   arguments = {},
   returns = {
     angle = {
@@ -16,5 +13,10 @@ return {
       arguments = {},
       returns = { 'angle' }
     }
+  },
+  related = {
+    'HingeJoint:getAxis',
+    'HingeJoint:getLimits',
+    'HingeJoint:setLimits'
   }
 }

api/lovr/physics/HingeJoint/getAxis.lua

@@ -1,6 +1,6 @@
 return {
-  summary = 'Get the HingeJoint\'s axis.',
-  description = 'Returns the axis of the hinge.',
+  summary = 'Get the rotation axis of the HingeJoint.',
+  description = 'Returns the axis of the hinge, in world space.',
   arguments = {},
   returns = {
     x = {
@@ -21,5 +21,9 @@ return {
       arguments = {},
       returns = { 'x', 'y', 'z' }
     }
+  },
+  related = {
+    'HingeJoint:getAngle',
+    'Joint:getAnchors'
   }
 }

api/lovr/physics/HingeJoint/getFriction.lua

@@ -0,0 +1,21 @@
+return {
+  summary = 'Get the friction of the HingeJoint.',
+  description = [[
+    Returns the friction of the HingeJoint.  This is a maximum torque force that will be applied, in
+    newton meters.
+  ]],
+  arguments = {},
+  returns = {
+    friction = {
+      type = 'number',
+      description = 'The friction, in newton meters.'
+    }
+  },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'friction' }
+    }
+  },
+  notes = 'Friction is only applied when the motor is disabled.'
+}

api/lovr/physics/HingeJoint/getLimits.lua

@@ -1,30 +1,28 @@
 return {
-  summary = 'Get the HingeJoint\'s angle limits.',
+  summary = 'Get the angle limits of the HingeJoint.',
   description = [[
-    Returns the upper and lower limits of the hinge angle.  These will be between -π and π.
+    Returns the angle limits of the HingeJoint.  The "zero" angle is determined by the relative
+    position of the colliders at the time the joint was created.
   ]],
   arguments = {},
   returns = {
-    lower = {
+    min = {
       type = 'number',
-      description = 'The lower limit, in radians.'
+      description = 'The minimum angle, in radians.  Always between -π and 0.'
     },
-    upper = {
+    max = {
       type = 'number',
-      description = 'The upper limit, in radians.'
+      description = 'The maximum angle, in radians.  Always between 0 and π.'
     }
   },
   variants = {
     {
       arguments = {},
-      returns = { 'lower', 'upper' }
+      returns = { 'min', 'max' }
     }
   },
+  notes = 'The default limits are -π and π.',
   related = {
-    'HingeJoint:getAngle',
-    'HingeJoint:getLowerLimit',
-    'HingeJoint:setLowerLimit',
-    'HingeJoint:getUpperLimit',
-    'HingeJoint:setUpperLimit'
+    'HingeJoint:getAngle'
   }
 }

api/lovr/physics/HingeJoint/getSpring.lua

@@ -0,0 +1,50 @@
+return {
+  summary = 'Get the spring parameters of the HingeJoint.',
+  description = [[
+    Returns the spring parameters of the HingeJoint.  Use this to make the angle limits of the hinge
+    "soft".  When the motor is active, a separate set of spring parameters can be set on the motor,
+    see `HingeJoint:setMotorSpring`.
+  ]],
+  arguments = {},
+  returns = {
+    frequency = {
+      type = 'number',
+      description = [[
+        The frequency of the spring, in hertz.  Higher frequencies make the spring more stiff.  When
+        zero, the spring is disabled.
+      ]]
+    },
+    damping = {
+      type = 'number',
+      description = 'The damping ratio of the spring.'
+    }
+  },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'frequency', 'damping' }
+    }
+  },
+  notes = [[
+    Higher frequencies make the spring more stiff.  When zero (the default), the spring is disabled
+    and the limits will be as stiff as possible.
+
+    The damping ratio controls how quickly the oscillation slows down:
+
+    - Undamped: Zero damping will cause the spring to oscillate forever.  (Note that the spring may
+      still lose a small amount of energy over time).
+    - Underdamped: Damping less than one results in a system that is underdamped.  The spring will
+      oscillate around the target, but the oscillations will decay over time, eventually stabilizing
+      at the target.
+    - Overdamped: Damping greater than one will not have any oscillation, and the spring will take
+      extra time to reach the target.
+    - Critical Damping: When the damping is exactly 1.0, there is no oscillation and the spring
+      takes the minimum amount of time to reach the target (based on the frequency).
+
+    The default damping ratio is zero.
+  ]],
+  related = {
+    'HingeJoint:getMotorSpring',
+    'HingeJoint:setMotorSpring'
+  }
+}

api/lovr/physics/HingeJoint/setFriction.lua

@@ -0,0 +1,21 @@
+return {
+  summary = 'Set the friction of the HingeJoint.',
+  description = [[
+    Sets the friction of the HingeJoint.  This is a maximum torque force that will be applied, in
+    newton meters.
+  ]],
+  arguments = {
+    friction = {
+      type = 'number',
+      description = 'The friction, in newton meters.'
+    }
+  },
+  returns = {},
+  variants = {
+    {
+      arguments = { 'friction' },
+      returns = {}
+    }
+  },
+  notes = 'Friction is only applied when the motor is disabled.'
+}

api/lovr/physics/HingeJoint/setLimits.lua

@@ -1,16 +1,17 @@
 return {
-  summary = 'Set the HingeJoint\'s angle limits.',
+  summary = 'Set the angle limits of the HingeJoint.',
   description = [[
-    Sets the upper and lower limits of the hinge angle.  These should be between -π and π.
+    Sets the angle limits of the HingeJoint.  The "zero" angle is determined by the relative
+    position of the colliders at the time the joint was created.
   ]],
   arguments = {
-    lower = {
+    min = {
       type = 'number',
-      description = 'The lower limit, in radians.'
+      description = 'The minimum angle, in radians.  Should be between -π and 0.'
     },
-    upper = {
+    max = {
       type = 'number',
-      description = 'The upper limit, in radians.'
+      description = 'The maximum angle, in radians.  Should be between 0 and π.'
     }
   },
   returns = {},
@@ -18,13 +19,15 @@ return {
     {
       arguments = { 'lower', 'upper' },
       returns = {}
+    },
+    {
+      description = 'Disable the limits, setting them to -π and π.',
+      arguments = {},
+      returns = {}
     }
   },
+  notes = 'The default limits are -π and π.',
   related = {
-    'HingeJoint:getAngle',
-    'HingeJoint:getLowerLimit',
-    'HingeJoint:setLowerLimit',
-    'HingeJoint:getUpperLimit',
-    'HingeJoint:setUpperLimit'
+    'HingeJoint:getAngle'
   }
 }

api/lovr/physics/HingeJoint/setSpring.lua

@@ -0,0 +1,50 @@
+return {
+  summary = 'Set the spring parameters of the HingeJoint.',
+  description = [[
+    Sets the spring parameters of the HingeJoint.  Use this to make the angle limits of the hinge
+    "soft".  When the motor is active, a separate set of spring parameters can be set on the motor,
+    see `HingeJoint:setMotorSpring`.
+  ]],
+  arguments = {
+    frequency = {
+      type = 'number',
+      description = [[
+        The frequency of the spring, in hertz.  Higher frequencies make the spring more stiff.  When
+        zero, the spring is disabled.
+      ]]
+    },
+    damping = {
+      type = 'number',
+      description = 'The damping ratio of the spring.'
+    }
+  },
+  returns = {},
+  variants = {
+    {
+      arguments = { 'frequency', 'damping' },
+      returns = {}
+    }
+  },
+  notes = [[
+    Higher frequencies make the spring more stiff.  When zero (the default), the spring is disabled
+    and the limits will be as stiff as possible.
+
+    The damping ratio controls how quickly the oscillation slows down:
+
+    - Undamped: Zero damping will cause the spring to oscillate forever.  (Note that the spring may
+      still lose a small amount of energy over time).
+    - Underdamped: Damping less than one results in a system that is underdamped.  The spring will
+      oscillate around the target, but the oscillations will decay over time, eventually stabilizing
+      at the target.
+    - Overdamped: Damping greater than one will not have any oscillation, and the spring will take
+      extra time to reach the target.
+    - Critical Damping: When the damping is exactly 1.0, there is no oscillation and the spring
+      takes the minimum amount of time to reach the target (based on the frequency).
+
+    The default damping ratio is zero.
+  ]],
+  related = {
+    'HingeJoint:getMotorSpring',
+    'HingeJoint:setMotorSpring'
+  }
+}