Update lovr.headset docs;

api/lovr/graphics/Model/init.lua

@@ -6,7 +6,7 @@ return {
   ]],
   constructors = {
     'lovr.graphics.newModel',
-    'Controller:newModel'
+    'lovr.headset.newModel'
   },
   example = [[
     local model

api/lovr/headset/Controller/getAngularVelocity.lua

@@ -1,27 +0,0 @@
-return {
-  summary = 'Get the angular velocity of the Controller.',
-  description = 'Returns the current angular velocity of the Controller.',
-  arguments = {},
-  returns = {
-    {
-      name = 'x',
-      type = 'number',
-      description = 'The x component of the angular velocity.'
-    },
-    {
-      name = 'y',
-      type = 'number',
-      description = 'The y component of the angular velocity.'
-    },
-    {
-      name = 'z',
-      type = 'number',
-      description = 'The z component of the angular velocity.'
-    }
-  },
-  related = {
-    'Controller:getVelocity',
-    'Controller:getOrientation',
-    'Controller:getPosition'
-  }
-}

api/lovr/headset/Controller/getAxis.lua

@@ -1,22 +0,0 @@
-return {
-  summary = 'Get the state of an axis on the Controller.',
-  description = 'Get the current state of an axis on the Controller.  Axis values are from 0 to 1.',
-  arguments = {
-    {
-      name = 'axis',
-      type = 'ControllerAxis',
-      description = 'The axis to query.'
-    }
-  },
-  returns = {
-    {
-      name = 'value',
-      type = 'number',
-      description = 'The current state of the axis.'
-    }
-  },
-  related = {
-    'ControllerAxis',
-    'Controller:isDown'
-  }
-}

api/lovr/headset/Controller/getHand.lua

@@ -1,15 +0,0 @@
-return {
-  summary = 'Get the hand the Controller is in.',
-  description = 'Returns which hand the controller is in, if known.',
-  arguments = {},
-  returns = {
-    {
-      name = 'hand',
-      type = 'ControllerHand',
-      description = 'The hand the controller is in.'
-    }
-  },
-  related = {
-    'ControllerHand'
-  }
-}

api/lovr/headset/Controller/getOrientation.lua

@@ -1,31 +0,0 @@
-return {
-  summary = 'Get the orientation of the Controller.',
-  description = 'Returns the current orientation of the Controller.',
-  arguments = {},
-  returns = {
-    {
-      name = 'angle',
-      type = 'number',
-      description = 'The number of radians the Controller is rotated around its axis of rotation.'
-    },
-    {
-      name = 'ax',
-      type = 'number',
-      description = 'The x component of the axis of rotation.'
-    },
-    {
-      name = 'ay',
-      type = 'number',
-      description = 'The y component of the axis of rotation.'
-    },
-    {
-      name = 'az',
-      type = 'number',
-      description = 'The z component of the axis of rotation.'
-    }
-  },
-  related = {
-    'lovr.headset.getOrientation',
-    'Controller:getPosition',
-  }
-}

api/lovr/headset/Controller/getPosition.lua

@@ -1,27 +0,0 @@
-return {
-  summary = 'Get the position of the Controller.',
-  description = 'Returns the current position of the Controller.',
-  arguments = {},
-  returns = {
-    {
-      name = 'x',
-      type = 'number',
-      description = 'The x position of the Controller.'
-    },
-    {
-      name = 'y',
-      type = 'number',
-      description = 'The y position of the Controller.'
-    },
-    {
-      name = 'z',
-      type = 'number',
-      description = 'The z position of the Controller.'
-    }
-  },
-  notes = 'Units are in meters.',
-  related = {
-    'lovr.headset.getPosition',
-    'Controller:getOrientation'
-  }
-}

api/lovr/headset/Controller/getVelocity.lua

@@ -1,27 +0,0 @@
-return {
-  summary = 'Get the linear velocity of the Controller.',
-  description = 'Returns the current linear velocity of the Controller, in meters per second.',
-  arguments = {},
-  returns = {
-    {
-      name = 'vx',
-      type = 'number',
-      description = 'The x component of the linear velocity.'
-    },
-    {
-      name = 'vy',
-      type = 'number',
-      description = 'The y component of the linear velocity.'
-    },
-    {
-      name = 'vz',
-      type = 'number',
-      description = 'The z component of the linear velocity.'
-    }
-  },
-  related = {
-    'Controller:getPosition',
-    'Controller:getOrientation',
-    'Controller:getAngularVelocity'
-  }
-}

api/lovr/headset/Controller/init.lua

@@ -1,29 +0,0 @@
-return {
-  summary = 'An object used to interact with connected VR controllers.',
-  description = [[
-    Controller objects represent the controllers held in players' hands.  To obtain a list of
-    currently connected controllers, use `lovr.headset.getControllers`.  To determine when
-    controllers are added and removed, use `lovr.controlleradded` and `lovr.controllerremoved`.
-    Often Controllers won't be considered "active" until they are moved around a bit.
-  ]],
-  example = {
-    description = 'Draw cubes for the controllers and vibrate them if the trigger is pressed.',
-    code = [[
-      function lovr.update(dt)
-        for i, controller in ipairs(lovr.headset.getControllers()) do
-          if controller:getAxis('trigger') > .9 then
-            controller:vibrate(.004)
-          end
-        end
-      end
-
-      function lovr.draw()
-        for i, controller in ipairs(lovr.headset.getControllers()) do
-          local x, y, z = controller:getPosition()
-          local angle, ax, ay, az = controller:getOrientation()
-          lovr.graphics.cube('fill', x, y, z, .08, angle, ax, ay, az)
-        end
-      end
-    ]]
-  }
-}

api/lovr/headset/Controller/isConnected.lua

@@ -1,17 +0,0 @@
-return {
-  summary = 'Determine if the Controller is still connected.',
-  description = 'Determine if the Controller is still connected.',
-  arguments = {},
-  returns = {
-    {
-      name = 'connected',
-      type = 'boolean',
-      description = 'Whether or not the Controller is connected.'
-    }
-  },
-  related = {
-    'lovr.headset.getControllers',
-    'lovr.controlleradded',
-    'lovr.controllerremoved'
-  }
-}

api/lovr/headset/Controller/isDown.lua

@@ -1,23 +0,0 @@
-return {
-  summary = 'Get the state of a button on the Controller.',
-  description = 'Returns the state of a button on the Controller.',
-  arguments = {
-    {
-      name = 'button',
-      type = 'ControllerButton',
-      description = 'The button to query.'
-    }
-  },
-  returns = {
-    {
-      name = 'down',
-      type = 'boolean',
-      description = 'The current state of the button.'
-    }
-  },
-  related = {
-    'ControllerButton',
-    'Controller:isTouched',
-    'Controller:getAxis'
-  }
-}

api/lovr/headset/Controller/isTouched.lua

@@ -1,26 +0,0 @@
-return {
-  summary = 'Check whether a button on the Controller is touched.',
-  description = [[
-    Returns whether or not a given button on the Controller is currently touched.  This may not mean
-    the button is actually pressed since some controllers are touch-sensitive.
-  ]],
-  arguments = {
-    {
-      name = 'button',
-      type = 'ControllerButton',
-      description = 'The button to query.'
-    }
-  },
-  returns = {
-    {
-      name = 'touched',
-      type = 'boolean',
-      description = 'Whether the button is touched.'
-    }
-  },
-  related = {
-    'ControllerButton',
-    'Controller:isDown',
-    'Controller:getAxis'
-  }
-}

api/lovr/headset/Controller/newModel.lua

@@ -1,25 +0,0 @@
-return {
-  summary = 'Get a Model for the Controller.',
-  description = 'Returns a new Model for the Controller.',
-  arguments = {},
-  returns = {
-    {
-      name = 'model',
-      type = 'Model',
-      description = 'The new Model, or `nil` if a model could not be loaded.'
-    }
-  },
-  notes = 'The Model will have a Texture applied.',
-  example = [[
-    local models = {}
-
-    function lovr.draw()
-      for _, controller in ipairs(lovr.headset.getControllers()) do
-        local x, y, z = controller:getPosition()
-        local angle, ax, ay, az = controller:getOrientation()
-        models[controller] = models[controller] or controller:newModel()
-        models[controller]:draw(x, y, z, 1, angle, ax, ay, az)
-      end
-    end
-  ]]
-}

api/lovr/headset/Controller/vibrate.lua

@@ -1,16 +0,0 @@
-return {
-  summary = 'Make the Controller go BZZZ!',
-  description = 'Causes the Controller to vibrate for a specified duration.',
-  arguments = {
-    {
-      name = 'duration',
-      type = 'number',
-      description = 'The amount of time to vibrate the Controller, in seconds.'
-    }
-  },
-  returns = {},
-  notes = [[
-    On the HTC Vive, the value for the `duration` currently must be less than .004 seconds.  Call
-    this function several frames in a row for stronger or prolonged vibration patterns.
-  ]]
-}

api/lovr/headset/ControllerAxis.lua

@@ -1,21 +0,0 @@
-return {
-  description = 'Axes on a Controller.',
-  values = {
-    {
-      name = 'grip',
-      description = 'The grip.'
-    },
-    {
-      name = 'trigger',
-      description = 'The trigger.'
-    },
-    {
-      name = 'touchx',
-      description = 'The x axis of the touchpad.  Positive values are to the right.'
-    },
-    {
-      name = 'touchy',
-      description = 'The y axis of the touchpad.  Positive values are upwards.'
-    }
-  }
-}

api/lovr/headset/Device.lua

@@ -0,0 +1,48 @@
+return {
+  description = 'Different types of input devices supported by the `lovr.headset` module.',
+  values = {
+    {
+      name = 'head',
+      description = 'The headset.'
+    },
+    {
+      name = 'hand',
+      description = [[
+        A hand with an unknown handedness, found on systems with a single controller like the Oculus
+        Go.
+      ]]
+    },
+    {
+      name = 'hand/left',
+      description = 'The left controller.'
+    },
+    {
+      name = 'hand/right',
+      description = 'The right controller.'
+    },
+    {
+      name = 'eye/left',
+      description = 'The left eye.'
+    },
+    {
+      name = 'eye/right',
+      description = 'The right eye.'
+    },
+    {
+      name = 'tracker/1',
+      description = 'The first tracker.'
+    },
+    {
+      name = 'tracker/2',
+      description = 'The second tracker.'
+    },
+    {
+      name = 'tracker/3',
+      description = 'The third tracker.'
+    },
+    {
+      name = 'tracker/4',
+      description = 'The fourth tracker.'
+    }
+  }
+}

api/lovr/headset/DeviceAxis.lua

@@ -0,0 +1,30 @@
+return {
+  description = 'Axes on an input device.',
+  values = {
+    {
+      name = 'trigger',
+      description = 'A trigger (1D).'
+    },
+    {
+      name = 'thumbstick',
+      description = 'A thumbstick (2D).'
+    },
+    {
+      name = 'touchpad',
+      description = 'A touchpad (2D).'
+    },
+    {
+      name = 'pinch',
+      description = 'A tracked pinch gesture between the thumb and index finger (1D, Leap Motion).'
+    },
+    {
+      name = 'grip',
+      description = 'A grip button or grab gesture (1D).'
+    }
+  },
+  related = {
+    'lovr.headset.getAxis',
+    'DeviceButton',
+    'DeviceBone'
+  }
+}

api/lovr/headset/DeviceBone.lua

@@ -0,0 +1,107 @@
+return {
+  description = 'Bones tracked by input devices.',
+  values = {
+    {
+      name = 'thumb',
+      description = 'The tip of the thumb.'
+    },
+    {
+      name = 'thumb/1',
+      description = 'The metacarpal bone of the thumb.'
+    },
+    {
+      name = 'thumb/2',
+      description = 'The proximal bone of the thumb.'
+    },
+    {
+      name = 'thumb/3',
+      description = 'The distal bone of the thumb.'
+    },
+    {
+      name = 'index',
+      description = 'The tip of the index finger.'
+    },
+    {
+      name = 'index/1',
+      description = 'The metacarpal bone of the index finger.'
+    },
+    {
+      name = 'index/2',
+      description = 'The proximal bone of the index finger.'
+    },
+    {
+      name = 'index/3',
+      description = 'The intermediate bone of the index finger.'
+    },
+    {
+      name = 'index/4',
+      description = 'The distal bone of the index finger.'
+    },
+    {
+      name = 'middle',
+      description = 'The tip of the middle finger.'
+    },
+    {
+      name = 'middle/1',
+      description = 'The metacarpal bone of the middle finger.'
+    },
+    {
+      name = 'middle/2',
+      description = 'The proximal bone of the middle finger.'
+    },
+    {
+      name = 'middle/3',
+      description = 'The intermediate bone of the middle finger.'
+    },
+    {
+      name = 'middle/4',
+      description = 'The distal bone of the middle finger.'
+    },
+    {
+      name = 'ring',
+      description = 'The tip of the ring finger.'
+    },
+    {
+      name = 'ring/1',
+      description = 'The metacarpal bone of the ring finger.'
+    },
+    {
+      name = 'ring/2',
+      description = 'The proximal bone of the ring finger.'
+    },
+    {
+      name = 'ring/3',
+      description = 'The intermediate bone of the ring finger.'
+    },
+    {
+      name = 'ring/4',
+      description = 'The distal bone of the ring finger.'
+    },
+    {
+      name = 'pinky',
+      description = 'The tip of the pinky finger.'
+    },
+    {
+      name = 'pinky/1',
+      description = 'The metacarpal bone of the pinky finger.'
+    },
+    {
+      name = 'pinky/2',
+      description = 'The proximal bone of the pinky finger.'
+    },
+    {
+      name = 'pinky/3',
+      description = 'The intermediate bone of the pinky finger.'
+    },
+    {
+      name = 'pinky/4',
+      description = 'The distal bone of the pinky finger.'
+    },
+  },
+  related = {
+    'lovr.headset.getBonePose',
+    'DeviceButton',
+    'DeviceAxis',
+    'Animator'
+  }
+}

api/lovr/headset/ControllerButton.lua → api/lovr/headset/DeviceButton.lua

@@ -1,41 +1,49 @@
 return {
-  description = 'Buttons on a Controller.',
+  description = 'Buttons on an input device.',
   values = {
     {
-      name = 'system',
-      description = 'The system button.'
+      name = 'trigger',
+      description = 'The trigger button.'
     },
     {
-      name = 'menu',
-      description = 'The menu button.'
+      name = 'thumbstick',
+      description = 'The thumbstick.'
     },
     {
-      name = 'trigger',
-      description = 'The trigger button.'
+      name = 'touchpad',
+      description = 'The touchpad.'
     },
     {
       name = 'grip',
       description = 'The grip button.'
     },
+    {
+      name = 'menu',
+      description = 'The menu button.'
+    },
     {
       name = 'touchpad',
       description = 'The button on the touchpad.'
     },
     {
       name = 'a',
-      description = 'The A button present on Oculus Touch controllers.'
+      description = 'The A button.'
     },
     {
       name = 'b',
-      description = 'The B button present on Oculus Touch controllers.'
+      description = 'The B button.'
     },
     {
       name = 'x',
-      description = 'The X button present on Oculus Touch controllers.'
+      description = 'The X button.'
     },
     {
       name = 'y',
-      description = 'The Y button present on Oculus Touch controllers.'
+      description = 'The Y button.'
+    },
+    {
+      name = 'proximity',
+      description = 'The proximity sensor on a headset.'
     }
   }
 }

api/lovr/headset/HeadsetEye.lua

@@ -1,16 +0,0 @@
-return {
-  summary = 'The two different eyes.',
-  description = [[
-    Represents either the left eye or the right eye.
-  ]],
-  values = {
-    {
-      name = 'left',
-      description = 'The left eye.'
-    },
-    {
-      name = 'right',
-      description = 'The right eye.'
-    }
-  }
-}

api/lovr/headset/getAcceleration.lua

@@ -0,0 +1,39 @@
+return {
+  tag = 'input',
+  summary = 'Get the linear acceleration of a device.',
+  description = [[
+    Returns the current linear acceleration of a device, in meters per second per second.
+  ]],
+  arguments = {
+    {
+      name = 'device',
+      type = 'Device',
+      default = 'head',
+      description = 'The device to get the acceleration of.'
+    }
+  },
+  returns = {
+    {
+      name = 'ax',
+      type = 'number',
+      description = 'The x component of the linear acceleration.'
+    },
+    {
+      name = 'ay',
+      type = 'number',
+      description = 'The y component of the linear acceleration.'
+    },
+    {
+      name = 'az',
+      type = 'number',
+      description = 'The z component of the linear acceleration.'
+    }
+  },
+  related = {
+    'lovr.headset.getPosition',
+    'lovr.headset.getOrientation',
+    'lovr.headset.getVelocity',
+    'lovr.headset.getAngularVelocity',
+    'lovr.headset.getAngularAcceleration'
+  }
+}

api/lovr/headset/getAngularAcceleration.lua

@@ -0,0 +1,37 @@
+return {
+  tag = 'input',
+  summary = 'Get the angular acceleration of a device.',
+  description = 'Returns the current angular acceleration of a device.',
+  arguments = {
+    {
+      name = 'device',
+      type = 'Device',
+      default = 'head',
+      description = 'The device to get the acceleration of.'
+    }
+  },
+  returns = {
+    {
+      name = 'ax',
+      type = 'number',
+      description = 'The x component of the angular acceleration.'
+    },
+    {
+      name = 'ay',
+      type = 'number',
+      description = 'The y component of the angular acceleration.'
+    },
+    {
+      name = 'az',
+      type = 'number',
+      description = 'The z component of the angular acceleration.'
+    }
+  },
+  related = {
+    'lovr.headset.getPosition',
+    'lovr.headset.getOrientation',
+    'lovr.headset.getVelocity',
+    'lovr.headset.getAngularVelocity',
+    'lovr.headset.getAcceleration'
+  }
+}

api/lovr/headset/getAngularVelocity.lua

@@ -1,8 +1,15 @@
 return {
-  tag = 'headset',
-  summary = 'Get the angular velocity of the headset.',
-  description = 'Returns the current angular velocity of the headset.',
-  arguments = {},
+  tag = 'input',
+  summary = 'Get the angular velocity of a device.',
+  description = 'Returns the current angular velocity of a device.',
+  arguments = {
+    {
+      name = 'device',
+      type = 'Device',
+      default = 'head',
+      description = 'The device to get the velocity of.'
+    }
+  },
   returns = {
     {
       name = 'x',
@@ -21,8 +28,10 @@ return {
     }
   },
   related = {
+    'lovr.headset.getPosition',
     'lovr.headset.getOrientation',
     'lovr.headset.getVelocity',
-    'lovr.headset.getPosition'
+    'lovr.headset.getAcceleration',
+    'lovr.headset.getAngularAcceleration',
   }
 }

api/lovr/headset/getAxis.lua

@@ -0,0 +1,35 @@
+return {
+  tag = 'input',
+  summary = 'Get the state of an analog axis on a device.',
+  description = [[
+    Get the current state of an analog axis on a device.  Axis values are usually between 0 and 1.
+     Some axes are multidimensional, for example a 2D touchpad or thumbstick with x/y axes.  For
+     multidimensional axes, this function will return multiple values, one number for each axis.
+  ]],
+  arguments = {
+    {
+      name = 'device',
+      type = 'Device',
+      description = 'The device.'
+    },
+    {
+      name = 'axis',
+      type = 'DeviceAxis',
+      description = 'The axis.'
+    }
+  },
+  returns = {
+    {
+      name = '...',
+      type = 'number',
+      description = [[
+        The current state of the components of the axis, or `nil` if the device does not have any
+        information about the axis.
+      ]]
+    }
+  },
+  related = {
+    'DeviceAxis',
+    'lovr.headset.isDown'
+  }
+}

api/lovr/headset/Controller/getPose.lua → api/lovr/headset/getBonePose.lua

@@ -1,27 +1,42 @@
 return {
-  summary = 'Get the pose of the Controller.',
-  description = 'Returns the current position and orientation of the Controller.',
-  arguments = {},
+  tag = 'input',
+  summary = 'Get the pose of a tracked bone.',
+  description = [[
+    Returns the current position and orientation of a bone tracked by a device.  This is mainly used
+    for tracking hands.
+  ]],
+  arguments = {
+    {
+      name = 'device',
+      type = 'Device',
+      description = 'The device.'
+    },
+    {
+      name = 'bone',
+      type = 'DeviceBone',
+      description = 'The bone.'
+    }
+  },
   returns = {
     {
       name = 'x',
       type = 'number',
-      description = 'The x position of the Controller.'
+      description = 'The x position.'
     },
     {
       name = 'y',
       type = 'number',
-      description = 'The y position of the Controller.'
+      description = 'The y position.'
     },
     {
       name = 'z',
       type = 'number',
-      description = 'The z position of the Controller.'
+      description = 'The z position.'
     },
     {
       name = 'angle',
       type = 'number',
-      description = 'The number of radians the Collider is rotated around its axis of rotation.'
+      description = 'The amount of rotation around the axis of rotation, in radians.'
     },
     {
       name = 'ax',
@@ -41,8 +56,6 @@ return {
   },
   notes = 'Units are in meters.',
   related = {
-    'Controller:getPosition',
-    'Controller:getOrientation',
     'lovr.headset.getPose'
   }
 }

api/lovr/headset/getControllerCount.lua

@@ -1,16 +0,0 @@
-return {
-  tag = 'controllers',
-  summary = 'Get the number of currently connected controller objects.',
-  description = 'Returns the number of currently connected controllers.',
-  arguments = {},
-  returns = {
-    {
-      name = 'count',
-      type = 'number',
-      description = 'The number of currently connected controllers.'
-    }
-  },
-  related = {
-    'lovr.headset.getControllers'
-  }
-}

api/lovr/headset/getControllers.lua

@@ -1,16 +0,0 @@
-return {
-  tag = 'controllers',
-  summary = 'Get a list of currently connected controller objects.',
-  description = 'Returns a list of currently connected controllers.',
-  arguments = {},
-  returns = {
-    {
-      name = 'controllers',
-      type = 'table',
-      description = 'A list of Controller objects.'
-    }
-  },
-  related = {
-    'lovr.headset.getControllerCount'
-  }
-}

api/lovr/headset/getDriver.lua

@@ -1,16 +1,36 @@
 return {
   tag = 'headset',
-  summary = 'Get the VR API currently in use.',
+  summary = 'Get the VR API currently in use for a device.',
   description = [[
-    Returns the `HeadsetDriver` that is currently powering the lovr.headset module.  You can change
-    the order of headset drivers using `lovr.conf` to prefer or exclude specific VR APIs.
+    Returns the `HeadsetDriver` that is currently in use, optionally for a specific device.  You can
+    change the order of headset drivers using `lovr.conf` to prefer or exclude specific VR APIs.
   ]],
-  arguments = {},
+  arguments = {
+    device = {
+      type = 'Device',
+      default = 'head',
+      description = [[
+        The device to get the active driver of.  This will be the first driver that is currently
+        returning a pose for the device.
+      ]]
+    }
+  },
   returns = {
-    {
-      name = 'driver',
+    driver = {
       type = 'HeadsetDriver',
       description = 'The driver of the headset in use, e.g. "OpenVR".'
     }
+  },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'driver' },
+      description = 'Return the current driver for the headset display.'
+    },
+    {
+      arguments = { 'device' },
+      returns = { 'driver' },
+      description = 'Return the current input driver for a device.'
+    }
   }
 }

api/lovr/headset/getName.lua

@@ -0,0 +1,16 @@
+return {
+  tag = 'headset',
+  summary = 'Get the name of the connected headset display.',
+  description = [[
+    Returns the name of the headset as a string.  The exact string that is returned depends on the
+    hardware and VR SDK that is currently in use.
+  ]],
+  arguments = {},
+  returns = {
+    {
+      name = 'name',
+      type = 'string',
+      description = 'The name of the headset as a string.'
+    }
+  }
+}

api/lovr/headset/getOrientation.lua

@@ -1,13 +1,20 @@
 return {
-  tag = 'headset',
-  summary = 'Get the orientation of the headset.',
-  description = 'Returns the current orientation of the headset.',
-  arguments = {},
+  tag = 'input',
+  summary = 'Get the orientation of a device.',
+  description = 'Returns the current orientation of a device, in angle/axis form.',
+  arguments = {
+    {
+      name = 'device',
+      type = 'Device',
+      default = 'head',
+      description = 'The device to get the orientation of.'
+    }
+  },
   returns = {
     {
       name = 'angle',
       type = 'number',
-      description = 'The amount of rotation around the axis of rotation.'
+      description = 'The amount of rotation around the axis of rotation, in radians.'
     },
     {
       name = 'ax',
@@ -28,6 +35,8 @@ return {
   related = {
     'lovr.headset.getPosition',
     'lovr.headset.getVelocity',
-    'lovr.headset.getAngularVelocity'
+    'lovr.headset.getAngularVelocity',
+    'lovr.headset.getAcceleration',
+    'lovr.headset.getAngularAcceleration'
   }
 }

api/lovr/headset/getPose.lua

@@ -1,8 +1,15 @@
 return {
-  tag = 'headset',
-  summary = 'Get the pose of the headset.',
-  description = 'Returns the current position and orientation of the headset.',
-  arguments = {},
+  tag = 'input',
+  summary = 'Get the pose of a device.',
+  description = 'Returns the current position and orientation of a device.',
+  arguments = {
+    {
+      name = 'device',
+      type = 'Device',
+      default = 'head',
+      description = 'The device to get the pose of.'
+    }
+  },
   returns = {
     {
       name = 'x',
@@ -42,6 +49,7 @@ return {
   },
   notes = 'Units are in meters.',
   related = {
+    'lovr.headset.getBonePose',
     'lovr.headset.getPosition',
     'lovr.headset.getOrientation',
   }

api/lovr/headset/getPosition.lua

@@ -1,28 +1,37 @@
 return {
-  tag = 'headset',
-  summary = 'Get the position of the headset.',
-  description = 'Returns the current position of the headset.',
-  arguments = {},
+  tag = 'input',
+  summary = 'Get the position of a device.',
+  description = 'Returns the current position of a device, in meters, relative to the play area.',
+  arguments = {
+    {
+      name = 'device',
+      type = 'Device',
+      default = 'head',
+      description = 'The device to get the position of.'
+    }
+  },
   returns = {
     {
       name = 'x',
       type = 'number',
-      description = 'The x position of the headset.'
+      description = 'The x position of the device.'
     },
     {
       name = 'y',
       type = 'number',
-      description = 'The y position of the headset.'
+      description = 'The y position of the device.'
     },
     {
       name = 'z',
       type = 'number',
-      description = 'The z position of the headset.'
+      description = 'The z position of the device.'
     }
   },
   related = {
     'lovr.headset.getOrientation',
     'lovr.headset.getVelocity',
-    'lovr.headset.getAngularVelocity'
+    'lovr.headset.getAngularVelocity',
+    'lovr.headset.getAcceleration',
+    'lovr.headset.getAngularAcceleration'
   }
 }

api/lovr/headset/getType.lua

@@ -1,13 +0,0 @@
-return {
-  tag = 'headset',
-  summary = 'Get the type of connected headset.',
-  description = 'Returns the type of headset as a string, see HeadsetType.',
-  arguments = {},
-  returns = {
-    {
-      name = 'type',
-      type = 'HeadsetType',
-      description = 'The type of the headset as a string, e.g. "Vive" for the HTC Vive.'
-    }
-  }
-}

api/lovr/headset/getVelocity.lua

@@ -1,8 +1,15 @@
 return {
-  tag = 'headset',
-  summary = 'Get the linear velocity of the headset.',
-  description = 'Returns the current linear velocity of the headset, in meters per second.',
-  arguments = {},
+  tag = 'input',
+  summary = 'Get the linear velocity of a device.',
+  description = 'Returns the current linear velocity of a device, in meters per second.',
+  arguments = {
+    {
+      name = 'device',
+      type = 'Device',
+      default = 'head',
+      description = 'The device to get the velocity of.'
+    }
+  },
   returns = {
     {
       name = 'vx',
@@ -23,6 +30,8 @@ return {
   related = {
     'lovr.headset.getPosition',
     'lovr.headset.getOrientation',
-    'lovr.headset.getAngularVelocity'
+    'lovr.headset.getAngularVelocity',
+    'lovr.headset.getAcceleration',
+    'lovr.headset.getAngularAcceleration'
   }
 }

api/lovr/headset/hands.lua

@@ -0,0 +1,21 @@
+return {
+  summary = 'Iterate over currently tracked hand devices.',
+  description = 'Returns a Lua iterator for all of the currently tracked hand devices.',
+  arguments = {},
+  returns = {
+    {
+      name = 'iterator',
+      type = 'function',
+      arguments = {},
+      returns = {},
+      description = 'The iterator function, usable in a for loop.  Will return `Device` paths.'
+    }
+  },
+  example = [[
+    function lovr.update(dt)
+      for hand in lovr.headset.hands() do
+        print(hand, lovr.headset.getPose(hand))
+      end
+    end
+  ]]
+}

api/lovr/headset/init.lua

@@ -10,9 +10,13 @@ return {
     {
       name = 'Headset',
       tag = 'headset',
+      description = 'Functions that return information about the active head mounted display (HMD).'
+    },
+    {
+      name = 'Input',
+      tag = 'input',
       description = [[
-        Functions that return information about the head mounted display (HMD) currently strapped to
-        the player's face.
+        Functions for accessing input devices, like controllers, hands, trackers, or gamepads.
       ]]
     },
     {
@@ -23,14 +27,6 @@ return {
         information about the "chaperone", a visual indicator that appears whenever a player is
         about to run into a wall.
       ]]
-    },
-    {
-      name = 'Controllers',
-      tag = 'controllers',
-      description = [[
-        Get a list of connected `Controller`s.  Also see `lovr.controlleradded` and
-        `lovr.controllerremoved`.
-      ]]
     }
   }
 }

api/lovr/headset/isDown.lua

@@ -0,0 +1,32 @@
+return {
+  tag = 'input',
+  summary = 'Get the state of a button on a device.',
+  description = 'Returns whether a button on a device is pressed.',
+  arguments = {
+    {
+      name = 'device',
+      type = 'Device',
+      description = 'The device.'
+    },
+    {
+      name = 'button',
+      type = 'DeviceButton',
+      description = 'The button.'
+    }
+  },
+  returns = {
+    {
+      name = 'down',
+      type = 'boolean',
+      description = [[
+        Whether the button on the device is currently pressed, or `nil` if the device does not have
+        the specified button.
+      ]]
+    }
+  },
+  related = {
+    'DeviceButton',
+    'lovr.headset.isTouched',
+    'lovr.headset.getAxis'
+  }
+}

api/lovr/headset/isMounted.lua

@@ -1,16 +0,0 @@
-return {
-  tag = 'headset',
-  summary = 'Get whether or not the headset is mounted.',
-  description = 'Determine if the headset is on someone\'s head or not.',
-  arguments = {},
-  returns = {
-    {
-      name = 'mounted',
-      type = 'boolean',
-      description = 'Whether or not the headset is mounted.'
-    }
-  },
-  related = {
-    'lovr.mount'
-  }
-}

api/lovr/headset/isTouched.lua

@@ -0,0 +1,32 @@
+return {
+  tag = 'input',
+  summary = 'Check if a button on a device is touched.',
+  description = 'Returns whether a button on a device is currently touched.',
+  arguments = {
+    {
+      name = 'device',
+      type = 'Device',
+      description = 'The device.'
+    },
+    {
+      name = 'button',
+      type = 'DeviceButton',
+      description = 'The button.'
+    }
+  },
+  returns = {
+    {
+      name = 'touched',
+      type = 'boolean',
+      description = [[
+        Whether the button on the device is currently touched, or `nil` if the device does not have
+        the button or it isn't touch-sensitive.
+      ]]
+    }
+  },
+  related = {
+    'DeviceButton',
+    'lovr.headset.isDown',
+    'lovr.headset.getAxis'
+  }
+}

api/lovr/headset/newModel.lua

@@ -0,0 +1,34 @@
+return {
+  tag = 'input',
+  summary = 'Get a Model for a device.',
+  description = 'Returns a new Model for the specified device.',
+  arguments = {
+    {
+      name = 'device',
+      type = 'Device',
+      default = 'head',
+      description = 'The device to get a model for.'
+    }
+  },
+  returns = {
+    {
+      name = 'model',
+      type = 'Model',
+      description = 'The new Model, or `nil` if a model could not be loaded.'
+    }
+  },
+  example = [[
+    local models = {}
+
+    function lovr.draw()
+      for hand in lovr.headset.hands() do
+        models[hand] = models[hand] or lovr.headset.newModel(hand)
+
+        if models[hand] then
+          local x, y, z, angle, ax, ay, az = lovr.headset.getPose(hand)
+          models[hand]:draw(x, y, z, 1, angle, ax, ay, az)
+        end
+      end
+    end
+  ]]
+}

api/lovr/headset/vibrate.lua

@@ -0,0 +1,46 @@
+return {
+  tag = 'input',
+  summary = 'Make a device go BZZZ!',
+  description = [[
+    Causes the device to vibrate with a custom strength, duration, and frequency, if possible.
+  ]],
+  arguments = {
+    {
+      name = 'device',
+      type = 'Device',
+      default = 'head',
+      description = 'The device to vibrate.'
+    },
+    {
+      name = 'strength',
+      type = 'number',
+      default = '1',
+      description = 'The strength of the vibration (amplitude), between 0 and 1.'
+    },
+    {
+      name = 'duration',
+      type = 'number',
+      default = '.5',
+      description = 'The duration of the vibration, in seconds.'
+    },
+    {
+      name = 'frequency',
+      type = 'number',
+      default = '0',
+      description = 'The frequency of the vibration, in hertz.  0 will use a default frequency.'
+    }
+  },
+  returns = {
+    {
+      name = 'vibrated',
+      type = 'boolean',
+      description = [[
+        Whether the device supports haptics and the vibration was successfully triggered.
+      ]]
+    }
+  },
+  notes = [[
+    When using OpenVR, the value for the `duration` currently must be less than .004 seconds.  Call
+    this function several frames in a row for stronger or prolonged vibration patterns.
+  ]]
+}