The VZfit SDK allows you to quickly create and adapt games that talk to the VZfit Sensor Kit and original VirZOOM Bike Controller. It provides access to all bike data, including speed, pedal direction, buttons, resistance setting, and heartrate. It also includes a high-level Player controller, using our patent-pending motion controls, that combine bike data with your head movement to comfortably move through large VR worlds.
The SDK is available on the Unity Asset Store for Unity 2017+ on Win32 (64-bit), UWP, and Android (6.0 and above). Its Player controller works with Oculus Rift, Oculus Quest, Oculus Go, HTC Vive, Windows MR, Google Daydream, and Samsung GearVR. It's not currently possible to develop with the SDK on Mac, Linux, iOS, or 32-bit Windows.
Besides this documentation, also see our SDK discussion forum and our UNITE 2015 talk for what you can do.
Usage of this SDK is governed by our License Agreement.
Initial release on Vive, Rift, and PSVR
Fixed initial calibration on Vive, no longer relies on SteamVR.ResetSeatedZeroPose()
Compatibility with Oculus 1.7 and SteamVR 1.1.1 plugins, though neither is required
Conforms to PS4 release requirements
No longer requires Visual Studio 2015 redistributable
Added Xbox 360 controller support
Tested with Unity 5.4.0p2
Added OpenSSL dlls for machines that don't have already
Tested with Unity 5.4.1p1
Tested up to Unity 5.4.2
Added face buttons to VZController API
Refactored gamepad support
VZPlayer now uses Camera from scene
Android support with Daydream and GearVR
Android 6.0 and above
HUD in test scene
Interactive bike model
Original VZ Sensor support
- with GearVR, Daydream, Rift Touch, or Vive hand controller
- not on PS4
Tilt steering option for Rift, Vive, and PSVR
Improved VZController abstraction
Bike firmware update
This can take a minute before connection, see VZController.ReprogramProgress()
Fixed missing Android file
Support VZfit Sensor Kit as well as original VirZOOM Bike Controller
Removed PS4 support
Setup & Requirements
The Unity SDK comes as a Unity package file that you import into your existing Unity project through the menu Assets->Import Package->Custom Package.
Then you need to set up your project to use our "input mappings" and settings for compatibility:
- Set Api Compatibility Level to .NET 2.0 (not Subset)
- Check Virtual Reality Supported
- Add your VR devices to the list of VR SDKs
- Copy or merge Assets/StreamingAssets/InputManager.asset into your ProjectSettings/InputManager.asset
For Windows builds, in BuildSettings set architecture to x86_64.
There are additional steps that users will need to use Sensor Kit with Windows. We will try to avoid these in the future, but for now Windows users will need a VZ Dongle to talk to their Sensor Kit. Also, UWP users will need to install Autohotkey and run the script from Assets/StreamingAssets/vzbutton.ahk.
The test.unity scene in VZ/Scenes can be the starting point for any game.
- A plane with a simple texture and mesh collider
- The VZPlayer.prefab (just the VZPlayer component, a rigidbody, an interactive model of our bike, and a HUD with input state)
- The directional light that Unity makes in any new scene
To try it in Unity,
- Open test.unity and hit Play
- Get on the bike, put on your VR headset, and hold the L and R triggers to calibrate
- Pedal to move forward, lean to turn
To make this into your game, replace the model of our bike with your own avatar, our HUD with your game HUD, and our plane with your terrain!
Tweak the parameters of VZPlayer to make your avatar move the way you want. You can subclass VZPlayer to override and extend its functions, like to add lift force as a function of Controller.InputSpeed, which is how our Pegasus flies.
We can add such examples to this scene at everyone's request.
VZPlayer is our high-level player controller, that translates VZController into comfortable VR motion with our custom physics.
Here's a quick rundown on VZPlayer motion parameters:
- Camera - player camera to control (if null defaults to MainCamera)
- HUD - gameobject that will be kept vertical and in front of the player
- DraftSpeed - target speed to go (zero disables drafting)
- DraftFactor - ratio of Controller.InputSpeed to DraftSpeed beyond which drafting stops
- SpeedFudge - makes you go faster or slower
- UphillFactor - how much slower you go up hills
- DownhillFactor - how much faster you go down hills
- MaxVertSpeed - limits your upward (climbing) and downward (falling) velocity
- MaxTurn - maximum turn amount
- LeanFudge - turns you more or less with your lean
- LeanIn - how much your avatar rotates when swerving
- LandingHardness - how hard you come down on the ground. Lower values make a softer landing that takes effect sooner
- LandingRadius - distance from VZPlayer origin that you want to touch ground softly. Set this smaller than your collision volume to feel the ground more. If you set this larger than your collision volume you will never reach the ground!
- NeckHeight - distance above VZPlayer origin of your virtual neck. Note that the VZPlayer rotates about its origin, while your neck is always kept vertical
- AllowRotate - set false to only allow strafing with your leaning, ignores your head look
- AllowRoll - set true to allow the VZPlayer to roll about the forward axis in response to terrain
- AllowDrift - set true to maintain your velocity in the air even when you stop pedaling
- BodyPrefab - should always be set to VZController.prefab or similar structure (contains required GameObjects)
- NearClipPlane - near plane of VR camera
- FarClipPlane - far plane of VR camera
- SlowRotateLimit - amount to limit your turning when you are stopped
- Reverse - put VZPlayer into reverse
Adding VZPlayer to a game object will cause your pedaling and leaning to move that game object. Your game object will also need a physics Collider and Rigidbody components to behave correctly. VZPlayer will also make the Camera a child of the game object to be moved around with it.
If your collider objects do not encompass the origin of your VZPlayer, you will need to change their layer to "Ignore Raycast". Otherwise, you may experience unintentional "jumping" behavior as VZPlayer raycasts downward to determine its height above the ground in order to soften landings, and may hit its own colliders instead.
Script code can access your VZPlayer anywhere like VZPlayer.Instance.
VZController performs our low-level bike connection and VR initialization. It also supports gamepad and keyboard control for testing when you don't have a bike or HMD.
It's loaded dynamically by VZPlayer, where it can be accessed as VZPlayer.Controller.
Its properties are
- LeftButton - state of left handlebar button on bike, or VR hand-controller primary button with sensor
- RightButton - state of right handlebar button on bike, VR hand-controller secondary button with sensor
- DpadUp, DpadDown, DpadLeft, DpadRight - thumb buttons on left bike grip, or DS4 controller on PS4
- RightUp, RightLeft, RightRight, RightDown - thumb buttons on right bike grip, or DS4 controller on PS4
- InputSpeed - your pedaling speed in meters/sec (approximated at resistance setting 3)
- HeadRot - yaw angle of your head in radians (positive counterclockwise)
- HeadLean - amount you are leaning left/right in meters (positive left)
- HeadBend - amount you are leaning foward/back in meters (positive forward)
- Distance - virtual kilometers traveled this session (influenced by calibrated resistance)
- Head - full transform of your head
- IsSteamVR - using VIVE headset (on PC)
- HasHmd() - using any VR headset
- BatteryVolts() - voltage of bike or sensor (starts at 3, replace at 2.1)
- HeartRate() - user heart rate on bike, or with S3 Watch on GearVR
- UncalibratedResistance() - proportional to resistance setting on bike, needs app calibration
These functions describe the state of VZ bike or sensor connection
- HasBikeDongle() - able to connect to bike or sensor
- ReprogramProgress() - progress from 0.0 to 1.0 that bike firmware is updating, which happens before a connection
- IsBikeConnected() - connected to bike or sensor
- IsAlphaBike() - prototype VZ bike without directional buttons or reverse pedaling or resistance sensing
- IsBetaBike() - original VZ bike
- IsBikeSensor() - VZfit sensor kit
The above buttons properties have these properties/methods
- Down - true for every frame one's being held down
- Pressed() - true for the frame a button goes down after being up
- Released() - true for the frame a button goes up after being down
- Held(float sec) - true for all the frames after a button has been held down for "sec"
- Clear() - used to "clear" down button state to make Held() and Released() return false after it's been called
Note the Sensor Kit does not provide the Dpad* or Right* thumb buttons, only the RightButton (A) and LeftButton (B).
You can test VZController functionality without a VZ bike or sensor when running from the Unity Editor with standard gamepads or keyboard, with the following mappings. Additional devices can be configured in Assets/VZ/Resources/VZControllerMap.xml
- Left joystick - head lean and bend
- Right joystick - head pitch and yaw
- Left shoulder - left button
- Right shoulder - right button
- Left trigger - forward pedaling
- Right trigger - reverse pedaling
- Dpad and face buttons - same
- WASD - head lean and bend
- Arrows - head pitch and yaw
- Enter - right button
- Backspace - left button
- Space - forward pedaling
- Tab - reverse pedaling
- IJKM - dpad on left bike grip
- Keypad 8462 - ABXY on right bike grip
You can use Playmaker with the VZ SDK by importing the Playmaker package and building your project with the VZ_PLAYMAKER flag.
The following global Playmaker variables will then be created and updated, corresponding to our Controller and Player states:
- VZPlayer (object for you to call methods on)
- VZPlayer.Speed (adjusted for terrain, speedups, etc)