Merge pull request #16 from getnamo/modern-rewrite

Modern rewrite for 4.14

HydraPlugin.uplugin

@@ -2,7 +2,7 @@
     "FileVersion" : 3,
 	"FriendlyName" : "Razer Hydra Plugin",
 	"Version" : 1,
-	"VersionName" : "0.8.10",
+	"VersionName" : "0.9.2",
 	"CreatedBy" : "Getnamo",
 	"CreatedByURL" : "http://getnamo.com",
 	"DocsURL" : "https://github.com/getnamo/hydra-ue4",

README.md

@@ -1,10 +1,8 @@
 ## Overview ##
 
-An Unofficial Razer Hydra Plugin for the Unreal Engine 4
+An Unofficial [Razer Hydra](https://en.wikipedia.org/wiki/Razer_Hydra) plugin for the [Unreal Engine 4](https://www.unrealengine.com/). 
 
-The plugin is designed with an event driven architecture through a delegate interface. You can access device events through Blueprintable classes provided or through C++. Main C++ support is from inheriting the HydraDelegate, through it you can extend your own custom class to support Hydra events. Additional functions in the delegate support polling for latest data.
-
-The plugin also handles hot plugging and emits HydraPluggedIn (HydraUnplugged for the reverse), allowing you to initialize if needed when the device is ready.
+Since version 0.8, the plugin works through both Unreal Engine [Motion Controller](https://docs.unrealengine.com/latest/INT/Platforms/VR/MotionController/) and [Input Mapping](https://docs.unrealengine.com/latest/INT/Gameplay/Input/) abstraction as well as through a convenience component for hydra specific events and functions.
 
 [Main discussion thread](https://forums.unrealengine.com/showthread.php?3505-Razer-Hydra-Plugin)
 
@@ -14,58 +12,88 @@ The plugin also handles hot plugging and emits HydraPluggedIn (HydraUnplugged fo
 
  1.	[Download Latest Release](https://github.com/getnamo/hydra-ue4/releases)
  2.	Create new or choose project.
- 3.	Browse to your project folder (typically found at Documents/Unreal Project/{Your Project Root})
+ 3.	Browse to your project folder (typically found at Documents/Unreal Project/*{Your Project Root}*)
  4.	Copy *Plugins* folder into your Project root.
+ 5.    Enable the plugin via Edit->Plugins. Scroll down to Project->Networking. Click Enabled.
  5.	Restart the Editor and open your project again. Plugin is now ready to use.
 
 ## Motion Controller Documentation ##
 
-Please refer to the [Motion Controller Component Setup unreal documentation](https://docs.unrealengine.com/latest/INT/Platforms/VR/MotionController/index.html) as this setup is hardware agnostic.
+Please refer to the [Motion Controller Component Setup unreal documentation](https://docs.unrealengine.com/latest/INT/Platforms/VR/MotionController/index.html) as this setup is hardware agnostic. Since 0.9 a basic motion controller setup should look like this:
+
+![IMG](http://i.imgur.com/vbrj4wY.png)
+
+Where visible static meshes are parented to the motion controllers which are in turn parented to a chosen offset, forward by 40cm from the camera in this particular example.
+
+###Input Mapping
+
+You can use either the Motion Controller input mapping (IM) events
+
+![IMG](http://i.imgur.com/toBD86X.png)
+
+or hydra specific ones
+
+![IMG](http://i.imgur.com/4Y2QyLh.png)
+
+###Hydra Tracking Notes
+
+No hydra specific component is required, tracking is handled internally and passed to the agnostic motion controller components and the input mapping system. Tracking should defer to other motion controllers if unplugged or docked.
+
+The origin of tracking is the hydra base station.
 
-NB:
 For input mapping purposes
 Hydra start == Face Button 5
-Hydra Joystick Click' == Face Button 6
+Hydra Joystick Click == Face Button 6
 
-## Hydra Specific and Calibration ##
+## Hydra Custom Functions and Events##
 
-![IMG](http://i.imgur.com/tTiZ3NI.png)
+![IMG](http://i.imgur.com/wlpdujf.png)
 
-If you want to calibrate or do anything specific, just add a hydra plugin component (renamed to avoid confusion with earlier components). These components are multicast and their events are as well so place them *anywhere* in multiples if you want to. They are also where you would poll for current or historical data for gesture recognition/etc.
+If you want to calibrate or do complex hydra specific things, just add a hydra controller component. 
 
-To calibrate you simply call Calibrate or SetBaseOffset on your component.
+Component are multicast and their events are as well so place them *anywhere* in multiples if you want to. They are also where you would poll for latest data for gesture recognition/etc.
 
-![IMG](http://i.imgur.com/BAyjapm.png)
+###Events
+How about events? Now there are no more interfaces to deal with, instead you click on your hydra plugin component and click the green + to add the event from the details pane. This should feel familiar as these are the same blueprint assignable multicast delegates that PrimitiveComponents use for collision checks (e.g. OnBeginOverlap)
 
-Calibrate recalibrates the origin as coming from the centroid of your two hydras + the offset. In its default settings it should work as a good T-pose to shoulder midpoint.
+####On Controller Moved
 
-![IMG](http://i.imgur.com/y82yzEv.png)
+E.g. draw a debug box for each hydra from a base offset scene component
+![IMG](http://i.imgur.com/2IMOcTR.png)
 
-If you want to do your own calibration, just come up with a good position offset and set it here, all values onward will maintain this calibration, even between PIE sessions.
+####Button Pressed/Released
 
-You can also set links to the MeshComponents attached to your MotionControllerComponents and let the plugin auto-hide the meshes whenever you dock that controller.
+e.g. verbose log of button presses/releases. Notice that you can break additional information from the controller data structure.
 
-![IMG](http://i.imgur.com/coPNZTx.png)
+![IMG](http://i.imgur.com/g9OUtM9.png)
 
-Just call SetMeshComponentLinks at some initialization stage e.g. BeginPlay and then check the option to HideMeshComponentsWhenDocked
 
+####Joystick Moved
 
+e.g. a verbose log of joystick movement
 
-How about events? Now there are no more interfaces to deal with, instead you click on your hydra plugin component and click the green + to add the event from the details pane. This should feel familiar as these are the same blueprint assignable multicast delegates that PrimitiveComponents use for collision checks (e.g. OnBeginOverlap)
 
-![IMG](http://i.imgur.com/YpEA2da.png)
+![IMG](http://i.imgur.com/eDDlKqZ.png)
+
+####Hotplugging Events
 
-e.g. if you want to have all the data to compare buttons or maybe do something with acceleration you can subscribe to the ControllerMoved event
+Called when you plug in or unplug the controller from the system usb.
+![IMG](http://i.imgur.com/jTfeerB.png)
 
-![IMG](http://i.imgur.com/2MyKAHq.png)
+the same type of events exist for docking.
 
-To wrap it up, use input mapping events for all joystick and button input. You can use either the hardware agnostic motion controller buttons or the hydra specific ones, they work the same
+### Optional Calibration methods
+Used to calculated 1:1 offset for your controllers. To calibrate you simply call Calibrate or SetBaseOffset on your component.
 
-![IMG](http://i.imgur.com/DvQDz0E.png)
+![IMG](http://i.imgur.com/BAyjapm.png)
+
+Calibrate recalibrates the origin as coming from the centroid of your two hydras + the offset. In its default settings it should work as a good T-pose to shoulder midpoint.
+
+If you want to do your own calibration, just come up with a good position offset and set it here, all values onward will maintain this calibration, even between PIE sessions.
 
 ## Shipping ##
 
-When you're ready to ship, just package the folder. With the current state the dll gets copied, but the project may not launch (fatal error)
+When you're ready to ship, just package the game it should all work out of the box.
 
 ### Shipping Troubleshoot ###
 
@@ -84,6 +112,7 @@ Your project runtime also continues working, but your hydra does not respond.
 ![alt text](http://i.imgur.com/j4UAp8t.png "DLL not found Error")
 
 Also you search your log file and find 
+
 ![alt text](http://i.imgur.com/jy6nsmX.png "Log of DLL not found Error")
 
 **Fix:** This error means the sixense dll file is missing.