VZfit SDK

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.

 

Release Notes

1.0
Initial release on Vive, Rift, and PSVR

1.1
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

1.2
Added OpenSSL dlls for machines that don’t have already
Tested with Unity 5.4.1p1

1.3
Tested up to Unity 5.4.2
Added face buttons to VZController API
Refactored gamepad support
VZPlayer now uses Camera from scene

1.4
Android support with Daydream and GearVR
Android 6.0 and above
HUD in test scene
Interactive bike model

1.5
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()

1.6
Fixed missing Android file

1.7
Support VZfit Sensor Kit as well as original VirZOOM Bike
Removed PS4 support

 

Setup & Requirements

Builds made with the VZfit SDK are free to be sold and distributed in any manner, but will only work with the VZfit Sensor Kits on an active Premium membership.

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:

In PlayerSettings

  • 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

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.

 

Test Scene

The test.unity scene in VZ/Scenes can be the starting point for any game.

It contains:

  • 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 turn scene 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, and do things like adding addng lift force as a function of Controller.InputSpeed to fly.

We’re happy to share how the avatars in our games all move, just ask on the forum!

 

VZPlayer Component

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:

  • BodyPrefab – should always be set to VZController.prefab or similar structure (contains Camera and required GameObjects)
  • 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
  • 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. When adding VZPlayer you should delete your scene Camera, because it will be loaded with the VZController.prefab to move around with the player.

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 Component

VZController is for accessing our bike data and providing HMD data to VZPlayer or your own custom control and dynamics. It also supports gamepad and keyboard control for testing when you don’t have a bike or HMD.

It’s loaded by VZPlayer as part of the VZController.prefab, where it can be accessed as VZPlayer.Controller. If you don’t use VZPlayer you can place the VZController.prefab directly in your scene, and access VZController on its top level object.

If you don’t use VZPlayer, you need to call ConnectBike() on VZController to get it started. 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
  • IsBikeLicensed() – whether it has Premium membership
  • LicenseStatus() – membership status string
  • IsAlphaBike() – prototype VZ bike without directional buttons or reverse pedaling or resistance sensing
  • IsBetaBike() – original VZ bike
  • IsBikeSensor() – VZfit sensor kit

The properties of VZController 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

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

Gamepad

  • 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

Keyboard

  • 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

 

Playmaker Support

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:

  • VZController.Distance
  • VZController.Head.Forward
  • VZController.Head.Position
  • VZController.Head.Bend
  • VZController.Head.Lean
  • VZController.Head.Rot
  • VZController.InputSpeed
  • VZController.LeftButton.Down
  • VZController.LeftButton.Pressed
  • VZController.LeftButton.Released
  • VZController.RightButton.Down
  • VZController.RightButton.Pressed
  • VZController.RightButton.Released
  • VZPlayer (object for you to call methods on)
  • VZPlayer.Restarted
  • VZPlayer.Speed (adjusted for terrain, speedups, etc)