Skip to main content

Wargrid Domain Foundation

This page explains the new Wargrid foundation that now exists in code.

Why the foundation moved first​

The repository changed from a prototype workspace into a Bun and Turborepo platform. The first implementation goal is not feature parity at any cost. The first goal is a stable system that AI and humans can change safely.

This foundation now lives in shared packages.

  • @wargrid/contracts defines shared Valibot schemas for content, queues, reports, ranks, and telemetry.
  • @wargrid/game-content holds the launch catalog for towers, traps, cards, enemies, skins, and starter decks.
  • @wargrid/game-rules defines queue presets, season defaults, rank tiers, and status effects.
  • @wargrid/game-sim defines deterministic short and long map layouts, lane routing, overlap analysis, and placement validation.
  • @wargrid/db defines the first Drizzle schema for player auth, admin auth, decks, matches, reports, telemetry, and multiplayer nodes.
  • @wargrid/auth defines Better Auth factories for player and admin surfaces.
  • @wargrid/design-system now exposes reusable Svelte UI components plus shared tokens for play, admin, and Storybook.
  • @wargrid/mail defines MJML templates and queue defaults.
  • @wargrid/testing-tools defines the bridge to the legacy CDP and asset validation flow.

Gameplay domain now encoded in data​

The launch catalog is now data-driven. That is the critical shift away from hardcoded prototype logic.

The current catalog contains:

  • 18 tower families
  • 8 traps
  • 12 active cards
  • 20 enemy archetypes
  • 6 curated starter decks
  • one default glitter skin for every launch content item

The purpose is not only content volume. The purpose is extension safety.

Each content item now carries:

  • localized labels and descriptions
  • element and role metadata
  • build or gold costs
  • a reusable stat block
  • tags for future search, deck filters, and studio tooling

Map and path direction​

The path layer now has two deterministic modes.

Short maps​

Short maps use one fixed elbow path. This keeps ranked validation simple and reproducible.

Long maps​

Long maps use a seeded layout with three lanes. The implementation already models:

  • three independent lane definitions
  • overlap cells resolved from rasterized lane corridors
  • build zones generated from free grid space instead of hand-placed rectangles
  • route checks for small and large units
  • structure placement validation for tower and trap cells
  • a shared matrix representation for Studio and play previews
  • an anti-stuck fallback push helper

This is not the final game simulation. It is the first stable contract for path and grid work.

The important architectural change is the shared analysis layer.

  • The API now exposes both the map layout and a computed analysis summary.
  • The Studio reads the same analysis to visualize build cells, path cells, and lane lengths.
  • The play preview also renders the lane corridor from @wargrid/game-sim.

That removes one of the biggest prototype risks. The board no longer means something different in each app.

Auth and operations split​

The repo now treats player auth and admin auth as different systems.

  • Player auth uses a Better Auth factory under /api/auth/player.
  • Admin auth uses a separate Better Auth factory under /api/auth/admin.
  • The Drizzle schema contains separate player and admin auth tables.
  • Moderation, telemetry, and multiplayer node records are first-class database entities.
  • The API now also exposes session-aware bootstrap routes for play and admin shells so the frontend starts from typed shared payloads instead of local mock state.
  • Deck import/default selection, social actions, and lobby creation now run through dedicated typed player routes instead of bootstrap-only fixture reads.
  • The mutable player meta state lives in apps/api/src/player-state.ts, which keeps the HTTP layer thin and directly testable.

This split matters because the admin surface must remain invite-only and auditable.

Testing strategy​

The old automation stack still matters. It remains the fastest path for AI-driven UI validation.

The new testing package now documents the standard bridge:

  • run a reusable CDP procedure
  • run the Pixi asset preview flow
  • inspect screenshots and summary files
  • fix regressions before merge

That bridge stays in place until the new testing package fully absorbs the old tooling.

UI system and Storybook​

The new UI layer is no longer only token-based.

  • AppShell, SurfaceCard, MetricCard, and WargridButton now live in @wargrid/design-system
  • apps/play hosts the Storybook build for those shared components
  • shared component stories are part of the validation path, not optional demo material