Play it: golpe.quest — or read
deploy/oracle/README.md to run your own.
A 2D sword-fighting game — GunZ: The Duel's K-Style rebuilt in two dimensions — on PixiJS 8 + React, with a custom deterministic AABB physics simulation shared verbatim between the client and an authoritative Geckos.io server.
Online first: every match runs through the server, including single player — the server fills the other slot with a bot. Playing the game is dogfooding the netcode.
Thirty seconds from a live eight-fighter AI deathmatch — sword chains, dash
trails, grenade arcs, traps and ultimates — recorded from the running game by
scripts/record-gameplay.ts. Click the clip to
download the full-quality MP4.
| Doc | What's in it |
|---|---|
| Specs | Source of truth for intended behaviour — movement, sword combat, ranged combat, arena, netcode. |
| Running the game | Every way to launch it: player vs AI, AI vs AI, player vs player, online AI vs AI, and the LAN host pack. Dev servers, controls, URL parameters, debug hooks, troubleshooting. |
| LAN host pack | One machine hosts; guests open a URL. One port, mDNS discovery, the LAN badge, and the build/protocol gate. |
| AGENTS.md | The index every agent session loads: the rules that bite, commands, controls, and where to find everything else. Also loaded as CLAUDE.md. |
| Architecture | Module map, the client/server boundary, and the online-first model. |
| Invariants | Every rule that was written by a real bug, with the bug that motivated it. |
| Diagnostics | The physics diagnostic tool: console hooks, reading the report, and the traps that produce false results. |
| Agent config | The write-once/run-everywhere symlink layout for OpenCode and Claude Code. |
| Feedback loop | The physics diagnostic: how to measure a bug before fixing it, and the catalogue of root causes already found. |
| Herdr dev workspace | Running the dev servers in visible herdr panes instead of background processes. |
| Knowledge sharpener | End-of-session routine for folding what was learned back into the docs. |
| Deployment | The Oracle free-tier VM: two Docker images behind Caddy, automatic HTTPS, and the GitHub Actions workflow that ships the deploy branch. |
# versions are pinned in .tool-versions (asdf) and package.json (corepack)
pnpm install
pnpm run dev:herdr # or: pnpm run dev:all
# then open one of (all served by the authoritative server):
# http://localhost:8084/ solo vs server bot
# http://localhost:8084/?ai=true AI vs AI, one tab
# http://localhost:8084/?mode=tdm&bots=7 team deathmatch, two sides
# http://localhost:8084/?online=true player vs player (two tabs)
# http://localhost:8084/?online=true&ai=true AI vs AI, two clients
# http://localhost:8084/?offline=true escape hatch, no server
# host a LAN game without the dev servers (host only; guests open the URL):
pnpm run lan:package
./build/golpe-lan/golpe-lanVerify a change with pnpm run verify (typechecks the client and the server,
then tests and builds), plus pnpm run diagnose for anything touching physics or
netcode.
GPL-3.0 — golpe is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License, version 3, as published by the Free Software Foundation. It is distributed in the hope that it will be useful, but without any warranty; see the LICENSE for the full terms.
Bundled third-party assets keep their own licenses — the MuseScore soundfont and
tinysoundfont-pybind are MIT (see audio/README.md).