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@alpha

pnpm

pnpm add three-flatland@alpha

yarn

yarn add three-flatland@alpha three koota

bun

bun add three-flatland@alpha

AI

Paste this into your AI assistant 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@alpha
Requires: three.js >= 0.183.1, 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@alpha @react-three/fiber@alpha

pnpm

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

yarn

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

bun

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

AI

Paste this into your AI assistant 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@alpha @react-three/fiber@alpha
Requires: React >= 19, R3F >= 10.0.0-alpha.2
Import from: "three-flatland/react"
Canvas import: import { Canvas } 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 Sprite2D as JSX
- A sprite loaded with useLoader(TextureLoader, url)
- Suspense boundary around the sprite component

Requirements

• Three.js: >= 0.183.1 (required for TSL/WebGPU support)
• koota: >= 0.1.0 (ECS for batch rendering)
• React: >= 19.0.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.