Appearance
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, which follow the latest version.
llms.txtlists every page with a summary,llms-full.txtholds them all in one file, and each page has a Markdown copy (.mdin place of.html). - Each package's
README.mdsays 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 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(...)).Shapedraws a primitive,Modela glTF file, andVisual(object)any three.js object you made. Do not add meshes toengine.sceneyourself: the engine adds, moves and removes the visuals of entities. - Move things by their traits:
Position,Rotation(a quaternion;euler()makes one from angles) andScale. 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 byengine.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,Spawnerand more. - Logic across many entities goes in systems (
engine.addSystem(fn, { phase }); the default phase isupdate, physics steps infixedUpdate). Take time from the system'sdelta, never fromDate.now(), and random numbers fromengine.random, neverMath.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
InputorActions(named actions over keys, mouse, touch and swipes, gamepad, tilt and on-screen buttons, withpressedWithin()/sequence()for buffered presses), and clicks on entities throughClickableand entity events (engine.events), not DOM listeners on the canvas. - With React,
<Pawn>creates the engine and hooks such asuseSystemanduseSpawnreplaceengine.addSystemandengine.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 }).