game-village-politics-frontend/CLAUDE.md

3.5 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.
  • 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

Until the backend serves the WS API, runtime config MOCK_SERVER (on by default) 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. Run against a real backend with NUXT_PUBLIC_MOCK_SERVER=false, and delete app/mock/ once nothing needs it.

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

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