Installation

Alpha Release

three-flatland is in alpha. Expect breaking changes between releases. Consider pinning the exact version in your package.json until you’re ready to migrate.

Package Manager

npm

npm install three-flatland three

pnpm

pnpm add three-flatland three

yarn

yarn add three-flatland three

bun

bun add three-flatland three

agents

Paste this into your agent to set up a new project:

Set up a new project with three-flatland, a 2D sprite and effects library
for Three.js using WebGPU and TSL (Three Shader Language).

Read the API reference: https://tjw.dev/three-flatland/llms-full.txt

Install: npm install three-flatland three
Requires: three.js ^0.185.1 and WebGPURenderer from "three/webgpu"
Import from: "three-flatland"

Create a minimal project with a Sprite2D on screen. Include:
- WebGPU renderer setup with await renderer.init()
- Orthographic camera
- A sprite loaded with TextureLoader

React Three Fiber (Optional)

React is not required. If you’re using React Three Fiber, add the additional dependencies:

npm

npm install three-flatland @react-three/fiber@10.0.0-alpha.3 react@~19.2.0 react-dom@~19.2.0

pnpm

pnpm add three-flatland @react-three/fiber@10.0.0-alpha.3 react@~19.2.0 react-dom@~19.2.0

yarn

yarn add three-flatland @react-three/fiber@10.0.0-alpha.3 three react@~19.2.0 react-dom@~19.2.0

bun

bun add three-flatland @react-three/fiber@10.0.0-alpha.3 react@~19.2.0 react-dom@~19.2.0

agents

Paste this into your agent to set up a new R3F project:

Set up a new React Three Fiber project with three-flatland, a 2D sprite
and effects library for Three.js using WebGPU and TSL.

Read the API reference: https://tjw.dev/three-flatland/llms-full.txt

Install: npm install three-flatland @react-three/fiber@10.0.0-alpha.3 react@~19.2.0 react-dom@~19.2.0
Requires: React ~19.2.0, R3F 10.0.0-alpha.3
Import from: "three-flatland/react" (re-exports core + JSX type augmentation)
Canvas import: import { Canvas, extend, useFrame, useThree } from "@react-three/fiber/webgpu"

Create a minimal R3F app with a Sprite2D. Include:
- Canvas with WebGPU (import from @react-three/fiber/webgpu)
- extend() call to register custom elements (Sprite2D, SpriteGroup, etc.)
- A sprite loaded with useLoader(TextureLoader, url)
- Suspense boundary around components that load assets
- useFrame for per-frame animation (refs + imperative updates)
- useState(() => ...) for WASM objects (SkiaPaint, SkiaPath) — survives strict mode

Requirements

• Three.js: ^0.185.1 (required for TSL/WebGPU support)
• React: ~19.2.0 (for three-flatland/react; R3F alpha.3 requires React < 19.3)
• @react-three/fiber: 10.0.0-alpha.3 (for three-flatland/react)
• Node.js: >= 22 (LTS)

TypeScript

three-flatland is written in TypeScript and ships with full type definitions. No additional @types packages are required.

See the LLMs page for more prompts and machine-readable documentation.