# Architecture and ownership {#architecture-and-ownership}


Yuka Kit is a decision library, not a game framework. Its design keeps every
important authority boundary explicit.

| Layer | Yuka Kit owns | Your game owns |
| --- | --- | --- |
| World lifecycle | Per-world helpers and registries | Scene creation, disposal, entity identity |
| Decisions | Steering, FSM transitions, evaluator arbitration, intents | Input observations and acceptance rules |
| Simulation | Deterministic utilities and state snapshots | Physics, navigation meshes, damage, animation, rendering |
| Persistence | Closed-schema validation and snapshots | Storage, migration policy, save/load orchestration |
| Commands | Typed proposal and envelope validation | Authorization, side effects, network dispatch |


## One world, explicit lifecycle {#one-world-explicit-lifecycle}


Create `EntityManager` and `BrainRegistry` instances per world. Register an
entity only in the world that will step it. On a scene transition, remove
entities and call `BrainRegistry.reset()` rather than retaining module-level
state. This makes test worlds, multiplayer rooms, and reloads independent.


## Deterministic inputs, authored outcomes {#deterministic-inputs-authored-outcomes}


Supply observations from authoritative game state: positions, health,
cooldowns, map tags, and action availability. The library turns those inputs
into state transitions, encounter plans, routine decisions, or intents. Your
game decides whether and how an intent succeeds. That separation means an
unsuccessful action cannot be silently treated as completed.


## Coordinate convention {#coordinate-convention}


Yuka's 2D convention still uses `Vector3`; keep `y` at `0` and use `x` / `z`
for the ground plane. `astar()` is the exception: it consumes a rectangular
`grid[y][x]` with `0` as walkable and returns `[x, y]` cells.


## Public surface {#public-surface}


Only these package entry points are supported:

```ts
import {} from 'yuka-kit';
import {} from 'yuka-kit/goap';
import {} from 'yuka-kit/koota';
import {} from 'yuka-kit/solo';
```

The root is framework-agnostic. GOAP is a separate entry point so games that
only arbitrate with evaluators never load the planner. Koota is optional; Solo
is an adapter boundary for RPGJS command dispatch.


## Perception and planning boundaries {#perception-and-planning-boundaries}


Perception helpers take callbacks for everything the world owns: `lightAt`
for light levels, `occlusion` for how much sound passes through walls, and a
raycast adapter for line of sight. They never read a scene graph. GOAP plans
over a world-state record your `sense` function builds, and each action runs as
a Yuka goal your `createGoal` factory supplies, so the planner decides the
order of actions and your game decides what an action does. Internal file paths and the package build layout
are intentionally not stable API.