game-village-politics-frontend/CLAUDE.md

42 lines
3.8 KiB
Markdown
Raw Normal View History

# Village Politics: frontend
This is the Nuxt client for a browser strategy game in the style of Tribal Wars. It runs on the web first and may ship on Steam later, wrapped in Electron or Tauri. The backend, its architecture, and the roadmap live in `../game-village-politics-backend`. Read `../game-village-politics-backend/docs/architecture.md` before you add a feature.
## Rules
- **The client is a view.** It sends intents over WS and renders what the server returns. It never computes costs, durations, combat, or loot. The only computation it does is projecting resources (`stored + rate × elapsed`) and countdowns from server timestamps. It refetches when a countdown reaches zero or a `village:updated` push arrives.
- **`ssr: false` for every target**, so one static build serves both the web and Steam. Code must not rely on Nuxt server routes or SSR-only APIs.
- **Transport** is WS-first through the `ws` singleton from `@blax-software/networking`, the same as learn-atc. HTTP is only for login and register, which return the bearer token. Load the `blax-websockets` skill before you write `ws.send` or `ws.listen` code.
- **Light Tailwind UI** (Tailwind 4, theme and component classes like `.panel`, `.btn` in `app/assets/css/main.css`) with simple hand-written inline SVG graphics (`app/components/icon/`, colours in `app/utils/palette.ts`). No paid, hosted or licensed assets: no icon packs, web fonts or images from outside the repo. Sprites per building level and drag-to-place stay in M7 (city view). Keep components small and typed, with state in composables (`useVillage`, `useWorld`).
- All user-facing text goes through i18n keys, with `en` as the first locale. Sources are `i18n/locales/` and `i18n/pages/` (`@blax-software/i18n` layout); register a new page file in `i18n/messageloader.ts`.
## Mock server
The client talks to the real backend by default (`server-village.localhost.at` locally; the server's `.env` points the static build at `server-village.blax.at`). For UI work without a backend, `NUXT_PUBLIC_MOCK_SERVER=true` swaps the `ws` singleton and login for `app/mock/`: an in-browser fake that answers the same intents with the payloads in `app/types/game.ts`, finishes build orders on timers, and pushes `village:updated`. Its numbers and rules are placeholders, not game design; the backend is the source of truth. Delete `app/mock/` once nothing needs it.
Every `ws.send` carries the bearer token as `authtoken` (added in `app/utils/networking.ts`): that is how the WS server authenticates a socket.
## 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
pnpm install
pnpm dev # https://village.localhost.at
pnpm typecheck
pnpm i18n:check # fails on missing keys
pnpm generate # static build for web and Steam
```
## Deploy
The prototype runs on https://village.blax.at (edgerealm, `/mnt/HC_Volume_102040804/srv/game-village-politics-frontend`, container `village-politics-frontend`). It is the logigate setup with a static twist: a one-shot build container runs `pnpm generate` into `.output/public`, and nginx serves it with an SPA fallback (`docker/nginx.conf`). Build-time settings come from `.env` on the server, created from `.env.example` on the first deploy.
Commit and push to `origin master`, then run `scripts/deploy-edgerealm.sh`. It is done when it prints `Live: https://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:`.