56 lines
7.0 KiB
Markdown
56 lines
7.0 KiB
Markdown
# 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.
|
||
- **The village is a ground-level land view** (`app/components/village/Diorama.vue`, geometry in `app/diorama/`): isometric low-poly, drawn as inline SVG, no WebGL. The land fills the frame edge to edge (no island, no sky), cut to the container's shape; narrow screens scroll sideways. There are no tiles or positions: the server only sends each building's `space` and the village's `space.used/max`, and the client lays everything out deterministically in id order. The village core sits in the middle (headquarters on the plaza, storage, hiding places and rally point around it, inside the wall ring when there is one, a dirt edge without). Resource sites stand outside in their zones: iron mines at the rocky hill (upper left), clay pits on clay ground (lower left), timber camps at the forest edge (lower right), farms with fields (right); dirt roads lead from the gates to each zone and forest fills the rest. Levels start at 1. Each type has a model per level tier (1–4, 5–14, 15+); the wall goes stakes → timber → stone with towers. Buildings are focusable buttons that open their details card; a type that doesn't stand yet keeps an invisible empty plot that opens its build card. Buildings never move or light up on hover: only a click outlines the ground under them.
|
||
- **Flat medieval colours only**, in the diorama and everywhere else: no gradients (CSS or SVG), no blur or backdrop-blur, no SVG filters or glows, no translucent overlays. Depth comes from the three flat shades per face in `app/diorama/iso.ts`, solid borders and hard shadows. Keep components small and typed, with state in composables (`useVillage`, `useWorld`).
|
||
- **One game shell, like Die Stämme.** Pages inside a world (village screens, map, reports) use `layouts/game.vue`: the dark menu bar (`GameMenuBar`: village, map, reports with the unread count, server clock, account menu), then the sticky village bar (`GameVillageBar`: which village, stock with storage meters, incoming troops, and the village's screens as tabs: Overview, Headquarters, Recruit, Rally point, Workforce). On phones the screens move to a bottom tab bar (`GameTabBar`). The bar's village is the URL's on village screens and the last opened one elsewhere; `GameVillageFrame` holds its one `useVillage()` and shares it through `useVillageContext()`, so the map and reports keep the village on top. Pages outside a world use `layouts/default.vue` (menu bar only). The overview stays clean: the village and a narrow column of boxes (incoming attacks, production, units, population, construction); tables live on the building screens.
|
||
- 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
|
||
```
|
||
|
||
## 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. `pnpm typecheck` and `pnpm i18n:check` pass, and the change works in the preview.
|
||
2. Commit (small, one concern each) and push to `origin master`.
|
||
3. Run `scripts/deploy-edgerealm.sh`. Done when it prints `Live: https://village.blax.at at <commit>`.
|
||
4. Name the live commit in the reply. When the change needs a new backend contract, deploy the backend first.
|
||
|
||
The authorization covers only `/mnt/HC_Volume_102040804/srv/game-village-politics-frontend`, `/mnt/HC_Volume_102040804/srv/game-village-politics-backend` and their containers. Everything else on edgerealm (a host shared with customer sites) still needs the user's go-ahead.
|
||
|
||
## Deploy
|
||
|
||
The game 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:`.
|