Sprites

The Sprite2D class is the foundation for 2D rendering in three-flatland.

Three.js

import { Sprite2D, SpriteGroup } from 'three-flatland';

const sprite = new Sprite2D({
  texture: myTexture,
  anchor: [0.5, 0.5],  // Center anchor
});

spriteGroup.add(sprite);

React

import { extend } from '@react-three/fiber/webgpu';
import { Sprite2D, SpriteGroup } from 'three-flatland/react';

// Register with R3F (required once)
extend({ Sprite2D, SpriteGroup });

function Scene() {
  return (
    <spriteGroup>
      <sprite2D texture={myTexture} anchor={[0.5, 0.5]} />
    </spriteGroup>
  );
}

Loading Textures

Use TextureLoader from three-flatland (or three-flatland/react) to load textures with automatic preset configuration. For spritesheets, use SpriteSheetLoader. See the Loaders guide for details.

Properties

Position

Sprites inherit from Three.js Mesh and support standard transform properties:

sprite.position.set(100, 200, 0);
sprite.rotation.z = Math.PI / 4;  // 45 degree rotation
sprite.scale.set(2, 2, 1);  // 2x scale

Anchor

The anchor point determines the sprite’s origin for positioning and rotation. Values range from 0 to 1.

Anchor	Description
[0, 0]	Bottom-left corner
[0.5, 0.5]	Center (default)
[0.5, 0]	Bottom-center
[1, 1]	Top-right corner

Size

Sprite size is automatically determined from the texture dimensions but can be overridden:

const sprite = new Sprite2D({
  texture: myTexture,
  width: 64,
  height: 64,
});

SpriteGroup

For batched rendering with many sprites, use SpriteGroup:

Three.js

import { SpriteGroup } from 'three-flatland';

const spriteGroup = new SpriteGroup();
scene.add(spriteGroup);

spriteGroup.add(sprite1);
spriteGroup.add(sprite2);

// In animation loop — no update() call needed
renderer.render(scene, camera);

React

import { extend } from '@react-three/fiber/webgpu';
import { Sprite2D, SpriteGroup } from 'three-flatland/react';

extend({ Sprite2D, SpriteGroup });

function Scene() {
  return (
    <spriteGroup>
      <sprite2D texture={texture1} />
      <sprite2D texture={texture2} />
    </spriteGroup>
  );
}

For simple cases with few sprites, you can add them directly to the scene without SpriteGroup.

Flatland

For a complete 2D pipeline with camera, post-processing, and global uniforms, use Flatland instead of adding a SpriteGroup to your scene manually.

Layers

Use the Layers enum to control render order:

import { Layers } from 'three-flatland';

sprite.layer = Layers.BACKGROUND;  // Renders behind other sprites
sprite.layer = Layers.ENTITIES;    // Normal render order for game entities
sprite.layer = Layers.FOREGROUND;  // Renders in front
sprite.layer = Layers.UI;          // UI layer (renders last)

Available layers (in render order):

• Layers.BACKGROUND - Background elements
• Layers.GROUND - Ground/terrain
• Layers.SHADOWS - Shadow sprites
• Layers.ENTITIES - Game entities (default)
• Layers.FOREGROUND - Foreground elements
• Layers.UI - User interface