20 KiB
Village Politics: frontend
The game is called Kronland (app.title); Village Politics is its code name. 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 avillage:updatedpush arrives. ssr: falsefor 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
wssingleton from@blax-software/networking, the same as learn-atc. HTTP is only for login and register, which return the bearer token. Load theblax-websocketsskill before you writews.sendorws.listencode. - 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 16 px root (17 px from 1800 px wide; rem sizes only,text-smfor body text, no fixedtext-[13px]), square frames with thin lines, tan header bands, tight table rows (.grid-table), small squared buttons (.btn-primarydark wood,.btn-attackred for attacks only), thin notice bars. Actions are buttons, not text links:.btnfor screen links and commands,.btn-fillfor the "(20)" that fills an amount field; names inside lists and tables stay links. Bigger text must not add line wraps: keep rowswhitespace-nowrapwhere they were one line. No rounded cards, pills, big padding or decorative icons: an icon only where it carries meaning. Theme and component classes live inapp/assets/css/main.css; hand-written inline SVG graphics inapp/components/icon/, colours inapp/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 inapp/diorama/): isometric low-poly. The village draws with WebGL through Three.js (useDioramaGl): everything that stands still is one mesh built frombuildScenein the painter's order (app/diorama/gl.ts), people, animals, smoke and crows are posed every frame from the samelife.tstiming (app/diorama/figures.ts), and each moving figure and ground ring gets a depth step of its own, so it sorts in among the buildings exactly as SVG layering would; a thin SVG over the canvas, on the same view, carries the click targets, keyboard focus, tags and countdowns. The close-up and the portraits stay inline SVG, so new life goes into both: the SVG components for them andfigures.tsfor the village. 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'sspaceand the village'sspace.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, footpaths from every door to the nearest road or the plaza, and forest fills the rest. Levels start at 1. Each type has a model per level tier (1–4, 5–14, 15+) and looks like what it is: the headquarters flies the village flag with banners at its door, the storage is a barn, the stable has stalls with horses looking out and a paddock, the workshop wheels and siege engines in the making, the barracks a training yard (tents, then a hall with shields, then battlements); the wall goes stakes → timber → stone with towers. Buildings are focusable buttons that enter the building (buildingRoute): the headquarters opens construction, the rally point its commands, a military building its recruiting, every other building its own screen (/village/<id>/building/<bid>); each of these screens starts withVillageBuildingHeader: a close-up (VillageCloseup,app/diorama/closeup.ts: the building large on its ground, its props and forest, its assigned workers walking to where they work and back carrying what they make), what it does now and one level up (effects/next_effectsfrom the server), workers, priority, upgrade and demolish. The open building stays outlined in the village, and clicking it again returns to the overview. Buildings are clickable anywhere on their outline (hit, a convex hull round their polygons and ground ring), the thin wall also along a wide band on its ring, and their tags and countdowns as well; a type that doesn't stand yet keeps an invisible empty plot that opens its build card. Every building wears a fixed tag (buildingTaginapp/utils/buildingTags.ts): its level and the one live number that says what it does: camps their production, the storage its fullest resource against the limit, the farm the free villagers, the headquarters the building space, a military building what it trains and when that is done, the rally point the troops in the village (red while an attack comes), wall, hiding place and watchtower their effect; amber when worth a look, red when it needs action. Tags that would overlap move up. Buildings never move or light up on hover: only a click outlines the ground under them. While a window or the build card is open, a pointer click in the village only closes it, so a stray click never swaps it for another building's (keys still open what has focus); Esc closes it too. The village feels alive, and life stays out of the way: flat ground shadows, smoke from chimneys, forges and kilns; workers go out to their zone with their tool (VillageWorker, timing inapp/diorama/life.ts: one SMIL clock per figure for the walk, stepping legs, the tool swing at work, the load on the way home and turning round), two villagers talk on the plaza, every order in the queue shows at its site (planks and stones piled up, a porter carrying more from the storage door, and while it runs a builder with a hammer, or a pick to tear down), units in training drill in front of their building with an instructor, villagers step out of their doors and go back in (a building's door is found by itsDOORcolour; resting figures withindoorsare out of sight), a guard paces inside the gate, soldiers stand guard at the doors while troops are in the village (two at the headquarters, one or two at every other door with a big army:guardsAt), sheep graze past the farms and chickens peck round the plaza (VillageAnimal), crows cross now and then and circle over the graves and the gallows (VillageBird); the close-up does the same for its building. The times are hard, and the land shows it (the look is grim and worn, never cheerful): tired olive grass, mud roads with wheel ruts and puddles, trodden mud between the houses, a ragged edge where the wall stands, mud splashed up the walls and rotten patches on most roofs (mudline,roofRotiniso.ts), stumps where the forest was cut and dead trees in it, a graveyard behind the village with a grave more as its points grow and the newest still open, the gallows by the main road, a burnt farmstead still smouldering, blood on the training yard and the rally ground. The land darkens a little away from the village into the forest (fadeinscene.ts). People wear undyed and faded cloth, smoke is sooty (SHIRTS,UNIFORM,SMOKEinmodels.ts). Nothing gory beyond blood stains: no bodies. All motion stops underprefers-reduced-motion; people who stay put then stand still. 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. A ring and flag in the relation's colour mark every village (RELATION_COLOURSinapp/utils/relations.ts, frommap.view'srelation): own yellow, the village the player is in white, tribe blue, allies light blue, NAP purple, enemies red, other players dark red, barbarians grey. Every group the player knows of (map.view'smovements) is a line from origin to target, dashed for returns, with the group at its current position (MapMarch: one to five soldiers by the size tier, stepping in place, a banner in the line's colour); raiders wait at their camp until they march. Map coordinates run around 0|0, negative included (−500 to 499 on a 1000-field map, lowest value frommap.view'smin); continents are named from the top-left like Die Stämme, so 0|0 is the corner of K44, K45, K54 and K55. Useapp/utils/map.tsfor bounds and continents, never0or500literals. - 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(overcast daylight: faces turned away drop to two thirds and cool a little), solid borders and hard shadows. The palette (Cinapp/diorama/models.ts, the ground colours inscene.ts, the map inWorldMap.vue) is muted, desaturated and worn, but it is daylight, never dusk; fire and blood are the only warm colours. In the diorama there are no outlines: a polygon strokes in its own fill only to close seams, detail comes from a few large shaded panels (house(): a stone plinth, half-timber beams on wooden walls, a framed door, framed windows with shutters, a ridge beam;openings()for stone halls; two-tier firs; people as shaded shapes inVillageWalker), not from many small nodes. Panels on a wall sort a step in front of that wall face's centroid depth. A face that must draw over its wall (doors, windows) setsdepth; offsets andshift()carry it along. In the close-up, workers are sorted in among the objects by depth. Surfaces carry small repeating patterns generated in code at startup (app/utils/patterns.ts→--pat-*custom properties, set byplugins/patterns.client.ts, painted perbg-parchment-*/bg-wood-*class and on.panel,.frame,.btn-primaryinmain.css): parchment flecks, woven header bands with a stitched hem, wood grain; flat opaque shades a step off the surface, never images or opacity. Keep them minimal. One look for every part: each header band is.panel-headwith a.panel-title, everything that floats over the village has the.floathard shadow and sits in a bordered frame, and every vertical scroll area is.scroll-y, whose bar always shows so content never shifts sideways; the one scrollbar style (wood handle with notches in a parchment track) lives inmain.css. Every page keeps the page scrollbar, the fullscreen village included (an empty track there), so the usable width never changes when hopping between the village, the map and the reports. Keep components small and typed, with state in composables (useVillage,useWorld). - The village fills the screen on its overview. On
/village/<id>GameVillageFramedraws the diorama fixed across the whole browser window and docks everything over it, solid and opaque: the menu and the village bar along the top, the overview boxes in a right column (on phones a bottom sheet), and on the left the build card of an empty plot picked in the village (useVillageSelection). Every other screen is a page of its own (next point). Screen grids use container queries (@4xl:, the page frame is the container), not viewport breakpoints. The village opens fitted, with a strip of land round it: the frame measures what the bars, the right column, the phone tab bar and the bottom sheet cover (inset), andbuildScenefits the whole village into the rest (home), so nothing of the village is cut off. From there the player pans and zooms (useDioramaCamera): drag or arrows to pan, the wheel, a pinch or the + − buttons at the bottom right of the free part to zoom (up to 4×), 0 or "Whole village" back home; a drag never opens a building. Ground and forest run on round the village (bounds: the view ×1.6, at most the village ×2.6, so phones grow sideways), opening into clearings further out; the camera never leaves them. Tags and countdowns keep their screen size at every zoom. The landing page's picture (still) has no camera and no land beyond its view. The player arranges it: a window (the chat) drags by its title bar on wide screens (a double-click there puts it back:useWindowOffset), and the boxes of a dock (the overview's, the map's) areUiDockcards: a click on the header folds one, a drag moves it to another place in the column or out to float anywhere over the stage, and a floating box has a button back into the column (useCardLayout, per dock). Layouts live in localStorage, per browser; phones keep the boxes in their sheet, foldable but not draggable. This is where the game deliberately leaves Die Stämme's look behind. - Screens are pages. Every other screen of a world is a page of its own, like the old browser games: the building screens (headquarters, recruit, rally point, workforce, and
/village/<id>/building/<bid>for the rest), the reports, the ranking and the tribe render across the full width under the menu, the village bar and the notices (GameVillageNotices): the screen in the left column, the village in a right column (wide screens; it stays in view while the page scrolls and outlines the building whose page is open, and a click on another building opens that one's page). The world's pages (not the building screens, which have their own header) carry a title band. Overview (V) goes back to the full village. Nothing in a world changes width between pages: the menu and the village bar always run the full width. The map fills the screen under the menu bar itself (it readsuseStage()for where the menu ends) and teleports its panels (centre and zoom, minimap with the jump form, field info, legend) into the right dock (#stage-dock); on phones a small strip with home and zoom floats over it. Pages outside a world, or of a world whose village isn't known yet, have the menu only. All world pages uselayouts/game.vue(GameVillageFramedraws the same parts, over the village on its overview): the dark main menu (GameMenuBar: village, map, reports with its count inline, tribe with its invites, ranking, each with a hover dropdown of its sub-pages; the chat toggle with its unread count; server clock; account dropdown), then the village header (GameVillageBar, in two pieces with the village showing between them: on the left the quick bar with the village's screens over the village row, on the right the stock in thin cells, each resource with its amount against the storage limit, its rate per hour and a fill bar, and the villagers with how many are free, then incoming troops; the space between lets clicks through), 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;GameVillageFrameholds its oneuseVillage()and shares it throughuseVillageContext(). Pages outside a world uselayouts/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, K ranking, S tribe. The chat (GameChat, state inuseChat) is a window of its own at the bottom left with a tab per channel (world, tribe, each conversation); it listens forchat:messagewhile mounted and keeps its own drag position. 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. Groups on the march are clickable on their line and their figure: a card at the group (MapMarchCard) tells from where to where, what (own units or the size tier) and when it arrives, and calls an own command back whilecancel_untilruns. A clicked village lists the groups leaving it and coming to it (MapMarchList, in its popup and the field box). A group leaves the map when it arrives, and the map reloads then and whenever the village bar learns of a change, so its way home shows up. The overview has an own-commands box (out and home) with the call-back button. The village row starts with the quest book (QuestBook, a native<dialog>without a veil): it opens by itself whenquests.claimablegoes up, and a goal's "show me" opens its screen, a building goal the headquarters with?hint=<type>marking that row. - All user-facing text goes through i18n keys, with
enas the first locale. Sources arei18n/locales/andi18n/pages/(@blax-software/i18nlayout); register a new page file ini18n/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.
pnpm typecheckandpnpm i18n:checkpass, and the change works in the preview.- Commit (small, one concern each) and push to
origin master. - Run
scripts/deploy-edgerealm.sh. Done when it printsLive: https://village.blax.at at <commit>. - 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:.