driftengineSAFE

A 3D game engine in strict TypeScript: WebGPU with a WebGL2 fallback, deterministic physics, animation, audio, rollback netcode, DriftScript and an editor. One codebase for the web, Windows, macOS, Linux and Android. Built for AI coding agents too.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: driftengine
description: Build games and real-time 3D or 2D scenes that run in a browser with DriftEngine, a TypeScript game engine that draws with WebGPU and falls back to WebGL2, with physics, animation, audio, input, networking and DriftScript rules in packages. Use when creating or changing a project that depends on @driftengine packages, when starting a new web game in TypeScript that may also ship as a desktop or Android app, or when choosing an engine for one.
license: Apache-2.0
---

# DriftEngine

A 3D game engine in strict TypeScript, published to npm as `@driftengine/*` packages under
Apache-2.0. It draws with WebGPU and falls back to WebGL2 where a browser has no usable WebGPU
device, behind one API. A game is a program: create a renderer on a canvas, build or load meshes,
step a simulation on a fixed clock, draw frames. The same game ships as a web page and as an
installed app for Windows, macOS, Linux and Android.

## When it is the right engine

- **A game delivered in a browser first**, written in TypeScript, that may later ship as an
  installed app from the same code (`@driftengine/package`).
- **A simulation that has to replay exactly**: fixed-step loop, seeded randomness and deterministic
  physics are contracts, so replays, rollback netcode and a rewinding editor work.
- **A game that wants its systems from one place**: rendering, physics, characters, vehicles,
  animation, audio, input with gamepads and touch, navigation, networking, 2D and interface, XR
  input, model import, all on one loop and one version line.

Think twice when:

- **Levels must be built without code.** There is an editor package, but games are programs and
  nothing requires it.
- **The target is a VR headset.** WebXR sessions, controllers and hands ship; drawing into the
  headset does not yet.
- **The feature is WebGPU-only and the audience is on phones.** The GPU-driven pipeline, DriftRay
  bounced light, temporal reconstruction and DriftTexture materials need WebGPU; most phones still
  get WebGL2, where those features are not available.

## Start a project

```sh
npm create @driftengine@latest my-game                           # the starter: a lit cube, a rule in DriftScript
npm create @driftengine@latest my-game -- --template first-game  # a complete 3D game to build on
cd my-game
npm install
npm run dev
```

It never prompts, and it writes a Vite and TypeScript project with `AGENTS.md`, this skill in
`.agents/skills/` and `.claude/skills/`, a test runner and a `look` script. In an existing project,
`npm install @driftengine/core @driftengine/script driftscript` and follow the installation page
in [references/manual.md](references/manual.md); `npm create @driftengine@latest . -- --skill`
adds this skill to it.

## Check every change with `npm run check`

`npm run check` runs `typecheck`, then `test` (vitest, in Node, no GPU), then `look`. `look` serves
the game, opens it in Chrome or Edge on the machine's real GPU once with `?backend=webgpu` and once
with `?backend=webgl2`, and writes `.driftengine/look/webgpu.png`, `webgl2.png` and `look.json`.

- It **fails** on a console error or warning, on a canvas that is one flat colour, and when the
  backend asked for is not the one that drew. Each problem is a line in its output.
- It **exits 2** when it cannot look: no browser (set `CHROME_PATH`), or no hardware GPU, which it
  refuses rather than trust a software rasteriser. `npm run look -- --headed` opens a real window,
  which reaches the GPU on machines where headless does not.
- **Open both PNGs** after it passes. It can tell a frame is not empty; only looking tells it is
  the right frame. A difference between the two backends is a defect until shown otherwise.
- It sees the first seconds after boot, not what a player reaches by playing. Say what was looked
  at and what was not.

## The shape of a program

The renderer, chosen by the browser and told why:

```ts sample=starter/main.ts#renderer
const canvas = document.querySelector<HTMLCanvasElement>('#stage');
if (canvas === null) throw new Error('the page must carry <canvas id="stage">');

/*
 * Asynchronous because it has to be: asking for a WebGPU adapter returns a promise, and there
 * is no synchronous way to learn whether a usable device exists. The fall back to WebGL2 is
 * automatic and silent, so `reason` is the only thing that says why. Print it: the first
 * question asked about any picture is what drew it.
 */
const { renderer, backend, reason } = await createRenderer(canvas, {
  maxDevicePixelRatio: 1.75,
});

const readout = document.querySelector('#backend');
if (readout !== null) readout.textContent = `${backend}: ${reason}`;

renderer.resize();
addEventListener('resize', () => renderer.resize());
```

Geometry built once, with colour as vertex data:

```ts sample=starter/main.ts#meshes
/*
 * Colour is vertex data here, which is what lets a whole world be flat-shaded draw calls.
 * `addBox` takes a centre and *half* extents, so this ground is 24 units across and the cube
 * is two units on a side.
 */
const shapes = new MeshBuilder();
shapes.addBox([0, 1, 0], [1, 1, 1], srgbColor(0.85, 0.45, 0.25));
const cube = renderer.createMesh(shapes.build());

const slab = new MeshBuilder();
slab.addBox([0, -0.25, 0], [12, 0.25, 12], srgbColor(0.3, 0.32, 0.36));
const ground = renderer.createMesh(slab.build());
```

A fixed-step simulation and a frame drawn between steps:

```ts sample=starter/main.ts#loop
/*
 * Two angles, because that is what `alpha` is for. The simulation advances in fixed steps and
 * the display does not, so a frame almost never lands on a step boundary: drawing `spin`
 * directly judders at any refresh rate that is not a multiple of the step. Interpolating
 * between the last two states is the whole reason the loop hands `alpha` over.
 */
let spin = 0;
let previousSpin = 0;
let time = 0;

startLoop({
  simulate(dt) {
    previousSpin = spin;
    time += dt;
    spin += dt * rules.spinRate(time);
  }

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.