zklmiao/CodeWar

CodeWar is a browser-based, turn-based competitive game for people who want to practice Python under time pressure: two players each control a character on a 5×5 board, and each turn they must choose one of four puzzle-backed actions — attack, move, block, or use a skill. It is a game first, with coding as the combat mechanic, so it fits players or groups looking for a coding duel rather than a tutorial or judge platform.

What you actually do

Four puzzles appear at once with a 75-second turn window, but only one can be submitted. Attack puzzles are mirrored, so both players race on the same problem, and clearing it faster raises the time multiplier on damage (0.6–1.0). A wrong submission locks you out for 5 seconds and costs 3 HP, and an action only takes effect when every test case passes. Difficulty is a risk/reward choice: higher caps raise both the damage and reward multipliers. Matches end at zero HP, or after 10 turns by remaining HP — and a simultaneous knockout is a draw with no ELO change (gameplay rules).

How the competition is run

Three character classes (swordsman, mage, ranger) differ in HP, attack shape, movement, and skills with 2–4-turn cooldowns. The server is authoritative: the client renders an event stream and sends submissions, while the engine decides everything. Puzzles come from a factory of 124 templates: the same seed always produces the same instance for reproducible tests, but a different seed produces a different one, so memorizing answers does not help. Human players, practice bots, and scripted replays all submit through the same port, so the engine has no special case for bots (architecture).

Modes and prerequisites

Available now: local hot-seat 1v1 with two browser windows, PvE practice against three bot levels (unrated), a four-level interactive tutorial that unlocks PvP, and accounts with match history and ELO. Online ranked 1v1 is explicitly not implemented; the event-stream protocol and surrender handshake are ready, but matchmaking is future work (roadmap).

The recommended start is the Docker Compose full stack, which opens on localhost:3001. It requires a running Docker daemon, because the judge launches a one-off python:3.12-slim sandbox container through docker.sock. The stack bundles the Go 1.26 server, Vue 3.5 client, Python 3.12 judge, and PostgreSQL 16. The README's separate local-development path also needs Docker for the judge, plus pip, Go, and pnpm (setup).

Licence condition that matters

The project is source-available, not OSI open source. Code, including puzzle templates, is under PolyForm Noncommercial 1.0.0 (free noncommercial use, modification, and distribution, with attribution kept in NOTICE); documentation content is under CC BY-NC-SA 4.0. Any commercial use, such as product integration, paid service, or commercial distribution, needs written permission from the author (licence).