Table of Contents
Game Features
Mod Support

About Half-Life 2: VR Mod

Who is developing HL2VR?

It is being developed by the SourceVR Mod Team, a group of VR enthusiasts. More information is available on the About page.

Can I support the SourceVR Mod Team?

HL2VR is, and always will be, free of charge. Even so, a lot of time has gone into its development. If you enjoy your time in City 17 and want to say thank you, consider buying us a coffee:

SourceVR Mod Team on Ko-Fi

But please, only donate if you are happy with what we have already released, and are financially able and willing to do so; do not treat it as a down-payment for any future development!

Alternatively, we are always happy to just hear a few kind words of your experience. :-)

How can I download and install it?

You will need to own the standard Half-Life 2 game on Steam (though it does not need to be installed; HL2VR itself will include everything you need).
Having the game available through Steam’s Family Share is not enough - your Steam account needs to own Half-Life 2.
You can purchase Half-Life 2 on Steam here: Half-Life 2

You also must have SteamVR installed. You can download it (for free) from Steam here: SteamVR

If you meet those requirements, HL2VR itself is available free of charge! You can download and install it via Steam here: Half-Life 2: VR Mod

Is the mod completely finished?

Since the original launch of HL2VR as a public beta in September 2022, we have pushed several significant updates improving on many aspects of the game. In our opinion, the mod now offers a polished experience from beginning to end and is mostly feature-complete.

However, that does not mean we are done quite yet, and there are still a few things left to do. For more details on what we have planned for the future, please visit our Roadmap.

What headsets are supported?

HL2VR is targeting SteamVR, so any headset supported by SteamVR should be good to go. So far, it has been successfully tested on Index, Quest, Vive, WMR, and Pimax headsets.

Can it run standalone on the Quest?

No, a PC is required to play. You can of course use Oculus Link, AirLink, or Virtual Desktop to play it with your Quest over a wired or wifi connection.

While the Quest 2 hardware might be powerful enough to run HL2VR, there is no legally available Android port of the Source engine that would be required to make it run on the headset directly.
Valve has refused to give their consent and support on this front, so the team will not be pursuing any standalone release.

Portal? L4D? TF2? CS?

Woah, woah! Let’s take this one game at a time. We’re focusing on Half-Life 2 and its Episodes right now. We’ll make public announcements if/when that changes in the future.

Portal 1 is the only other Valve title that is a viable option right now for multiple reasons, and while we do hope to make it happen, it won’t be for some time yet. It will also only happen if Valve approves.

Game Features

Will Episode 1 and 2 be supported?

The Episodes are being released as separate titles, similar to the standard Half-Life 2 and Episode 1/2 titles.

Episode 1 launched on March 17th, 2023. You can find it here on Steam: Half-Life 2: VR Mod - Episode 1

Episode 2’s release date is planned for April 2023. Please wishlist it here on Steam: Half-Life 2: VR Mod - Episode 2 - this helps boost its visibility!

World interaction

You can pick up, move, and interact with physics objects, props, weapons, health kits, etc.

An “immersive” ladder climbing mode is enabled by default, in which you can grab the ladder and pull yourself up or down. A more standard stick-based climbing option is also available.

Detailed interactions with doors, levers, and yes - valves - is a work in progress, and not enabled at this time. For now, please simply use the Use button to interact with these items!

Comfort options

A standard movement vignette is available.
While moving, the borders of your screen will be blackened, reducing your field of view and reducing the impact of motion sickness.

Artificial turning can be configured to be either smooth or in fixed intervals (snap turns).

Teleport movement
Teleport movement is available as of the February 2023 update, and can be used on the ground or in water. See the Manual for details.

Seated mode
This mode fixes Gordon’s in-game height to match the base game regardless of the player’s headset position.
To properly utilize this, enable the option then use the “Recalibrate view” button on the pause menu.

World scale
Players uncomfortable with the standard world scale can adjust it to be larger or smaller.

How does anyone stomach the vehicle sections?

The vehicle sections require strong “VR legs”. However, there are some additional comfort options available to help you survive them!

By default, the game uses a “fixed horizon” mode.
This prevents your view from tilting left or right, which can help keep your view more stable even as the vehicle thrashes around.

The movement vignette is also available (as a separate toggle) and can be activated for the vehicle rides.

A 3rd person camera perspective is available.
In this mode, the camera follows the vehicle at a distance and is not directly subjected to the vehicle’s rapid movements and turns, which should reduce motion sickness dramatically. (It does, however, make controlling the vehicles a little more awkward.)
An additional mode using an experimental teleporting camera is also available, to further reduce artificial locomotion during these sections.

Weapons & Controls

Manual reloading?

Yes, all weapons support manual reloading. Partially used magazines and other ejected ammo can be recovered and added back into your inventory. A “quick reload” option has been added that simplifies the process, for players looking for an easier reloading option.

For more details, see the Reloading section of the Manual.

Manual reload for the crowbar has been disabled.

Two-handed weapons?

Yes! All weapons can be held two-handed.

Some weapons only benefit slightly from a two-hand grip, such as the Pistol.
Some weapons are designed to be held two-handed to reduce recoil and spread, such as the SMG and Combine Pulse Rifle.
And some weapons require two hands to use, including the Shotgun (which needs to be pumped in between shots).

I want to hit things with the crowbar?

Good news - you can! Crowbar damage also scales, to some extent, with both your swing distance and speed.

However, props cannot be used as melee weapons (except when thrown with the Gravity Gun, as usual).

How do controls work in-game, and what options are available??

HL2VR will offer some in-game hints on the required actions and buttons you need to perform certain actions. For a comprehensive overview of the controls, check the Manual.

Smooth locomotion movement is enabled by default. The direction of motion can be configured to either follow your head, or either of the two controllers. Turning can be configured to be either smooth or in fixed intervals (snap turns).

A Teleport movement option is also available.

Is left-handed mode supported?

Yes, you can configure the dominant hand, which determines the hand that is holding weapons. It will also swap the control scheme accordingly, so (by default) movement is on the off-hand and turning is on the primary hand.

If you would like to hold your weapons in the left hand while still moving with the left stick, you will need to configure a custom SteamVR controller binding (or use a preset that another community member has created and shared via SteamVR).

Why did you put (this action) on (this button)?

Unfortunately, the amount of inputs provided by most VR controllers is limited, and we have a selection of actions that need to be mapped to the primary-hand controller. These include the weapon selection menu, primary and alt fire, eject magazine, turning, jump, and crouch. While some of these actions could, in theory, be bound to the left controller, doing so feels unintuitive or in many cases would be impossible to use properly.

As a consequence, we have no choice but to bind some of these actions to the up/down movement on the joystick. After some experimentation, it was found that neither the weapon selection menu nor alt-fire were a good candidate to place on the stick as the sticks have a higher accidental misfire probability. Putting jump on the stick is less harmful in most situations. It also means that both sticks are now fully devoted to controlling movement, with the right stick controlling turning, jumping, and crouching.
Additionally, it allows us to make the overall controls very similar to Half-Life: Alyx, which most of our players are probably familiar with.

While it may take some getting used to initially, the vast majority of our playtesters have not had any issues with the controls. But if you still do not like the assignments, the controls are fully customizable via SteamVR controller bindings, and many community members have created and shared control preset that work well for them!

Mod Support

Is the Steam Workshop supported?

Yes! You can visit it here: Half-Life 2: VR Mod - Steam Workshop

For more information on how to upload items to the Steam Workshop, visit the Workshop Support page.

Is HL2VR compatible with Black Mesa?

No. We agree that Black Mesa would be amazing in VR, but that would have to be a whole new project made by, or at least in collaboration with, the Black Mesa team. Unfortunately, Crowbar Collective has stated they will not be pursuing a VR version by themselves, and see no feasible way to give a third party access to their source code. An official VR version of the retail release is - at this point in time - not planned.

Is HL2VR compatible with other mods?

Yes, to a limited degree. In general, custom maps and campaigns as well as asset mods (like texture and model mods) are expected to work, although we cannot give any guarantees for any individual mod. Any mod that includes custom code or custom weapons, however, is incompatible and would require specific changes to be ported to HL2VR. As a rule of thumb, if the mod includes its own custom DLLs, expect it to not work.

Custom content (such as texture mods) can go in the /Half-Life 2 VR/hlvr/custom directory. You can also take a look at the #hl-modding channel in the Discord server for advice on the most popular community mods.

The HL2VR team cannot provide any support for external mods!

Will you make the source code for HL2VR available?

That is our intention. HL2VR is based on the publically available Source SDK 2013 edition and can, in principle, be open sourced under the same license terms.

However, given the long development history of the project and the changes in the core team who worked on it over the years, we first need to do our due diligence to ensure that the source code is in a releasable state and that there are no technical and legal issues preventing it from being published. While we do not expect any major issues, this process will require some time. The source code release will therefore happen some time in the future, and there is currently no definitive timeline.


How can I increase the resolution of the desktop mirror for higher-quality recordings?

Right-click on the game in Steam, select “Properties” and then add the following to the “Launch options”:

-w 1920 -h 1080

This will size the desktop mirror at 1080p. You can also select any other resolution you want to use. Note, however, that the desktop mirror is essentially a copy of one of your eyes and thus limited by the VR render resolution. If you select a 4K resolution for the desktop mirror, you will not actually get 4K quality unless your VR render resolution is also at least 4K per eye.

Can I stop the desktop mirror from doubling the in-game HUD / menu?

Yes. Go to the options, then click the button in the lower left to bring up the console. Type hlvr_hud_on_mirror 0 to deactivate mirroring the ingame HUD to the mirror window. Or type hlvr_hud_on_mirror -1 to additionally disable mirroring of the main menu on the desktop mirror. The setting persists, so you only have to do it once. If you wish to revert the change, type hlvr_hud_on_mirror 1.

How can I select which eye is mirrored to the desktop?

By default, the right eye is mirrored. If you wish to change it to the left eye, go to the console and type hlvr_mirror_eye 0. To change it back to the right eye, type hlvr_mirror_eye 1.