5.3 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}. 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. 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.
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.
vendor/bin/pestandvendor/bin/pint --testpass.- Commit (small, one concern each) and push to
origin master. - Run
scripts/deploy-edgerealm.sh. Done when it printsLive: https://server-village.blax.at at <commit>. - 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).