3.2 KiB
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, x, y}. The server checks ownership, cost, 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. Thegame:eventsworker 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/*.phpplus per-world overrides inworlds.config. Game code reads them throughWorldConfig. app/Game/is pure PHP: no Eloquent, no facades, nonow(). 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
ConfigLintcheck. 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.
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).
Commits
Make small commits, one concern each, with prefixes like feat:, fix:, test:, docs:, chore: (the same style as learn-atc).