game-village-politics-frontend/CLAUDE.md

8.9 KiB
Raw Blame 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.
  • Dense and plain, like the old browser strategy games (the reference is Die Stämme; notes and screenshots in the sibling repo game-village-politics-research (../game-village-politics-research/die-staemme/), kept out of this repo). A 14 px base, square frames with thin lines, tan header bands, tight table rows (.grid-table), small squared buttons (.btn-primary dark wood, .btn-attack red for attacks only), thin notice bars. No rounded cards, pills, big padding or decorative icons: an icon only where it carries meaning. Theme and component classes live in app/assets/css/main.css; hand-written inline SVG graphics in 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, and nothing copied from Die Stämme.
  • 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. Ambient life is welcome and stays out of the way: flat ground shadows, smoke from chimneys, forges and kilns, villagers walking the roads to the zones they work in; all motion stops under prefers-reduced-motion. The same models draw the building portraits on screen headers, the HQ list and the building cards (VillageBuildingPortrait). The world map groups forests, lakes and rocky hills by smooth noise of the coordinates, and village markers grow in five sizes with points. Map coordinates run around 0|0, negative included (−500 to 499 on a 1000-field map, lowest value from map.view's min); continents are named from the top-left like Die Stämme, so 0|0 is the corner of K44, K45, K54 and K55. Use app/utils/map.ts for bounds and continents, never 0 or 500 literals.
  • 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. Everything sits in one centred column (1100 px). Pages inside a world (village screens, map, reports) use layouts/game.vue: the dark main menu (GameMenuBar: village, map, reports with its count inline, each with a hover dropdown of its sub-pages; server clock; account dropdown), then the village header (GameVillageBar: a quick bar with the village's screens, and one row with the village, its stock in thin cells and incoming troops), thin notices, and the content in a .frame. On phones the screens move to a bottom tab bar (GameTabBar). The header'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(). Pages outside a world use layouts/default.vue (menu only). A page has one of two shapes: a title with box tabs (UiSubTabs: buildings like the rally point) or a title with a sub-menu on the left (UiSideMenu: lists like reports). One key per screen (useShortcuts): V overview, H headquarters, T recruit, P rally point, W workforce, M map, R reports. The overview stays clean: the village and a narrow column of boxes (incoming attacks, production, units, population, construction); tables live on the building screens. The map shows a popup over a hovered village and actions under a clicked one.
  • 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. vue-i18n reads a bare | as a plural separator and drops what follows, so coordinates in messages are written "{x}{'|'}{y}" inside a double-quoted string.

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

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:.