---
url: /pawn/docs/guide/agents.md
description: >-
  Rules for coding agents that build apps with Pawn: where the docs and types
  are, how a scene is made, and how to test it. Every @pawnjs library package
  ships this page as AGENTS.md.
---

# For coding agents

This page is for coding agents (Claude Code, Codex, Cursor...) that write
apps with Pawn. Every `@pawnjs` library package ships it as `AGENTS.md`, so
an agent finds it in `node_modules/@pawnjs/core/AGENTS.md` without
searching; a project made with `bun create @pawnjs` points its own
`AGENTS.md` and `CLAUDE.md` there.

## Where to look

* The types: `node_modules/@pawnjs/<package>/dist/*.d.ts`. Every public
  name has JSDoc. They match the installed version, so when they and the
  docs differ, the types win. Do not guess an API: look it up.
* The docs: [jakubprill.github.io/pawn/docs](https://jakubprill.github.io/pawn/docs/),
  which follow the latest version.
  [`llms.txt`](https://jakubprill.github.io/pawn/docs/llms.txt) lists every
  page with a summary, [`llms-full.txt`](https://jakubprill.github.io/pawn/docs/llms-full.txt)
  holds them all in one file, and each page has a Markdown copy (`.md` in
  place of `.html`).
* Each package's `README.md` says what it is for.

| Package | What it adds |
|---|---|
| `@pawnjs/core` | The engine, entities and traits, shapes, lights, cameras, input, sound, models, behaviors, prefabs, snapshots, test helpers (`@pawnjs/core/testing`). |
| `@pawnjs/react` | `<Pawn>`, `<PawnView>` and hooks; read world state with `koota/react`. |
| `@pawnjs/tween` | Tweens of position, rotation and scale. |
| `@pawnjs/physics` | Rapier rigid bodies, colliders (meshes and heightfields too), a character controller, collision events. Not on npm yet. |
| `@pawnjs/data` | One entity per item of a live feed. Not on npm yet. |
| `@pawnjs/maps` | A scene on a Google map. Not on npm yet. |
| `@pawnjs/json-render` | Scenes generated as JSON from a catalog of prefabs. Not on npm yet. |

## How a Pawn app is built

Pawn is an ECS on [koota](https://github.com/pmndrs/koota) and three.js. An
entity is an id, a trait is data on it, a system is a function the engine
runs each frame. Write the scene in those terms, not as three.js objects.

```ts
import { Engine, Shape, Spin } from "@pawnjs/core";

const canvas = document.querySelector<HTMLCanvasElement>("#scene");
if (!canvas) throw new Error("no canvas");

// The quick start options set up a camera, a background and lights.
const engine = new Engine({
  canvas,
  camera: { position: { y: 1.5, z: 4 } },
  lights: "studio",
});

engine.spawn(Shape({ kind: "box", color: "#6366f1" }), Spin({ speed: 1 }));
engine.start();
```

* **Spawn entities with traits** (`engine.spawn(...)`). `Shape` draws a
  primitive, `Model` a glTF file, and `Visual(object)` any three.js object
  you made. Do not add meshes to `engine.scene` yourself: the engine adds,
  moves and removes the visuals of entities.
* **Move things by their traits**: `Position`, `Rotation` (a quaternion;
  `euler()` makes one from angles) and `Scale`. The engine copies them
  into three.js before drawing. `entity.set(Trait, value)` needs the trait
  on the entity; `put(entity, Trait, value)` adds it when missing.
* **A kind of entity is a prefab** (`definePrefab`): its traits with
  defaults, spawned by `engine.spawn(Prefab)`, with overrides checked
  against its params. **What one entity does is a behavior**
  (`defineBehavior`), and a bundle of behaviors is a preset. Look for a
  built-in first: `Hoverable`, `Clickable`, `Spin`, `SoundOn`, `FlashOn`,
  `Spawner` and more.
* **Logic across many entities goes in systems** (`engine.addSystem(fn,
  { phase })`; the default phase is `update`, physics steps in
  `fixedUpdate`). Take time from the system's `delta`, never from
  `Date.now()`, and random numbers from `engine.random`, never
  `Math.random()`, so a run can be replayed.
* **Plugins are classes**: `engine.plugin(Class)` returns the installed one
  and installs a default one when missing.
* **Input goes through `Input` or `Actions`** (named actions over keys,
  mouse, touch and swipes, gamepad, tilt and on-screen buttons, with
  `pressedWithin()` / `sequence()` for buffered presses), and clicks on entities
  through `Clickable` and entity events (`engine.events`), not DOM
  listeners on the canvas.
* **With React**, `<Pawn>` creates the engine and hooks such as
  `useSystem` and `useSpawn` replace `engine.addSystem` and
  `engine.spawn`.
* **Dispose what you create**: `engine.dispose()` when the scene goes away,
  and on a hot reload.

```ts
import { Engine, Position, type System } from "@pawnjs/core";
import { trait } from "koota";

const engine = new Engine();
const Drift = trait({ x: 0, y: 0, z: 0 });

const move: System = ({ world, delta }) => {
  world.query(Drift, Position).updateEach(([d, p]) => {
    p.x += d.x * delta;
    p.y += d.y * delta;
    p.z += d.z * delta;
  });
};

engine.addSystem(move);
engine.spawn(Position, Drift({ x: 1 }));
```

One koota trap: a query with `Changed(Trait)` does not see values another
system wrote with `updateEach`, unless something subscribes to
`onChange(Trait)`. Write with `entity.set()` when another system must
notice the change.

## Test it headless

An engine without a canvas runs without a page, so scene logic is tested
like any other code. `@pawnjs/core/testing` makes an engine whose time
moves only when the test says so.

```ts
import { Position, Velocity } from "@pawnjs/core";
import { createTestEngine, runFor } from "@pawnjs/core/testing";
import { expect, test } from "bun:test";

test("the ball rises", () => {
  const engine = createTestEngine();
  const ball = engine.spawn(Position, Velocity({ y: 1 }));

  runFor(engine, 2); // two seconds of frames

  expect(ball.get(Position)?.y).toBeCloseTo(2);
  engine.dispose();
});
```

A test sends clicks and other entity events itself:
`engine.events.emit(entity, "click", { button: 0, point: undefined })`.
