# WebWars — Hedgewars in Your Browser

A browser port of [**Hedgewars**](https://hedgewars.org/), the free turn-based artillery game. No downloads, no installs — just open a link and play.

This project is built on top of [Hedgewars](https://github.com/hedgewars/hw) (GPL v2), created by Andrey Korotaev (unC0Rr) and the Hedgewars community. The game engine is written in Free Pascal — a language with no native WebAssembly target. What makes this port possible is [**pas2c**](https://github.com/hedgewars/hw/tree/master/tools/pas2c), a Pascal-to-C transpiler written by unC0Rr specifically for the Hedgewars project. pas2c converts the entire engine (~40K lines of Pascal) into C, which I then compile to WebAssembly through Emscripten. Without pas2c, this project simply wouldn't exist.

The game server is also theirs — a Haskell binary that handles lobby, rooms, and multiplayer relay. All game assets (graphics, sounds, fonts, maps, 117 Lua scripts) are from the Hedgewars project. I wrote the browser integration layer, the WebSocket gateway, and the web frontend — but the game itself is entirely their work. Huge thanks to unC0Rr and the Hedgewars team for building such a great game and releasing it as free software.

**🎮 Play now: [webwars.link](https://webwars.link)**

## Quick Start

**Solo (hotseat):** Open [webwars.link](https://webwars.link) — two teams on one keyboard, taking turns. Right-click to pick a weapon, Space to fire, Arrow keys to move.

**Custom game:** Open [webwars.link/play.html](https://webwars.link/play.html) to choose a theme (30 options), game style (22 modes like Racer, Shoppa, King), scheme, and weapon set before starting.

**Multiplayer:** Open [webwars.link/lobby.html](https://webwars.link/lobby.html) in two browser tabs:
1. Enter a nickname and click Connect
2. One player creates a room, the other joins it
3. Both players add a team, then the room chief starts the game

## How It Works

Hedgewars is written in Pascal. I compile it to WebAssembly using this pipeline:

```
Pascal → pas2c (Pascal-to-C) → C → Emscripten → WebAssembly
```

The engine runs natively in the browser at 60fps. Multiplayer uses the real Hedgewars server — a WebSocket gateway bridges browsers to the TCP-based server protocol.

```
Browser (WASM engine) ←WebSocket→ Gateway (Node.js) ←TCP→ Hedgewars Server (Haskell)
```

| Component | Tech | Description |
|-----------|------|-------------|
| Game engine | WebAssembly (3.97MB) | Full Hedgewars engine compiled from Pascal via C |
| Core assets | Preloaded .data (7MB) | Sprites, shaders, fonts, sounds, scripts, Nature theme |
| Theme assets | Fetched on demand (~3-7MB) | 29 themes + music loaded dynamically per game |
| WS gateway | Node.js | Bridges browser WebSocket to HW server TCP |
| Game server | Haskell | Official Hedgewars server (rooms, relay, protocol) |
| Admin panel | Flask + Leaflet | Live traffic map, visitor geo, bot detection |

## Building from Source

### Prerequisites

- Linux (tested on Ubuntu 22.04)
- [Emscripten SDK](https://emscripten.org/docs/getting_started/downloads.html)
- Rust with `wasm32-unknown-emscripten` target
- Node.js 18+
- GHC 9.4+ and Cabal (for the game server)
- CMake 3.20+

### Build & Run

```bash
# 1. Build the WASM engine
source ~/emsdk/emsdk_env.sh
source ~/.cargo/env
mkdir -p build/wasm && cd build/wasm && rm -rf *
cmake ../../hedgewars -DBUILD_ENGINE_JS=ON -DNOSERVER=ON \
  -DCMAKE_TOOLCHAIN_FILE=$EMSDK/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake
make -j$(nproc)
cp ../../web/*.html ../../web/*.js bin/

# 2. Build the game server
cd ../../hedgewars/gameServer && cabal build

# 3. Run all three services
./bin/hedgewars-server &
cd gateway && npm install && WS_PORT=8080 HW_HOST=localhost HW_PORT=46631 node src/index.js &
cd build/wasm/bin && python3 -m http.server 8081 --bind 0.0.0.0
```

Open http://localhost:8081 in your browser.

## Project Structure

```
webwars/
├── hedgewars/                  # Hedgewars source (forked, with WASM patches)
│   ├── hedgewars/              # Pascal engine source
│   ├── project_files/hwc/      # C shims: IPC bridge, main loop wrapper
│   ├── project_files/web/      # pre.js / post.js (browser integration)
│   └── gameServer/             # Haskell multiplayer server
├── generated/pas2c/            # C source generated by pas2c (62 .c + 64 .h files)
├── dist/                       # Final WASM build output (see below)
├── gateway/src/index.js        # WebSocket ↔ TCP bridge
├── web/                        # Browser frontend (menu, quick play, lobby, game config)
├── admin/                      # Admin panel (Flask + Leaflet dashboard)
└── scripts/                    # Build scripts
```

### Build Outputs (`dist/`)

| File | Size | Checked in? | Description |
|------|------|-------------|-------------|
| `hwengine.wasm` | 3.8MB | ✅ Yes | Compiled engine (WebAssembly binary) |
| `hwengine.js` | 2.2MB | ✅ Yes | Emscripten glue code (loads and runs the WASM) |
| `hwengine.data` | 187MB | ❌ Gitignored | Game assets (graphics, sounds, fonts, maps, Lua scripts) |

The `.data` file is too large for git. It's generated during the build by Emscripten's `--preload-file` which packages the entire `Data/` directory. Run the build to generate it, or download it from [webwars.link/hwengine.data](https://webwars.link/hwengine.data).

The `generated/` directory contains the intermediate C source produced by pas2c — see [`generated/README.md`](generated/README.md) for details.

## What I Built

This isn't just "compile and ship." Hedgewars was designed as a desktop app with a Qt/C++ frontend (~95K lines), TCP socket IPC, and OpenGL rendering. None of that works in a browser. Here's what I had to build or rewrite:

### Web Frontend (replaces Qt desktop client)

The original Hedgewars client is a full Qt desktop application that handles the lobby, room management, team configuration, and game launch. I replaced all of it with ~1,600 lines of HTML/JS across four files: a lobby page, a quick-play page, a menu page with custom game setup, and a shared config module. The lobby connects to the real Hedgewars server through my WebSocket gateway, implementing the same text-based protocol the Qt client speaks.

A key design decision: the game engine loads dynamically into the lobby page via `<script>` injection rather than opening a new window. This keeps the WebSocket connection alive during gameplay — engine messages (EM) relay directly through function calls in the same JS context. `window.open()` is blocked by popup blockers in incognito mode, and navigating away would kill the connection.

### Engine Modifications

**Pascal changes** — I patched the engine source (`uIO.pas`, `hwengine.pas`, `uStore.pas`, `uSound.pas`, `uRender.pas`) to work in a browser environment. The IPC layer (`uIO.pas`) was rewired to read/write through C shim functions instead of SDL_net sockets. The shutdown path (`hwengine.pas`) skips SDL teardown entirely in WASM builds — `SDL_Quit` and `SDL_GL_DeleteContext` crash Emscripten, so page reload is the only clean reset. Init paths that called `SDL_Delay` were changed to busy-poll instead, since IPC messages are already queued in JavaScript before the engine starts.

**C shims** — Two new C files bridge the engine to the browser. `ipc_browser.c` replaces SDL_net with `EM_JS` calls to a JavaScript message queue — the engine's `IPCCheckSock` reads from JS, `SendIPCRaw` writes to JS, same interface, completely different transport. `web_entry.c` intercepts the engine's blocking `hwengine_MainLoop` (via the `--wrap` linker flag) and replaces it with `emscripten_set_main_loop` (requestAnimationFrame). A multi-tick catch-up system uses the engine's `cOnlyStats` flag to run game logic at real-time speed while only rendering the final tick per frame.

**JSPI** — The engine uses JavaScript Promise Integration (`-sJSPI`) to handle points where WASM needs to yield to the browser (e.g., waiting for IPC during init). JSPI suspends and resumes the WASM call stack without instrumenting every function, keeping the binary small (3.97MB).

### Rendering Optimization

The engine's original renderer made one `glDrawArrays` call per sprite — ~200+ draw calls per frame. Through Chrome's ANGLE layer (WebGL → D3D11), each GL call becomes a D3D resource operation. This pushed GPU frame time to 40-55ms (well over the 16ms budget for 60fps).

I added a sprite batch system in `uRender.pas`: a 1024-quad buffer that accumulates vertices and flushes in a single draw call per texture. All sprite functions (`DrawTextureRotatedF`, `DrawHedgehog`, `DrawSpriteRotatedF`, etc.) were converted from matrix-stack transforms to CPU-side vertex math feeding into `BatchQuad`. GPU frame time dropped from 40-55ms to 1-9ms.

### Multiplayer Sync

Hedgewars multiplayer is deterministic — the server doesn't run game logic, it just relays player inputs. Each engine sends its actions as IPC messages, which get base64-encoded and sent as `EM` commands through the server to other players. The receiving engine injects them into its message queue and replays them identically.

The tricky parts: `IPCCheckSock` must run before and between `DoTimer` catch-up ticks (not just after), or incoming messages aren't parsed into the command queue in time and the engine enters lag mode. Background tabs throttle `requestAnimationFrame` to ~1fps, so I fall back to `setInterval` at 10Hz with rendering disabled to keep game logic in sync.

### WebSocket Gateway

The Hedgewars server speaks a text-based TCP protocol (newline-delimited messages, double-newline between commands). Browsers can't open raw TCP sockets, so I wrote a Node.js gateway that bridges WebSocket to TCP. The browser sends JSON arrays (`["NICK","player1"]`), the gateway converts them to the HW wire format (`NICK\nplayer1\n\n`), and vice versa. Each browser connection gets its own TCP connection to the server.

### Admin Panel

A Flask + Leaflet dashboard (`admin/`) for monitoring production traffic. It polls the prod server every 30 seconds via SSH — parses nginx access logs, counts active WebSocket and game connections, and geolocates visitor IPs using ip-api.com.

Features:
- Live world map with color-coded markers (active players, past visitors, bots)
- Multi-layer bot detection: user-agent patterns, probe path filtering, fake UA detection, cloud ISP blocklist
- Visitor log with city/country/ISP, filterable by bot status
- 24-hour connection history charts

On day one I discovered that ~99% of "unique visitors" were actually bots, scanners, and cloud-hosted probes (LeakIX, Censys, Onyphe, etc.). The only reliable signal for real players is the 187MB `.data` file download — bots never fetch it.

To run the admin panel:
```bash
cd admin
cp .env.example .env   # fill in your server IPs and SSH key path
pip3 install flask requests apscheduler
python3 app.py          # runs on port 5052
```

### Other Details

- **OpenGL compat** (`gl_emscripten_compat.h`): Maps desktop GL constants (`GL_QUADS`, `GL_CLAMP`) to GLES2/WebGL2 equivalents
- **Asset caching**: 187MB `.data` file served with 7-day `Cache-Control` — return visits load instantly from disk cache
- **WebGL2 context**: Created in JS with explicit attributes (`antialias:false`, `alpha:false`, `desynchronized:false`) and passed to Emscripten via `GL_PREINITIALIZED_CONTEXT` to prevent SDL from overriding them
- **Game config UI**: A shared config module (`gameconfig.js`) defines all 16 scheme presets, 13 weapon sets, and 22 game styles extracted from the Qt source code, with human-readable descriptions from Lua script headers. Game styles that lock specific schemes or weapons (extracted from Qt `.cfg` files) disable those dropdowns automatically. The menu page (`play.html`) lets players pick from 30 themes, choose a game style, scheme, and weapon set before launching.

## Known Issues

1. Some theme sprite masks fail to load (visual only, gameplay unaffected)
2. Game exit triggers page reload (SDL teardown not supported in Emscripten)
3. First load downloads ~194MB of game assets (7MB core + ~187MB themes/maps/sounds, cached after that)

## License

GPL v2 (same as [Hedgewars](https://hedgewars.org/))


## Codex development

Start Codex in this directory. [AGENTS.md](AGENTS.md) defines the project role; [PROGRESS.md](PROGRESS.md) is the current handover and work log; [.codex/knowledge/INDEX.md](.codex/knowledge/INDEX.md) indexes detailed inherited knowledge. Original history and Kiro skills remain preserved.