Skip to content

Client and SVG Pipeline

Client Direction

The client is built with SvelteKit, deployed via @sveltejs/adapter-cloudflare to Cloudflare Pages. Svelte compiles to plain DOM manipulation with no runtime — this keeps the bundle small, cold loads fast from the edge, and battery use low on mobile.

The game is UI-driven and reactive, not real-time rendered. The client responds to server state changes (settlement tick results, board updates, event triggers) rather than running a continuous render loop. SVG handles all map, character preview, and overlay graphics natively within Svelte components.

Phaser is not used. If a future feature requires sprite-based animation (e.g., a district view), PixiJS can be loaded as an isolated component on demand — it does not need to be the application shell.

See browser-first-constraints.md for the rules that keep the design grounded in browser-friendly interaction and rendering limits.

  • Boot
  • Login
  • Character Creation
  • Town
  • World Map
  • Mission Planning
  • Expedition Status
  • Market
  • Guild Hall
  • Codex

Character Creation Route Rule

Character Creation should be guided, short, and preview-driven.

Recommended panels:

  • name and appearance
  • lineage summary
  • village-origin and starter village preview
  • archetype and starter loadout preview
  • background and starter utility preview
  • final review card

Final review should show start district in the main hub city, starter contacts, Familiar skills granted at creation, starter loadout suggestion, and first-board bias in one screen.

See ../world/character-origins.md for full creation model.

Creation Preview Layer Stack

Character Creation preview should use fixed SVG layer stack so appearance customization and starter-loadout preview stay cheap and readable.

Recommended order:

  1. body base and silhouette
  2. skin tone and face base
  3. hair, facial hair, and human-like family variants
  4. lineage marker details and small cultural or district accents
  5. base clothing layer
  6. starter archetype silhouette overlay
  7. held weapon or tool preview
  8. village-origin banner, village prop, or backdrop marker

Rules:

  • do not render full inventory paper-doll system in creation route
  • use starter-loadout silhouette preview, not final gear-stat paper sheet
  • keep lineage identity visible even under archetype preview layers
  • use village-themed backdrop cues so village-origin selection feels different immediately
  • all preview combinations should come from reusable SVG parts, not separate full-character illustrations

World Map Rule

The world map and local survey views should use tile-based rendering with fog-of-war overlays rather than one fully revealed static image.

The full hex grid (160×120 = 19,200 tiles) must never be fully mounted in the DOM. A browser SVG layer saturates around 3,000 simultaneous DOM elements. Use 2D viewport culling: store all tile data as plain JS, derive the visible tile set from current pan offset and viewport size, and mount only those tiles into the SVG.

Data vs. Render Split

  • All tile data lives in a flat JS array (or Map keyed by q,r) with precomputed pixel coordinates. Never in the DOM.
  • Visible tile set is a $derived value that filters by pan position + viewport rect + buffer zone.
  • SVG DOM only contains the ~300–500 tiles that overlap the visible region.

Viewport Culling Rules

  • Maintain a buffer of at least 2 hex rows/columns beyond every viewport edge to prevent pop-in during pan.
  • Recompute visible set on every pan delta — the filter over 19,200 numeric comparisons costs ~0.1ms and is safe on pointermove.
  • Translate the inner SVG <g> via CSS transform: translate(x, y) on pan rather than moving individual tile coordinates. Only the transform changes each frame.
  • Use Svelte Spring for pan deceleration on drag release.

Layer Order (SVG <g> groups, back to front)

  1. #terrain — hex fill and biome props
  2. #stale-overlay — hatched/muted overlay on stale tiles
  3. #fog — fog-of-war fill, same culled tile set
  4. #sites — site footprint icons and markers
  5. #routes — road and path lines
  6. #annotations — player and guild markers, event warnings
  7. #ui — tooltip targets and selection ring

Chunk Loading

Server tile data is fetched in area chunks (not individual tiles). Fetch a chunk when pan brings its region boundary within 3 hex rows of the viewport edge. Cache fetched chunks in a client-side store keyed by chunk id. Never re-fetch a chunk that is already loaded in the current session unless explicitly stale.

Fog Layer

Fog is a separate <g> layer using the same visible tile set. Fogged tiles render a solid fill at --bg-base with 80% opacity. Tiles in traversed state render at 40% opacity. Tiles in explored or higher render no fog. Animate fog clearing with a fade transition on the fog element removal.

Recommended client rules:

  • keep logical tile data separate from SVG art layers
  • cull: mount only tiles in viewport + 2-hex buffer
  • translate inner <g> for pan, not individual tile coords
  • load tile data in area chunks on viewport approach
  • render fog as its own <g> layer above terrain, below markers
  • show stale tiles with hatched or muted overlay
  • use markers and annotations in topmost <g> layer

See ../systems/exploration/map-tiles-fog-and-cartography.md for the exploration model behind this route.

SVG Art Direction

All graphics should be vector-first. The world should look deliberate and readable rather than overly detailed.

Asset Categories

  • character bodies and layered equipment
  • monsters and boss variants
  • weapons, tools, and supplies
  • map icons and route markers
  • town buildings and biome props
  • heraldry and faction symbols
  • UI frames and codex illustrations

Inspiration Rules

Take inspiration from public-domain and historical sources such as:

  • heraldry
  • medieval bestiaries
  • antique maps
  • illuminated manuscripts
  • botanical studies
  • folklore motifs

Do not trace copyrighted game art. Redraw original assets with simplified shapes and a controlled style language.

Technical Rules for SVG Assets

  • keep shapes clean and reusable
  • prefer limited palettes per region
  • use layerable parts for equipment swaps
  • optimize paths and remove unnecessary detail
  • avoid embedding scripts or unsafe markup

UI Direction

The UI should support quick status review and planning. Important screens must communicate duration, risk, supplies, weather or climate pressure, and expected reward at a glance.

The UI should assume players are often alt-tabbed, returning briefly, or checking the game while another main game is running.