# @hathor/world

**Facade (shim) — CGI scene-definition contract only.** Worldbuilding logic
lives elsewhere; see the pointer table below.

## At a glance

- **Path:** `libs/hathor/world`
- **Domain:** hathor (active)
- **Owner:** @GreyChimp
- **Docs:** [deep-dive](/docs/domains/hathor/deep-dive) ·
  [systems one-pager](/docs/systems/lib-hathor.md)
- **Nx project:** `@hathor/world`

## Facade role

This library owns exactly one thing: the **CGI scene-definition** contract
engine-facing consumers import, validate, and serialize. It holds no
worldbuilding logic of its own and must not grow any.

## The contract it owns

- `HathorWorldCgiSceneDefinition` — one scene's engine-facing definition
  (region/location context, era and time period, architectural styling).
- `createHathorWorldCgiSceneDefinition` /
  `validateHathorWorldCgiSceneDefinition` /
  `serializeHathorWorldCgiSceneDefinition` — build, check, wire-encode.

Golden-file round-trip contract tests (`src/cgi-packet-contract.spec.ts`) cover
the shape, so consumers get explicit breakage instead of silent drift.

## Logic lives in

| Concern                                       | Where it actually lives               |
| --------------------------------------------- | ------------------------------------- |
| Cultures, values, traditions, cultural phases | `@hathor/domain-models` (`culture`)   |
| Regions, geography, climate                   | `@hathor/domain-models` (`geography`) |
| Locations, architecture, points of interest   | `@hathor/domain-models` (`location`)  |
| Eras, time periods, world dates               | `@hathor/domain-models` (`timeline`)  |
| Culture evolution & drift simulation          | `@hathor/simulation` (`culture`)      |
| World versioning, branches, entity state      | `apps/hathor/world-api`               |

## Adding logic here is a bug

New worldbuilding behavior belongs in the owning library above — this facade
should only grow when the **scene-definition contract** changes. A guard test
(`src/facade-guard.spec.ts`) enforces that the source stays under a line budget
and that imports resolve only to public entry points (`@hathor/domain-models`),
never deep implementation paths. If the guard fails, move the logic to its
owning library rather than raising the budget.

## Commands

```bash
pnpm nx test @hathor/world
pnpm nx lint @hathor/world
```