Quick Start

This guide shows you how to create your first sprite using three-flatland. Two minutes from copy-paste to “there’s a thing on the screen.”

Create a Sprite

Three.js

import { WebGPURenderer } from 'three/webgpu';
import { Scene } from 'three';
import { PixelPerfectCamera, Sprite2D, TextureLoader } from 'three-flatland';

async function main() {
  // Create scene and camera
  const scene = new Scene();
  const camera = new PixelPerfectCamera({ viewSize: 400 });

  // Create WebGPU renderer
  const renderer = new WebGPURenderer({ antialias: false });
  renderer.setPixelRatio(Math.min(devicePixelRatio, 2));
  renderer.setSize(window.innerWidth, window.innerHeight);
  camera.setDrawingBufferSize(renderer.domElement.width, renderer.domElement.height);
  renderer.setViewport(camera.getLogicalViewport(renderer.getPixelRatio()));
  document.body.appendChild(renderer.domElement);
  await renderer.init();

  window.addEventListener('resize', () => {
    renderer.setSize(window.innerWidth, window.innerHeight);
    camera.setDrawingBufferSize(renderer.domElement.width, renderer.domElement.height);
    renderer.setViewport(camera.getLogicalViewport(renderer.getPixelRatio()));
  });

  // Load texture (presets automatically applied)
  const texture = await TextureLoader.load('/sprite.png');

  // Create sprite
  const sprite = new Sprite2D({ texture, anchor: [0.5, 0.5] });
  sprite.scale.set(100, 100, 1);
  scene.add(sprite);

  // Animation loop
  function animate() {
    requestAnimationFrame(animate);
    renderer.render(scene, camera);
  }
  animate();
}

main();

React

import { Suspense } from 'react';
import { Canvas, extend, useLoader } from '@react-three/fiber/webgpu';
import { Sprite2D, TextureLoader, usePixelPerfectCamera } from 'three-flatland/react';

extend({ Sprite2D });

function Camera() {
  usePixelPerfectCamera({ viewSize: 400 });
  return null;
}

function Sprite() {
  // Presets automatically applied (pixel-art by default)
  const texture = useLoader(TextureLoader, '/sprite.png');

  return (
    <sprite2D texture={texture} anchor={[0.5, 0.5]} scale={[100, 100, 1]} />
  );
}

export default function App() {
  return (
    <Canvas orthographic>
      <Camera />
      <Suspense>
        <Sprite />
      </Suspense>
    </Canvas>
  );
}

The await renderer.init() line is not optional

WebGPU initialization is async. Forgetting await renderer.init() before the first render is the single most common bug in fresh three-flatland projects. If you see a blank canvas with no errors, this is almost always why.

Next Steps

• Learn about sprites - Position, scale, and customize sprites
• Keep pixel art crisp - Coordinate cameras, snapping, textures, and DPR
• Add animation - Animate sprites with spritesheets
• Batch rendering - Optimize for thousands of sprites
• Browse examples - Interactive code examples

Want a live performance dashboard during development? See the Devtools guide.