declarative-hex-worlds

Declarative, deterministic hex worlds for TypeScript games. Bootstrap KayKit assets in one command. First-class React + Three.js bindings.

A deterministic gameboard runtime for TypeScript games. Declare a harbor, a procedural forest, or a multi-depth cliff once; the library compiles it through recipe → blueprint → scenario into a koota ECS world your React + Three.js stack renders.

Read the docs → · Browse features → · API reference →

---

Quickstart

pnpm add declarative-hex-worlds
pnpm exec declarative-hex-worlds bootstrap

import { useEffect } from 'react';
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 HarborBoard() {
  return (
    <HexWorld.GameboardProvider runtime={runtime}>
      <Canvas><Scene /></Canvas>
    </HexWorld.GameboardProvider>
  );
}

function Scene() {
  const rt = HexWorld.useGameboardRuntime();
  useEffect(() => { rt.tick(1 / 60); }, [rt]);
  return null; // your three.js render of rt.snapshot() goes here
}

That's it. The bootstrap command downloads 221 KayKit FREE GLTFs into public/assets/models/addons/kaykit_medieval_hexagon_pack/Assets/gltf/ and writes a SHA-256 sidecar for integrity verification. The plan + runtime are deterministic — same seed, same render, byte-for-byte.

@react-three/fiber is an optional companion (pnpm add @react-three/fiber). It's not a hard dep because some consumers prefer a different react-three layer; the library's own /three subpath gives you the raw helpers if you'd rather skip it.

---

Why this exists

• Declarative API for hex worlds. Describe what you want (a harbor, a forest, a cliff with three depth tiers). The library handles tile selection, connectivity, prop scatter, and validation.
• Deterministic seed-driven generation. Same seed produces byte-identical output across processes and platforms. Server-authoritative simulation, save games, cross-process replay — all work out of the box.
• First-class React + Three.js bindings. Not optional peer-deps. The library tests against the versions it ships; install one package and start rendering.

---

Module map

The umbrella (declarative-hex-worlds) re-exports everything. For tighter tree-shaking and clearer intent, import from subpaths:

Subpath	What it gives you
declarative-hex-worlds (umbrella)	Everything. Prototyping.
/gameboard	Plan builder, tile + placement spec types
/coordinates	Hex algebra, axial / world transforms
/scenario, /blueprint, /recipe	Scenario → blueprint → recipe compiler
/koota	ECS world + actor / placement spawn helpers
/runtime	Runtime facade + snapshot
/react	React provider + hooks
/three	three.js loaders + scene helpers
/bootstrap	Programmatic asset bootstrap (CLI alternative)
/errors	GameboardError + subclasses for instanceof catching
/manifest/free, /manifest/schema	The FREE manifest metadata + schema

Full subpath list with API reference →

---

Docs

Get started	Features	Reference
Quickstart	Feature gallery	API reference
Asset bootstrap	CLI	Errors
Bindings + bundling	Determinism contract	Architecture
Testing	Design rationale	Deployment

---

CLI

The library ships a Node binary. Common commands:

declarative-hex-worlds bootstrap       # download FREE pack assets (run once)
declarative-hex-worlds doctor          # check local setup
declarative-hex-worlds validate-scenario --scenario ./my-scenario.json
declarative-hex-worlds coverage --json # release-readiness ledger

Full CLI reference →

---

What ships

• The npm tarball is small (~2.3 MB; ~134 files). It contains the manifest, the compiled JS + DTS, the README, and a handful of curated showcase PNGs.
• The KayKit FREE GLTF tree (~30 MB; 221 models) is bootstrap-fetched at install time. CC0 license; the bootstrap command also writes a SHA-256 integrity sidecar.
• The EXTRA edition is a paid itch.io purchase. The library supports it via bootstrap --source zip --zip <your-extra.zip> but never bundles it.

---

Contributing

pnpm verify runs every CI gate locally. See CONTRIBUTING.md. The PRD in docs/PRD/1.0.md explains the why.

Conventional Commits required. PRs are squash-merged. Coverage gate enforces 100 / 100 / 100 / 100; regressions block merge.

---

License

MIT for the library code.

KayKit Medieval Hexagon Pack © Kay Lousberg, CC0-1.0. Adventurers / EXTRA pack and other KayKit content have their own licenses; see NOTICE.md.