How wvaske/hex-crawl-app works
HexCrawl VTT is a self-hosted, real-time tabletop for wilderness exploration. A DM configures maps, terrain, clues, and encounters; players join through a shared link, claim characters, and travel. The server handles campaign commands and state synchronization, computes gated discoveries, and returns role-appropriate campaign state. The client renders the hex map and table panels. The README documents additional exploration and campaign features whose individual runtime wiring is not shown in the sampled source, so those links are left unspecified.
Main entry points: app.ts HTTP API · runtime.ts Campaign runtime · ws.ts WebSocket client · handlers.ts Command handlers
Components 27
Web client
- Web app entry
packages/client/src/main.tsx - Campaign access
packages/client/src/views/CampaignGate.tsx - Table view
packages/client/src/views/TableView.tsx - Hex map canvas
packages/client/src/engine/CanvasEngine.ts - Table panels
packages/client/src/components/panels - Session state
packages/client/src/stores/session.ts - WebSocket client
packages/client/src/ws.ts - HTTP client
packages/client/src/api.ts - Plugin registry
packages/client/src/plugins/registry.ts
Server runtime
- HTTP API
packages/server/src/http/app.ts - Command handlers
packages/server/src/ws/handlers.ts - WebSocket hub
packages/server/src/ws/hub.ts - Campaign runtime
packages/server/src/state/runtime.ts - State store
packages/server/src/state/store.ts - Persistent database
packages/server/src/db/sqlite.ts - Plugin host
packages/server/src/plugins/host.ts
Exploration engines
- Knowledge gates
packages/server/src/engine/knowledge.ts - Discovery delivery
packages/server/src/engine/deliver.ts - Fog of war
packages/server/src/engine/fog.ts - Trail discovery
packages/server/src/engine/trails.ts - Encounters
packages/server/src/engine/encounters.ts - Time and weather
packages/server/src/engine/weather.ts
Shared domain
- Campaign model
packages/shared/src/domain.ts - Known-ground routing
packages/shared/src/rules/route.ts
Integrations
- MCP integration
mcp/hexcrawl-mcp.mjs
Other components
- DM
- Players
Connections 28
- DM → Web app entry: opens table
- Players → Web app entry: opens shared link
- Web app entry → Campaign access: routes campaign
- Campaign access → WebSocket client: connects live
- Campaign access → HTTP client: requests campaign
- HTTP client → HTTP API: HTTP requests
- WebSocket client → WebSocket hub: WebSocket messages
- WebSocket hub → Command handlers: dispatches commands
- Command handlers → Campaign runtime: updates campaign
- HTTP API → State store: reads campaign
- Command handlers → State store: uses state
- State store → Campaign runtime: manages runtime
- State store → Persistent database: persists state
- HTTP API → Knowledge gates: evaluates clues
- HTTP API → Discovery delivery: delivers discoveries
- HTTP API → Campaign runtime: reads campaign
- Command handlers → Campaign runtime: records travel
- Campaign runtime → Campaign model: uses campaign model
- Known-ground routing → Campaign model: uses hex model
- WebSocket client → Session state: applies snapshots
- Table view → Session state: reads session
- Table view → Hex map canvas: renders map
- Table view → Table panels: shows controls
- Hex map canvas → WebSocket client: sends map actions
- Table panels → WebSocket client: sends commands
- MCP integration → HTTP API: calls integration API
- Plugin host → Campaign runtime: extends campaign
- Plugin registry → Table view: registers client plugins