66 lines
5.3 KiB
Markdown
66 lines
5.3 KiB
Markdown
# 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](docs/architecture.md) before you change game logic, the data model, or the event engine. The milestone plan is in [docs/roadmap.md](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
|
||
|
||
```bash
|
||
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).
|