modding the source engine for the Oculus Rift

Menu

We’re currently in the process of wrapping up the latest release of Half-Life VR, which will include HL2: episode 1 VR support. Over the last month a lot of work has gone into the mod, in both new features and fixing bugs (many of which are just elements of the source engine that just didn’t translate to VR very well). While the razer hydra is perfectly fine for our current work, we’re really looking forward to adding sixense STEM support when the developer kits come out next year and have plenty of ideas for ways to utilize the additional trackers.

In addition to working out the issues in Episode 1, here’s a list of some of the features that’ll be included in the next release:

Hud integrated in-game – You’ll notice in the video the HUD is not integrated in-game and shows the weapon ammo information directly on the side of the gun. On the back of gordon’s right hand you’ll see an HEV overlay showing health and suit stats (like looking at a watch).

Fixed aim vectors – the dirty little secret (or maybe obvious part if you played much ) of the last release was that the weapons were still shooting from eye center the same way they normally do in source games. This is corrected now (as it was in the older 2007 versions of the mod).

Reworked gravity gun and physical interactions to allow more control with hydras

I’m happy to finally say a new version of Half-life VR built on top of Valve’s native rift support is now available for download here. The mod is still focused on integrating the razer hydra for 1-to-1 accurate weapon (and now body) tracking. In addition to that we’ve been gathering feedback both from the earlier release of the mod and Valve’s latest HL2 release and working against the most common complaints we heard that prevented it from being a proper VR experience.

Simplified Setup

Eliminating the difficult installation/setup was one of the major focus areas for this release. Previous versions required both vireio to handle processing the output for the rift and sixense motion creator to handle mapping the hydra inputs into the game. With this latest release you can now simply download and run the installer and start the game. All of the controls should have a functional binding by default, and you can now customize your control settings using the in-game menus. You can also now control the mouse in the in-game menus using the right hydra joystick and the trigger for clicking.

Calibration

Calibrating the weapon position in the default mode ( a hydra in each hand ) is pretty simple, make sure you’re facing forward relative to the hydra base, hold your left hydra up to the base of your neck ( right above the collar bone ) and press the calibrate button ( right hydra start button ). When holding it up to your neck, you’ll get the best results if you align the part of the hydra where the wire comes out with the center of your neck since that’s roughly where the tracker is. If you’re using one of the other control modes (mt_control_mode option in the console), this position is where your left hydra should be permanently attached.

More than just a rift integration

Valve’s excellent rift integration was an excellent foundation to begin with for a VR setup. Now with 1-to-1 razer hydra integration for both your aim and body tracking allow you to extend the immersion to your movements within the world. The optional body positional tracking is a huge immersion boost, allowing you to lean down and examine a destroyed scanner drone, peak over a ledge is, duck behind a desk, etc. I’ll outline how to use body positional tracking settings in more detail in a follow-up post, including some ways to attach your hydra for positional tracking. Although using a hydra as a positional tracker is fairly limiting given that you give up on half the inputs available, you can work around this by using an xbox 360 controller in your left hand. I’ve opted in on the Kickstarter for a sixense S.T.E.M tracker setup and will integrate it once the dev-kits ship next summer.

Aside from the hydra integration, a lot of the work has gone into small tweaks to the game to fix things that just weren’t very compatible with the rift. Movement speeds have been adjusted, as was the player height. The game now fades out and back in during level loads to reduce the nausea that many people experienced. Wormslayer and I are working toward a cool new approach for bringing the HUD in-game (not in this version unfortunately).

Update: This version of the mod is obsolete at this point, check more recent posts for information on the latest version of the mod.

As I’m about to release a very early version of my Half-Life VR mod updated with full positional tracking via Razer Hydra integration, I wanted to outline a few things that will hopefully help anyone interested in trying it get the best experience possible.

Installing the mod

You’ll need to have the Source SDK Base 2006 and 2007 installed via steam before installing the app. You can download them for free under Library->Tools in steam The installation process for the mod is simple, just download the installer from here and run it and it should take care of everything else. There is a chance that you’ll also need to install a microsoft c++ runtime before the mod will work, if you try starting the mod and it just drops out on start, you can download the runtime here: http://www.microsoft.com/en-us/download/details.aspx?id=5555. Once installed try to start the mod again and fingers-crossed, everything should load up fine. If not, post a comment here, this is still very early and I’m sure there will be issues when running on some setups, I’ll do my best to sort through the issues. Assuming the mod started up ok, you’re ready to configure a few things and start playing.

Configuring your Hydra

Use your razer hydra configuration utility to map the buttons on your hydra to the usual FPS keys you like for HL2.exe. There are a few things you’ll need to make sure though:

Don’t map anything to the analog sticks, you can do WASD emulation here but I’m already using the analog inputs directly through their api (so you get real analog movement) so anything you do here with them will conflict with that. You can map the stick push down to a key.

Don’t map any gestures or use the controller motions or this will conflict with the game actually trying to use the motion to directly control your weapons on screen.

Map the right hand start button to the “L” key, this will be your recalibration control (more on that later)

Map a button on your hydra to “J”, this will toggle walk mode (in tight spaces or non-combat areas this really helps maintain immersion where the standard movement speeds are unwieldy)

Assuming you’ve mapped all the controls you need, there should be more than enough buttons.

Configuring Vireio Perception

The most important part of the configuration is making sure you have vireio perception configured properly. Assuming it’s set correctly you should be able to get a result that is near the level of native implementations but finding the right settings can be challenging. First off, check out the vireio wiki for an in-depth guide to your one-time configuration: http://www.mtbs3d.com/wiki/index.php?title=Vireio.

Once you have the convergence and eye separation set to your liking, you may want to tweak the FOV depending on how near the lenses your eyes are. I’ve got it defaulting to 100 degrees at install, but I actually have my rift set on the nearest adjustment and found that ~105 worked well for me. Play with these settings in game by pulling up the console and running “fov_desired 110”. Once you find something that really works, open up your Steam/steamapps/sourcemods/halflife-vr/cfg/autoexec.cfg and update the fov_desired and viewmodel_fov variables to the value that works best for you.

The one last thing I had to do was change the distortion factor. You can do this in vireio (I’m using beta_11 at this point) with shift+F1. What you’re trying to eliminate is any warping out around the edges, which is easiest to see by looking at a fixed object up and in front of you and turning your head up or down while following the object. If it appears to warp away from you as it nears the edges, hold shift+f1 while continuing to watch it until the effect is corrected. You can use F1 to adjust the other way if you go too far.

Unfortunately the distortion factor doesn’t currently save with your profile like the rest of the settings yet so don’t forget to do this again next time you start the game, it only takes a second once you know what you’re looking for.

Note: When running vireio perception for this mod, make sure you set tracking to “Disabled”. I’m using the tracking information in the game directly so this vireio mouse emulation isn’t necessary (and will actually cause problems with the mod).

In-game calibration

Once your hydra controls are mapped and vireio is setup, you’re ready to play. When you first load a map, you’ll want to calibrate your trackers so they’re all on the same page. Make sure you’re facing forward relative to your hydra base with your head level and your right hydra controller pointed in the same direction as your head and press the start button on the right controller to calibrate. You’ll generally want to hold it in line with your shoulder at somewhere near shoulder height and not too far in front of your shoulder. Play with different positions to find what is suitable for you, calibrating higher means the gun is naturally lower, calibrate further forward and at rest the gun is closer to the screen. It’s all a matter of preference from there.

You may need to occasionally do this again as rift current drifts since its magnetometer isn’t being used in the current rift apis.

If your weapon ever jumps from one spot to another (typically a fairly large jump) this means your hydra tracking wasn’t properly initialized and can’t tell which hemisphere your device is in. Hydra sensor values are the same in mirrored locations on both sides of the base station which is why when you start up your hydra software it asks you to point the left and right at the base, which it can use to determine which of the two positions the controller is in. I’m not sure if there is anything you can do in game here at the moment, I typically save and exit and restart my motion creator but there is likely a better way to handle this.

A Few Tips for Your First Play-through

Don’t expect to be amazing right of the bat (and play on easy). It’s easy to forget how much time we’ve spent perfecting our ability to aim with a mouse, aiming with an actual physical object in 3D space is challenging at first. It’s also really rewarding as you realize how much better you are after a few hours.

Try not to run and gun too much, take your time, use walk whenever you don’t need to explicitly run, take in the atmosphere, use cover and pick off the enemies, etc. Sprinting around firing wildly and spinning around are all pretty disorienting with the rift, even though I don’t ever get motion sick it’s still just not an enjoyable experience.

Most of my videos have almost exclusively featured independent head and weapon tracking, and while this isn’t technically a requirement to play with the mod, it’s definitely the most fun and immersive way to play through the mod.

This guide will take you all the way from “that video looks interesting” to playing it yourself if you’re willing to buy the necessary components. This tutorial does make the assumption that you have an Oculus Rift as your HMD which should work out of the box with the mod for head tracking. Don’t let the length of this deter you, once you have everything initially set up, the actual process of playing the game is as simple as pushing the button on the controller, starting the game and putting on your rift.

The Hardware

In addition to the Oculus rift, you’ll need a handful of off-the-shelf (or internet) bits of hardware to get the mod working with independent head and weapon tracking.

The Gun Controller

I’ve tried a handful of gun controllers but the so far the only one that’s been cost effective is the xbox 360 version of the Top Shot Elite. You can pick it up for anywhere between $40-50 typically. You’ll also need an xbox 360 controller wireless adapter if you don’t already have one, they typically run for around $15 online.

The controller should be plug-and-play and is recognized by your computer as an xbox 360 controller. You won’t need the infrared bar or the scope since the tracking so you can toss those out.

The Tracker

In my initial build (and videos online) I used Hillcrest Labs FSM-6 trackers, which are the same one that John Carmack used in his doom 3 rift demos at E3 last year. They cost $100 initially run at 120hz but you can get the 250hz firmware upgrade from Hillcrest. Unfortunately while the tracking is plenty responsive the FSM-6 only has a gyro and accelerometer but lack a magnetometer that allows it to keep a consistent directional orientation which doesn’t matter much when using a single tracker, but when using head and weapon tracking this frequently causes the gun to drift horizontally. While I’ll continue to support the hillcrest trackers for people who already have them, I wouldn’t recommend buying it at this point for VR applications.

I’ve recently migrated both my head and weapon tracking over to YEI 3-space trackers. With an update rate of 1000hz and a magnetometer that prevents drift between the two trackers, it’s a major improvement over the Hillcrest without costing much more. You can purchase them from their website http://tech.yostengineering.com for anywhere between $100 – $170 for the USB version. For $100 you’ll get just the actual chip and need a bit of soldering know-how to attach a micro-usb connector, but the more expensive version comes in a very consumer-friendly form factor with a mini-b connector. You’ll also need a usb cable for the tracker, I use a thin 15 ft usb mini-b cable, but depending on your setup you may need more length. You’ll also need to install the 3 space software package available on their site which includes the drivers.

Attaching the tracker to the gun is pretty trivial, I’d suggest having the tracker facing up with the usb port toward the back of the gun. You can just electrical tape it to the to gun-site rail with electrical tape like I did or I’m sure there are plenty of fancier ways to attach it.

So now that you’ve got your tracker mounted and plugged in, assuming you mounted your tracker oriented the way I mentioned above, the last thing you’ll need to do is adjust the orientation using the 3-space sensor suite. Start the “3 space suite” program and connect to your device using the drop-down on the bottom.

The Software

To play the mod, you’ll need to have Half-Life 2 (and the episodes if you want them to work) installed and you’ll also need to install the source sdk 2007. Aside from that, download the latest version of the mod and run the installer. Once it’s through, you’ll need to restart steam to see the new Half-Life VR (and ep1 & 2) entries in your game list.

If you start up the game with the gun controller on, my default controls should already all be set. Feel free to remap whatever Here’s the general layout:

Left Stick – Movement (sprint when clicked)

Button Beside Left Stick – Use

D-Pad – Up and down cycle weapons, forward is last weapon, backward is gravity gun

Button Behind D-Pad – toggle crouch

Right Stick – turn left and right in addition to the head tracking, you can bind up and down to things if you like but be aware, you’ll likely trigger them accidentally when turning

Click Right Stick – recenters the weapon horizontally with the view (this was much more necessary with the hillcrest trackers, but you’ll still need to do this initially on first load since I’m not currently saving off the calibration data so you’ll want this to be handy)

Left button behind the right stick (jump)

Trigger – fire

Pump – secondary fire

Reload – ‘back” or select button on the clip (I personally like physically having to do sort of a reload movement,but it’s definitely not the most efficient place)

Flashlight – start button on the clip

When the game loads a map for the first time, depending on how you mounted your tracker you’re weapon on-screen will likely be oriented incorrectly. Make sure your head and weapon are both level and facing the same direction and press the “L” key. Everything now should be all set for you to start playing.