- docs/NEXT.md: where to pick up, prioritised, with the known wall-selling bug and its two-line fix - docs/review-2026-10-09/: 85 reviewer findings (touch, co-op, client code, visual, reverse proxy) with verification status, repro scripts archive and the review workflow script; nothing fixed yet by design - docs/BALANCE.md + tools/bot.js: headless balance bot and the untuned baseline (IDS Sniper dominates, maze is a near-guaranteed win, credits snowball) - test/sim.test.js derives tunable numbers from the tables, plus a shape test - README status note Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Tb8pW2KAN4oFkh1aK1BfD8
179 lines
9.4 KiB
Markdown
179 lines
9.4 KiB
Markdown
# NETWALL
|
|
|
|
**Build the firewall. Stretch the route. Protect the server.**
|
|
|
|
An open-map, maze-building tower defence game for the browser, with two-player co-op. Hostile packets (pings, worms,
|
|
trojans, spam, spoofed flyers and the odd rootkit boss) pour in from internet gateways and head for your server along the
|
|
shortest open route. You can't walk them off the map, but you can make that route **long**: cheap Firewall walls,
|
|
placed anywhere, force them on a detour past your turrets. You may never seal the route completely, so every wall is
|
|
a decision.
|
|
|
|
* Plays in any modern browser, **desktop and mobile** (portrait and landscape, touch, pinch-zoom).
|
|
* **Solo** works straight from the files (no server needed).
|
|
* **Co-op online**: two players, one shared map, one base and one pot of credits, building at the same time, with live
|
|
partner cursors and map pings. Needs the small Node server in this repo.
|
|
* No build step, no framework, no external requests. Vanilla JS + canvas.
|
|
|
|
> **Status:** playable, but a review pass found bugs that are not fixed yet (for example, a placed Firewall cannot be
|
|
> sold because selecting it throws). The full list, balance analysis and the plan for the next session are in
|
|
> [docs/NEXT.md](docs/NEXT.md).
|
|
|
|
## Run it
|
|
|
|
```bash
|
|
# Debian / Ubuntu: sudo apt install nodejs npm
|
|
npm install # one dependency: ws
|
|
npm start # http://localhost:8080 (prints your LAN URLs too)
|
|
```
|
|
|
|
Open the printed URL on any device on your network. Pick a map and press **Play solo**, or **Co-op online** to create a
|
|
room and send the invite link (or the 4-letter code) to a friend.
|
|
|
|
Solo only: you can also just open `public/index.html` in a browser (the built-in synth music plays; your own tracks
|
|
need the server, because browsers block loading the track list from a `file://` page).
|
|
|
|
Environment variables: `PORT` (8080), `HOST` (`::`, dual-stack IPv4 + IPv6), `TRUST_PROXY`, `ALLOWED_ORIGINS`,
|
|
`MAX_CONN_PER_IP`, `GRACE_MS`. Full reference and troubleshooting: [docs/DEPLOY.md](docs/DEPLOY.md).
|
|
|
|
## Setup guide: Debian 13 LXC behind nginx Proxy Manager
|
|
|
|
The game is one small Node process (static files + a WebSocket at `/ws`), so the proxy only has to forward HTTP and
|
|
WebSockets. Nothing is stored on disk; a restart ends running games.
|
|
|
|
### 1. Install it in the LXC (as root)
|
|
|
|
```bash
|
|
apt update && apt install -y nodejs npm git # Debian 13 ships Node 20, which is plenty (18+ works)
|
|
git clone ssh://forgejo@int.git.vanvikinternet.no/jvanvik/towerdef.git /opt/netwall
|
|
cd /opt/netwall && npm install --omit=dev # only "ws"
|
|
|
|
useradd --system --home-dir /opt/netwall --shell /usr/sbin/nologin netwall
|
|
install -m 0644 deploy/netwall.service /etc/systemd/system/netwall.service
|
|
systemctl daemon-reload && systemctl enable --now netwall
|
|
|
|
curl http://127.0.0.1:8080/healthz # -> ok
|
|
curl -g 'http://[::1]:8080/healthz' # -> ok (the server listens on IPv4 and IPv6 at once)
|
|
journalctl -u netwall -f # live log
|
|
```
|
|
|
|
The service listens on `[::]:8080` (dual stack) and runs as the unprivileged `netwall` user. Change `PORT`, `HOST`,
|
|
`TRUST_PROXY` or `ALLOWED_ORIGINS` in the unit's `Environment=` lines (or `systemctl edit netwall`) and
|
|
`systemctl restart netwall`. If the unit fails with a sandboxing error inside an unprivileged Proxmox container,
|
|
comment out the line it names (see the notes in `deploy/netwall.service`).
|
|
|
|
### 2. Add a Proxy Host in nginx Proxy Manager
|
|
|
|
**Hosts > Proxy Hosts > Add Proxy Host**
|
|
|
|
| Tab / field | Value |
|
|
|---|---|
|
|
| Details: Domain Names | `game.example.com` (your name for it) |
|
|
| Details: Scheme | `http` |
|
|
| Details: Forward Hostname / IP | the LXC's IP address |
|
|
| Details: Forward Port | `8080` |
|
|
| Details: Cache Assets | **off** |
|
|
| Details: **Websockets Support** | **on** (without it the page loads but co-op cannot connect) |
|
|
| SSL: Certificate | Request a new SSL Certificate (Let's Encrypt), **Force SSL** on, **HTTP/2** on |
|
|
| Advanced (optional) | `proxy_read_timeout 3600s;` and `proxy_send_timeout 3600s;` for very long idle games |
|
|
|
|
NPM passes the original `Host` header through, which is what the server's WebSocket origin check expects, so no
|
|
extra configuration is needed. If the server log ever shows `refused websocket ... does not match Host` (HTTP 403 on
|
|
the upgrade), set `ALLOWED_ORIGINS=https://game.example.com` in the unit and restart.
|
|
|
|
### 3. IPv6 (optional)
|
|
|
|
The server side is already dual stack. Publish an `AAAA` record for the game name **after** your proxy really answers
|
|
on IPv6 (`curl -6 -I https://game.example.com/`); a published but broken `AAAA` breaks IPv6 visitors and certificate
|
|
issuance. The proxy-to-LXC hop can stay IPv4.
|
|
|
|
### 4. Check it, play it
|
|
|
|
```bash
|
|
curl -i https://game.example.com/healthz # 200 ok
|
|
```
|
|
|
|
Open `https://game.example.com/` on two phones, press **Co-op online**, create a room on one and tap the invite link
|
|
(or type the 4-letter code) on the other. On a phone, "Add to Home Screen" gives a full-screen app.
|
|
|
|
Lock the LXC down so that only the proxy can reach port 8080 (firewall example in `docs/DEPLOY.md`).
|
|
|
|
### 5. Update
|
|
|
|
```bash
|
|
cd /opt/netwall && git pull && npm install --omit=dev && systemctl restart netwall
|
|
```
|
|
|
|
Running games end with the restart (players see the room is gone and can create a new one).
|
|
|
|
Under a path prefix such as `https://example.com/netwall/`, the proxy must strip the prefix; see section 7 of
|
|
[docs/DEPLOY.md](docs/DEPLOY.md). A dedicated sub-domain is simpler.
|
|
|
|
## How to play
|
|
|
|
| | |
|
|
|---|---|
|
|
| **Goal** | Survive 30 waves (then keep going in endless mode). Every packet that reaches the server costs integrity. |
|
|
| **Firewall** (5) | A wall. Packets path-find around it; the route preview shows how much longer it makes their trip. |
|
|
| **Packet Filter** | Fast and cheap. Weak against armour. |
|
|
| **IDS Sniper** | Long range, hits hard, slow. The answer to armour and bosses. |
|
|
| **Flood Mortar** | Splash damage on ground swarms. Cannot hit flyers. |
|
|
| **Rate Limiter** | Slows everything in range. Rootkits resist it. |
|
|
| **Router Arc** | Chain lightning between nearby packets. |
|
|
| **Spoofed packets** | Fly straight over your maze: keep some anti-air. |
|
|
| **Credits** | From kills and cleared waves. Upgrade turrets to level 3; selling returns 70% (walls 100%). |
|
|
|
|
Controls, desktop: click to build, drag to paint walls, right-click cancels, `1`-`6` pick a tower, `Space` next wave,
|
|
`U` upgrade, `X` sell, `T` change targeting, `P` pause, `F` speed, `A` auto-waves, `M` mute, wheel zoom, Alt+click pings.
|
|
|
|
Controls, touch: tap a tower type, tap the map to preview (the new route is drawn), tap the check mark (or the same cell
|
|
again) to build. Walls paint as you drag. Two fingers pan and zoom; long-press pings your partner. In portrait the board
|
|
turns 90 degrees so the cells stay big.
|
|
|
|
## Music
|
|
|
|
The game has a built-in synth melody, and plays your own tracks if you add them. Drop files in
|
|
`public/assets/music/` and name them in `public/assets/music/tracks.json`:
|
|
|
|
```json
|
|
{ "theme": "menu.mp3", "battle": "battle.mp3", "boss": "boss.mp3", "win": "win.mp3", "lose": "lose.mp3" }
|
|
```
|
|
|
|
Any entry left `null` keeps the synth version. See `public/assets/music/README.md` for prompt ideas for Suno.
|
|
|
|
## How it works
|
|
|
|
```
|
|
public/ static client (also the web root)
|
|
index.html, css/ layout: grid that reflows for desktop / landscape phone / portrait phone
|
|
js/sim.js the whole game rules: pure, deterministic, no DOM. Runs in the browser (solo) AND in Node (co-op)
|
|
js/controllers.js LocalController (runs sim in the tab) | RemoteController (WebSocket, snapshot interpolation, reconnect)
|
|
js/render.js canvas renderer: camera, zoom/pan, portrait rotation, effects
|
|
js/main.js screens, HUD, mouse + touch input, lobby
|
|
js/audio.js sfx + music
|
|
server/ Node: static files + authoritative co-op rooms over WebSocket
|
|
docs/PROTOCOL.md wire protocol and server requirements
|
|
test/ node:test suites (sim rules, server)
|
|
tools/bot.js headless bot used to balance the game
|
|
```
|
|
|
|
**Pathing.** Every placement is checked against a flow field (Dijkstra from the server, 8-way movement, no corner cutting
|
|
so two diagonal walls really are a wall). A wall is refused if it would seal any gateway or trap any packet already on the
|
|
board. The browser keeps a mirror of the maze so it can preview a placement and the resulting route instantly, even in co-op.
|
|
|
|
**Co-op.** The server owns the one true simulation per room and ticks it at a fixed 60 Hz. Clients send commands
|
|
(place, sell, upgrade, ...); the server broadcasts compact 20 Hz snapshots, and clients render them slightly in the past,
|
|
interpolating. Nothing is simulated twice, so nothing can drift. A dropped connection (phone locked, wifi switch)
|
|
reconnects automatically and resumes the same seat for a minute.
|
|
|
|
## Tests
|
|
|
|
```bash
|
|
npm test # rules + server: placement validation, route sealing, corner cutting, targeting, waves, economy,
|
|
# protocol, rooms, reconnects, security checks, static files, dual stack
|
|
npm run e2e # real browsers: desktop, phone touch (tap-to-build, drag-paint, pinch, long-press), end screens,
|
|
# two-browser co-op incl. reconnect, and a 14-size layout matrix
|
|
```
|
|
|
|
`npm run e2e` drives Chromium through Playwright (a devDependency). Install the browser once with
|
|
`npx playwright-core install chromium-headless-shell` (on a minimal Debian also `npx playwright-core install-deps`
|
|
as root). It starts its own server on a random port and writes screenshots to `e2e/out/`.
|