https://github.com/jbcom/declarative-hex-worlds
TypeScript gameboard runtime for KayKit Medieval Hexagon assets
https://github.com/jbcom/declarative-hex-worlds
Last synced: 7 days ago
JSON representation
TypeScript gameboard runtime for KayKit Medieval Hexagon assets
- Host: GitHub
- URL: https://github.com/jbcom/declarative-hex-worlds
- Owner: jbcom
- License: mit
- Created: 2026-05-23T17:06:20.000Z (27 days ago)
- Default Branch: main
- Last Pushed: 2026-06-06T11:56:55.000Z (13 days ago)
- Last Synced: 2026-06-06T13:21:50.609Z (13 days ago)
- Language: TypeScript
- Homepage: http://jonbogaty.com/declarative-hex-worlds/
- Size: 33.8 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Notice: NOTICE.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# declarative-hex-worlds
**Declarative, deterministic hex worlds for TypeScript games.**
Bootstrap KayKit assets in one command. First-class React + Three.js bindings.
[](https://github.com/jbcom/declarative-hex-worlds/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/declarative-hex-worlds)
[](./LICENSE)
[](https://jonbogaty.com/declarative-hex-worlds/reference/index/)
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](https://koota.dev) ECS world your React + Three.js stack renders.
[**Read the docs →**](https://jonbogaty.com/declarative-hex-worlds/) · [**Browse features →**](https://jonbogaty.com/declarative-hex-worlds/features/) · [**API reference →**](https://jonbogaty.com/declarative-hex-worlds/reference/index/)
---
## Quickstart
```bash
pnpm add declarative-hex-worlds
pnpm exec declarative-hex-worlds bootstrap
```
```tsx
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 (
);
}
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`](https://github.com/pmndrs/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 →](https://jonbogaty.com/declarative-hex-worlds/reference/index/)
---
## Docs
| Get started | Features | Reference |
|---|---|---|
| [Quickstart](https://jonbogaty.com/declarative-hex-worlds/guides/getting-started/) | [Feature gallery](https://jonbogaty.com/declarative-hex-worlds/features/) | [API reference](https://jonbogaty.com/declarative-hex-worlds/reference/index/) |
| [Asset bootstrap](https://jonbogaty.com/declarative-hex-worlds/guides/asset-bootstrap/) | [CLI](https://jonbogaty.com/declarative-hex-worlds/guides/cli-reference/) | [Errors](https://jonbogaty.com/declarative-hex-worlds/guides/errors/) |
| [Bindings + bundling](https://jonbogaty.com/declarative-hex-worlds/guides/bindings/) | [Determinism contract](https://jonbogaty.com/declarative-hex-worlds/guides/determinism/) | [Architecture](https://jonbogaty.com/declarative-hex-worlds/about/architecture/) |
| [Testing](https://jonbogaty.com/declarative-hex-worlds/guides/testing/) | [Design rationale](https://jonbogaty.com/declarative-hex-worlds/about/design/) | [Deployment](https://jonbogaty.com/declarative-hex-worlds/about/deployment/) |
---
## CLI
The library ships a Node binary. Common commands:
```bash
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 →](https://jonbogaty.com/declarative-hex-worlds/guides/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](https://kaykit.itch.io/medieval-hexagon-pack) purchase. The library supports it via `bootstrap --source zip --zip ` but never bundles it.
---
## Contributing
`pnpm verify` runs every CI gate locally. See [CONTRIBUTING.md](https://github.com/jbcom/declarative-hex-worlds/blob/main/CONTRIBUTING.md). The PRD in [`docs/PRD/1.0.md`](https://github.com/jbcom/declarative-hex-worlds/blob/main/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](./LICENSE) for the library code.
KayKit Medieval Hexagon Pack © [Kay Lousberg](https://kaylousberg.com/), [CC0-1.0](https://creativecommons.org/publicdomain/zero/1.0/). Adventurers / EXTRA pack and other KayKit content have their own licenses; see [`NOTICE.md`](./NOTICE.md).