th0mk / nfsu2-web

# Need for Speed: Underground 2 in the browser
A fan project that runs the PC game *Need for Speed: Underground 2* (2004) in Google Chrome and Firefox. The game's
x86 code is translated to C ahead of time and compiled to WebAssembly. Direct3D 9 runs on WebGPU and the sound on
Web Audio. You bring your own copy of the game.
> Not affiliated with or endorsed by Electronic Arts. This repository contains none of the game's code or data.
## What you need
- **The game:** your own PC copy, patched to v1.2 (North America), with this exact `SPEED2.EXE` (other versions
 will not work): 4,800,512 bytes, SHA-256 `f9dd86c054878ce6276beb07c1fd61874f7a1e4bf1f241b084c65b73e24168a7`.
- **To build:** an Apple Silicon Mac (the tested setup) or Linux, Python 3, Node.js 20 or newer, and
 wasi-sdk 34 for that system unpacked into `deps/`. On Windows,
 build in WSL 2 with the clone in the Linux file system (`~/nfsu2-web`): under `/mnt/c` it builds much slower.
- **To play:** the latest Google Chrome, or Firefox where it has WebGPU (Windows, macOS).
## Build
 [code] 
The generated C and the compiled module are made from the game, so they are never committed (`.gitignore`).
## Play
 [code] 
Open **http://localhost:8080/** in Chrome or Firefox and press **Play**. The start page has the settings, your saves
and the controls. The player's guide is docs/web/PLAYING.md.
To play with friends, run the server behind HTTPS, for example on a small VPS with Docker:
docs/web/VPS.md.
Everyone who plays from the same server can meet in free roam.
## How it works
- **`tools/`:** a Python lifter (Capstone) turns every function of `SPEED2.EXE` into C.
- **`runtime/`:** Windows, Direct3D 9, DirectSound and DirectInput, reimplemented. `runtime/web/` holds the browser
 parts.
- **`web/src/`:** the page. It runs the game's threads as workers on one shared memory, draws with WebGPU and plays
 sound through an AudioWorklet.
- **`web/server/`:** serves the page, the module and your game folder, and connects players for multiplayer.
More in docs/web/DESIGN.md. The same tree still builds the native macOS version
(`./gen.sh`, `./build.sh && ./link.sh`, `./run.sh`).
## Credits
Based on Talha Müderrisoğlu's static recompilation of NFSU2 for Apple Silicon, which in turn follows the method of
N64: Recompiled and XenonRecomp.
Built with the help of Claude Code.
## License
MIT (LICENSE). *Need for Speed* and *Need for Speed: Underground 2* are trademarks of Electronic Arts Inc.