角頭械鬥 · Turf War: Taipei

A round-based SWAT vs Militia shooter set in the streets of Taipei — free in your browser, nothing to install.

Play · Gameplay guide · Contributing

• About
• Features
• Screenshots
• Getting started
• Project structure
• How it works
• Roadmap
• Contributing
• Security and privacy
• Support the project
• Acknowledgements
• License

Turf War: Taipei is an open-source, browser-first team shooter. Two teams of up to 24 fight short, one-life rounds across Taipei — Ximending's neon streets, an office floor 383 m up Taipei 101, the Chiang Kai-shek Memorial Hall — with cash, a store and weapon attachments in the spirit of the classic browser shooter BeGone. It runs on TypeScript and Three.js in the browser and a server-authoritative SpacetimeDB module online, with the same simulation powering offline play.

Gameplay

• Two modes: Elimination and Sabotage (Militia arms the bomb at site A or B; SWAT defends or disarms). First to 10 rounds, one life per round, a 4 s freeze and 20 s of buy time.
• Thirteen maps: Ximending (西門町), Taipei 101 · Xinyi, Taipei 101 · 88F with its tuned mass damper, Memorial Hall (中正紀念堂), Sanchong (三重) across the river, homages to BeGone's maps and original battlefields — see Maps.
• Vehicles: cars and taxis with handbrake drifts, scooters you can shoot from, and a helicopter.
• Economy: cash for kills, headshots, assists and objectives; five primaries, two secondaries, grenades, and optics, suppressors, lasers and more (weapons).

Multiplayer

• Rooms of every size: 1v1, 6v6 and 24v24. Quick play joins the fullest open room, Start a server opens a public room or a private one with a 4-letter code, and Join a server lists every live room with its ping.
• Bots fill empty slots, online and offline, at three difficulties.
• Server-authoritative: damage, cash, purchases, rounds and the bomb run on the server; movement is client-predicted and server-validated.

Accessibility and platforms

• English and 繁體中文, switchable at any time.
• Rebindable controls for every action, using physical key positions (AZERTY and Dvorak work).
• Phones and tablets: touch controls with an editable layout, hold-to-aim firing, and an installable app (PWA) — see Phones and tablets.
• Solo and practice need no server at all.

Taipei 101 · 88F: the damper hall in the tower's core	Ximending: storefronts and covered streets
Memorial Hall (中正紀念堂): the grand staircase from Liberty Square	Xinyi: the plaza beside Taipei 101

Prerequisites: Bun 1.3.10 (use bun / bunx, never npm or npx). For local online play, also the SpacetimeDB CLI 2.10.2.

git clone https://github.com/madeyexz/turfwar.git
cd turfwar
bun install --frozen-lockfile
bun install --cwd spacetimedb --frozen-lockfile
bun run dev            # http://localhost:5173 — Solo and Practice work right away

Online play on your machine — in a second terminal:

bun run dev:spacetime  # local SpacetimeDB on :3000 with the module published as "turfwar"
VITE_SPACETIMEDB_URI=same-origin VITE_SPACETIMEDB_DATABASE=turfwar bun run dev

Checks (the same ones CI runs on every push and pull request):

bun run test             # Vitest (not `bun test`)
bun run build            # type-check and production build
bun run typecheck:module # the SpacetimeDB server module

shared/          Simulation shared by the browser and the server: movement, collision,
  maps/          weapons, vehicles, bots, rounds and the thirteen maps
  match/         Match state, economy, rooms, the packed per-tick frame and the tick itself
spacetimedb/     The SpacetimeDB server module: tables, reducers, admin views, scheduled tick
src/             The browser game: rendering, HUD, input, audio, lobby, online client
  module_bindings/  Generated client bindings for the module
public/          Models, textures, sounds, fonts, icons and the PWA manifest
admin/ privacy/  The owner's dashboard and the privacy page
about/ en/about/ The static about pages (繁體中文, English) with the FAQ, for search and AI answers (docs/SEO.md)
deploy/          The self-hosted SpacetimeDB container and its release scripts
tools/           Asset import and conversion tools (their own dependencies)
docs/            Gameplay, architecture and development guides

• One simulation, two places. Movement, collision, weapons, bots and rounds live in shared/ and run unchanged in the browser (Solo, Practice, client prediction) and in the server module.
• The server decides. Players' reducers only queue input; a 30 Hz scheduled tick applies it with the shared rules and publishes one packed frame per room, which clients interpolate.
• Validated movement. Clients predict their own movement and report it; the server checks every report against speed, collision and vehicle rules and corrects anything out of bounds.
• Always on. The game server (Taipei) never sleeps; if the lobby cannot reach it, it says so after 30 seconds and offers Retry.

The full design — validation, performance budgets and known trade-offs — is in docs/ARCHITECTURE.md.

Ideas the project would welcome help with (see known limitations):

• Lag compensation (server-side rewind) for hit validation
• Interest management, so clients receive only nearby soldiers
• More Taipei maps, and authored reload animations
• Skill-based matchmaking, vote kick and clans
• Testing and polish on Safari and Firefox

Contributions are welcome — bug reports, maps, balance, translations and code alike.

1. Read CONTRIBUTING.md for setup, the checks and the rules of the codebase.
2. Branch from dev and open your pull request against dev (never main).
3. Make sure CI is green, and include screenshots for anything visual.

Please follow the Code of Conduct. Bugs and ideas go to GitHub issues.

• Security: please report vulnerabilities privately as described in SECURITY.md, not in a public issue.
• Privacy: no accounts and no ads. The game keeps your settings and an anonymous ID in your browser, gameplay stats on the game server, and uses anonymous analytics. The full statement is on the privacy page (source).

If you enjoy the game, ⭐ the repository and share it. Hosting is paid out of pocket — to sponsor the servers, email ian@rippling.computer.

• BeGone by nPlay — the rules, numbers and maps this game pays homage to.
• Quaternius, Poly Haven and the authors of The Free Firearm Sound Library — CC0 models, textures and sounds.
• Three.js, SpacetimeDB, Vite and Bun.
• Built largely with Claude (Claude Opus 5.5).

The code is released under the MIT License. Third-party assets keep their own licences (CC0 and the SIL Open Font License). The names 角頭械鬥 and Turf War: Taipei and the logo are not licensed for reuse — forks are welcome under a different name.

The TW app icon was generated with Amp Painter. Its source is tools/app-icon.png; run bun tools/make-icons.ts (after installing tools/ dependencies) to regenerate the browser and home-screen sizes.

An approved, hand-traced SVG version is also available: eight editable vector paths with flat colors and no embedded raster image. It follows the same logo reuse restriction above. The icon generator still uses the original PNG; adding the SVG does not change the shipped icons.

For use without the black tile, download the transparent SVG or its 1024px PNG export. Both keep the same emblem and logo reuse restriction; the white W works best on dark backgrounds. These variants do not replace the app icons.