Documentation (#126)

* Fix indentation in action manifest * Rename action sets to drop unnecessary prefix notation Since the variable is in the action_sets namespace it does not make sense to prepend it with an identifier for it being constant, or a set. * Rename input keys to drop prefix notation The vars are in a namespace that only contains constant inputs, it doesn't make sense to prepend it to every var. * Rename actions to drop prefixes It is implicit that actions are const values for sets, therefore the prefix is not needed. * Remove unneeded action set member func * Move active action set in preparation for more action sets * Move action strings above class Class is not able to use variables in namespaces, which is stupid. * Move sets into member variable * Split music into separate action set * Convert action_manifest.json to spaces only * Refactor actions into separate action sets * Rename main set to haptic * Reorder action sets The haptics and misc sets are misc bindings. * added partial action list to readme * finished action descriptions. * fixed conflict * added no link guide * fixed formatting * linked input guide to main page * added pictures * fixed file directories * fixed formatting * removed force revive setting * changed version to RC2 * hid revive force on settings page * revert to RC1 * updated screenshots * updated documentation * updated straggler changes * minor formatting change * formatting * Update Readme.md Co-Authored-By: ykeara <ykeara1@gmail.com> * Update Readme.md Co-Authored-By: ykeara <ykeara1@gmail.com> * Update Readme.md Co-Authored-By: ykeara <ykeara1@gmail.com> * Update Readme.md Co-Authored-By: ykeara <ykeara1@gmail.com> * Update Readme.md Co-Authored-By: ykeara <ykeara1@gmail.com> * Update Readme.md Co-Authored-By: ykeara <ykeara1@gmail.com> * Update Readme.md Co-Authored-By: ykeara <ykeara1@gmail.com> * Update Readme.md Co-Authored-By: ykeara <ykeara1@gmail.com> * Update Readme.md Co-Authored-By: ykeara <ykeara1@gmail.com> * Update Readme.md Co-Authored-By: ykeara <ykeara1@gmail.com> * 2nd batch of changes * fixed formatting for table * fixed table
2019-03-23 23:58:55 -05:00
parent 74573eefaa
commit 97703098e6
24 changed files with 233 additions and 52 deletions
@@ -16,13 +16,14 @@
 >   * [SteamVR Page](#steamvr_page)
 >   * [Chaperone Page](#chaperone_page)
 >   * [Chaperone Proximity Warning Settings Page](#chaperone_proximity_page)
- >   * [Play Space Page](#play_space_page)
- >   * [Playspace Fix Page](#playspace_fix_page)
+ >   * [Space Offset](#play_space_page)
+ >   * [Motion Page](#motion_page)
+ >   * [Space Fix Page](#space_fix_page)
 >   * [Audio Page](#audio_page)
- >   * [Revive Page](#revive_page)
 >   * [Utilities Page](#utilities_page)
 >   * [Statistics Page](#statistics_page)
 >   * [Settings Page](#settings_page)
+ > * [SteamVR Input Guide](#steamvr_input_guide)
 > * [How To Compile](#how_to_compile)
 >   * [Building on Windows](#building_on_windows)
 >   * [Building on Linux](#building_on_linux)
@@ -46,17 +47,23 @@ Adds an overlay to the OpenVR dashboard that allows access to advanced settings.
 - Chaperone Proximity Warning: Several warning methods can be configured.
 - Chaperone Profiles: Allows to quickly switch chaperone geometry and settings while in VR.
 - Temporarily move and rotate the playspace.
- Floor height fix.
+- Floor height fix, for knuckles and wands.
+- Floor Center fix.
 - Displays several performance statistics and other statistics (e.g. headset rotations).
 - Select the playback/mirror/recording audio device
 - Mute/unmute and set volume of audio mirror device.
 - Mute/unmute and set volume of microphone device.
- Implements push-to-talk and allows to configure push-to-talk profiles.
+- Implements push-to-talk, and push-to-mute
 - Desktop mode shows a window on the desktop instead of a VR overlay.
- Revive settings support (Requires [Revive 1.0.4+](https://github.com/LibreVR/Revive) for full functionality).
 - VR Keyboard Input Utilities
 - Simple Alarm Clock
- Player height adjust toggle (Credits to mklim)
+- Player height adjust toggle
+- Snap Turn option.
+- Advanced Space Features: gravity, space-turn, and space-drag
+- Simple Media Player macro keybind
+- SteamVR Input Action System implemented for maximum control of keybinds.
+- Removed forced on Die-in-Game Die-in-Life setting.
+

 <a name="usage"></a>
 # Usage
@@ -82,17 +89,64 @@ To upgrade an existing installation first stop SteamVR and delete the old applic

 After SteamVR beta 1.3.1 the bindings for Advanced Settings will show up in the bindings menu.

-By default no buttons are bound.
+By default no buttons are bound. TODO

 The following actions currently exist:
+### Music
+
+Actions associated with media player.

 |    Action     |     Type      |  Explanation  |
 | ------------- | ------------- |  ------------ |
-| NextSong      | Binary/Button | The same as using the media keys. Tells a media player to play the next song.|
-| PreviousSong  | Binary/Button | The same as using the media keys. Tells a media player to play the previous song. |
-| pausePlaySong | Binary/Button | The same as using the media keys. Tells the media player to press play/pause. |
-| stopSong      | Binary/Button | The same as using the media keys. Tells the media player to stop playback. |
+| Play Next Track | Binary/Button | The same as using the media keys. Tells a media player to play the next song.|
+| Play Previous Track | Binary/Button | The same as using the media keys. Tells a media player to play the previous song. |
+| Pause/Play Track | Binary/Button | The same as using the media keys. Tells the media player to press play/pause. |
+| Stop Track| Binary/Button | The same as using the media keys. Tells the media player to stop playback. |

+### Motion
+
+Actions associated with motion tab, and motion.
+
+Override actions will take priority over non-override actions during simultaneous activation. Example: binding space turn to single click and space drag (override) to double click on the same physical button.
+
+|    Action     |     Type      |  Explanation  |
+| ------------- | ------------- |  ------------ |
+| Left Hand Space Turn | Binary/Button | Rotates PlaySpace based on left controller rotation while held. |
+| Right Hand Space Turn | Binary/Button | Rotates PlaySpace based on right controller rotation while held. |
+| Left Hand Space Drag | Binary/Button | Moves PlaySpace based on left controller position while held. |
+| Right Hand Space Drag | Binary/Button | Moves PlaySpace based on right controller position while held. |
+| (Optional Override) Left Hand Space Turn | Binary/Button | Override version: will activate instead of non-override during simultaneous activation. |
+| (Optional Override) Right Hand Space Turn | Binary/Button | Override version: will activate instead of non-override during simultaneous activation. |
+| (Optional Override) Left Hand Space Drag | Binary/Button | Override version: will activate instead of non-override during simultaneous activation. |
+| (Optional Override) Right Hand Space Drag | Binary/Button | Override version: will activate instead of non-override during simultaneous activation. |
+| Swap Active Space Drag to Left Hand (Override) | Binary/Button |  Activates space drag on left controller only if right controller is currently active in space drag. (Useful for climbing motions) |
+| Swap Active Space Drag to Right Hand (Override) | Binary/Button | Activates space drag on right controller only if left controller is currently active in space drag. (Useful for climbing motions) |
+| Gravity Toggle | Binary/Button |  Toggles Gravity state when pressed. |
+| Gravity Reverse | Binary/Button |  Temporarily Reverses Gravity while held. |
+| Reset Offsets | Binary/Button |  Resets your offset and rotation to 0. |
+| Height Toggle | Binary/Button |  Shifts the gravity floor level by offset configured in motion tab. If gravity is inactive: also shifts the user's current y-axis position by offset configured in motion tab. |
+| Snap-Turn Left | Binary/Button |  Rotates a set value to the left based on settings in motion tab. |
+| Snap-Turn Right | Binary/Button |  Rotates a set value to the right based on settings in motion tab. |
+
+### Misc.
+
+Actions that don't have a clear category.
+
+|    Action     |     Type      |  Explanation  |
+| ------------- | ------------- |  ------------ |
+| X-Axis Lock Toggle | Binary/Button | Toggles the lock of the X-Axis for offsets.|
+| Y-Axis Lock Toggle | Binary/Button | Toggles the lock of the Y-Axis for offsets.|
+| Z-Axis Lock Toggle | Binary/Button | Toggles the lock of the Z-Axis for offsets.|
+| Push to Talk | Binary/Button |  Acts as starter for PTT, can mute if push-to-mute is selected.|
+
+### Haptics.
+
+Actions to be handled by the system.
+
+|    Action     |     Type      |  Explanation  |
+| ------------- | ------------- |  ------------ |
+| Haptics Left | Vibration | Handle for haptic events on the Left Controller. |
+| Haptics Right | Vibration | Handle for haptic events on the Right Controller. |

 <a name="command_line_arguments"></a>
 ## Command Line Arguments
@@ -140,7 +194,6 @@ These version are not stable and this should be considered for advanced users on
 - **Enable Manual Supersampling Override**: Enables user control of Supersampling, instead of SteamVR auto profiles.
 - **Enable Motion Smoothing**: Enables Motion Smoothing, and disables asynchronous reprojection.
 - **Restart SteamVR**: Restart SteamVR (May crash the Steam overlay when SteamVR Home is running when you restart. Therefore I advice that you close SteamVR Home before restarting).
-
 <a name="chaperone_page"></a>
 ## - Chaperone Page:

@@ -164,32 +217,54 @@ These version are not stable and this should be considered for advanced users on
 ![Chaperone Proximity Warning Settings Page](docs/screenshots/ChaperoneWarningPage.png)

 - **Switch to Beginner Mode**: Switches the chaperone bound's style to beginner mode when the user's distance to the chaperone falls below the configured activation distance.
- **Trigger Haptic Feedback**: The left and right controller start vibrating when the user's distance to the chaperone falls below the configured activation distance.
+- **Trigger Haptic Feedback**: The left and right controller start vibrating when the user's distance to the chaperone falls below the configured activation distance. (HMD or controllers can trigger)
 - **Audio Warning**: Plays an alarm sound when the user's distance to the chaperone falls below the configured activation distance.
  - **Loop Audio**: Whether the audio alarm should only be played once or in a loop.
  - **Loop Audio**: Modify audio volume as a function of the user's distance to the chaperone.
 - **Open dashboard**: Opens the dashboard when the user's distance to the chaperone falls below the configured activation distance. The idea is to pause the game (most single-player games auto-pause when the dashboard is shown) to give the user time for reorientation.
 - **Velocity Dependent Fade/Activation Distance**: Dynamically modifies the chaperone's fade distance and the proximity warning's activation distance as a function of the player's speed. The used formula is: *distance = old_distance * ( 1 + distance_modifier * max(left_controller_speed, right_controller_speed, hmd_speed) )*

-<a name="play_space_page"></a>
-## - Play Space Page:
+<a name="space_offset_page"></a>
+## - Space Offset Page:

-![Play Space Page](docs/screenshots/PlayspacePage.png)
+![Play Space Page](docs/screenshots/OffsetPage.png)

-Allows to temporarily move and rotate the center of the playspace. This allows to reach interaction elements that are just inside our real-world walls or otherwise inaccessible (e.g. when your playspace is smaller than the recommended one). Can also be used to discover the terrors that lie outside of the intended playspace (ever wondered what's behind the door in The Lab?).
+Allows users to temporarily move and rotate the center of the playspace. This allows to reach interaction elements that are just outside our real-world walls or otherwise inaccessible (e.g. when your playspace is smaller than the recommended one). Can also be used to discover the terrors that lie outside of the intended playspace (ever wondered what's behind the door in The Lab?).

- **Virtual Move Shortcut**: Allows moving the placespace center by holding down the application menu shortcut and moving the controller.
- **Adjust Chaperone**: When enabled then the chaperone bounds stay in place when the playspace is moved or rotated (so noone gets hurt). Unfortunately this does not work when moving up/down.
+- **Adjust Chaperone**: When enabled, the chaperone bounds stay accurate even when the playspace is moved or rotated (so noone gets hurt). Depending on chaperone mode this may or may not adjust with height.

-<a name="playspace_fix_page"></a>
-## - Playspace Fix Page:
+<a name="motion_page"></a>
+## - Motion Page:
+
+![Motion Page](docs/screenshots/MotionPage.png)
+
+- **Space Drag**: Allows shifting your playspace by dragging your controller, Binds must be set via SteamVR Input system.
+  - **Enable Left/Right Hand**: Toggles functionality (must be active in addition to binding via input system to work.)
+  - **Drag Comfort Mode**: Limits the rate at which your movement updates, reducing smoothness so that perceived motion starts to feel more like mini-teleports. Higher values reduce smoothness more.
+- **Space Turn**: Allows rotating your playspace by rotating your controller. Binds must be set via SteamVR Input system.
+  - **Enable Left/Right Hand**: Toggles functionality (must be active in addition to binding via input system to work.)
+  - **Turn Comfort Mode**: Limits the rate at which your rotation updates, reducing smoothness so that perceived rotation starts to feel more like mini-snap-turns. Higher values reduce smoothness more.
+- **Height Toggle**: Toggle between zero and an offset for gravity floor height. If gravity is inactive the user is also moved to this offset. (Example: allows for quick switching between a seated and standing height.) Can be bound via SteamVr Input System.
+  - **On**: Current toggle state, Binds directly modify this.
+  - **Height Offset**: The amount of the offset (+ is down.)
+  - **Set From Y-Offset**: grabs the Y-Offset value from Offset Page.
+- **Gravity Settings**: Provides a gravity and momentum simulation to dynamically move your space offset.
+  - **On**: Current toggle state, Binds directly modify this.
+  - **Gravity Strength**: Gravity simulation's downward acceleration in meters per second squared. Planet buttons provide quick settings for well known gravity strengths. Values can also be typed in directly.
+  - **Save Momentum**: whether your momentum is saved between on/off toggles of gravity.
+  - **fling Strength**: adjusts the strength at which you "throw" yourself with space drag feature.
+- **Snap Turn**: Allows snap (instant) turning by the specified angle. Can type in values or use the preset buttons for angles that neatly divide 360 degrees. Must bind actions via SteamVR Input interface.
+
+<a name="space_fix_page"></a>
+## - Space Fix Page:

 ![Playspace Fix Page](docs/screenshots/FloorFixPage.png)

-
 - **Fix Floor** Allows you to fix the height of your floor. Just place one controller on your floor and press the button.
 - **Recenter Playspace** Besides fixing the floor height, also recenters the place space around the controller on the floor.
-
+- **Undo Fix** Removes last "fix"
+- **Apply Space Settings Offsets as Center** Takes current values from Offsets page and re-caliberates center/rotation. **Caution** The reset function will then refer to this location as the new zero location, overriding the old zero location.
+  
 <a name="audio_page"></a>
 ## - Audio Page:

@@ -198,36 +273,12 @@ Allows to temporarily move and rotate the center of the playspace. This allows t
 - **Playback Device**: Allows to select the playback device.
 - **Mirror Device**: Allows to select the mirror device, set its volume and to mute/unmute it.
 - **Microphone**: Allows to select the microphone device, set its volume and to mute/unmute it.
- **Proximity Sensor Mutes/Unmutes Microphone**: Allows the proximity sensor to mute the microphone when the user is not wearing the HMD, and to unmute it when the user is wearing the HMD.
 - **Push-to-Talk**: Enable/disable push-to-talk. When push-to-talk is activated the microphone gets muted unless the Push To Talk action is activated.
 - **Show Notification**: Shows a notification icon in the headset when the Push To Talk action is activated.
- **Push-to-Mute**: Inverse push-to-talk. The Microphone is unmuted by default and muted when any of the configured buttons is pressed.
+- **Push-to-Mute**: Inverse push-to-talk. The Microphone is unmuted by default and muted when the keybind is pressed.
+  - **NOTE**: The Push-to-talk box must be enabled for this feature to work.
 - **Audio Profile**: Allows you to apply/define/delete audio profiles that save playback devices, mute state, and volume.

-<a name="revive_page"></a>
-## - Revive Page:
-
-![Revive Page](docs/screenshots/RevivePage.png)
-
-**The Revive page is not currently being maintained. Features may not be stable, performant or actually work.**
-
-The Revive page is only visible when the [Revive overlay](https://github.com/LibreVR/Revive) is installed. In case an installed Revive overlay is not correctly detected you can force the Revive page in the settings.
-
-Any changes to controller settings are immediately applied by Revive (Requires Revive 1.0.4+).
-
- **Render Target Override**: Overrides the Oculus-side render target (aka supersampling). Enabling it prevents Oculus applications from dynamically modifying this value. Warning: Is applied on top of the SteamVR supersampling value. (pixelsPerDisplayPixel setting in the vrsettings file)
- **Grip Button mode**: Allows to set the grip button mode. (ToggleGrip setting in the vrsettings file)
- **Toggle Delay**: Allows to configure the toggle delay. (ToggleDelay setting in the vrsettings file)
- **Trigger As Grip**:  Swaps the trigger and grip. (TriggerAsGrip setting in the vrsettings file)
- **Deadzone**: Allows to modify the simulated thumbsticks' deadzone. (ThumbDeadzone setting in the vrsettings file)
- **Sensitivity**: Allows to modify the simulated thumbsticks' sensitivity. (ThumbSensitivity setting the vrsettings file)
- **Yaw**: Allows to modify the touch controllers yaw orientation. (TouchYaw setting the vrsettings file)
- **Pitch**: Allows to modify the touch controllers pitch orientation. (TouchPitch setting the vrsettings file)
- **Roll**: Allows to modify the touch controllers roll orientation. (TouchRoll setting the vrsettings file)
- **X**: Allows to modify the touch controllers x-offset. (TouchX setting the vrsettings file)
- **Y**: Allows to modify the touch controllers y-offset. (TouchY setting the vrsettings file)
- **Z**: Allows to modify the touch controllers z-offset. (TouchZ setting the vrsettings file)
- **Controller Profile**: Allows to apply/define/delete controller profiles that save the controller settings (grip button mode, deadzone, sensitivity, pitch/yaw/roll and x/y/z-offsets).

 <a name="utilities_page"></a>
 ## - Utilities Page:
@@ -238,7 +289,7 @@ Any changes to controller settings are immediately applied by Revive (Requires R

 - **Alarm Clock:** Just a simple alarm clock so you don't miss important appointments. VR can sure mess up perception of time. Does not work in desktop mode.

- **Steam Desktop Overlay Width:** Allows to increase the size of the Steam desktop overlay. Useful for multi-monitor setups.
+- **Steam Desktop Overlay Width:** Allows to increase the size of the Steam desktop overlay. Useful for multi-monitor setups. It is saved between sessions.

 - **Media Control Keys:** Allows controlling a media player through the media keys. This is the same as having a keyboard with media keys and then pressing them. Should support most common media players.

@@ -263,7 +314,14 @@ Any changes to controller settings are immediately applied by Revive (Requires R
 ![Settings Page](docs/screenshots/SettingsPage.png)

 - **Autostart:** Allows you to enable/disable auto start.
- **Force Revive Page:** Force the Revive page button on the root page to be visible.
+- **Force Revive Page:** No Longer Supported Does Nothing.
+
+<a name="steamvr_input_guide"></a>
+# SteamVR Input Guide
+
+A Guide to the SteamVR Input System can be found [here](docs/SteamVRInputGuide.md)
+
+**Or** a Video guide by Kung can be found [here](https://youtu.be/2ZHdjOfnqOU)

 <a name="how_to_compile"></a>
 # How to Compile
@@ -0,0 +1,121 @@
+# SteamVR Input Guide
+
+## What is SteamVR Input?
+
+- A universal keybind system for all controllers (in steamVR)
+- A way for You to share/find keybind layouts.
+- A way for developers to easily program for all controllers [needs a driver]
+
+## What do I need to know?
+
+- You don’t bind buttons like a/b. you bind “actions”
+- An action is simply just that an action…. Like “jump,” “shoot,” or “interact”
+  - Action Have Types such as : Digital (on/off), Analog (range of values 0-100 say), or special ones like Vibration (specifically for haptics)
+
+## Okay Cool? How do I do this?
+
+1. Go to SteamVR dashboard->Steam->Controller Bindings OR go to http://127.0.0.1:8998/dashboard/controllerbinding.html from a desktop browser WHILE steamVR is running
+(pic)
+2. Select your application you want to modify keybinds (Advanced Settings will currently always be at the bottom)
+3. Select your Controller, (the controller must be on)
+4. Select your binding.
+5. Now We Are Ready to Bind our Actions!
+
+### Binding UI
+
+![Binding Overview](screenshots/guide/bindingoverview.png)
+
+- A – Action sets, these tabs essentially let programmers have different keybinds for different events… say you may want different controls if you are driving a car versus running around. [In Advanced Settings we simply use them as a grouping utility, and ALL action sets are active ALL the time.]
+- B – Input options – your “buttons”
+- C – Chords/ Special Binds. More on these later.
+- D – Controller Diagram, visually shows you the button location on a depiction of the controller
+
+### My First Bind
+
+In this example we are going to use the "grip" button on a vive wand.
+
+- First WE click the  [+] on the grip line to create an emtpy binding
+
+![Grip Plus](screenshots/guide/gripplus.png)
+
+- We then select the behavior of the button.
+
+![Button Type](screenshots/guide/buttontype.png)
+
+  - Button – action is active when button is pressed
+  - Toggle Button – Action toggles state when button is pressed i.e. on until pressed again
+  - Set Analog Action – for Actions that are not binary i.e. trigger is pressed 50%
+- Now we select our action for the button “click” By Clicking the “none” box.
+- Upon Clicking it a popup will let us choose the desired action.
+
+![Action List](screenshots/guide/actionlist.png)
+
+- Now Simply Click the Checkmark to save changes, and you should be good to go!
+
+### Advanced Bindings
+
+And you thought you were done?
+
+- First we will start by editing an action, hover over a set action and click the pen
+
+![Edit Action](screenshots/guide/actionlist.png)
+
+- Now you will notice two important things the “more options” and the cog.
+- The Cog allows you to set up haptics for activating an action 
+
+![Edit Action Haptics](screenshots/guide/actionhaptics.png)
+
+  - Amplitude - how powerful 0-100% the haptics should be.
+  - Duration – how long it will last 0-4 seconds.
+  - Frequency – The frequency/”feel” of the vibration
+- But What about the “more options?!”
+
+![More Options](screenshots/guide/moreoptions.png)
+
+  - Single – single click
+  - Double – double click (about .25 seconds in between clicks max)
+  - Long Hold – Long hold ~1-2 seconds
+  - Held – Action active when held!
+  - Touch – Active when the button is being touched (knuckles/ touch)
+  - And More – Analog inputs (i.e. Triggers/joysticks/ trackpads ) have more options and configurations you can try out!
+ 
+### Chord Bindings
+ 
+ **The Combo Maker!** Chords are just that, they allow you to combine a combination of Keys to do an action for example a Grip + trigger + trackpad Press.
+ 
+**NOTE:** For you to be able to select a button in the chord menu you need to have clicked the [+] for the button and have an empty slot like below, And the behavior (toggle/Button etc.) must also be correct.
+
+![Empty Action](screenshots/guide/emptyaction.png)
+
+- Make sure you have empty Bindings or a binding for all keys you will want to use in your chord, then click the “Add Chords” followed by “Add New Chord”.
+- You will be prompted for an action, select the result of your chord.
+- You will Now see the prototype for your chord and can add inputs as you desire
+
+![Chord Prototype](screenshots/guide/chordproto.png)
+
+- And keep adding if you want to make sure you really don’t accidently press it!
+
+![Chord Complete](screenshots/guide/chordcomplete.png)
+
+- That’s is it add more or close and you are done!
+
+### Odds and Ends.... and Haptics!
+
+- Haptics are a special Action. as it essentially tells the program which controller this haptic “action” belongs to.
+- The add/edit Haptics button will be  next to the add/edit chord button. [in our app haptics only exist in the “haptics” action set, as such you will want to set them.]
+- **YOU MUST HAVE AN EMPTY BINDING**, otherwise haptics will not be bind-able. Anything will do… even “unused”
+
+![Empty Action](screenshots/guide/emptyaction.png)
+
+- Other than that just place the appropriate haptic action in the appropriate spot!
+
+### But Wait it’s Broke!
+
+- We recommend a Separate bind for every action. Multiple actions to one bind can cause un-predictable behavior.
+
+![Multiple Actions](screenshots/guide/multipleactions.png)
+
+- This Guide Did not cover Legacy Applications or Simulated Actions, as the old input method is deprecated.
+- We also include default bindings with our program, but it is impossible for us to include bindings for all controllers.
+
+
@@ -100,7 +100,9 @@
      "requirement": "optional",
      "type": "boolean"
    },
+    
    {
+
      "name": "/actions/motion/in/HeightToggle",
      "requirement": "optional",
      "type": "boolean"