game-village-politics-backend/CLAUDE.md

4.5 KiB
Raw Blame History

Village Politics: backend

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.

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.

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).