Porting Half-Life 2 to Web: Memory Management Challenges

Porting a 20-year-old physics-heavy masterpiece to the web isn't actually a graphics problem. It's a memory management war. Most people assume the hurdle is getting the shaders to look right in a browser, but the real fight happens in the heap.

WebAssembly is great, but it doesn't just magically handle the kind of aggressive memory allocation these old engines rely on. When you're dealing with a codebase written before modern garbage collection was a standard consideration, you end up with leaks that would make a C++ developer blush. I've spent the last few weeks chasing a memory leak that only appeared when a specific type of physics object collided at a certain angle. It's the kind of tedious, invisible work that makes you wonder why we bother bringing legacy software to the browser at all.

The result is a weird tension. You have this incredibly stable, polished game on one side and the volatile, sandboxed environment of a web browser on the other. Getting them to play nice requires more than just a compiler. It requires a willingness to rip apart how the game thinks about memory and rebuild it from the ground up.

The question is whether the performance trade-offs are worth the convenience of a URL.

The Architecture of WebAssembly

WebAssembly (Wasm) is a binary instruction format that lets you run C++ or Rust in the browser at near-native speed. It isn't a language you write by hand; it's a compilation target. You use the Emscripten compiler to turn your C++ code into a .wasm file, which the browser's engine then executes. Because Wasm is a low-level bytecode, the browser doesn't have to spend time parsing complex text like it does with JavaScript. It just maps the bytecode to machine instructions and runs.

The sandbox is the part that's genuinely confusing. For security, Wasm can't touch your actual hard drive. It doesn't have direct access to the file system. Instead, Emscripten creates a "virtual file system" in the browser's memory. If your game tries to save a high score to save.dat, it's actually just writing to a chunk of RAM. To make that data persist after a page refresh, you have to manually sync that virtual memory to IndexedDB.

git clone https://github.com/emscripten-core/emsdk.git
./emsdk/emsdk install latest
./emsdk/emsdk activate latest
emcc main.cpp -o index.html # Compiles C++ to Wasm and generates an HTML wrapper

This memory isolation is a trade-off. You get a massive performance boost, but you lose the ability to do simple I/O. You're essentially building a tiny, isolated operating system inside a browser tab. It's a weird way to handle files, but it's the only way to keep the user's computer from being compromised by a malicious binary.

The Memory Bottleneck

Browsers aren't designed to handle gigabytes of game assets. While a native OS lets a process request more memory until the hardware hits its limit, a browser tab lives in a sandbox with a strict heap limit. If you push the heap too far, the browser doesn't just slow down; it kills the process. This is the "Aw, Snap!" crash.

To avoid this, the game doesn't load everything into the main JavaScript heap. It uses SharedArrayBuffers to store heavy data like textures and geometry in a way that's accessible to both the main thread and Web Workers. This moves the heavy lifting out of the garbage collector's sight, which prevents those stuttering frames that happen when the browser tries to clean up a few hundred megabytes of temporary objects.

The trade-off is that you can't just "load" a level. You have to stream it. This means the game is constantly swapping assets in and out of GPU memory based on where the player is looking. It's a balancing act: load too much and you crash the tab; load too little and you see textures popping in.

// Allocate a shared buffer for asset data to avoid main-thread heap bloat
const buffer = new SharedArrayBuffer(1024 * 1024 * 64); // 64MB buffer
const view = new Uint8Array(buffer);

// Worker threads can now write asset data directly to this view
// without triggering expensive main-thread garbage collection

This part is genuinely confusing because the browser's memory reporting is a lie. If you check the Chrome Task Manager, the "Memory Footprint" is often much higher than the actual JS heap size. It's because the browser is counting the GPU's VRAM and the SharedArrayBuffers separately, making it hard to tell exactly how close you are to a crash until it actually happens.

Practical Implementation

The build pipeline starts by compiling Rust code into WebAssembly using wasm-pack. This tool handles the heavy lifting by running the wasm32-unknown-unknown target and generating a .wasm binary. It also creates a JavaScript wrapper file that manages the memory bridge between the browser's JS engine and the WASM linear memory.

The glue code is the part that's genuinely confusing. Because WASM can't directly access the DOM or complex JS objects, the wrapper translates strings and objects into pointers that the WASM module can understand. If you're using wasm-bindgen, this happens automatically during the build.

curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
wasm-pack build --target web

Once the build finishes, you have a pkg/ folder containing the .wasm binary and the .js glue code. You can't just open the HTML file from your hard drive because browsers block WASM loading over the file:// protocol for security reasons. You need a local server.

• wasm-pack handles the compilation and JS wrapping.
• The .wasm file contains the compiled logic.
• The .js file acts as the interface.
• A static server is required for execution.

You can use a simple Python server to get it running in seconds.

python3 -m http.server 8000

In your HTML, you just import the generated JS module and call the init function. It's a straightforward process, though debugging the memory boundary between Rust and JS is where things usually get annoying.

Bridging the Input and Graphics Gap

Getting Half-Life 2 to run in a browser via WASM is a neat technical feat, but I'm not convinced it changes how we actually distribute games. The community is treating this as a win for "the open web," but for most players, the friction of a browser—input lag, memory limits, and the lack of a native filesystem—is still higher than just hitting "Play" in Steam. I think the celebration here is more about the possibility of the tech than the actual utility of the experience.

That said, this matters for the tool-chain. If we can get a complex, physics-heavy engine like Source to behave in a tab, it makes the argument for web-based editors like Godot much stronger. I'm less interested in playing a twenty-year-old game in Chrome and more interested in the idea that I can open a full-scale development environment without installing a single dependency.

I'm still skeptical about where the performance ceiling actually sits. We can port the logic, but can we get the latency low enough for a competitive shooter to feel right? That's the real question.

Conclusion

Getting Half-Life 2 to run in a browser is a hell of a technical feat, but it doesn't suddenly make WebAssembly the default for everything. The memory bottlenecks are still there, and the input lag is a reminder that the browser is still just a wrapper around a much more complex set of hardware realities.

I'm still not convinced we're moving toward a world where the native OS disappears. We've seen this cycle before. For now, just try the demo and see if the frame drops bother you as much as they bother me.