Skip to content

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 ​

PackageWhat it adds
@pawnjs/coreEngine, 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/tweenTweens of Position, Rotation and Scale, the TweenOn behavior
@pawnjs/dataFeeds that keep one entity per item of an API or WebSocket stream, smooth movement
@pawnjs/physicsRapier rigid bodies and colliders as traits
@pawnjs/mapsThe engine drawn into a Google Maps vector map
@pawnjs/json-renderScenes from a JSON spec of registered prefabs, streamed by an AI model
@pawnjs/createbun 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 dev

Without 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/ship

Its 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-showcase

Your 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 a WebGLRenderer for the canvas and a new koota world (engine.world). Without a canvas the engine runs headless.
  • camera adds 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).
  • background is the color the canvas is cleared to, and lights: "studio" spawns a soft hemisphere light and a sun as Light entities.
  • 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. Shape gives it a mesh described by data, and Spin is a behavior that turns it.
  • engine.start() ticks the engine on every requestAnimationFrame.

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 ​

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.