---
url: /pawn/docs/guide/getting-started.md
description: What Pawn is, its packages, and a first scene with a spinning cube.
---

# Getting started

Pawn is a 3D engine for the browser written in TypeScript. It renders with
[three.js](https://threejs.org) and keeps game state in a
[koota](https://github.com/pmndrs/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](#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](./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](https://jakubprill.github.io/pawn/racer/) 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](https://ui.shadcn.com/docs/registry/registry-item-json)
(`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](./stability.md)
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.

::: warning 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`](https://github.com/jakubprill/pawn/blob/main/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](./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](./entities).

When you are done, `engine.dispose()` stops the loop and releases what the
engine created. Geometries and materials of your own `Visual`s stay yours;
`disposeObject3D(root)` frees them.

## Next

* [Engine and frame](./engine): phases, the clock and loop drivers.
* [Entities and systems](./entities): traits, queries and the transform traits.
* [Headless](./headless): the same scene in tests and scripts, without a page.
* [@pawnjs/react](../packages/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`](../llms.txt){target="\_self"} lists every page with a
one-line summary, and [`llms-full.txt`](../llms-full.txt){target="\_self"} 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](./agents.md)
as `AGENTS.md`, and a project made with `bun create @pawnjs` has an
`AGENTS.md` and a `CLAUDE.md` that point agents to it.
