game-village-politics-backend/CLAUDE.md

5.8 KiB
Raw Blame History

Village Politics: backend

The game is called Kronland; Village Politics is its code name (repos, domains, Taiga board). A browser strategy game in the style of Tribal Wars (Die Stämme), with one big difference: a village has a fixed amount of building space instead of a fixed building list. Players choose what goes in that space, and multiple instances of a building type are allowed, so one village can become a farming village and another a military village.

This repo is the Laravel backend. The Nuxt client is in ../game-village-politics-frontend.

Read docs/architecture.md before you change game logic, the data model, or the event engine. The milestone plan is in docs/roadmap.md. Tick its boxes as work ships.

Game rules for the code

  • Server-authoritative. The client sends only intents, such as village.build {village_id, type}. The server checks ownership, cost, building space, queue, and requirements, and computes every cost, duration, and timestamp itself.
  • Lazy state. Resources, loyalty, and recruit progress are stored + rate × elapsed. Before any change, settle the current value into the row, then apply the change.
  • Timed effects are rows in game_events. The game:events worker processes them in (fire_at, id) order. Game logic is never a delayed queue job, because those don't keep order.
  • Config, not literals. Game values live in config/game/*.php plus per-world overrides in worlds.config. Game code reads them through WorldConfig.
  • app/Game/ is pure PHP: no Eloquent, no facades, no now(). Time and config come in as arguments, so every formula can be unit tested.
  • No locks. A village may fail, but it must never get stuck. Any new rule or config value needs a way out and, where possible, a ConfigLint check. The list is in the "No locks" section of the architecture doc.
  • Mutations catch up the village's due events first. Then they run in a transaction with lockForUpdate() on the village row.

Tests

Every formula in app/Game/ gets a Pest unit test. Every action gets a feature test that moves time with Carbon::setTestNow(). A milestone is done when its tests are green.

Tests run on SQLite; production is MySQL. After a deploy, scripts/e2e-edgerealm.sh runs the WS API end to end (join, show, build with its push, map) in a throwaway container on edgerealm with its own database, so production data stays untouched. Never register test accounts on the live backend. A check against live data runs inside a transaction that is rolled back.

WebSocket API

The API is WS-first, the same as learn-atc. It uses native controllers in app/Websocket/Controllers/ (blax-software/laravel-websockets). Load the blax-websockets skill before you write a controller or a push. HTTP is used only to log in, register (issues the Sanctum bearer token), and serve health checks. After the engine processes an event, it pushes the change to the owner's sockets with ws_whisper.

Task tracking: Taiga board village-politics

Every deliverable has a card on the Taiga board village-politics (one epic per roadmap milestone). Follow the loop in the taiga skill: search before you create, move the card to In progress when you start, and run done when it is implemented.

Commands

docker compose up -d
docker compose exec app php artisan test                 # all tests
docker compose exec app php artisan test --filter=Combat # one area
docker compose exec app php artisan migrate:fresh --seed # reset local world

The game:events worker and the WS server run as supervisor programs in the app container (docker/supervisor/). Restart the container after you change engine or WS code, because both cache code at boot.

Local: https://server-village.localhost.at (HTTP), wss://ws-server-village.localhost.at (WS).

On Windows without Docker, the tests run on a user-local PHP 8.4 (the image's version) and Composer in %LOCALAPPDATA%\Programs\php84: vendor/bin/pest and vendor/bin/pint (SQLite in memory, per phpunit.xml). The WS server needs pcntl, so it only runs on Linux.

Finishing a change

Every change ends live, right away: the user wants each change on the URL as soon as it is done, not batched. The user has authorized this for this project: deploying the game's containers on edgerealm needs no further go-ahead.

  1. vendor/bin/pest and vendor/bin/pint --test pass.
  2. Commit (small, one concern each) and push to origin master.
  3. Run scripts/deploy-edgerealm.sh. Done when it prints Live: https://server-village.blax.at at <commit>.
  4. Name the live commit in the reply. If the frontend needs the change too, deploy it right after (see its CLAUDE.md).

The authorization covers only /mnt/HC_Volume_102040804/srv/game-village-politics-backend, /mnt/HC_Volume_102040804/srv/game-village-politics-frontend and their containers. Everything else on edgerealm (a host shared with customer sites) still needs the user's go-ahead.

Deploy

The backend runs on edgerealm at https://server-village.blax.at (HTTP) and wss://ws-server-village.blax.at/app/village-politics (WS), from /mnt/HC_Volume_102040804/srv/game-village-politics-backend with containers app, mysql and redis on the shared web network. deploy.sh runs there: pull, composer install, migrate, seed the worlds, optimize, restart the WS server and worker. The first run creates .env from .env.example with generated secrets.

Commit and push to origin master, then run scripts/deploy-edgerealm.sh. It is done when it prints Live: https://server-village.blax.at at <commit>. On Windows, run it as PATH="/c/Windows/System32/OpenSSH:$PATH" scripts/deploy-edgerealm.sh.

Commits

Make small commits, one concern each, with prefixes like feat:, fix:, test:, docs:, chore: (the same style as learn-atc).