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 koota

pnpm

pnpm add three-flatland three koota

yarn

yarn add three-flatland three koota

bun

bun add three-flatland three koota

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://thejustinwalsh.com/three-flatland/llms-full.txt

Install: npm install three-flatland three koota
Requires: three.js >= 0.183.1, koota, 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@alpha

pnpm

pnpm add three-flatland @react-three/fiber@alpha

yarn

yarn add three-flatland @react-three/fiber@alpha three koota react react-dom

bun

bun add three-flatland @react-three/fiber@alpha

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://thejustinwalsh.com/three-flatland/llms-full.txt

Install: npm install three-flatland @react-three/fiber@alpha
Requires: React >= 19, R3F >= 10.0.0-alpha.2
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.183.1 (required for TSL/WebGPU support)
• koota: >= 0.6.5 (ECS for batch rendering)
• React: >= 19.2.0 (for three-flatland/react)
• @react-three/fiber: >= 10.0.0-alpha.2 (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.