Skip to content

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.txt lists every page with a summary, 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.
PackageWhat it adds
@pawnjs/coreThe 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/tweenTweens of position, rotation and scale.
@pawnjs/physicsRapier rigid bodies, colliders (meshes and heightfields too), a character controller, collision events. Not on npm yet.
@pawnjs/dataOne entity per item of a live feed. Not on npm yet.
@pawnjs/mapsA scene on a Google map. Not on npm yet.
@pawnjs/json-renderScenes 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(...)). 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 }).