Half-Life 2 on the Switch

This is a guide for running Half-Life 2 on your Switch. Please be aware that this isn't a great way of playing Half-Life 2 - do not expect this mod to work perfectly.

Thank you to Bringus Studios for fixing save files not showing up!

NOTE: I am assuming that you have basic knowledge about how modding games on the Switch works. I will not provide support for questions like "how do I install Atmosphère / CFW", "how do I make an emuMMC", "how do I extract games", etc. For help with modding your console, see the NH Switch Guide.

WARNING: While this mod should be fairly safe to use, I do not take any responsibility if your Portal save data is deleted, you get banned from Nintendo Switch Online, or if your Switch explodes.

Instructions

You will need:

A modded Switch
7-Zip
A copy of Portal: Companion Collection
A copy of Half-Life 2 (I used the Android version, the PC one might work)

Let's get started.

Dump the Portal 1 title and extract its romfs to somewhere on your PC.
Extract the game.zip archive to a folder.
Delete the portal and nxcontent/portal folders from the extracted archive folder. We don't need them.
Rename the nxcontent/hl2 folder to nxcontent/portal.
(OPTIONAL) Open nxcontext/rom_boot_params.txt in your favourite text editor and add the following to the end of the file:

+sv_unlockedchapters
15

Copy the hl2/maps folder from your Half-Life 2 game files to hl2 in the extracted archive folder.
Copy the hl2/sound/music folder from your Half-Life 2 game files to hl2/sound in the extracted archive folder.
Rename the hl2 folder to portal.
Rename the portal/resource/hl2_<your language>.txt file to portal/resource/portal_<your language>.txt.
Open the following files in your favourite text editor and replace all instances of hl2 with portal:

portal/gameinfo.txt
portal/scripts/titles.txt
portal/resource/portal_<your language>.txt

Create a new ZIP archive using 7-Zip with the folders portal, nxcontent, and platform. (You can easily do this by by selecting all three folders in File Manager -> right click to open the context menu -> open the 7-Zip menu -> select "Add to xyz.zip".)
Rename the new archive to game.zip if it isn't named that already.
Open the new game.zip file and verify that you see the folders portal, nxcontent, and platform in the root. If you do not see these folders, you did not create the ZIP file correctly.

Create the folder atmosphere/contents/01007BB017812000/romfs on your microSD card.
Copy the game.zip file into the romfs folder you created in the previous step.
Create the folder atmosphere/nro_patches/portal on your microSD card.
Download this IPS patch and move it into the portal folder you created in the previous step. Do not change the file name. It must be named A74E2D73E62E187F0F0422482BD37ED8F0FA0777000000000000000000000000.ips to work properly.
Start Portal 1 on your Switch. It should boot into Half-Life 2.

Troubleshooting

Half-Life 2 doesn't boot!

Ensure that you have followed every step (paying special attention to comments in bold) and placed all files in their correct places.

Also, if you aren't using 7-Zip, try using it. I used Archive Utility on macOS once and it didn't work.

It doesn't work on yuzu or Ryujinx!

Yuzu is not able to boot Portal 1 or 2 at the time of writing (July 2, 2022). The relevant bug report for yuzu is located here.

If you are using Ryujinx, update to version 1.1.166 or newer.

Why does my health regenerate automatically?

You are playing as a Portal player, which is programmed to regenerate health over time.

Can I run Half-Life 2: Episode 1 and Episode 2?

Kinda.

Just add the episodic and ep2 folders to the game.zip, and change -game hl2 to -game episodic (for Episode 1) or -game ep2 (for Episode 2) in rom_boot_params.txt.

However, be warned - Episode 1 and 2 are very unstable and like to crash.

Can I run Team Fortress 2 / Counter-Strike Source / Left 4 Dead 1 or 2 / (insert some other Source engine game here)?

Probably not, at least without a significant amount of effort. The main problem here is that the client.nro and server.nro files only contain code for Portal and the Half-Life 2 games. They do not contain the code for any other games.

That being said, you can probably get their maps to load in Portal or Half-Life 2. It might be necessary to do some conversion between file formats for things like models. (I believe some other Source engine branches have their own modified model format?)

Known Issues

Here is a list of the known issues with this mod:

The game randomly crashes.
NPCs don't animate correctly while walking.
The Combine's guns don't do any damage to the player.
Health regenerates over time, like in Portal.
In-game cameras drawn onto surfaces don't render at the correct places, if they even appear at all.
The game stutters a lot, possibly due to shader compilation.
After a map loads, the game has to rebuild the node graph.

If you want to try and fix some of these issues, see the next section for potentially useful information.

Technical Details & Potential Improvements

Here's the technical stuff that some people might be interested in.

How was the Portal 1 port achieved?

The Switch version of Portal 1 appears to be based on the NVIDIA Shield version made by NVIDIA Lightspeed Studios.

The main executable in the exefs is a launcher for the Source engine. All NROs (the Switch's version of DLL files) are present in the romfs in the nro folder on the romfs.

All game files are compressed into a single ZIP archive called game.zip. The nxcontent folder in game.zip appears to contain game files that should be overriden specifically on the Switch, along with various other files like shader binaries and caches. The rom_boot_params.txt file in nxcontent contains the command line arguments (and console variables / commands) that are passed to the engine.

Are you able to open the developer console?

Yes, if you add -console to the rom_boot_params.txt file. However, while the console appears, it is seemingly impossible to interact with it. (Plugging in a USB keyboard does nothing.)

What does that IPS patch do?

It removes this call to PointCameraSetupVisibility in CHL2_Player::SetupVisibility() from server.nro. I'm not sure why this crashes.

Here's the specific patch code, if you're interested:

005465D8 1F2003D5 // NOP

What happens when the game randomly crashes?

As far as I can tell, most of the random crashes appear to occur in CUtlMultiList<T, I>::Alloc() called by some AI behaviour class (possibly CAI_SimpleBehavior or a subclass?). I believe this likely means that either the "exhausted index range" or "exhausted memory allocator" errors are occurring, but I haven't confirmed this yet.

How do I debug a crash?

Atmosphère will create crash logs with full stack traces and register dumps in atmosphere/crash_reports on the microSD card. It is also possible to attach the GDB debugger to the game's process. Use these tools to debug crashes.

I managed to fix something!

Great! If you could let me know, that would be awesome. (My Twitter is @OatmealDome, or you can click here to send me an e-mail.) Also, if you release something based on my work, I'd appreciate if you give me a shoutout.

OatmealDome/HL2ForSwitch.md