Start Shape and Joint docs;

api/lovr/physics/BallJoint/getAnchors.lua

@@ -1,42 +0,0 @@
-return {
-  summary = 'Get the anchor points of the BallJoint.',
-  description = [[
-    Returns the anchor points of the BallJoint, in world coordinates.  The first point is the anchor
-    on the first collider, and the second point is on the second collider.  The joint tries to keep
-    these points the same, but they may be different if the joint is forced apart by some other
-    means.
-  ]],
-  arguments = {},
-  returns = {
-    x1 = {
-      type = 'number',
-      description = 'The x coordinate of the first anchor point, in world coordinates.'
-    },
-    y1 = {
-      type = 'number',
-      description = 'The y coordinate of the first anchor point, in world coordinates.'
-    },
-    z1 = {
-      type = 'number',
-      description = 'The z coordinate of the first anchor point, in world coordinates.'
-    },
-    x2 = {
-      type = 'number',
-      description = 'The x coordinate of the second anchor point, in world coordinates.'
-    },
-    y2 = {
-      type = 'number',
-      description = 'The y coordinate of the second anchor point, in world coordinates.'
-    },
-    z2 = {
-      type = 'number',
-      description = 'The z coordinate of the second anchor point, in world coordinates.'
-    }
-  },
-  variants = {
-    {
-      arguments = {},
-      returns = { 'x1', 'y1', 'z1', 'x2', 'y2', 'z2' }
-    }
-  }
-}

api/lovr/physics/BallJoint/getResponseTime.lua

@@ -1,25 +0,0 @@
-return {
-  summary = 'Get the response time of the joint.',
-  description = [[
-    Returns the response time of the joint.  See `World:setResponseTime` for more info.
-  ]],
-  arguments = {},
-  returns = {
-    responseTime = {
-      type = 'number',
-      description = 'The response time setting for the joint.'
-    }
-  },
-  variants = {
-    {
-      arguments = {},
-      returns = { 'responseTime' }
-    }
-  },
-  related = {
-    'DistanceJoint:getResponseTime',
-    'DistanceJoint:setResponseTime',
-    'World:getResponseTime',
-    'World:setResponseTime'
-  }
-}

api/lovr/physics/BallJoint/getTightness.lua

@@ -1,25 +0,0 @@
-return {
-  summary = 'Get the joint tightness.',
-  description = [[
-    Returns the tightness of the joint.  See `World:setTightness` for how this affects the joint.
-  ]],
-  arguments = {},
-  returns = {
-    tightness = {
-      type = 'number',
-      description = 'The tightness of the joint.'
-    }
-  },
-  variants = {
-    {
-      arguments = {},
-      returns = { 'tightness' }
-    }
-  },
-  related = {
-    'DistanceJoint:getTightness',
-    'DistanceJoint:setTightness',
-    'World:getTightness',
-    'World:setTightness'
-  }
-}

api/lovr/physics/BallJoint/setAnchor.lua

@@ -1,35 +0,0 @@
-return {
-  summary = 'Set the anchor point of the BallJoint.',
-  description = 'Sets a new anchor point for the BallJoint.',
-  arguments = {
-    x = {
-      type = 'number',
-      description = 'The x coordinate of the anchor point, in world coordinates.'
-    },
-    y = {
-      type = 'number',
-      description = 'The y coordinate of the anchor point, in world coordinates.'
-    },
-    z = {
-      type = 'number',
-      description = 'The z coordinate of the anchor point, in world coordinates.'
-    },
-    anchor = {
-      type = 'Vec3',
-      description = 'The anchor point, in world coordinates.'
-    }
-  },
-  returns = {},
-  variants = {
-    {
-      description = 'Sets the anchor point using numbers.',
-      arguments = { 'x', 'y', 'z' },
-      returns = {}
-    },
-    {
-      description = 'Sets the anchor point using a vector.',
-      arguments = { 'anchor' },
-      returns = {}
-    }
-  }
-}

api/lovr/physics/BallJoint/setResponseTime.lua

@@ -1,23 +0,0 @@
-return {
-  summary = 'Set the response time of the joint.',
-  description = 'Sets the response time of the joint.  See `World:setResponseTime` for more info.',
-  arguments = {
-    responseTime = {
-      type = 'number',
-      description = 'The new response time setting for the joint.'
-    }
-  },
-  returns = {},
-  variants = {
-    {
-      arguments = { 'responseTime' },
-      returns = {}
-    }
-  },
-  related = {
-    'DistanceJoint:getResponseTime',
-    'DistanceJoint:setResponseTime',
-    'World:getResponseTime',
-    'World:setResponseTime'
-  }
-}

api/lovr/physics/BallJoint/setTightness.lua

@@ -1,25 +0,0 @@
-return {
-  summary = 'Set the joint tightness.',
-  description = [[
-    Sets the tightness of the joint.  See `World:setTightness` for how this affects the joint.
-  ]],
-  arguments = {
-    tightness = {
-      type = 'number',
-      description = 'The tightness of the joint.'
-    }
-  },
-  returns = {},
-  variants = {
-    {
-      arguments = { 'tightness' },
-      returns = {}
-    }
-  },
-  related = {
-    'DistanceJoint:getTightness',
-    'DistanceJoint:setTightness',
-    'World:getTightness',
-    'World:setTightness'
-  }
-}

api/lovr/physics/BoxShape/getDimensions.lua

@@ -21,8 +21,5 @@ return {
       arguments = {},
       returns = { 'width', 'height', 'depth' }
     }
-  },
-  related = {
-    'Shape:getVolume'
   }
 }

api/lovr/physics/BoxShape/setDimensions.lua

@@ -1,14 +1,6 @@
 return {
   summary = 'Set the dimensions of the BoxShape.',
-  description = [[
-    Sets the width, height, and depth of the BoxShape.
-
-    This changes the mass of the shape.  If the shape is attached to a collider and that collider is
-    set to use automatic mass, the mass properties of the collider will update as well.
-
-    Changing shapes can make the physics engine explode since it can cause objects to overlap in
-    unnatural ways.
-  ]],
+  description = 'Sets the width, height, and depth of the BoxShape.',
   arguments = {
     width = {
       type = 'number',
@@ -29,5 +21,12 @@ return {
       arguments = { 'width', 'height', 'depth' },
       returns = {}
     }
-  }
+  },
+  notes = [[
+    This changes the mass of the shape.  If the shape is attached to a collider with automatic mass
+    enabled, the mass properties of the collider will update as well.
+
+    Changing shapes can make the physics engine explode since it can cause objects to overlap in
+    unnatural ways.
+  ]]
 }

api/lovr/physics/CapsuleShape/getLength.lua

@@ -13,5 +13,9 @@ return {
       arguments = {},
       returns = { 'length' }
     }
+  },
+  related = {
+    'CapsuleShape:getRadius',
+    'CapsuleShape:setRadius'
   }
 }

api/lovr/physics/CapsuleShape/getRadius.lua

@@ -13,5 +13,9 @@ return {
       arguments = {},
       returns = { 'radius' }
     }
+  },
+  related = {
+    'CapsuleShape:getLength',
+    'CapsuleShape:setLength'
   }
 }

api/lovr/physics/CapsuleShape/setLength.lua

@@ -13,5 +13,16 @@ return {
       arguments = { 'length' },
       returns = {}
     }
+  },
+  notes = [[
+    This changes the mass of the shape.  If the shape is attached to a collider with automatic mass
+    enabled, the mass properties of the collider will update as well.
+
+    Changing shapes can make the physics engine explode since it can cause objects to overlap in
+    unnatural ways.
+  ]],
+  related = {
+    'CapsuleShape:getRadius',
+    'CapsuleShape:setRadius'
   }
 }

api/lovr/physics/CapsuleShape/setRadius.lua

@@ -13,5 +13,16 @@ return {
       arguments = { 'radius' },
       returns = {}
     }
+  },
+  notes = [[
+    This changes the mass of the shape.  If the shape is attached to a collider with automatic mass
+    enabled, the mass properties of the collider will update as well.
+
+    Changing shapes can make the physics engine explode since it can cause objects to overlap in
+    unnatural ways.
+  ]],
+  related = {
+    'CapsuleShape:getLength',
+    'CapsuleShape:setLength'
   }
 }

api/lovr/physics/Collider/getLinearVelocity.lua

@@ -25,6 +25,9 @@ return {
       returns = { 'vx', 'vy', 'vz' }
     }
   },
+  notes = [[
+    Currently, velocity is clamped to 500 meters per second to improve stability of the simulation.
+  ]],
   related = {
     'Collider:applyForce',
     'Collider:getLinearVelocityFromLocalPoint',

api/lovr/physics/Collider/getUserData.lua

@@ -1,5 +1,5 @@
 return {
-  summary = 'Return the Lua value associated with the Collider.',
+  summary = 'Get the Lua value associated with the Collider.',
   description = 'Returns the Lua value associated with the Collider.',
   arguments = {},
   returns = {
@@ -27,5 +27,11 @@ return {
 
     The user data is not shared between threads.  Each thread has its own user data for the
     Collider.
-  ]]
+  ]],
+  related = {
+    'Shape:getUserData',
+    'Shape:setUserData',
+    'Joint:getUserData',
+    'Joint:setUserData'
+  }
 }

api/lovr/physics/Collider/setLinearVelocity.lua

@@ -47,6 +47,8 @@ return {
 
     If the Collider has a tag that was marked as static when the World was created, then the
     Collider can not move and this function will do nothing.
+
+    Currently, velocity is clamped to 500 meters per second to improve stability of the simulation.
   ]],
   related = {
     'Collider:applyForce',

api/lovr/physics/Collider/setUserData.lua

@@ -29,5 +29,11 @@ return {
 
     The user data is not shared between threads.  Each thread has its own user data for the
     Collider.
-  ]]
+  ]],
+  related = {
+    'Shape:getUserData',
+    'Shape:setUserData',
+    'Joint:getUserData',
+    'Joint:setUserData'
+  }
 }

api/lovr/physics/ConeJoint/getAxis.lua

@@ -0,0 +1,29 @@
+return {
+  summary = 'Get the axis of the cone.',
+  description = [[
+    Returns the axis of the ConeJoint, in world space.  The axis is relative to the first Collider
+    connected to the Joint, so it will rotate as the collider does.  The relative angle between the
+    axis and the second collider will be constrained based on the ConeJoint's angle limit.
+  ]],
+  arguments = {},
+  returns = {
+    ax = {
+      type = 'number',
+      description = 'The x component of the axis.'
+    },
+    ay = {
+      type = 'number',
+      description = 'The y component of the axis.'
+    },
+    az = {
+      type = 'number',
+      description = 'The z component of the axis.'
+    }
+  },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'ax', 'ay', 'az' }
+    }
+  }
+}

api/lovr/physics/ConeJoint/getLimit.lua

@@ -0,0 +1,21 @@
+return {
+  summary = 'Get the angle limit of the ConeJoint.',
+  description = [[
+    Returns the angle limit of the ConeJoint.  The relative angle between the ConeJoint's axis and
+    the second Collider will be constrained to this limit.
+  ]],
+  arguments = {},
+  returns = {
+    limit = {
+      type = 'number',
+      description = 'The angle limit, in radians.'
+    }
+  },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'limit' }
+    }
+  },
+  notes = 'The default limit is zero, preventing any rotation away from the axis.'
+}

api/lovr/physics/ConeJoint/setLimit.lua

@@ -0,0 +1,21 @@
+return {
+  summary = 'Set the angle limit of the ConeJoint.',
+  description = [[
+    Returns the angle limit of the ConeJoint.  The relative angle between the ConeJoint's axis and
+    the second Collider will be constrained to this limit.
+  ]],
+  arguments = {
+    limit = {
+      type = 'number',
+      description = 'The new limit in radians, between 0 and pi.'
+    }
+  },
+  returns = {},
+  variants = {
+    {
+      arguments = { 'limit' },
+      returns = {}
+    }
+  },
+  notes = 'The default limit is zero, preventing any rotation away from the axis.'
+}

api/lovr/physics/ConvexShape/getFace.lua

@@ -0,0 +1,31 @@
+return {
+  summary = 'Get the point indices of one of the faces of the convex hull.',
+  description = [[
+    Returns the indices of points that make up one of the faces of the convex hull.
+  ]],
+  arguments = {
+    index = {
+      type = 'number',
+      description = 'The index of the face.'
+    }
+  },
+  returns = {
+    points = {
+      type = 'table',
+      description = [[
+        A table with point indices.  Use `ConvexShape:getPoint` to get the coordinates.  The points
+        are given in counterclockwise order.
+      ]],
+    }
+  },
+  variants = {
+    {
+      arguments = { 'index' },
+      returns = { 'points' }
+    }
+  },
+  related = {
+    'ConvexShape:getPoint',
+    'ConvexShape:getFaceCount'
+  }
+}

api/lovr/physics/ConvexShape/getFaceCount.lua

@@ -0,0 +1,20 @@
+return {
+  summary = 'Get the number of faces in the convex hull.',
+  description = 'Returns the number of faces in the convex hull.',
+  arguments = {},
+  returns = {
+    count = {
+      type = 'number',
+      description = 'The number of faces.'
+    }
+  },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'count' }
+    }
+  },
+  related = {
+    'ConvexShape:getFace'
+  }
+}

api/lovr/physics/ConvexShape/getPoint.lua

@@ -0,0 +1,33 @@
+return {
+  summary = 'Get one of the points in the convex hull.',
+  description = 'Returns one of the points in the convex hull, in local space.',
+  arguments = {
+    index = {
+      type = 'number',
+      description = 'The index of the point.'
+    }
+  },
+  returns = {
+    x = {
+      type = 'number',
+      description = 'The x coordinate.'
+    },
+    y = {
+      type = 'number',
+      description = 'The y coordinate.'
+    },
+    z = {
+      type = 'number',
+      description = 'The z coordinate.'
+    }
+  },
+  variants = {
+    {
+      arguments = { 'index' },
+      returns = { 'x', 'y', 'z' }
+    }
+  },
+  related = {
+    'ConvexShape:getPointCount'
+  }
+}

api/lovr/physics/ConvexShape/getPointCount.lua

@@ -0,0 +1,24 @@
+return {
+  summary = 'Get the number of points in the convex hull.',
+  description = 'Returns the number of points in the convex hull.',
+  arguments = {},
+  returns = {
+    count = {
+      type = 'number',
+      description = 'The number of points.'
+    }
+  },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'count' }
+    }
+  },
+  notes = [[
+    This isn't necessarily the same as the number of points or vertices that were used to create the
+    shape, since points inside the hull will be discarded.
+  ]]
+  related = {
+    'ConvexShape:getPoint'
+  }
+}

api/lovr/physics/CylinderShape/getLength.lua

@@ -13,5 +13,9 @@ return {
       arguments = {},
       returns = { 'length' }
     }
+  },
+  related = {
+    'CylinderShape:getRadius',
+    'CylinderShape:setRadius'
   }
 }

api/lovr/physics/CylinderShape/getRadius.lua

@@ -13,5 +13,9 @@ return {
       arguments = {},
       returns = { 'radius' }
     }
+  },
+  related = {
+    'CylinderShape:getLength',
+    'CylinderShape:setLength'
   }
 }

api/lovr/physics/CylinderShape/setLength.lua

@@ -13,5 +13,16 @@ return {
       arguments = { 'length' },
       returns = {}
     }
+  },
+  notes = [[
+    This changes the mass of the shape.  If the shape is attached to a collider with automatic mass
+    enabled, the mass properties of the collider will update as well.
+
+    Changing shapes can make the physics engine explode since it can cause objects to overlap in
+    unnatural ways.
+  ]],
+  related = {
+    'CylinderShape:getRadius',
+    'CylinderShape:setRadius'
   }
 }

api/lovr/physics/CylinderShape/setRadius.lua

@@ -13,5 +13,16 @@ return {
       arguments = { 'radius' },
       returns = {}
     }
+  },
+  notes = [[
+    This changes the mass of the shape.  If the shape is attached to a collider with automatic mass
+    enabled, the mass properties of the collider will update as well.
+
+    Changing shapes can make the physics engine explode since it can cause objects to overlap in
+    unnatural ways.
+  ]],
+  related = {
+    'CylinderShape:getLength',
+    'CylinderShape:setLength'
   }
 }

api/lovr/physics/DistanceJoint/getAnchors.lua

@@ -1,37 +0,0 @@
-return {
-  summary = 'Get the anchor points of the DistanceJoint.',
-  description = 'Returns the anchor points of the DistanceJoint.',
-  arguments = {},
-  returns = {
-    x1 = {
-      type = 'number',
-      description = 'The x coordinate of the first anchor point, in world coordinates.'
-    },
-    y1 = {
-      type = 'number',
-      description = 'The y coordinate of the first anchor point, in world coordinates.'
-    },
-    z1 = {
-      type = 'number',
-      description = 'The z coordinate of the first anchor point, in world coordinates.'
-    },
-    x2 = {
-      type = 'number',
-      description = 'The x coordinate of the second anchor point, in world coordinates.'
-    },
-    y2 = {
-      type = 'number',
-      description = 'The y coordinate of the second anchor point, in world coordinates.'
-    },
-    z2 = {
-      type = 'number',
-      description = 'The z coordinate of the second anchor point, in world coordinates.'
-    }
-  },
-  variants = {
-    {
-      arguments = {},
-      returns = { 'x1', 'y1', 'z1', 'x2', 'y2', 'z2' }
-    }
-  }
-}

api/lovr/physics/DistanceJoint/getDistance.lua

@@ -1,20 +0,0 @@
-return {
-  summary = 'Get the target distance of the DistanceJoint.',
-  description = [[
-    Returns the target distance for the DistanceJoint.  The joint tries to keep the Colliders this
-    far apart.
-  ]],
-  arguments = {},
-  returns = {
-    distance = {
-      type = 'number',
-      description = 'The target distance.'
-    }
-  },
-  variants = {
-    {
-      arguments = {},
-      returns = { 'distance' }
-    }
-  }
-}

api/lovr/physics/DistanceJoint/getLimits.lua

@@ -0,0 +1,26 @@
+return {
+  summary = 'Get the minimum and maximum distance.',
+  description = 'Returns the minimum and maximum distance allowed between the Colliders.',
+  arguments = {},
+  returns = {
+    min = {
+      type = 'number',
+      description = [[
+        The minimum distance, in meters.  The Colliders won't be able to get closer than this.
+      ]]
+    },
+    max = {
+      type = 'number',
+      description = [[
+        The maximum distance, in meters.  The Colliders won't be able to get further than this.
+      ]]
+    }
+  },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'min', 'max' }
+    }
+  },
+  notes = 'The limits default to the distance between the Colliders when the Joint was created.'
+}

api/lovr/physics/DistanceJoint/getResponseTime.lua

@@ -1,25 +0,0 @@
-return {
-  summary = 'Get the response time of the joint.',
-  description = [[
-    Returns the response time of the joint.  See `World:setResponseTime` for more info.
-  ]],
-  arguments = {},
-  returns = {
-    responseTime = {
-      type = 'number',
-      description = 'The response time setting for the joint.'
-    }
-  },
-  variants = {
-    {
-      arguments = {},
-      returns = { 'responseTime' }
-    }
-  },
-  related = {
-    'BallJoint:getResponseTime',
-    'BallJoint:setResponseTime',
-    'World:getResponseTime',
-    'World:setResponseTime'
-  }
-}

api/lovr/physics/DistanceJoint/getSpring.lua

@@ -0,0 +1,39 @@
+return {
+  summary = 'Get the spring parameters of the joint.',
+  description = [[
+    Returns the DistanceJoint's spring parameters.  Use this to control how fast the joint pulls the
+    colliders back together at the distance limits.
+  ]],
+  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.'
+    }
+  },
+  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.
+  ]]
+}

api/lovr/physics/DistanceJoint/getTightness.lua

@@ -1,25 +0,0 @@
-return {
-  summary = 'Get the joint tightness.',
-  description = [[
-    Returns the tightness of the joint.  See `World:setTightness` for how this affects the joint.
-  ]],
-  arguments = {},
-  returns = {
-    tightness = {
-      type = 'number',
-      description = 'The tightness of the joint.'
-    }
-  },
-  variants = {
-    {
-      arguments = {},
-      returns = { 'tightness' }
-    }
-  },
-  related = {
-    'BallJoint:getTightness',
-    'BallJoint:setTightness',
-    'World:getTightness',
-    'World:setTightness'
-  }
-}

api/lovr/physics/DistanceJoint/setAnchors.lua

@@ -1,51 +0,0 @@
-return {
-  summary = 'Set the anchor points of the DistanceJoint.',
-  description = 'Sets the anchor points of the DistanceJoint.',
-  arguments = {
-    x1 = {
-      type = 'number',
-      description = 'The x coordinate of the first anchor point, in world coordinates.'
-    },
-    y1 = {
-      type = 'number',
-      description = 'The y coordinate of the first anchor point, in world coordinates.'
-    },
-    z1 = {
-      type = 'number',
-      description = 'The z coordinate of the first anchor point, in world coordinates.'
-    },
-    x2 = {
-      type = 'number',
-      description = 'The x coordinate of the second anchor point, in world coordinates.'
-    },
-    y2 = {
-      type = 'number',
-      description = 'The y coordinate of the second anchor point, in world coordinates.'
-    },
-    z2 = {
-      type = 'number',
-      description = 'The z coordinate of the second anchor point, in world coordinates.'
-    },
-    first = {
-      type = 'Vec3',
-      description = 'The first anchor point, in world coordinates.'
-    },
-    second = {
-      type = 'Vec3',
-      description = 'The second anchor point, in world coordinates.'
-    }
-  },
-  returns = {},
-  variants = {
-    {
-      description = 'Sets the anchor points using numbers.',
-      arguments = { 'x1', 'y1', 'z1', 'x2', 'y2', 'z2' },
-      returns = {}
-    },
-    {
-      description = 'Sets the anchor points using vectors.',
-      arguments = { 'first', 'second' },
-      returns = {}
-    }
-  }
-}

api/lovr/physics/DistanceJoint/setDistance.lua

@@ -1,20 +0,0 @@
-return {
-  summary = 'Set the target distance of the DistanceJoint.',
-  description = [[
-    Sets the target distance for the DistanceJoint.  The joint tries to keep the Colliders this far
-    apart.
-  ]],
-  arguments = {
-    distance = {
-      type = 'number',
-      description = 'The new target distance.'
-    }
-  },
-  returns = {},
-  variants = {
-    {
-      arguments = { 'distance' },
-      returns = {}
-    }
-  }
-}

api/lovr/physics/DistanceJoint/setLimits.lua

@@ -0,0 +1,36 @@
+return {
+  summary = 'Set the minimum and maximum distance.',
+  description = 'Sets the minimum and maximum distance allowed between the Colliders.',
+  arguments = {
+    min = {
+      type = 'number',
+      default = '0',
+      description = [[
+        The minimum distance, in meters.  The Colliders won't be able to get closer than this.
+      ]]
+    },
+    max = {
+      type = 'number',
+      default = 'min',
+      description = [[
+        The maximum distance, in meters.  The Colliders won't be able to get further than this.
+      ]]
+    }
+  },
+  returns = {},
+  variants = {
+    {
+      arguments = { 'min', 'max' },
+      returns = {}
+    },
+    {
+      description = [[
+        Remove the limits, setting the minimum distance to zero and the maximum distance to
+        infinity.
+      ]],
+      arguments = {},
+      returns = {}
+    }
+  },
+  notes = 'The limits default to the distance between the Colliders when the Joint was created.'
+}

api/lovr/physics/DistanceJoint/setResponseTime.lua

@@ -1,23 +0,0 @@
-return {
-  summary = 'Set the response time of the joint.',
-  description = 'Sets the response time of the joint.  See `World:setResponseTime` for more info.',
-  arguments = {
-    responseTime = {
-      type = 'number',
-      description = 'The new response time setting for the joint.'
-    }
-  },
-  returns = {},
-  variants = {
-    {
-      arguments = { 'responseTime' },
-      returns = {}
-    }
-  },
-  related = {
-    'BallJoint:getResponseTime',
-    'BallJoint:setResponseTime',
-    'World:getResponseTime',
-    'World:setResponseTime'
-  }
-}

api/lovr/physics/DistanceJoint/setSpring.lua

@@ -0,0 +1,39 @@
+return {
+  summary = 'Set the spring parameters of the joint.',
+  description = [[
+    Sets the DistanceJoint's spring parameters.  Use this to control how fast the joint pulls the
+    colliders back together at the distance limits.
+  ]],
+  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 = {},
+  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.
+  ]]
+}

api/lovr/physics/DistanceJoint/setTightness.lua

@@ -1,25 +0,0 @@
-return {
-  summary = 'Set the joint tightness.',
-  description = [[
-    Sets the tightness of the joint.  See `World:setTightness` for how this affects the joint.
-  ]],
-  arguments = {
-    tightness = {
-      type = 'number',
-      description = 'The tightness of the joint.'
-    }
-  },
-  returns = {},
-  variants = {
-    {
-      arguments = { 'tightness' },
-      returns = {}
-    }
-  },
-  related = {
-    'BallJoint:getTightness',
-    'BallJoint:setTightness',
-    'World:getTightness',
-    'World:setTightness'
-  }
-}

api/lovr/physics/Joint/destroy.lua

@@ -1,6 +1,10 @@
 return {
   summary = 'Destroy the Joint.',
-  description = 'Destroy the Joint, removing it from Colliders it\'s attached to.',
+  description = [[
+    Destroys the Joint, removing it from the World and breaking the connection between its
+    Colliders.  There is no way to get the Joint back after destroying it, and attempting to use it
+    will throw an error.  To temporarily disable a Joint, use `Joint:setEnabled`.
+  ]],
   arguments = {},
   returns = {},
   variants = {
@@ -9,8 +13,13 @@ return {
       returns = {}
     }
   },
-  notes = 'Calling functions on the Joint after destroying it is a bad idea.',
+  notes = [[
+    Joints are automatically destroyed if either of their Colliders are destroyed or if the World is
+    destroyed or garbage collected.
+  ]],
   related = {
+    'Joint:isDestroyed',
+    'Joint:setEnabled',
     'Collider:destroy',
     'Shape:destroy',
     'World:destroy'

api/lovr/physics/Joint/getAnchors.lua

@@ -0,0 +1,43 @@
+return {
+  summary = 'Get the anchor points of the Joint.',
+  description = [[
+    Returns the world space anchor points of the Joint.  Joints are attached to each collider at a
+    single point, which is defined when the Joint is created.
+  ]],
+  arguments = {},
+  returns = {
+    x1 = {
+      type = 'number',
+      description = 'The x coordinate of the anchor point on the first Collider, in world space.'
+    },
+    y1 = {
+      type = 'number',
+      description = 'The y coordinate of the anchor point on the first Collider, in world space.'
+    },
+    z1 = {
+      type = 'number',
+      description = 'The z coordinate of the anchor point on the first Collider, in world space.'
+    },
+    x2 = {
+      type = 'number',
+      description = 'The x coordinate of the anchor point on the second Collider, in world space.'
+    },
+    y2 = {
+      type = 'number',
+      description = 'The y coordinate of the anchor point on the second Collider, in world space.'
+    },
+    z2 = {
+      type = 'number',
+      description = 'The z coordinate of the anchor point on the second Collider, in world space.'
+    }
+  },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'x1', 'y1', 'z1', 'x2', 'y2', 'z2' }
+    }
+  },
+  related = {
+    'Joint:getColliders'
+  }
+}

api/lovr/physics/Joint/getColliders.lua

@@ -1,8 +1,6 @@
 return {
   summary = 'Get the Colliders the Joint is attached to.',
-  description = [[
-    Returns the Colliders the Joint is attached to.  All Joints are attached to two colliders.
-  ]],
+  description = 'Returns the Colliders the Joint is attached to.',
   arguments = {},
   returns = {
     colliderA = {
@@ -19,5 +17,8 @@ return {
       arguments = {},
       returns = { 'colliderA', 'colliderB' }
     }
+  },
+  related = {
+    'Collider:getJoints'
   }
 }

api/lovr/physics/Joint/getForce.lua

@@ -0,0 +1,31 @@
+return {
+  summary = 'Get the force used to satisfy the Joint\'s constraint.',
+  description = [[
+    Returns the magnitude of the force used to satisfy the Joint's constraint during the last
+    physics update, in newtons.
+
+    This is useful for breakable joints.  Use `Joint:destroy` to break the joint if its force goes
+    above a threshold.
+  ]],
+  arguments = {},
+  returns = {
+    force = {
+      type = 'number',
+      description = 'The magnitude of the force used to satisfy the Joint\'s constraint.'
+    }
+  },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'force' }
+    }
+  },
+  notes = [[
+    This does not include the motor force of a `SliderJoint`, see `SliderJoint:getMotorForce`.
+    that.
+  ]],
+  related = {
+    'Joint:getTorque',
+    'SliderJoint:getMotorForce'
+  }
+}

api/lovr/physics/Joint/getPriority.lua

@@ -0,0 +1,21 @@
+return {
+  summary = 'Get the priority of the Joint.',
+  description = [[
+    Returns the priority of the Joint.  Joints with a higher priority are more likely to be solved
+    correctly.  Priority values are non-negative integers.
+  ]],
+  arguments = {},
+  returns = {
+    priority = {
+      type = 'number',
+      description = 'The integer priority value.'
+    }
+  },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'priority' }
+    }
+  },
+  notes = 'The default priority is zero.'
+}

api/lovr/physics/Joint/getTorque.lua

@@ -0,0 +1,30 @@
+return {
+  summary = 'Get the torque used to satisfy the Joint\'s constraint.',
+  description = [[
+    Returns the magnitude of the torque used to satisfy the Joint's constraint during the last
+    physics update, in newton meters.
+
+    This is useful for breakable joints.  Use `Joint:destroy` to break the joint if its torque goes
+    above a threshold.
+  ]],
+  arguments = {},
+  returns = {
+    torque = {
+      type = 'number',
+      description = 'The magnitude of the torque used to satisfy the Joint\'s constraint.'
+    }
+  },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'torque' }
+    }
+  },
+  notes = [[
+    This does not include the motor force of a `HingeJoint`, see `HingeJoint:getMotorForce`.
+  ]],
+  related = {
+    'Joint:getTorque',
+    'HingeJoint:getMotorForce'
+  }
+}

api/lovr/physics/Joint/getUserData.lua

@@ -1,6 +1,6 @@
 return {
-  summary = 'Get the Joint\'s user data.',
-  description = 'Returns the user data associated with the Joint.',
+  summary = 'Get the Lua value associated with the Joint.',
+  description = 'Returns the Lua value associated with the Joint.',
   arguments = {},
   returns = {
     data = {
@@ -13,5 +13,14 @@ return {
       arguments = {},
       returns = { 'data' }
     }
+  },
+  notes = [[
+    The user data is not shared between threads.  Each thread has its own user data for the Joint.
+  ]],
+  related = {
+    'Collider:getUserData',
+    'Collider:setUserData',
+    'Shape:getUserData',
+    'Shape:setUserData'
   }
 }

api/lovr/physics/Joint/isDestroyed.lua

@@ -0,0 +1,28 @@
+return {
+  summary = 'Check if a Joint is destroyed.',
+  description = [[
+    Returns whether a Joint has been destroyed.  This the only method that can be called on a
+    destroyed Joint, using the Joint in any other way will error.
+  ]],
+  arguments = {},
+  returns = {
+    destroyed = {
+      type = 'boolean',
+      description = 'Whether the Joint has been destroyed.'
+    }
+  },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'destroyed' }
+    }
+  },
+  related = {
+    'Joint:destroy',
+    'Joint:isEnabled',
+    'Joint:setEnabled',
+    'Collider:destroy',
+    'Shape:destroy',
+    'World:destroy'
+  }
+}

api/lovr/physics/Joint/isEnabled.lua

@@ -1,6 +1,10 @@
 return {
   summary = 'Check if the Joint is enabled.',
-  description = 'Returns whether the Joint is enabled.',
+  description = [[
+    Returns whether the Joint is enabled.  Disabled joints do not affect the simulation in any way.
+    Use `Joint:setEnabled` to reactivate the Joint later.  If the Joint is no longer needed,
+    `Joint:destroy` is a better option that completely removes the Joint from the simulation.
+  ]],
   arguments = {},
   returns = {
     enabled = {
@@ -13,5 +17,8 @@ return {
       arguments = {},
       returns = { 'enabled' }
     }
+  },
+  related = {
+    'Joint:destroy'
   }
 }

api/lovr/physics/Joint/setEnabled.lua

@@ -1,6 +1,10 @@
 return {
   summary = 'Enable or disable the Joint.',
-  description = 'Enable or disable the Joint.',
+  description = [[
+    Enable or disable the Joint.  Disabled joints do not affect the simulation in any way.  If the
+    Joint is no longer needed, `Joint:destroy` is a better option that completely removes the Joint
+    from the simulation.
+  ]],
   arguments = {
     enabled = {
       type = 'boolean',
@@ -13,5 +17,8 @@ return {
       arguments = { 'enabled' },
       returns = {}
     }
+  },
+  related = {
+    'Joint:destroy'
   }
 }

api/lovr/physics/Joint/setPriority.lua

@@ -0,0 +1,21 @@
+return {
+  summary = 'Set the priority of the Joint.',
+  description = [[
+    Sets the priority of the Joint.  Joints with a higher priority are more likely to be solved
+    correctly.  Priority values are non-negative integers.
+  ]],
+  arguments = {
+    priority = {
+      type = 'number',
+      description = 'The integer priority value.'
+    }
+  },
+  returns = {},
+  variants = {
+    {
+      arguments = { 'priority' },
+      returns = {}
+    }
+  },
+  notes = 'The default priority is zero.'
+}

api/lovr/physics/Joint/setUserData.lua

@@ -1,10 +1,10 @@
 return {
-  summary = 'Set the Joint\'s user data.',
-  description = 'Sets the user data associated with the Joint.',
+  summary = 'Associate a Lua value with the Joint.',
+  description = 'Associates a Lua value with the Joint.',
   arguments = {
     data = {
       type = '*',
-      description = 'The custom value associated with the Joint.'
+      description = 'The custom value to associate with the Joint.'
     }
   },
   returns = {},
@@ -13,5 +13,16 @@ return {
       arguments = { 'data' },
       returns = {}
     }
+  },
+  notes = [[
+    Set the user data to `nil` to clear any existing reference.
+
+    The user data is not shared between threads.  Each thread has its own user data for the Joint.
+  ]],
+  related = {
+    'Collider:getUserData',
+    'Collider:setUserData',
+    'Shape:getUserData',
+    'Shape:setUserData'
   }
 }

api/lovr/physics/Shape/destroy.lua

@@ -1,6 +1,6 @@
 return {
   summary = 'Destroy the Shape.',
-  description = 'Destroy the Shape, removing it from Colliders it\'s attached to.',
+  description = 'Destroys the Shape, removing it from the Collider it\'s attached to.',
   arguments = {},
   returns = {},
   variants = {
@@ -9,8 +9,14 @@ return {
       returns = {}
     }
   },
-  notes = 'Calling functions on the Shape after destroying it is a bad idea.',
+  notes = [[
+    Calling methods on the Shape after destroying it will error (except for `Shape:isDestroyed`).
+
+    If the Shape is attached to a Collider with automatic mass enabled, the collider's mass
+    properties will update.
+  ]],
   related = {
+    'Shape:isDestroyed',
     'Collider:destroy',
     'Joint:destroy',
     'World:destroy'

api/lovr/physics/Shape/getAABB.lua

@@ -1,6 +1,6 @@
 return {
   summary = 'Get the Shape\'s axis aligned bounding box.',
-  description = 'Returns the bounding box for the Shape.',
+  description = 'Returns the axis aligned bounding box of the Shape.',
   arguments = {},
   returns = {
     minx = {

api/lovr/physics/Shape/getCollider.lua

@@ -1,11 +1,19 @@
 return {
   summary = 'Get the Collider the Shape is attached to.',
-  description = 'Returns the Collider the Shape is attached to.',
+  description = [[
+    Returns the Collider the Shape is attached to.
+
+    This function will return `nil` if the Shape is not attached to a Collider.  When a Shape isn't
+    attached to a Collider, the Shape can still be used for queries with `World:overlapShape` and
+    `World:shapecast`.
+  ]],
   arguments = {},
   returns = {
     collider = {
       type = 'Collider',
-      description = 'The Collider the Shape is attached to.'
+      description = [[
+        The Collider the Shape is attached to, or nil if the Shape isn't attached to a Collider.
+      ]]
     }
   },
   variants = {
@@ -17,6 +25,8 @@ return {
   notes = 'A Shape can only be attached to one Collider at a time.',
   related = {
     'Collider',
+    'Collider:getShape',
+    'Collider:getShapes',
     'Collider:addShape',
     'Collider:removeShape'
   }

api/lovr/physics/Shape/getDensity.lua

@@ -0,0 +1,29 @@
+return {
+  summary = 'Get the density of the Shape.',
+  description = [[
+    Returns the density of the Shape, in kilograms per cubic meter.  The density, combined with the
+    volume of the Shape, determines the Shape's overall mass.
+  ]],
+  arguments = {},
+  returns = {
+    density = {
+      type = 'number',
+      description = 'The density of the Shape, in kilograms per cubic meter.'
+    }
+  },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'density' }
+    }
+  },
+  notes = [[
+    The default density is 1,000, which is the density of water.
+
+    `MeshShape` and `TerrainShape` do not have volume, and return 0.
+  ]],
+  related = {
+    'Shape:getVolume',
+    'Shape:getMass'
+  }
+}

api/lovr/physics/Shape/getInertia.lua

@@ -0,0 +1,4 @@
+return {
+  summary = 'Get the inertia of the Shape.',
+  description = 'Returns the inertia of the Shape.'
+}

api/lovr/physics/Shape/getMass.lua

@@ -1,48 +1,35 @@
 return {
-  summary = 'Compute mass properties of the Shape.',
-  description = 'Computes mass properties of the Shape.',
-  arguments = {
-    density = {
-      type = 'number',
-      description = 'The density to use, in kilograms per cubic meter.'
-    },
-  },
+  summary = 'Get the mass of the Shape.',
+  description = [[
+    Returns the mass of the Shape, in kilograms.  The mass is the volume multiplied by the density.
+  ]],
+  arguments = {},
   returns = {
-    cx = {
-      type = 'number',
-      description = 'The x position of the center of mass.'
-    },
-    cy = {
-      type = 'number',
-      description = 'The y position of the center of mass.'
-    },
-    cz = {
-      type = 'number',
-      description = 'The z position of the center of mass.'
-    },
     mass = {
       type = 'number',
-      description = 'The mass of the Shape.'
-    },
-    inertia = {
-      type = 'table',
-      description = [[
-        A table containing 6 values of the rotational inertia tensor matrix.  The table contains the
-        3 diagonal elements of the matrix (upper left to bottom right), followed by the 3 elements
-        of the upper right portion of the 3x3 matrix.
-      ]]
+      description = 'The mass of the Shape, in kilograms.'
     }
   },
   variants = {
     {
-      arguments = { 'density' },
-      returns = { 'cx', 'cy', 'cz', 'mass', 'inertia' }
+      arguments = {},
+      returns = { 'mass' }
     }
   },
+  notes = [[
+    The mass of a Collider is the sum of the mass of all of its Shapes.  The center of a mass of a
+    Collider is the average of all of its Shapes, weighted by their mass.
+
+    `MeshShape` and `TerrainShape` do not have mass, and will return 0.
+  ]],
   related = {
     'Collider:getMass',
     'Collider:setMass',
-    'Collider:getMassData',
-    'Collider:setMassData'
+    'Collider:resetMassData',
+    'Shape:getVolume',
+    'Shape:getDensity',
+    'Shape:setDensity',
+    'Shape:getInertia',
+    'Shape:getCenterOfMass'
   }
 }

api/lovr/physics/Shape/getPosition.lua

@@ -1,6 +1,6 @@
 return {
-  summary = 'Get the Shape\'s position.',
-  description = 'Get the position of the Shape relative to its Collider.',
+  summary = 'Get the position of the Shape in the world.',
+  description = 'Get the position of the Shape in the world.',
   arguments = {},
   returns = {
     x = {

api/lovr/physics/Shape/getUserData.lua

@@ -1,6 +1,6 @@
 return {
-  summary = 'Get the Shape\'s user data.',
-  description = 'Returns the user data associated with the Shape.',
+  summary = 'Get the Lua value associated with the Shape.',
+  description = 'Returns the Lua value associated with the Shape.',
   arguments = {},
   returns = {
     data = {
@@ -14,5 +14,13 @@ return {
       returns = { 'data' }
     }
   },
-  notes = 'User data can be useful to identify the Shape in callbacks.'
+  notes = [[
+    The user data is not shared between threads.  Each thread has its own user data for the Shape.
+  ]],
+  related = {
+    'Collider:getUserData',
+    'Collider:setUserData',
+    'Joint:getUserData',
+    'Joint:setUserData'
+  }
 }

api/lovr/physics/Shape/getVolume.lua

@@ -0,0 +1,26 @@
+return {
+  summary = 'Get the volume of the Shape.',
+  description = 'Returns the volume of the Shape, in cubic meters.',
+  arguments = {},
+  returns = {
+    volume = {
+      type = 'number',
+      description = 'The volume of the shape, in cubic meters.'
+    }
+  },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'volume' }
+    }
+  },
+  notes = [[
+    `MeshShape` and `TerrainShape` do not have volume, and will return 0.
+  ]],
+  related = {
+    'Shape:getDensity',
+    'Shape:setDensity',
+    'Shape:getMass',
+    'Shape:getAABB'
+  }
+}

api/lovr/physics/Shape/isDestroyed.lua

@@ -0,0 +1,19 @@
+return {
+  summary = 'Check if the Shape is destroyed.',
+  description = [[
+    Returns whether the Shape has been destroyed.  Destroyed shapes can not be used for anything.
+  ]],
+  arguments = {},
+  returns = {
+    destroyed = {
+      type = 'boolean',
+      description = 'Whether the Shape has been destroyed.'
+    }
+  },
+  related = {
+    'Shape:destroy',
+    'Collider:isDestroyed',
+    'Joint:isDestroyed',
+    'World:isDestroyed'
+  }
+}

api/lovr/physics/Shape/setDensity.lua

@@ -0,0 +1,32 @@
+return {
+  summary = 'Set the density of the Shape.',
+  description = [[
+    Sets the density of the Shape, in kilograms per cubic meter.  The density, combined with the
+    volume of the Shape, determines the Shape's overall mass.
+  ]],
+  arguments = {
+    density = {
+      type = 'number',
+      description = 'The density of the Shape, in kilograms per cubic meter.'
+    }
+  },
+  returns = {},
+  variants = {
+    {
+      arguments = { 'density' },
+      returns = {}
+    }
+  },
+  notes = [[
+    This changes the mass of the Shape.  If the Shape is attached to a Collider with automatic mass
+    enabled, the Collider's mass properties will change as well.
+
+    The default density is 1,000, which is the density of water.
+
+    `MeshShape` and `TerrainShape` do not have mass.
+  ]],
+  related = {
+    'Shape:getVolume',
+    'Shape:getMass'
+  }
+}

api/lovr/physics/Shape/setUserData.lua

@@ -1,10 +1,10 @@
 return {
-  summary = 'Set the Shape\'s user data.',
-  description = 'Sets the user data associated with the Shape.',
+  summary = 'Associate a Lua value with the Shape.',
+  description = 'Associates a Lua value with the Shape.',
   arguments = {
     data = {
       type = '*',
-      description = 'The custom value associated with the Shape.'
+      description = 'The custom value to associate with the Shape.'
     }
   },
   returns = {},
@@ -14,5 +14,15 @@ return {
       returns = {}
     }
   },
-  notes = 'User data can be useful to identify the Shape in callbacks.'
+  notes = [[
+    Set the user data to `nil` to clear any existing reference.
+
+    The user data is not shared between threads.  Each thread has its own user data for the Shape.
+  ]],
+  related = {
+    'Collider:getUserData',
+    'Collider:setUserData',
+    'Joint:getUserData',
+    'Joint:setUserData'
+  }
 }

api/lovr/physics/SphereShape/getRadius.lua

@@ -13,8 +13,5 @@ return {
       arguments = {},
       returns = { 'radius' }
     }
-  },
-  related = {
-    'Shape:getVolume'
   }
 }

api/lovr/physics/SphereShape/setRadius.lua

@@ -1,14 +1,6 @@
 return {
   summary = 'Set the radius of the SphereShape.',
-  description = [[
-    Sets the radius of the SphereShape.
-
-    This changes the mass of the shape.  If the shape is attached to a collider and that collider is
-    set to use automatic mass, the mass properties of the collider will update as well.
-
-    Changing shapes can make the physics engine explode since it can cause objects to overlap in
-    unnatural ways.
-  ]],
+  description = 'Sets the radius of the SphereShape.',
   arguments = {
     radius = {
       type = 'number',
@@ -21,5 +13,12 @@ return {
       arguments = { 'radius' },
       returns = {}
     }
-  }
+  },
+  notes = [[
+    This changes the mass of the shape.  If the shape is attached to a collider with automatic mass
+    enabled, the mass properties of the collider will update as well.
+
+    Changing shapes can make the physics engine explode since it can cause objects to overlap in
+    unnatural ways.
+  ]]
 }

api/lovr/physics/World/destroy.lua

@@ -3,7 +3,8 @@ return {
   summary = 'Destroy the World!!  Muahaha!',
   description = [[
     Destroys the World.  This will destroy all colliders, shapes, and joints in the world.  After
-    calling this function, the world can no longer be used.
+    calling this function, the world can no longer be used.  Attempting to call a method on the
+    World after destroying it will error, with the exception of `World:isDestroyed`.
   ]],
   arguments = {},
   returns = {},
@@ -13,6 +14,12 @@ return {
       returns = {}
     }
   },
+  notes = [[
+    If a World gets garbage collected, it will be destroyed and, consequently, all of the colliders,
+    shapes, and joints in the World will be destroyed as well, even if they can still be reached by
+    Lua.  This is an exception to the way objects in LÖVR normally work, and is done to avoid issues
+    with cycles in reference counting.
+  ]],
   related = {
     'Collider:destroy',
     'Shape:destroy',