{"id":50777079,"url":"https://github.com/jbcom/declarative-hex-worlds","last_synced_at":"2026-06-12T00:30:41.994Z","repository":{"id":359840197,"uuid":"1247704779","full_name":"jbcom/declarative-hex-worlds","owner":"jbcom","description":"TypeScript gameboard runtime for KayKit Medieval Hexagon assets","archived":false,"fork":false,"pushed_at":"2026-06-06T11:56:55.000Z","size":35406,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-06T13:21:50.609Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://jonbogaty.com/declarative-hex-worlds/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jbcom.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE.md","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-23T17:06:20.000Z","updated_at":"2026-06-06T11:56:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jbcom/declarative-hex-worlds","commit_stats":null,"previous_names":["jbcom/medieval-hexagon-gameboard","jbcom/declarative-hex-worlds"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/jbcom/declarative-hex-worlds","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbcom%2Fdeclarative-hex-worlds","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbcom%2Fdeclarative-hex-worlds/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbcom%2Fdeclarative-hex-worlds/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbcom%2Fdeclarative-hex-worlds/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jbcom","download_url":"https://codeload.github.com/jbcom/declarative-hex-worlds/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbcom%2Fdeclarative-hex-worlds/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34224103,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-12T00:30:37.125Z","updated_at":"2026-06-12T00:30:41.936Z","avatar_url":"https://github.com/jbcom.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"https://raw.githubusercontent.com/jbcom/declarative-hex-worlds/main/docs-site/public/hero.png\" alt=\"Declarative Hex Worlds\" width=\"540\"\u003e\n\n# declarative-hex-worlds\n\n**Declarative, deterministic hex worlds for TypeScript games.**\nBootstrap KayKit assets in one command. First-class React + Three.js bindings.\n\n[![CI](https://github.com/jbcom/declarative-hex-worlds/actions/workflows/ci.yml/badge.svg)](https://github.com/jbcom/declarative-hex-worlds/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/declarative-hex-worlds.svg)](https://www.npmjs.com/package/declarative-hex-worlds)\n[![license](https://img.shields.io/npm/l/declarative-hex-worlds.svg)](./LICENSE)\n[![types](https://img.shields.io/npm/types/declarative-hex-worlds.svg)](https://jonbogaty.com/declarative-hex-worlds/reference/index/)\n\n\u003c/div\u003e\n\nA 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.\n\n[**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/)\n\n---\n\n## Quickstart\n\n```bash\npnpm add declarative-hex-worlds\npnpm exec declarative-hex-worlds bootstrap\n```\n\n```tsx\nimport { useEffect } from 'react';\nimport { Canvas } from '@react-three/fiber';\nimport * as HexWorld from 'declarative-hex-worlds';\n\nconst plan = HexWorld.createGameboardBuilder({\n  seed: 'harbor-village-1',\n  shape: { kind: 'rectangle', width: 6, height: 6 },\n}).build();\n\nconst runtime = HexWorld.createGameboardRuntimeFromScenario({\n  plan,\n  scenario: { actors: [], quests: [] },\n});\n\nexport function HarborBoard() {\n  return (\n    \u003cHexWorld.GameboardProvider runtime={runtime}\u003e\n      \u003cCanvas\u003e\u003cScene /\u003e\u003c/Canvas\u003e\n    \u003c/HexWorld.GameboardProvider\u003e\n  );\n}\n\nfunction Scene() {\n  const rt = HexWorld.useGameboardRuntime();\n  useEffect(() =\u003e { rt.tick(1 / 60); }, [rt]);\n  return null; // your three.js render of rt.snapshot() goes here\n}\n```\n\nThat'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.\n\n\u003e [`@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.\n\n---\n\n## Why this exists\n\n- **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.\n- **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.\n- **First-class React + Three.js bindings.** Not optional peer-deps. The library tests against the versions it ships; install one package and start rendering.\n\n---\n\n## Module map\n\nThe umbrella (`declarative-hex-worlds`) re-exports everything. For tighter tree-shaking and clearer intent, import from subpaths:\n\n| Subpath | What it gives you |\n|---|---|\n| `declarative-hex-worlds` (umbrella) | Everything. Prototyping. |\n| `/gameboard` | Plan builder, tile + placement spec types |\n| `/coordinates` | Hex algebra, axial / world transforms |\n| `/scenario`, `/blueprint`, `/recipe` | Scenario → blueprint → recipe compiler |\n| `/koota` | ECS world + actor / placement spawn helpers |\n| `/runtime` | Runtime facade + snapshot |\n| `/react` | React provider + hooks |\n| `/three` | three.js loaders + scene helpers |\n| `/bootstrap` | Programmatic asset bootstrap (CLI alternative) |\n| `/errors` | `GameboardError` + subclasses for `instanceof` catching |\n| `/manifest/free`, `/manifest/schema` | The FREE manifest metadata + schema |\n\n[Full subpath list with API reference →](https://jonbogaty.com/declarative-hex-worlds/reference/index/)\n\n---\n\n## Docs\n\n| Get started | Features | Reference |\n|---|---|---|\n| [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/) |\n| [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/) |\n| [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/) |\n| [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/) |\n\n---\n\n## CLI\n\nThe library ships a Node binary. Common commands:\n\n```bash\ndeclarative-hex-worlds bootstrap       # download FREE pack assets (run once)\ndeclarative-hex-worlds doctor          # check local setup\ndeclarative-hex-worlds validate-scenario --scenario ./my-scenario.json\ndeclarative-hex-worlds coverage --json # release-readiness ledger\n```\n\n[Full CLI reference →](https://jonbogaty.com/declarative-hex-worlds/guides/cli-reference/)\n\n---\n\n## What ships\n\n- 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.\n- 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.\n- 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 \u003cyour-extra.zip\u003e` but never bundles it.\n\n---\n\n## Contributing\n\n`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.\n\nConventional Commits required. PRs are squash-merged. Coverage gate enforces 100 / 100 / 100 / 100; regressions block merge.\n\n---\n\n## License\n\n[MIT](./LICENSE) for the library code.\n\nKayKit 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).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjbcom%2Fdeclarative-hex-worlds","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjbcom%2Fdeclarative-hex-worlds","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjbcom%2Fdeclarative-hex-worlds/lists"}