World:raycastAny/World:raycastClosest;

api/init.lua

@@ -38050,7 +38050,7 @@ return {
             {
               name = "raycast",
               tag = "worldBasics",
-              summary = "Cast a ray through the World.",
+              summary = "Cast a ray through the World, calling a function for each hit.",
               description = "Casts a ray through the World, calling a function every time the ray intersects with a Shape.",
               key = "World:raycast",
               module = "lovr.physics",
@@ -38061,6 +38061,8 @@ return {
               },
               notes = "The callback is passed the shape that was hit, the hit position (in world coordinates), and the normal vector of the hit.",
               related = {
+                "World:raycastAny",
+                "World:raycastClosest",
                 "World:queryBox",
                 "World:querySphere"
               },
@@ -38189,6 +38191,308 @@ return {
                 }
               }
             },
+            {
+              name = "raycastAny",
+              tag = "worldBasics",
+              summary = "Cast a ray through the World, returning any hit.",
+              description = "Casts a ray through the World, returning the first detected Shape that was hit.  This might not be the closest shape.",
+              key = "World:raycastAny",
+              module = "lovr.physics",
+              notes = "Compared to `World:raycast`, this avoids creating a closure and might be more convenient.  It also might be slightly faster than `World:raycastClosest` because it just returns the first hit and doesn't need to compare distance values.",
+              related = {
+                "World:raycast",
+                "World:raycastClosest",
+                "World:queryBox",
+                "World:querySphere"
+              },
+              variants = {
+                {
+                  arguments = {
+                    {
+                      name = "x1",
+                      type = "number",
+                      description = "The x coordinate of the starting position of the ray."
+                    },
+                    {
+                      name = "y1",
+                      type = "number",
+                      description = "The y coordinate of the starting position of the ray."
+                    },
+                    {
+                      name = "z1",
+                      type = "number",
+                      description = "The z coordinate of the starting position of the ray."
+                    },
+                    {
+                      name = "x2",
+                      type = "number",
+                      description = "The x coordinate of the ending position of the ray."
+                    },
+                    {
+                      name = "y2",
+                      type = "number",
+                      description = "The y coordinate of the ending position of the ray."
+                    },
+                    {
+                      name = "z2",
+                      type = "number",
+                      description = "The z coordinate of the ending position of the ray."
+                    },
+                    {
+                      name = "tag",
+                      type = "string",
+                      description = "A tag filter.  Shapes will only be returned if their Collider has this tag.",
+                      default = "nil"
+                    }
+                  },
+                  returns = {
+                    {
+                      name = "shape",
+                      type = "Shape",
+                      description = "The Shape that was hit, or nil if there wasn't a hit."
+                    },
+                    {
+                      name = "x",
+                      type = "number",
+                      description = "The x position of the intersection point."
+                    },
+                    {
+                      name = "y",
+                      type = "number",
+                      description = "The y position of the intersection point."
+                    },
+                    {
+                      name = "z",
+                      type = "number",
+                      description = "The z position of the intersection point."
+                    },
+                    {
+                      name = "nx",
+                      type = "number",
+                      description = "The x component of the normal vector at the intersection point."
+                    },
+                    {
+                      name = "ny",
+                      type = "number",
+                      description = "The y component of the normal vector at the intersection point."
+                    },
+                    {
+                      name = "nz",
+                      type = "number",
+                      description = "The z component of the normal vector at the intersection point."
+                    }
+                  }
+                },
+                {
+                  arguments = {
+                    {
+                      name = "start",
+                      type = "Vec3",
+                      description = "The starting position of the ray."
+                    },
+                    {
+                      name = "end",
+                      type = "Vec3",
+                      description = "The end position of the ray."
+                    },
+                    {
+                      name = "tag",
+                      type = "string",
+                      description = "A tag filter.  Shapes will only be returned if their Collider has this tag.",
+                      default = "nil"
+                    }
+                  },
+                  returns = {
+                    {
+                      name = "shape",
+                      type = "Shape",
+                      description = "The Shape that was hit, or nil if there wasn't a hit."
+                    },
+                    {
+                      name = "x",
+                      type = "number",
+                      description = "The x position of the intersection point."
+                    },
+                    {
+                      name = "y",
+                      type = "number",
+                      description = "The y position of the intersection point."
+                    },
+                    {
+                      name = "z",
+                      type = "number",
+                      description = "The z position of the intersection point."
+                    },
+                    {
+                      name = "nx",
+                      type = "number",
+                      description = "The x component of the normal vector at the intersection point."
+                    },
+                    {
+                      name = "ny",
+                      type = "number",
+                      description = "The y component of the normal vector at the intersection point."
+                    },
+                    {
+                      name = "nz",
+                      type = "number",
+                      description = "The z component of the normal vector at the intersection point."
+                    }
+                  }
+                }
+              }
+            },
+            {
+              name = "raycastClosest",
+              tag = "worldBasics",
+              summary = "Cast a ray through the World, returning the closest hit.",
+              description = "Casts a ray through the World, returning the closest Shape that was hit.",
+              key = "World:raycastClosest",
+              module = "lovr.physics",
+              notes = "Compared to `World:raycast`, this avoids creating a closure and might be more convenient.  It might be slightly slower than `World:raycastAny` though.",
+              related = {
+                "World:raycast",
+                "World:raycastAny",
+                "World:queryBox",
+                "World:querySphere"
+              },
+              variants = {
+                {
+                  arguments = {
+                    {
+                      name = "x1",
+                      type = "number",
+                      description = "The x coordinate of the starting position of the ray."
+                    },
+                    {
+                      name = "y1",
+                      type = "number",
+                      description = "The y coordinate of the starting position of the ray."
+                    },
+                    {
+                      name = "z1",
+                      type = "number",
+                      description = "The z coordinate of the starting position of the ray."
+                    },
+                    {
+                      name = "x2",
+                      type = "number",
+                      description = "The x coordinate of the ending position of the ray."
+                    },
+                    {
+                      name = "y2",
+                      type = "number",
+                      description = "The y coordinate of the ending position of the ray."
+                    },
+                    {
+                      name = "z2",
+                      type = "number",
+                      description = "The z coordinate of the ending position of the ray."
+                    },
+                    {
+                      name = "tag",
+                      type = "string",
+                      description = "A tag filter.  Shapes will only be returned if their Collider has this tag.",
+                      default = "nil"
+                    }
+                  },
+                  returns = {
+                    {
+                      name = "shape",
+                      type = "Shape",
+                      description = "The Shape that was hit, or nil if there wasn't a hit."
+                    },
+                    {
+                      name = "x",
+                      type = "number",
+                      description = "The x position of the intersection point."
+                    },
+                    {
+                      name = "y",
+                      type = "number",
+                      description = "The y position of the intersection point."
+                    },
+                    {
+                      name = "z",
+                      type = "number",
+                      description = "The z position of the intersection point."
+                    },
+                    {
+                      name = "nx",
+                      type = "number",
+                      description = "The x component of the normal vector at the intersection point."
+                    },
+                    {
+                      name = "ny",
+                      type = "number",
+                      description = "The y component of the normal vector at the intersection point."
+                    },
+                    {
+                      name = "nz",
+                      type = "number",
+                      description = "The z component of the normal vector at the intersection point."
+                    }
+                  }
+                },
+                {
+                  arguments = {
+                    {
+                      name = "start",
+                      type = "Vec3",
+                      description = "The starting position of the ray."
+                    },
+                    {
+                      name = "end",
+                      type = "Vec3",
+                      description = "The end position of the ray."
+                    },
+                    {
+                      name = "tag",
+                      type = "string",
+                      description = "A tag filter.  Shapes will only be returned if their Collider has this tag.",
+                      default = "nil"
+                    }
+                  },
+                  returns = {
+                    {
+                      name = "shape",
+                      type = "Shape",
+                      description = "The Shape that was hit, or nil if there wasn't a hit."
+                    },
+                    {
+                      name = "x",
+                      type = "number",
+                      description = "The x position of the intersection point."
+                    },
+                    {
+                      name = "y",
+                      type = "number",
+                      description = "The y position of the intersection point."
+                    },
+                    {
+                      name = "z",
+                      type = "number",
+                      description = "The z position of the intersection point."
+                    },
+                    {
+                      name = "nx",
+                      type = "number",
+                      description = "The x component of the normal vector at the intersection point."
+                    },
+                    {
+                      name = "ny",
+                      type = "number",
+                      description = "The y component of the normal vector at the intersection point."
+                    },
+                    {
+                      name = "nz",
+                      type = "number",
+                      description = "The z component of the normal vector at the intersection point."
+                    }
+                  }
+                }
+              }
+            },
             {
               name = "setAngularDamping",
               tag = "worldProperties",

api/lovr/physics/World/raycast.lua

@@ -1,6 +1,6 @@
 return {
   tag = 'worldBasics',
-  summary = 'Cast a ray through the World.',
+  summary = 'Cast a ray through the World, calling a function for each hit.',
   description = [[
     Casts a ray through the World, calling a function every time the ray intersects with a Shape.
   ]],
@@ -105,6 +105,8 @@ return {
     end
   ]],
   related = {
+    'World:raycastAny',
+    'World:raycastClosest',
     'World:queryBox',
     'World:querySphere'
   }

api/lovr/physics/World/raycastAny.lua

@@ -0,0 +1,98 @@
+return {
+  tag = 'worldBasics',
+  summary = 'Cast a ray through the World, returning any hit.',
+  description = [[
+    Casts a ray through the World, returning the first detected Shape that was hit.  This might not
+    be the closest shape.
+  ]],
+  arguments = {
+    x1 = {
+      type = 'number',
+      description = 'The x coordinate of the starting position of the ray.',
+    },
+    y1 = {
+      type = 'number',
+      description = 'The y coordinate of the starting position of the ray.',
+    },
+    z1 = {
+      type = 'number',
+      description = 'The z coordinate of the starting position of the ray.',
+    },
+    x2 = {
+      type = 'number',
+      description = 'The x coordinate of the ending position of the ray.',
+    },
+    y2 = {
+      type = 'number',
+      description = 'The y coordinate of the ending position of the ray.',
+    },
+    z2 = {
+      type = 'number',
+      description = 'The z coordinate of the ending position of the ray.',
+    },
+    start = {
+      type = 'Vec3',
+      description = 'The starting position of the ray.'
+    },
+    ['end'] = {
+      type = 'Vec3',
+      description = 'The end position of the ray.'
+    },
+    tag = {
+      type = 'string',
+      default = 'nil',
+      description = 'A tag filter.  Shapes will only be returned if their Collider has this tag.'
+    }
+  },
+  returns = {
+    shape = {
+      type = 'Shape',
+      description = 'The Shape that was hit, or nil if there wasn\'t a hit.'
+    },
+    x = {
+      type = 'number',
+      description = 'The x position of the intersection point.'
+    },
+    y = {
+      type = 'number',
+      description = 'The y position of the intersection point.'
+    },
+    z = {
+      type = 'number',
+      description = 'The z position of the intersection point.'
+    },
+    nx = {
+      type = 'number',
+      description = 'The x component of the normal vector at the intersection point.'
+    },
+    ny = {
+      type = 'number',
+      description = 'The y component of the normal vector at the intersection point.'
+    },
+    nz = {
+      type = 'number',
+      description = 'The z component of the normal vector at the intersection point.'
+    }
+  },
+  variants = {
+    {
+      arguments = { 'x1', 'y1', 'z1', 'x2', 'y2', 'z2', 'tag' },
+      returns = { 'shape', 'x', 'y', 'z', 'nx', 'ny', 'nz' }
+    },
+    {
+      arguments = { 'start', 'end', 'tag' },
+      returns = { 'shape', 'x', 'y', 'z', 'nx', 'ny', 'nz' }
+    }
+  },
+  notes = [[
+    Compared to `World:raycast`, this avoids creating a closure and might be more convenient.  It
+    also might be slightly faster than `World:raycastClosest` because it just returns the first hit
+    and doesn't need to compare distance values.
+  ]],
+  related = {
+    'World:raycast',
+    'World:raycastClosest',
+    'World:queryBox',
+    'World:querySphere'
+  }
+}

api/lovr/physics/World/raycastClosest.lua

@@ -0,0 +1,94 @@
+return {
+  tag = 'worldBasics',
+  summary = 'Cast a ray through the World, returning the closest hit.',
+  description = 'Casts a ray through the World, returning the closest Shape that was hit.',
+  arguments = {
+    x1 = {
+      type = 'number',
+      description = 'The x coordinate of the starting position of the ray.',
+    },
+    y1 = {
+      type = 'number',
+      description = 'The y coordinate of the starting position of the ray.',
+    },
+    z1 = {
+      type = 'number',
+      description = 'The z coordinate of the starting position of the ray.',
+    },
+    x2 = {
+      type = 'number',
+      description = 'The x coordinate of the ending position of the ray.',
+    },
+    y2 = {
+      type = 'number',
+      description = 'The y coordinate of the ending position of the ray.',
+    },
+    z2 = {
+      type = 'number',
+      description = 'The z coordinate of the ending position of the ray.',
+    },
+    start = {
+      type = 'Vec3',
+      description = 'The starting position of the ray.'
+    },
+    ['end'] = {
+      type = 'Vec3',
+      description = 'The end position of the ray.'
+    },
+    tag = {
+      type = 'string',
+      default = 'nil',
+      description = 'A tag filter.  Shapes will only be returned if their Collider has this tag.'
+    }
+  },
+  returns = {
+    shape = {
+      type = 'Shape',
+      description = 'The Shape that was hit, or nil if there wasn\'t a hit.'
+    },
+    x = {
+      type = 'number',
+      description = 'The x position of the intersection point.'
+    },
+    y = {
+      type = 'number',
+      description = 'The y position of the intersection point.'
+    },
+    z = {
+      type = 'number',
+      description = 'The z position of the intersection point.'
+    },
+    nx = {
+      type = 'number',
+      description = 'The x component of the normal vector at the intersection point.'
+    },
+    ny = {
+      type = 'number',
+      description = 'The y component of the normal vector at the intersection point.'
+    },
+    nz = {
+      type = 'number',
+      description = 'The z component of the normal vector at the intersection point.'
+    }
+  },
+  variants = {
+    {
+      arguments = { 'x1', 'y1', 'z1', 'x2', 'y2', 'z2', 'tag' },
+      returns = { 'shape', 'x', 'y', 'z', 'nx', 'ny', 'nz' }
+    },
+    {
+      arguments = { 'start', 'end', 'tag' },
+      returns = { 'shape', 'x', 'y', 'z', 'nx', 'ny', 'nz' }
+    }
+  },
+  notes = [[
+    Compared to `World:raycast`, this avoids creating a closure and might be more convenient.  It
+    might be slightly slower than `World:raycastAny` though.
+  ]],
+  related = {
+    'World:raycast',
+    'World:raycastAny',
+    'World:queryBox',
+    'World:querySphere'
+  }
+}