Package Exports
- three-flatland
- three-flatland/animation
- three-flatland/animation/AnimationController
- three-flatland/animation/index
- three-flatland/animation/types
- three-flatland/animation/utils
- three-flatland/loaders
- three-flatland/loaders/SpriteSheetLoader
- three-flatland/loaders/TextureLoader
- three-flatland/loaders/index
- three-flatland/loaders/texturePresets
- three-flatland/materials
- three-flatland/materials/EffectMaterial
- three-flatland/materials/MaterialEffect
- three-flatland/materials/Sprite2DMaterial
- three-flatland/materials/index
- three-flatland/pipeline
- three-flatland/pipeline/LayerManager
- three-flatland/pipeline/PassEffect
- three-flatland/pipeline/SpriteBatch
- three-flatland/pipeline/SpriteGroup
- three-flatland/pipeline/index
- three-flatland/pipeline/layers
- three-flatland/pipeline/types
- three-flatland/react
- three-flatland/react/animation/index
- three-flatland/react/attach
- three-flatland/react/index
- three-flatland/react/loaders/index
- three-flatland/react/materials/index
- three-flatland/react/pipeline/index
- three-flatland/react/sprites/index
- three-flatland/react/tilemap/index
- three-flatland/react/types
- three-flatland/sprites
- three-flatland/sprites/AnimatedSprite2D
- three-flatland/sprites/Sprite2D
- three-flatland/sprites/index
- three-flatland/sprites/types
- three-flatland/tilemap
- three-flatland/tilemap/LDtkLoader
- three-flatland/tilemap/TileLayer
- three-flatland/tilemap/TileMap2D
- three-flatland/tilemap/TiledLoader
- three-flatland/tilemap/Tileset
- three-flatland/tilemap/index
- three-flatland/tilemap/types
Readme
three-flatland
High-performance 2D sprites, tilemaps, and effects for Three.js — built for WebGPU with composable TSL shaders.
Alpha Release — three-flatland is in active development. The API will evolve and breaking changes are expected between releases. Pin your version and check the changelog before upgrading.
Why three-flatland?
Three.js is a 3D engine. Building 2D games on top of it means fighting the renderer — no batching, no sprite sheets, no layer ordering, no pixel-perfect rendering. three-flatland fixes all of that.
- 10,000+ sprites at 60fps — automatic GPU batching, one draw call
- WebGPU native — TSL shaders, not GLSL strings. Effects that weren't possible before
- Proper 2D pipeline — layers, z-ordering, anchor points, pixel-art texture presets
- Composable effects — tint, outline, dissolve, palette swap, CRT, bloom — mix and match
- Animation system — spritesheet-driven with frame-perfect timing
- Tilemap support — Tiled and LDtk editor formats with animated tiles
- React Three Fiber — first-class R3F integration via
three-flatland/react - Tree-shakeable — import only what you use, deep imports for maximum control
Install
npm install three-flatland@alphaFor React Three Fiber:
npm install three-flatland@alpha @react-three/fiber@alphaRequirements
- three >= 0.183.1 (WebGPU/TSL support)
- koota >= 0.1.0 (ECS for batch rendering)
- React >= 19 and @react-three/fiber >= 10.0.0-alpha.2 (optional, for R3F)
Quick Start
Three.js
import { WebGPURenderer } from 'three/webgpu'
import { Scene, OrthographicCamera } from 'three'
import { Sprite2D, SpriteGroup, TextureLoader } from 'three-flatland'
const scene = new Scene()
const camera = new OrthographicCamera(-400, 400, 300, -300, 0.1, 1000)
camera.position.z = 100
const renderer = new WebGPURenderer()
renderer.setSize(800, 600)
document.body.appendChild(renderer.domElement)
await renderer.init()
// Load texture with pixel-art defaults
const texture = await TextureLoader.load('/sprite.png')
// Create a sprite group for automatic batching
const group = new SpriteGroup()
scene.add(group)
// Create sprites
const sprite = new Sprite2D({ texture, anchor: [0.5, 0.5] })
group.add(sprite)
function animate() {
requestAnimationFrame(animate)
renderer.render(scene, camera)
}
animate()React Three Fiber
import { Canvas, extend, useLoader } from '@react-three/fiber/webgpu'
import { Suspense } from 'react'
import { Sprite2D, SpriteGroup, TextureLoader } from 'three-flatland/react'
// attachEffect manages effect add/remove lifecycle on the parent sprite
// EffectElement gives your custom effect JSX props with full type safety
import { attachEffect, type EffectElement } from 'three-flatland/react'
import { createMaterialEffect } from 'three-flatland'
import { tintAdditive } from '@three-flatland/nodes'
import { vec4 } from 'three/tsl'
// Define a reusable shader effect with typed, animatable properties
const DamageFlash = createMaterialEffect({
name: 'damageFlash',
schema: { intensity: 0 } as const,
node: ({ inputColor, attrs }) => {
const flashed = tintAdditive(inputColor, [1, 1, 1], attrs.intensity)
return vec4(flashed.rgb.mul(inputColor.a), inputColor.a)
},
})
// Register three-flatland classes + your effects with R3F
extend({ Sprite2D, SpriteGroup, DamageFlash })
// Declare JSX types for your custom effects
declare module '@react-three/fiber' {
interface ThreeElements {
damageFlash: EffectElement<typeof DamageFlash>
}
}
function Sprite() {
const texture = useLoader(TextureLoader, '/sprite.png')
return (
<spriteGroup>
{/* attachEffect auto-calls addEffect/removeEffect on mount/unmount */}
<sprite2D texture={texture} anchor={[0.5, 0.5]}>
<damageFlash attach={attachEffect} intensity={0.8} />
</sprite2D>
</spriteGroup>
)
}
export default function App() {
return (
<Canvas orthographic camera={{ zoom: 1, position: [0, 0, 100] }}>
<Suspense>
<Sprite />
</Suspense>
</Canvas>
)
}Subpath Exports
Import only what you need:
// Everything
import { Sprite2D, SpriteGroup, AnimatedSprite2D } from 'three-flatland'
// By category
import { Sprite2D } from 'three-flatland/sprites'
import { AnimatedSprite2D } from 'three-flatland/animation'
import { Sprite2DMaterial } from 'three-flatland/materials'
import { SpriteSheetLoader, TextureLoader } from 'three-flatland/loaders'
import { SpriteGroup, SpriteBatch } from 'three-flatland/pipeline'
import { TileMap2D, TiledLoader, LDtkLoader } from 'three-flatland/tilemap'
// React (re-exports core + JSX types + attach helper)
import { Sprite2D, attachEffect, type EffectElement } from 'three-flatland/react'Companion Packages
| Package | Description |
|---|---|
@three-flatland/nodes |
50+ TSL shader nodes — tint, outline, dissolve, blur, CRT, palette swap, and more |
@three-flatland/presets |
Pre-configured effect combinations (coming soon) |
Documentation
Full docs, interactive examples, and API reference at thejustinwalsh.com/three-flatland
License
This README was created with AI assistance. AI can make mistakes — please verify claims and test code examples. Submit corrections here.