declarative-hex-worlds

What you ship

Declarative API

Describe what you want — a harbor with three depth tiers, a procedural forest, a road network connecting both. The library handles tile selection, connectivity, prop scatter, and validation. No imperative grid bookkeeping.

Deterministic by construction

Same seed, same output — byte-identical, across processes and platforms. Server-authoritative simulation, save-game replays, and cross-machine reproducibility all work out of the box.

First-class React + Three.js

Not optional peer-deps. The library tests against the versions it ships and exposes idiomatic hooks and scene helpers. Install one package and start rendering.

Bootstrap in three steps

1. Install the package

   pnpm add declarative-hex-worlds

2. Fetch the FREE KayKit asset pack (CC0-licensed; ~30 MB)

   pnpm exec declarative-hex-worlds bootstrap

   Downloads 221 GLTF models into public/assets/models/addons/kaykit_medieval_hexagon_pack/. SHA-256 sidecar verified.

3. Render your first harbor

   import { Canvas } from '@react-three/fiber';
   import * as HexWorld from 'declarative-hex-worlds';
   
   const plan = HexWorld.createGameboardBuilder({
     seed: 'harbor-village-1',
     shape: { kind: 'rectangle', width: 6, height: 6 },
   }).build();
   
   const runtime = HexWorld.createGameboardRuntimeFromScenario({
     plan,
     scenario: { actors: [], quests: [] },
   });
   
   export function Harbor() {
     return (
       <HexWorld.GameboardProvider runtime={runtime}>
         <Canvas>{/* your three.js scene of rt.snapshot() */}</Canvas>
       </HexWorld.GameboardProvider>
     );
   }

Explore the library

Pieces & actors Declare buildings, units, decorations. The library spawns + binds them to ECS entities.

Multi-depth stacks Stacked terrain (water → land → cliff → peak) with validated transitions.

Harbors Sandy crescents, piers, fishing villages — composable harbor recipes.

Bridges & connectors Spans, ferries, roads — connectivity validation across biome edges.

Quests Patrol routes, spawn groups, scripted scenarios. Deterministic replay.

Determinism & replay The full seed → blueprint → scenario → simulation chain, byte-for-byte.

Tile injection Drop bespoke tiles into procedural maps without breaking constraints.

Prop injection Authored set-pieces (a watchtower, a graveyard) layered onto generated terrain.

Cross-kit composition Mix the FREE pack with EXTRA-pack tiles or third-party GLTFs.

Movement & patrols Actor movement, patrol routes, navigation predicates.

Why this exists

Hex-grid games are simple in concept and a maintenance nightmare in code. Tile adjacency rules, biome blending, asset selection, deterministic seeding, multiplayer-safe replay — each is a small problem; all of them together is a six-month detour from shipping a game.

declarative-hex-worlds treats the whole stack as one declarative pipeline: recipe → blueprint → scenario → koota ECS world → React + Three.js render. You declare what you want and what’s allowed; the library decides what goes where, validates it, and gives you back a deterministic snapshot.

The hex-tile assets are the KayKit Medieval Hexagon Pack by Kay Lousberg — gorgeous, low-poly, CC0. The library bootstraps them at install time; the npm tarball stays small (~2.3 MB) and asset licensing stays clean.

Architecture How recipe / blueprint / scenario / runtime fit together.

Design rationale Why determinism is the product, and why react+three are runtime deps.

API reference Every public symbol across the 21 subpath exports.

CLI reference 36 commands — bootstrap, validate, simulate, coverage, and more.