@zylem/behaviors 0.4.0 → 0.5.1

package/README.md

@@ -1,6 +1,18 @@
 # Zylem Behaviors
 
-Tree-shakable Zylem behavior descriptors, systems, coordinators, and shared behavior helpers.
+The simulation layer of the Zylem framework: tree-shakable behavior descriptors, FSMs, coordinators, and the `Simulation` API that owns the `@zylem/runtime` WASM module (ECS + Rapier physics).
+
+`@zylem/behaviors` sits between the game framework and the runtime:
+
+```
+@zylem/game-lib  →  @zylem/behaviors  →  @zylem/runtime (WASM)
+```
+
+- **`createSimulation()` / `Simulation`** — loads and owns the WASM stage, exposes `spawn`/`despawn` with opaque `EntityHandle`s, a fixed-timestep `update(delta)` loop, snapshot/pose accessors, raycasts, debug rendering, and translated `SimulationEvent`s (collision start/stop with handles instead of raw slots).
+- **Behavior descriptors** (`Platformer3DBehavior`, `TopDownMovementBehavior`, …) — attach WASM-side controllers to entities and forward per-frame input through batched buffers; FSM state is read back from snapshots.
+- **`MockBehaviorRuntime`** — in-memory `BehaviorRuntime` implementation for unit-testing behaviors without loading WASM.
+
+Physics simulation is WASM-only; there is no TypeScript physics fallback. Disposal chains downward: `Simulation.dispose()` destroys the WASM stage.
 
 Use per-behavior entrypoints when you want bundlers to pull only the behavior family you import: