Get started - declarative-hex-worlds

declarative-hex-worlds is a deterministic, ECS-driven, React + Three.js library for building hex-grid games on top of the KayKit Medieval Hexagon GLTF pack. This page gets you from pnpm add to rendered hexes in under five minutes.

1. Install + bootstrap

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

The library ships the typed runtime + the FREE manifest metadata; the GLTF binaries themselves are downloaded at install time from the KayKit upstream GitHub repo by the bootstrap subcommand. The default --out heuristic targets public/assets/models/ (Vite / Next.js convention); see Asset bootstrap for the full workflow including the EXTRA edition and reproducible-build options.

After bootstrap, your asset tree looks like:

public/assets/models/addons/kaykit_medieval_hexagon_pack/
├── Assets/gltf/...     # 221 .gltf + .bin files
├── Textures/...
└── .bootstrap.json     # integrity sidecar

2. Point the runtime at your bootstrap target

import { setGameboardAssetRoot } from 'declarative-hex-worlds';

// Call once at app boot:
setGameboardAssetRoot('/public/assets/models');

Or set HEX_WORLDS_ASSET_ROOT in your environment — the runtime falls through override → globalThis → process.env → 'public/assets/models' default.

3. Build a deterministic gameboard

import {
  buildGameboardBlueprint,
  createGameboardWorldFromScenario,
} from 'declarative-hex-worlds';

// One-call: shape + seed → fully populated scenario.
const { scenario } = buildGameboardBlueprint({
  shape: { kind: 'rectangle', width: 12, height: 8 },
  seed: 'tutorial-island',
});

// Spawn into a Koota world with traits, occupancy, navigation graphs, etc.
const runtime = createGameboardWorldFromScenario(scenario);

buildGameboardBlueprint compiles biome fills, mountain ranges, towns, roads, rivers, harbors, and prop clusters into a GameboardScenario that the Koota runtime can spawn deterministically from a seed.

4. Render with the React + Three.js bindings

import { Canvas } from '@react-three/fiber';
import { GameboardScene } from 'declarative-hex-worlds/react';

export function App({ runtime }: { runtime: GameboardRuntime }) {
  return (
    <Canvas camera={{ position: [0, 12, 18], fov: 50 }}>
      <ambientLight intensity={0.4} />
      <directionalLight position={[10, 20, 10]} intensity={1.5} />
      <GameboardScene runtime={runtime} />
    </Canvas>
  );
}

React + Three.js are first-class runtime dependencies (not optional peers), so the bindings work without any extra installs.

5. Next steps

Asset bootstrap — full bootstrap workflow, including EXTRA edition, reproducible builds, and --verify.
KayKit upstream layout — the on-disk shape the bootstrap step mirrors.
CLI reference — every CLI subcommand and flag.
declarative-hex-worlds — typed API reference.