Appearance
Getting started
Pawn is a 3D engine for the browser written in TypeScript. It renders with three.js and keeps game state in a koota ECS world:
- an entity is an id,
- a trait is data attached to an entity (
Position,Visual, your own), - a system is a function the engine runs every frame over the world.
Packages
| Package | What it adds |
|---|---|
@pawnjs/core | Engine, frame phases and systems, transform traits, hierarchy, instancing, views, picking, input and actions, camera rig, labels, glTF models, sound, behaviors, presets, prefabs and Spawner, snapshots, Grid and SpatialIndex, seeded random, Debug, test helpers, plugin API |
@pawnjs/react | <Pawn>, <PawnView>, <EntityLabel>, useEngine, useSystem, useSpawn, useEntityEvent, useAssetProgress |
@pawnjs/tween | Tweens of Position, Rotation and Scale, the TweenOn behavior |
@pawnjs/data | Feeds that keep one entity per item of an API or WebSocket stream, smooth movement |
@pawnjs/physics | Rapier rigid bodies and colliders as traits |
@pawnjs/maps | The engine drawn into a Google Maps vector map |
@pawnjs/json-render | Scenes from a JSON spec of registered prefabs, streamed by an AI model |
@pawnjs/create | bun create @pawnjs: a new project from a template; add: a prefab from the item registry |
koota is a peer dependency of every package, and three of every package except @pawnjs/data.
Create a project
bun create @pawnjs makes a new project from a template: Vite and TypeScript, a small solar system (planets on orbits to hover, click and follow) with a test of it, and the koota patch described under Install.
bash
bun create @pawnjs my-scene # TypeScript and Vite
bun create @pawnjs my-scene --template react # with @pawnjs/react
cd my-scene
bun install
bun run devWithout a directory or template it asks for them. The project depends on exactly the @pawnjs versions released with the command, and bun run test runs its scene headless. bun create pawn does the same.
From code, createProject({ directory, template, name }) from @pawnjs/create does the same without asking and resolves to the project's directory, name, template and @pawnjs version. The directory must be missing or empty. TEMPLATES lists the template names (DEFAULT_TEMPLATE is "vanilla"), parseTemplate(text) checks one, and packageName(text) turns a directory name into a valid package name (DEFAULT_NAME when nothing is left).
Add a prefab from the registry
Pawn.'s item registries hold prefabs to copy into a project, with the modules they import, one beside each example that has one. The racer's holds ship, sky, tower and stadium. Add one in the project's directory, named <registry>/<item>:
bash
bunx @pawnjs/create add racer/shipIts files go under src/pawn/ (src/pawn/racer/ship.ts and what it imports), as your own code to change. Import Ship from ./pawn/racer/ship and spawn it with engine.spawn(Ship).
Everything is checked before a file is written. A file already there with other content stops the add unless you pass --overwrite; one with the same content, such as a module two items share, stays as it is. When the item imports a package the project lacks, the command prints the bun add to run.
shadcn's CLI adds the same items, also to a project without a components.json: npx shadcn@latest add https://jakubprill.github.io/pawn/racer/r/ship.json.
An item can also be a URL or a path to its JSON, or a name alone with --registry naming the registry (a URL or a directory) to look it up in. PAWN_REGISTRIES lists Pawn.'s registries by name. Items are JSON in shadcn's registry item format (name, dependencies, and files with each one's path, target and content). From code, addItem({ item, directory, registry, overwrite }) from @pawnjs/create does the same and parseRegistryItem(json) checks an item's JSON. To serve your own prefabs, buildRegistry(entries, out, { src, folder }) builds items from their entry modules ({ name, title, description, roots }), following their local imports, and writes them with registry.json. Their files go in src/pawn/, or in folder inside it (the racer's use racer).
Install
Until 0.1.0 every version is a prerelease (0.1.0-alpha.N). Add the package with its peers:
bash
bun add @pawnjs/core koota@0.6.6 three
bun add -d @types/three@types/three is for TypeScript; Versions and stability says why, and what each version promises.
@pawnjs/react, @pawnjs/tween and the starter (@pawnjs/create, create-pawn) are on npm too. Data, physics, maps and json-render are not published yet.
Patch koota for big scenes
koota 0.6.6 takes time quadratic in the entities destroyed between two queries (20k destroys make a 1.4 s frame). The repository fixes it with patches/koota@0.6.6.patch, which only applies inside the monorepo. In your app, copy the file to patches/ and list it in package.json:
json
{ "patchedDependencies": { "koota@0.6.6": "patches/koota@0.6.6.patch" } }That is Bun's format; other package managers need the change in their own. Small scenes run fine without it.
To work on the engine itself, clone the repository:
bash
bun install
bun run build # builds every package
bun run test
bunx turbo run dev --filter=pawn-showcaseYour first scene
A canvas, a camera, lights, and a cube that spins:
ts
import { Engine, Shape, Spin } from "@pawnjs/core";
export default function firstScene(canvas: HTMLCanvasElement): Engine {
canvas.style.cssText = "display:block;width:100%;height:100%";
const engine = new Engine({
canvas,
camera: { position: { y: 2, z: 5 } },
background: "#09090b",
lights: "studio",
});
engine.spawn(Shape({ kind: "box", color: "#6366f1" }), Spin({ speed: 1.5 }));
engine.start();
return engine;
}Call it with a canvas that has a CSS size, for example firstScene(document.querySelector("canvas")!). The scene above runs this very file.
What happens here:
new Engine({ canvas })creates aWebGLRendererfor the canvas and a new koota world (engine.world). Without a canvas the engine runs headless.cameraadds a view that draws a perspective camera into the whole canvas, looking at the origin. Without it nothing is drawn until you add a view yourself (see Views).backgroundis the color the canvas is cleared to, andlights: "studio"spawns a soft hemisphere light and a sun asLightentities.- The drawing buffer follows the canvas's CSS size, also when the canvas resizes. The canvas needs a CSS size, as above, or it would grow with its own drawing buffer.
engine.spawn(...)spawns an entity into the world.Shapegives it a mesh described by data, andSpinis a behavior that turns it.engine.start()ticks the engine on everyrequestAnimationFrame.
Your own traits and systems take over where the built-in ones end: see Entities and systems.
When you are done, engine.dispose() stops the loop and releases what the engine created. Geometries and materials of your own Visuals stay yours; disposeObject3D(root) frees them.
Next
- Engine and frame: phases, the clock and loop drivers.
- Entities and systems: traits, queries and the transform traits.
- Headless: the same scene in tests and scripts, without a page.
- @pawnjs/react: the same scene as React components.
Docs for AI agents
These docs are also published as plain Markdown for coding agents and LLM tools: llms.txt lists every page with a one-line summary, and llms-full.txt holds all pages in one file. Every page has a Markdown copy at the same path with .md in place of .html, and the Copy page button under each page title copies it or opens it in ChatGPT or Claude.
Every @pawnjs library package also ships For coding agents as AGENTS.md, and a project made with bun create @pawnjs has an AGENTS.md and a CLAUDE.md that point agents to it.