Shortcuts to getting started.

<SYSTEM>This is the full developer documentation for flatland</SYSTEM>

# three-flatland: Composable 2D library for three.js + react-three-fiber

> The composable 2D library for Three.js. Primitives for 2D graphics, TSL composability, react-three-fiber, ECS-driven sprite batching.

import FeatureCard from '../../components/FeatureCard.astro';
import StatsBanner from '../../components/StatsBanner.astro';
import ValueProp from '../../components/ValueProp.astro';
import HeroShader from '../../components/HeroShader.tsx';
import { Tabs, TabItem, Aside } from 'starlight-theme/components';

<section class="hero-fullscreen not-content">
  <div class="hero-canvas" aria-hidden="true">
    <HeroShader client:only="react" />
  </div>
  <div class="hero-overlay">
    {/* MDX auto-wraps any text content that sits on its own line
        inside a JSX tag with a markdown <p>. Net result: the text
        ends up in a sibling <p>, leaving the tagged tag empty —
        my .hero-tagline / .hero-subtagline classes were attached to
        EMPTY <p> elements while the actual text lived in unclassed
        siblings (broken CSS, voided SEO of the keyword-dense text).
        Same issue inside <a> tags — link labels were wrapped in
        block <p>, producing invalid `<a><p>text</p><svg/></a>`.
        Fix: keep tag + content on a single line so MDX skips the
        markdown-paragraph auto-wrap. */}
    <div class="hero-overlay-inner">
      <p class="hero-eyebrow">three-flatland</p>
      <h1 class="hero-title">The composable 2D library for Three.js</h1>
      <p class="hero-subtagline">2D primitives for three.js and react-three-fiber. ECS-driven sprite batching with TSL effect composition.</p>
      <div class="hero-actions">
        <a href="/three-flatland/getting-started/introduction/" class="sl-link-button primary"><span>Get Started</span><svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M5 12h14M12 5l7 7-7 7" /></svg></a>
        <a href="https://github.com/thejustinwalsh/three-flatland" class="sl-link-button secondary"><span>View on GitHub</span><svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M7 17l9.2-9.2M17 17V7H7" /></svg></a>
      </div>
    </div>
  </div>
</section>

<div class="page-body not-content">

<StatsBanner stats={[
  { value: "20K+", label: "Sprites at 60fps", color: "diamond" },
  { value: "ECS", label: "Batch archetypes", color: "pink" },
  { value: "TSL", label: "Composable shader nodes", color: "gold" },
  { value: "WebGPU", label: "and WebGL rendering", color: "amethyst" },
]} />

<h2 class="section-heading">Features</h2>

<div class="feature-grid">
  <FeatureCard
    icon="image"
    title="Sprites"
    color="diamond"
    stat="Instanced"
    statLabel="Atlas + per-instance animation"
  >
    Sprites should be cheap enough to scatter without counting them. `Sprite2D` and `AnimatedSprite2D` join an instanced batch on scenegraph entry. The spritesheet loader speaks TexturePacker; the animation system drives per-instance playback.
  </FeatureCard>

  <FeatureCard
    icon="list"
    title="Effect-aware batching"
    color="emerald"
    stat="ECS"
    statLabel="Dynamic batch archetypes"
  >
    An ECS packs sprite state into compact GPU buffers, so per-sprite effects share one material without fragmenting the batch. Tint, outline, dissolve, palette swap — written in TSL, branch-pruned at compile time.
  </FeatureCard>

  <FeatureCard
    icon="user"
    title="React Three Fiber"
    color="amethyst"
    stat="v10 Alpha"
    statLabel="Three.js >= 0.183"
  >
    Every primitive ships a typed JSX wrapper — `<sprite2D>`, `<tileMap2D>`, `<spriteGroup>`, `<flatland>`. Hooks compose with `useFrame` and `useThree`. Compatible with react-three-fiber v10's alpha WebGPU canvas, mounts inside `<Canvas>` like any other element.
  </FeatureCard>

  <FeatureCard
    icon="palette"
    title="Pixel-art rendering"
    color="gold"
    stat="Retro"
    statLabel="Pixel-art shader effects"
  >
    The retro effect category — CRT scanlines, dithering, pixelation, palette quantization — runs as per-sprite TSL nodes. `TextureLoader` applies pixel-art presets: nearest-neighbor filtering, no mipmaps, no subpixel bleeding.
  </FeatureCard>

  <FeatureCard
    icon="sparkles"
    title="Composable TSL effects"
    color="salmon"
    stat="50+"
    statLabel="Composable shader effects"
  >
    Pixelate, dither, CRT scanlines, dissolve, palette swap, chromatic aberration — a TSL effect library composed per-sprite via a typed schema. Override the color node to drop in your own.
  </FeatureCard>

  <FeatureCard
    icon="map"
    title="Chunked tilemaps"
    color="pink"
    stat="Chunked"
    statLabel="Per-chunk visibility"
  >
    `TileMap2D` batches like sprites, with chunks instead of per-tile draws — only visible chunks render. Loads from Tiled or LDtk JSON, with multiple layers, animated tiles, and collision data.
  </FeatureCard>
</div>

<h2 class="section-heading">Quick start: 2D in three.js</h2>

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
```typescript
import { Sprite2D, SpriteGroup } from 'three-flatland'

// Create a sprite group and add to your scene
const spriteGroup = new SpriteGroup()
scene.add(spriteGroup)

// Create sprites with textures
const player = new Sprite2D({ texture: playerTexture })
const enemy = new Sprite2D({ texture: enemyTexture })
enemy.position.set(2, 0, 0)

// Add sprites to the group
spriteGroup.add(player, enemy)
```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
```tsx
import { Canvas, extend } from '@react-three/fiber/webgpu'
import { Sprite2D, SpriteGroup } from 'three-flatland/react'

extend({ Sprite2D, SpriteGroup })

function Game() {
  return (
    <Canvas>
      <spriteGroup>
        <sprite2D texture={playerTexture} position={[0, 0, 0]} />
        <sprite2D texture={enemyTexture} position={[2, 0, 0]} />
      </spriteGroup>
    </Canvas>
  )
}
```
  </TabItem>
</Tabs>

<h2 class="section-heading">Built for three.js</h2>

<ValueProp title="Native to the three.js scenegraph" color="diamond">
  Composing existing 2D rendering libraries with three.js is hard. Pull one in and you're running a second full renderer that competes for the frame, with GPU resources shared by hand and the integration held together by hacks. Inside react-three-fiber the cost doubles: another reconciler, state marshaled across two React instances.

  three-flatland is built directly on three.js. There's no parallel renderer to coordinate, no bridge between React instances to maintain. three.js is the renderer, react-three-fiber is the reconciler, and every 2D primitive — `Sprite2D`, `TileMap2D`, `SpriteGroup` — is a Three.js object that mounts into the scenegraph the same way a `Mesh` does.
</ValueProp>

<ValueProp title="Sprite batches that survive your effects" color="emerald" align="right">
  Most sprite batchers fall apart the moment a single sprite needs special treatment. Changing a uniform tanks the batch; shifting a z-index forces a scenegraph reorder; attaching an effect reflows the scene around it.

  three-flatland's batcher composes effects on a single shared material — adding a glow to one sprite doesn't fragment the batch or rebuild the shader. The cost stays proportional to what's actually used: the uber-shader prunes unused branches at compile time, and the ECS keeps batch archetypes optimal as effects appear and disappear. To customize beyond the defaults, swap the color node or write a new effect against the same schema.
</ValueProp>

<ValueProp title="The ecosystem is three.js" color="amethyst">
  Flatland doesn't define a secondary ecosystem inside three.js — three.js is the ecosystem. Each `@three-flatland/*` package follows a Unix-style one-job rule, is tree-shakable, and works in any three.js project, with or without Flatland.

  `@three-flatland/skia` brings Skia to Three.js — with a native WebGPU backend (Graphite/Dawn) that CanvasKit doesn't ship, plus a Zig-built WASM bundle tuned for size and speed. A TSL port of the Slug glyph-rendering algorithm is in flight — fully shader-driven, accurate at any scale, with real dynamic kerning instead of bitmap atlas sampling. A KTX2 Basis transcoder and runtime encoder (WASM + SIMD) and a VS Code plugin for 2D web projects are in development.
</ValueProp>

<ValueProp title="When not to reach for Flatland" color="ruby" align="right">
  If your only 2D need is in-canvas app UI (buttons, panels, settings menus, dialogs), uikit is purpose-built for that. Flatland isn't.

  For sprites, tilemaps, particles, shaders, HUDs, data viz, hybrid 2.5D — that's three-flatland's territory. Every `@three-flatland/*` package stands on its own, so adopting Flatland is incremental, not all-or-nothing.
</ValueProp>

</div>

<style>
{`
  /* Hero stays dark-mode regardless of the site-wide theme.
     The hero canvas is a near-black gem-flow shader; the H1, eyebrow,
     subtagline, and CTAs are all tuned to read against that surface.
     In light mode the surrounding page goes paper-toned, but the hero
     itself must stay on its own dark stage so the typography halos and
     gem-tinted highlights still land.

     Token override — mirror the dark-mode :root tokens that the hero
     subtree consumes (background, foreground, muted-foreground, the
     gem palette for eyebrow + buttons, plus the link-button surface
     tokens like --card and --primary-foreground). Only listed tokens
     are overridden; tokens we do NOT use (sidebar, popover, etc.) are
     left to inherit from the active site theme. */
  @media (prefers-color-scheme: light) {
    .hero-fullscreen {
      /* Match the shader's light-mode bg paint (HeroShader.tsx bgLight =
       * oklch(42% 0.006 250)). Previously near-black (18%), which caused
       * a noticeable black flash before WebGL composited its first frame. */
      --background: oklch(42% 0.006 250);
      --foreground: oklch(92% 0.008 250);
      --muted-foreground: oklch(68% 0.011 250);
      --card: oklch(20% 0.008 250);
      --border: oklch(28% 0.008 245);
      --primary: oklch(63% 0.24 295);
      --primary-foreground: oklch(99% 0 0);
      --secondary: oklch(24% 0.010 250);
      --secondary-foreground: oklch(92% 0.008 250);
      /* Gems re-tuned to their dark-mode vibrant values (light-mode
         palette runs darker for paper-bg legibility, which kills the
         eyebrow + CTA halos against the dark canvas). */
      --gold: oklch(72% 0.16 85);
      --gold-high: oklch(82% 0.17 88);
      --gold-low: oklch(34% 0.10 80);
      --diamond: oklch(75% 0.15 215);
      --amethyst: oklch(63% 0.24 295);
      --link: oklch(75% 0.15 215);
      --link-hover: oklch(85% 0.13 215);
      /* Hero-to-page fade: the canvas is dark but the page below is
         paper. The fade meets the page bg, not the overridden hero bg.
         Light-mode fade is 12% — about half of the prior 20% (which was
         already shorter than dark mode's 33%). The dark→paper contrast
         carries the transition; a smaller fade band reads as a crisp
         horizon line rather than a long wash. Dark mode unchanged. */
      --hero-fade-end: oklch(98% 0.008 80);
      --hero-fade-height: 12%;
    }
  }

  /* Half-viewport hero — canvas extends UP behind the transparent
     site header so the gem flow reads as one uninterrupted plane
     from the very top of the viewport down to the hero's end.
     60vh hero keeps the StatsBanner above the fold. */
  .hero-fullscreen {
    position: relative;
    width: 100%;
    height: 60vh;
    min-height: 24rem;
    margin: 0;
  }
  .hero-canvas {
    position: absolute;
    /* Extend up past the hero's top edge by the header height so the
       canvas covers the area BEHIND the (transparent) site header. */
    top: calc(var(--header-height, 3.5rem) * -1);
    left: 0;
    right: 0;
    bottom: 0;
    overflow: hidden;
    background: var(--background);
    z-index: 0;
  }
  .hero-canvas > :global(*) {
    position: absolute;
    inset: 0;
  }

  /* Overlay sits ON TOP of the canvas, fills the hero area, centers
     the title/tagline/CTAs vertically. */
  .hero-overlay {
    position: absolute;
    inset: 0;
    display: flex;
    flex-direction: column;
    align-items: center;
    justify-content: center;
    padding: clamp(1.5rem, 4vw, 3rem);
    padding-top: var(--header-height, 3.5rem);
    pointer-events: none;
    z-index: 2;
  }
  /* Bottom-fade gradient masks the canvas to the page background so the
     transition into the .page-body content reads as a soft horizon.
     Uses --hero-fade-end (NOT --background) because the hero's
     darkmode-lock override redefines --background to the dark value;
     the fade needs to meet the actual page below, which is paper in
     light mode and near-black in dark mode. See the
     @media (prefers-color-scheme: light) block above for the light-mode override. */
  .hero-overlay::after {
    content: '';
    position: absolute;
    left: 0;
    right: 0;
    bottom: 0;
    height: var(--hero-fade-height, 33%);
    background: linear-gradient(
      to bottom,
      transparent 0%,
      color-mix(in oklab, var(--hero-fade-end, var(--background)) 70%, transparent) 60%,
      var(--hero-fade-end, var(--background)) 100%
    );
    pointer-events: none;
  }
  .hero-overlay-inner {
    position: relative;
    z-index: 3;
    pointer-events: auto;
    text-align: center;
    /* width:100% + max-width:56rem so this container expands up to its
     * cap and the children's max-widths and margin-inline:auto resolve
     * against a stable width. Without width:100%, the flex parent's
     * align-items:center sized this to its widest child (the tagline
     * at 42rem ~672px) — buttons and subtagline ended up off-center
     * relative to the viewport because their auto margins resolved
     * against the constrained 672px container, not the intended 56rem. */
    width: 100%;
    max-width: 56rem;
    margin-inline: auto;
  }

  /* Package-name eyebrow — small mono, tracked uppercase, reads as
     'install name' / code reference rather than competing for visual
     mass with the h1 below. The brand 'flatland' is already in the
     header wordmark; this eyebrow exists so first-time visitors
     landing from a search for 'three-flatland' get immediate
     confirmation they're on the right page, but without sacrificing
     the SEO-load-bearing h1 below. */
  .hero-eyebrow {
    font-family: 'JetBrains Mono', ui-monospace, monospace;
    font-size: clamp(0.75rem, 1vw, 0.875rem);
    font-weight: 500;
    letter-spacing: 0.12em;
    text-transform: uppercase;
    color: color-mix(in oklab, var(--gold) 50%, var(--muted-foreground));
    margin-block: 0 calc(var(--spacing) * 4);
    margin-inline: auto;
    /* Layered halo — close shadow carves the character edges out of
     * the dithered canvas, wider shadow gives breathing room. Tuned
     * to compete with the (capped) ~75% max brightness of the
     * pixelated hero behind. */
    text-shadow:
      0 1px 3px color-mix(in oklab, var(--background) 90%, transparent),
      0 2px 16px color-mix(in oklab, var(--background) 70%, transparent);
  }

  /* Editorial display heading — h1 now carries the value-proposition
     statement (Tailwind/Vercel/Linear hero pattern). Public Sans 200
     at editorial display size; sentence case (no uppercase transform)
     because the longer text reads better in sentence flow. Slightly
     smaller clamp than the old wordmark-h1 since the longer string
     would overflow on common viewports — text-wrap: balance gives a
     clean 2-line wrap on most screens. */
  .hero-title {
    font-family: 'Public Sans', system-ui, sans-serif;
    font-size: clamp(2rem, 4.5vw, 3.5rem);
    font-weight: 200;
    line-height: 1.05;
    letter-spacing: -0.015em;
    color: var(--foreground);
    max-width: 28ch;
    margin-block: 0 calc(var(--spacing) * 5);
    margin-inline: auto;
    text-wrap: balance;
    /* Triple-layer halo against the dithered pixel-art canvas:
     *   - 1px close: carves a hard edge around character strokes so
     *     8px big-pixels behind don't bleed visually into glyph forms
     *   - 24px medium: punchy character separation
     *   - 56px wide: gentle outer wash so the title sits on its own
     *     "lit pad" instead of competing with the busy posterized bg
     * Without these the (capped) 75%-brightness big-pixels still
     * sit close enough to white-ish to make the thin 200-weight
     * Public Sans display strokes vibrate. */
    text-shadow:
      0 1px 3px color-mix(in oklab, var(--background) 92%, transparent),
      0 2px 24px color-mix(in oklab, var(--background) 75%, transparent),
      0 0 56px color-mix(in oklab, var(--background) 55%, transparent);
  }
  /* Supporting line below the hero tagline — claim-stack pattern
     (shadcn-style). Each comma-separated phrase lands one ecosystem
     perk: primitives (composability), TSL (modern shader stack),
     react-three-fiber (ecosystem), performance (no opt-in tax).
     Smaller, lighter weight so it reads as supporting evidence,
     not the headline. */
  .hero-subtagline {
    font-family: 'JetBrains Mono', ui-monospace, monospace;
    font-size: clamp(0.7rem, 1vw, 0.8125rem);
    font-weight: 400;
    line-height: 1.5;
    letter-spacing: 0.01em;
    color: color-mix(in oklab, var(--muted-foreground) 80%, var(--foreground));
    max-width: 48rem;
    /* Explicit margin-block:0 top so we don't pick up the default
       1em top margin on paragraphs; bottom pushes CTAs into a clear band. */
    margin-block: 0 calc(var(--spacing) * 10);
    margin-inline: auto;
    /* Two-layer halo — same idea as .hero-title but pulled back since
     * the subtagline is small mono and reads through faster. */
    text-shadow:
      0 1px 3px color-mix(in oklab, var(--background) 90%, transparent),
      0 2px 18px color-mix(in oklab, var(--background) 70%, transparent);
  }
  .hero-actions {
    display: flex;
    justify-content: center;
    gap: calc(var(--spacing) * 3);
    flex-wrap: wrap;
    margin: calc(var(--spacing) * 3) auto;
  }
  /* Page body — everything below the hero gets reasonable horizontal
     padding so content isn't edge-to-edge on splash pages. The hero
     stays edge-to-edge for the fullscreen vibe. */
  .page-body {
    padding-inline: clamp(1.5rem, 4vw, 3rem);
    padding-block: calc(var(--spacing) * 16) calc(var(--spacing) * 12);
    max-width: 90rem;
    margin: 0 auto;
    position: relative;
    z-index: 1;
    background: var(--background);
  }

  /* Section headings inside .page-body — Public Sans display, smaller
     than h1 and at semi weight for structural clarity, with consistent
     vertical rhythm between sections. */
  .section-heading {
    font-family: 'Public Sans', system-ui, sans-serif;
    font-size: clamp(1.625rem, 2.6vw, 2rem);
    font-weight: 600;
    line-height: 1.15;
    letter-spacing: -0.02em;
    color: var(--foreground);
    margin: calc(var(--spacing) * 16) 0 calc(var(--spacing) * 6);
  }
  .section-heading:first-child {
    margin-top: 0;
  }

  .feature-grid {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(min(100%, 320px), 1fr));
    grid-auto-rows: 1fr;
    gap: 1.5rem;
    margin: 0 0 calc(var(--spacing) * 4);
    align-items: stretch;
  }
  .feature-grid > :global(article) {
    height: 100%;
    display: flex;
    flex-direction: column;
  }
  @media (min-width: 900px) {
    .feature-grid {
      grid-template-columns: repeat(3, 1fr);
    }
  }
  @media (min-width: 600px) and (max-width: 899px) {
    .feature-grid {
      grid-template-columns: repeat(2, 1fr);
    }
  }
`}
</style>

# three-flatland

## Modules

- [nodes/src](/three-flatland/api/nodes/src/index/)
- [presets/src](/three-flatland/api/presets/src/index/)
- [three-flatland/src](/three-flatland/api/three-flatland/src/index/)
- [three-flatland/src/react](/three-flatland/api/three-flatland/src/react/index/)

# nodes/src

## Interfaces

- [CRTOptions](/three-flatland/api/nodes/src/interfaces/crtoptions/)
- [DissolveOptions](/three-flatland/api/nodes/src/interfaces/dissolveoptions/)
- [Light2DResult](/three-flatland/api/nodes/src/interfaces/light2dresult/)
- [LitSpriteOptions](/three-flatland/api/nodes/src/interfaces/litspriteoptions/)
- [OutlineOptions](/three-flatland/api/nodes/src/interfaces/outlineoptions/)

## Type Aliases

- [ColorInput](/three-flatland/api/nodes/src/type-aliases/colorinput/)
- [FloatInput](/three-flatland/api/nodes/src/type-aliases/floatinput/)
- [Vec2Input](/three-flatland/api/nodes/src/type-aliases/vec2input/)
- [Vec3Input](/three-flatland/api/nodes/src/type-aliases/vec3input/)
- [Vec4Input](/three-flatland/api/nodes/src/type-aliases/vec4input/)

## Functions

- [afterimage](/three-flatland/api/nodes/src/functions/afterimage/)
- [afterimageGlow](/three-flatland/api/nodes/src/functions/afterimageglow/)
- [afterimageTinted](/three-flatland/api/nodes/src/functions/afterimagetinted/)
- [alphaMask](/three-flatland/api/nodes/src/functions/alphamask/)
- [alphaMaskInvert](/three-flatland/api/nodes/src/functions/alphamaskinvert/)
- [alphaMaskValue](/three-flatland/api/nodes/src/functions/alphamaskvalue/)
- [alphaTest](/three-flatland/api/nodes/src/functions/alphatest/)
- [alphaTestOpaque](/three-flatland/api/nodes/src/functions/alphatestopaque/)
- [ambientLight2D](/three-flatland/api/nodes/src/functions/ambientlight2d/)
- [analogGlitch](/three-flatland/api/nodes/src/functions/analogglitch/)
- [bayerDither](/three-flatland/api/nodes/src/functions/bayerdither/)
- [bayerDither2x2](/three-flatland/api/nodes/src/functions/bayerdither2x2/)
- [bayerDither4x4](/three-flatland/api/nodes/src/functions/bayerdither4x4/)
- [bayerDither8x8](/three-flatland/api/nodes/src/functions/bayerdither8x8/)
- [bloom](/three-flatland/api/nodes/src/functions/bloom/)
- [bloomAnamorphic](/three-flatland/api/nodes/src/functions/bloomanamorphic/)
- [bloomSimple](/three-flatland/api/nodes/src/functions/bloomsimple/)
- [bloomThreshold](/three-flatland/api/nodes/src/functions/bloomthreshold/)
- [blurBox](/three-flatland/api/nodes/src/functions/blurbox/)
- [blurBox3x3](/three-flatland/api/nodes/src/functions/blurbox3x3/)
- [blurBoxDirectional](/three-flatland/api/nodes/src/functions/blurboxdirectional/)
- [blurBoxSmooth](/three-flatland/api/nodes/src/functions/blurboxsmooth/)
- [blurFocus](/three-flatland/api/nodes/src/functions/blurfocus/)
- [blurGaussian](/three-flatland/api/nodes/src/functions/blurgaussian/)
- [blurGaussian2Pass](/three-flatland/api/nodes/src/functions/blurgaussian2pass/)
- [blurGaussian9](/three-flatland/api/nodes/src/functions/blurgaussian9/)
- [blurKawase](/three-flatland/api/nodes/src/functions/blurkawase/)
- [blurKawaseDown](/three-flatland/api/nodes/src/functions/blurkawasedown/)
- [blurKawaseMulti](/three-flatland/api/nodes/src/functions/blurkawasemulti/)
- [blurKawaseSimple](/three-flatland/api/nodes/src/functions/blurkawasesimple/)
- [blurKawaseUp](/three-flatland/api/nodes/src/functions/blurkawaseup/)
- [blurMotion](/three-flatland/api/nodes/src/functions/blurmotion/)
- [blurMotionObject](/three-flatland/api/nodes/src/functions/blurmotionobject/)
- [blurMotionVelocity](/three-flatland/api/nodes/src/functions/blurmotionvelocity/)
- [blurRadial](/three-flatland/api/nodes/src/functions/blurradial/)
- [blurRadialDistance](/three-flatland/api/nodes/src/functions/blurradialdistance/)
- [blurShake](/three-flatland/api/nodes/src/functions/blurshake/)
- [blurSpin](/three-flatland/api/nodes/src/functions/blurspin/)
- [brightness](/three-flatland/api/nodes/src/functions/brightness/)
- [brightnessClamped](/three-flatland/api/nodes/src/functions/brightnessclamped/)
- [brightnessMultiply](/three-flatland/api/nodes/src/functions/brightnessmultiply/)
- [c64Palette](/three-flatland/api/nodes/src/functions/c64palette/)
- [cgaPalette](/three-flatland/api/nodes/src/functions/cgapalette/)
- [chromaticAberration](/three-flatland/api/nodes/src/functions/chromaticaberration/)
- [chromaticAberrationCustom](/three-flatland/api/nodes/src/functions/chromaticaberrationcustom/)
- [chromaticAberrationPulse](/three-flatland/api/nodes/src/functions/chromaticaberrationpulse/)
- [chromaticAberrationRadial](/three-flatland/api/nodes/src/functions/chromaticaberrationradial/)
- [colorBleeding](/three-flatland/api/nodes/src/functions/colorbleeding/)
- [colorRemap](/three-flatland/api/nodes/src/functions/colorremap/)
- [colorRemapCustom](/three-flatland/api/nodes/src/functions/colorremapcustom/)
- [colorReplace](/three-flatland/api/nodes/src/functions/colorreplace/)
- [colorReplaceHard](/three-flatland/api/nodes/src/functions/colorreplacehard/)
- [colorReplaceMultiple](/three-flatland/api/nodes/src/functions/colorreplacemultiple/)
- [contrast](/three-flatland/api/nodes/src/functions/contrast/)
- [contrastSCurve](/three-flatland/api/nodes/src/functions/contrastscurve/)
- [crtBloom](/three-flatland/api/nodes/src/functions/crtbloom/)
- [crtColorBleed](/three-flatland/api/nodes/src/functions/crtcolorbleed/)
- [crtComplete](/three-flatland/api/nodes/src/functions/crtcomplete/)
- [crtConvergence](/three-flatland/api/nodes/src/functions/crtconvergence/)
- [crtCurvature](/three-flatland/api/nodes/src/functions/crtcurvature/)
- [crtCurvatureWithCorners](/three-flatland/api/nodes/src/functions/crtcurvaturewithcorners/)
- [crtVignette](/three-flatland/api/nodes/src/functions/crtvignette/)
- [directionalLight2D](/three-flatland/api/nodes/src/functions/directionallight2d/)
- [dissolve](/three-flatland/api/nodes/src/functions/dissolve/)
- [dissolveDirectional](/three-flatland/api/nodes/src/functions/dissolvedirectional/)
- [dissolvePixelated](/three-flatland/api/nodes/src/functions/dissolvepixelated/)
- [dissolveSimple](/three-flatland/api/nodes/src/functions/dissolvesimple/)
- [distortBarrel](/three-flatland/api/nodes/src/functions/distortbarrel/)
- [distortBulge](/three-flatland/api/nodes/src/functions/distortbulge/)
- [distortDisplace](/three-flatland/api/nodes/src/functions/distortdisplace/)
- [distortNoise](/three-flatland/api/nodes/src/functions/distortnoise/)
- [distortPerlin](/three-flatland/api/nodes/src/functions/distortperlin/)
- [distortPinch](/three-flatland/api/nodes/src/functions/distortpinch/)
- [distortPixelate](/three-flatland/api/nodes/src/functions/distortpixelate/)
- [distortPixelateCount](/three-flatland/api/nodes/src/functions/distortpixelatecount/)
- [distortShatter](/three-flatland/api/nodes/src/functions/distortshatter/)
- [distortSimplex](/three-flatland/api/nodes/src/functions/distortsimplex/)
- [distortSpherize](/three-flatland/api/nodes/src/functions/distortspherize/)
- [distortTurbulence](/three-flatland/api/nodes/src/functions/distortturbulence/)
- [distortTwirl](/three-flatland/api/nodes/src/functions/distorttwirl/)
- [dmgPalette](/three-flatland/api/nodes/src/functions/dmgpalette/)
- [dotMatrix](/three-flatland/api/nodes/src/functions/dotmatrix/)
- [eagle](/three-flatland/api/nodes/src/functions/eagle/)
- [fadeEdge](/three-flatland/api/nodes/src/functions/fadeedge/)
- [fadeEdgeHorizontal](/three-flatland/api/nodes/src/functions/fadeedgehorizontal/)
- [fadeEdgeRadial](/three-flatland/api/nodes/src/functions/fadeedgeradial/)
- [fadeEdgeVertical](/three-flatland/api/nodes/src/functions/fadeedgevertical/)
- [filmGrain](/three-flatland/api/nodes/src/functions/filmgrain/)
- [flash](/three-flatland/api/nodes/src/functions/flash/)
- [flashAdditive](/three-flatland/api/nodes/src/functions/flashadditive/)
- [flashAlpha](/three-flatland/api/nodes/src/functions/flashalpha/)
- [flashDamage](/three-flatland/api/nodes/src/functions/flashdamage/)
- [flashHeal](/three-flatland/api/nodes/src/functions/flashheal/)
- [flashPowerUp](/three-flatland/api/nodes/src/functions/flashpowerup/)
- [flashSmooth](/three-flatland/api/nodes/src/functions/flashsmooth/)
- [gbcPalette](/three-flatland/api/nodes/src/functions/gbcpalette/)
- [ghost](/three-flatland/api/nodes/src/functions/ghost/)
- [ghostSpeed](/three-flatland/api/nodes/src/functions/ghostspeed/)
- [ghostTrail](/three-flatland/api/nodes/src/functions/ghosttrail/)
- [glowSelective](/three-flatland/api/nodes/src/functions/glowselective/)
- [grayscale](/three-flatland/api/nodes/src/functions/grayscale/)
- [hq2x](/three-flatland/api/nodes/src/functions/hq2x/)
- [hq3x](/three-flatland/api/nodes/src/functions/hq3x/)
- [hq4x](/three-flatland/api/nodes/src/functions/hq4x/)
- [hueShift](/three-flatland/api/nodes/src/functions/hueshift/)
- [hueShiftNormalized](/three-flatland/api/nodes/src/functions/hueshiftnormalized/)
- [interlacing](/three-flatland/api/nodes/src/functions/interlacing/)
- [lcdBacklightBleed](/three-flatland/api/nodes/src/functions/lcdbacklightbleed/)
- [lcdGBC](/three-flatland/api/nodes/src/functions/lcdgbc/)
- [lcdGhosting](/three-flatland/api/nodes/src/functions/lcdghosting/)
- [lcdGrid](/three-flatland/api/nodes/src/functions/lcdgrid/)
- [lcdMotionGhost](/three-flatland/api/nodes/src/functions/lcdmotionghost/)
- [lcdPocket](/three-flatland/api/nodes/src/functions/lcdpocket/)
- [litCelShaded](/three-flatland/api/nodes/src/functions/litcelshaded/)
- [litDiffuse](/three-flatland/api/nodes/src/functions/litdiffuse/)
- [litRim](/three-flatland/api/nodes/src/functions/litrim/)
- [litSpecular](/three-flatland/api/nodes/src/functions/litspecular/)
- [litSprite](/three-flatland/api/nodes/src/functions/litsprite/)
- [litSpriteMulti](/three-flatland/api/nodes/src/functions/litspritemulti/)
- [md9bitPalette](/three-flatland/api/nodes/src/functions/md9bitpalette/)
- [normalFromHeight](/three-flatland/api/nodes/src/functions/normalfromheight/)
- [normalFromHeightSmooth](/three-flatland/api/nodes/src/functions/normalfromheightsmooth/)
- [ntscComposite](/three-flatland/api/nodes/src/functions/ntsccomposite/)
- [outline](/three-flatland/api/nodes/src/functions/outline/)
- [outline8](/three-flatland/api/nodes/src/functions/outline8/)
- [palettize](/three-flatland/api/nodes/src/functions/palettize/)
- [palettizeDithered](/three-flatland/api/nodes/src/functions/palettizedithered/)
- [palettizeNearest](/three-flatland/api/nodes/src/functions/palettizenearest/)
- [phosphorApertureGrille](/three-flatland/api/nodes/src/functions/phosphoraperturegrille/)
- [phosphorMask](/three-flatland/api/nodes/src/functions/phosphormask/)
- [phosphorShadowMask](/three-flatland/api/nodes/src/functions/phosphorshadowmask/)
- [phosphorSimple](/three-flatland/api/nodes/src/functions/phosphorsimple/)
- [phosphorSlotMask](/three-flatland/api/nodes/src/functions/phosphorslotmask/)
- [pixelate](/three-flatland/api/nodes/src/functions/pixelate/)
- [pixelateBySize](/three-flatland/api/nodes/src/functions/pixelatebysize/)
- [pocketPalette](/three-flatland/api/nodes/src/functions/pocketpalette/)
- [pointLight2D](/three-flatland/api/nodes/src/functions/pointlight2d/)
- [posterize](/three-flatland/api/nodes/src/functions/posterize/)
- [posterizeGamma](/three-flatland/api/nodes/src/functions/posterizegamma/)
- [ppuPalette](/three-flatland/api/nodes/src/functions/ppupalette/)
- [pulse](/three-flatland/api/nodes/src/functions/pulse/)
- [pulseGlow](/three-flatland/api/nodes/src/functions/pulseglow/)
- [pulseHeartbeat](/three-flatland/api/nodes/src/functions/pulseheartbeat/)
- [pulseRadial](/three-flatland/api/nodes/src/functions/pulseradial/)
- [pulseRainbow](/three-flatland/api/nodes/src/functions/pulserainbow/)
- [quantize](/three-flatland/api/nodes/src/functions/quantize/)
- [quantizeRGB](/three-flatland/api/nodes/src/functions/quantizergb/)
- [sai2x](/three-flatland/api/nodes/src/functions/sai2x/)
- [sampleSprite](/three-flatland/api/nodes/src/functions/samplesprite/)
- [saturate](/three-flatland/api/nodes/src/functions/saturate/)
- [scale2x](/three-flatland/api/nodes/src/functions/scale2x/)
- [scale3x](/three-flatland/api/nodes/src/functions/scale3x/)
- [scanlines](/three-flatland/api/nodes/src/functions/scanlines/)
- [scanlinesGlow](/three-flatland/api/nodes/src/functions/scanlinesglow/)
- [scanlinesGrid](/three-flatland/api/nodes/src/functions/scanlinesgrid/)
- [scanlinesInterlaced](/three-flatland/api/nodes/src/functions/scanlinesinterlaced/)
- [scanlinesSmooth](/three-flatland/api/nodes/src/functions/scanlinessmooth/)
- [shadow2D](/three-flatland/api/nodes/src/functions/shadow2d/)
- [shadowDrop](/three-flatland/api/nodes/src/functions/shadowdrop/)
- [shadowDropSoft](/three-flatland/api/nodes/src/functions/shadowdropsoft/)
- [shadowSDF2D](/three-flatland/api/nodes/src/functions/shadowsdf2d/)
- [shadowSoft2D](/three-flatland/api/nodes/src/functions/shadowsoft2d/)
- [shimmer](/three-flatland/api/nodes/src/functions/shimmer/)
- [shimmerHolographic](/three-flatland/api/nodes/src/functions/shimmerholographic/)
- [shimmerMetallic](/three-flatland/api/nodes/src/functions/shimmermetallic/)
- [shimmerWave](/three-flatland/api/nodes/src/functions/shimmerwave/)
- [signalInterference](/three-flatland/api/nodes/src/functions/signalinterference/)
- [snesPalette](/three-flatland/api/nodes/src/functions/snespalette/)
- [sparkle](/three-flatland/api/nodes/src/functions/sparkle/)
- [sparkleRainbow](/three-flatland/api/nodes/src/functions/sparklerainbow/)
- [sparkleStar](/three-flatland/api/nodes/src/functions/sparklestar/)
- [speedLines](/three-flatland/api/nodes/src/functions/speedlines/)
- [spotLight2D](/three-flatland/api/nodes/src/functions/spotlight2d/)
- [spriteUV](/three-flatland/api/nodes/src/functions/spriteuv/)
- [staticNoise](/three-flatland/api/nodes/src/functions/staticnoise/)
- [superEagle](/three-flatland/api/nodes/src/functions/supereagle/)
- [tint](/three-flatland/api/nodes/src/functions/tint/)
- [tintAdditive](/three-flatland/api/nodes/src/functions/tintadditive/)
- [trail](/three-flatland/api/nodes/src/functions/trail/)
- [trailAdditive](/three-flatland/api/nodes/src/functions/trailadditive/)
- [trailBlur](/three-flatland/api/nodes/src/functions/trailblur/)
- [trailVelocity](/three-flatland/api/nodes/src/functions/trailvelocity/)
- [uvFlip](/three-flatland/api/nodes/src/functions/uvflip/)
- [uvOffset](/three-flatland/api/nodes/src/functions/uvoffset/)
- [uvRotate](/three-flatland/api/nodes/src/functions/uvrotate/)
- [uvScale](/three-flatland/api/nodes/src/functions/uvscale/)
- [vbPalette](/three-flatland/api/nodes/src/functions/vbpalette/)
- [vhsDistortion](/three-flatland/api/nodes/src/functions/vhsdistortion/)
- [vignette](/three-flatland/api/nodes/src/functions/vignette/)
- [waveHorizontal](/three-flatland/api/nodes/src/functions/wavehorizontal/)
- [waveRadial](/three-flatland/api/nodes/src/functions/waveradial/)
- [waveRipple](/three-flatland/api/nodes/src/functions/waveripple/)
- [waveVertical](/three-flatland/api/nodes/src/functions/wavevertical/)
- [waveWater](/three-flatland/api/nodes/src/functions/wavewater/)

# afterimage

> **afterimage**(`currentColor`, `previousTex`, `uv`, `persistence?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/afterimage.ts:20](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/afterimage.ts#L20)

Create afterimage/ghost effect by blending with a previous frame.
Requires a texture containing the previous frame.

## Parameters

### currentColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Current frame color

### previousTex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Previous frame texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### persistence?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.8`

How much previous frame persists (0-1, default: 0.8)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Blended color with afterimage

## Example

```ts
// Render to texture, then use previous frame
const ghosted = afterimage(currentColor, previousFrameTexture, uv, 0.85)
```

# afterimageGlow

> **afterimageGlow**(`currentColor`, `previousTex`, `uv`, `persistence?`, `intensity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/afterimage.ts:76](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/afterimage.ts#L76)

Additive afterimage for glowing ghost effects.

## Parameters

### currentColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Current frame color

### previousTex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Previous frame texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### persistence?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.7`

Persistence amount

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Glow intensity

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with additive afterimage

# afterimageTinted

> **afterimageTinted**(`currentColor`, `previousTex`, `uv`, `persistence?`, `ghostTint?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/afterimage.ts:46](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/afterimage.ts#L46)

Afterimage with color tinting for ghost trails.

## Parameters

### currentColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Current frame color

### previousTex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Previous frame texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### persistence?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.8`

Persistence amount

### ghostTint?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Color tint for the ghost (default: slight blue)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with tinted afterimage

# alphaMask

> **alphaMask**(`inputColor`, `maskTex`, `maskUV`, `strength?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/alpha/alphaMask.ts:24](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/alpha/alphaMask.ts#L24)

Multiply alpha by a mask texture's value.
The mask texture's red channel (or luminance) is used as the mask value.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### maskTex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Mask texture (uses red channel)

### maskUV

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates for mask sampling

### strength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Mask strength (0 = no mask, 1 = full mask)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with masked alpha

## Examples

```ts
// Apply mask texture
alphaMask(texture(tex, uv()), maskTexture, uv())
```

```ts
// Partial mask effect
alphaMask(texture(tex, uv()), maskTexture, uv(), 0.5)
```

# alphaMaskInvert

> **alphaMaskInvert**(`inputColor`, `maskTex`, `maskUV`, `strength?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/alpha/alphaMask.ts:68](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/alpha/alphaMask.ts#L68)

Invert mask and apply to alpha (areas with high mask value become transparent).

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### maskTex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Mask texture (uses red channel, inverted)

### maskUV

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates for mask sampling

### strength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Mask strength

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with inverted mask applied to alpha

# alphaMaskValue

> **alphaMaskValue**(`inputColor`, `mask`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/alpha/alphaMask.ts:53](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/alpha/alphaMask.ts#L53)

Multiply alpha by a mask value (single float instead of texture).

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### mask

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Mask value (0-1)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with masked alpha

## Example

```ts
// Fade sprite by 50%
alphaMaskValue(texture(tex, uv()), 0.5)
```

# alphaTest

> **alphaTest**(`inputColor`, `threshold`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/alpha/alphaTest.ts:21](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/alpha/alphaTest.ts#L21)

Discard pixels with alpha below a threshold.
Useful for hard-edged transparency (pixel art, text).

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### threshold

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Alpha threshold (pixels below this are discarded)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color unchanged, or discarded if below threshold

## Examples

```ts
// Discard nearly transparent pixels
alphaTest(texture(tex, uv()), 0.5)
```

```ts
// Animated alpha cutoff
alphaTest(texture(tex, uv()), thresholdUniform)
```

# alphaTestOpaque

> **alphaTestOpaque**(`inputColor`, `threshold`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/alpha/alphaTest.ts:39](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/alpha/alphaTest.ts#L39)

Discard pixels with alpha below threshold and set remaining alpha to 1.
Creates a hard mask effect.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### threshold

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Alpha threshold

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Opaque color if above threshold, discarded otherwise

# ambientLight2D

> **ambientLight2D**(`lightColor?`, `intensity?`): [`Light2DResult`](/three-flatland/api/nodes/src/interfaces/light2dresult/)

Defined in: [packages/nodes/src/lighting/lights.ts:169](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/lights.ts#L169)

Ambient light provides uniform illumination from all directions.

## Parameters

### lightColor?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Light color

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.2`

Light intensity

## Returns

[`Light2DResult`](/three-flatland/api/nodes/src/interfaces/light2dresult/)

Light2DResult with upward direction (for ambient occlusion compatibility)

## Example

```ts
const ambient = ambientLight2D([0.2, 0.2, 0.3], 1.0)
```

# analogGlitch

> **analogGlitch**(`tex`, `uv`, `time`, `intensity?`, `speed?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/analog/videoArtifacts.ts:190](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/analog/videoArtifacts.ts#L190)

Analog glitch effect with continuous distortion.

## Parameters

### tex

[`TextureNode`](https://threejs.org/docs/)\<`"vec4"`\>

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### time

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Animation time

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.03`

Glitch intensity (default: 0.03)

### speed?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Animation speed (default: 1)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with analog glitch

# bayerDither

> **bayerDither**(`inputColor`, `levels?`, `scale?`, `screenCoord?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/retro/bayerDither.ts:298](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/retro/bayerDither.ts#L298)

Apply Bayer matrix ordered dithering (defaults to 4x4).
Alias for bayerDither4x4 as it's the most commonly used pattern.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### levels?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `2`

Number of color levels per channel (default: 2 = binary)

### scale?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Scale of dither pattern (default: 1)

### screenCoord?

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Screen coordinates (use UV * textureSize for per-sprite)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Dithered color

## Examples

```ts
// Binary dithering (2-color)
bayerDither(texture(tex, uv()), 2, 1, screenUV.mul(resolution))
```

```ts
// 4-level dithering for retro look
bayerDither(color, 4)
```

# bayerDither2x2

> **bayerDither2x2**(`inputColor`, `levels?`, `scale?`, `screenCoord?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/retro/bayerDither.ts:173](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/retro/bayerDither.ts#L173)

Apply 2x2 Bayer matrix ordered dithering.
Creates a coarse dither pattern - good for very low resolution retro effects.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### levels?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `2`

Number of color levels per channel (default: 2 = binary)

### scale?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Scale of dither pattern (default: 1)

### screenCoord?

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Screen coordinates (use UV * textureSize for per-sprite)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Dithered color

## Example

```ts
// Binary dithering on sprite
bayerDither2x2(color, 2, 1, uv().mul(textureSize))
```

# bayerDither4x4

> **bayerDither4x4**(`inputColor`, `levels?`, `scale?`, `screenCoord?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/retro/bayerDither.ts:214](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/retro/bayerDither.ts#L214)

Apply 4x4 Bayer matrix ordered dithering.
Standard dither pattern - good balance of quality and retro aesthetic.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### levels?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `2`

Number of color levels per channel (default: 2 = binary)

### scale?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Scale of dither pattern (default: 1)

### screenCoord?

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Screen coordinates (use UV * textureSize for per-sprite)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Dithered color

## Example

```ts
// 4-level dithering for retro look
bayerDither4x4(color, 4, 1, uv().mul(textureSize))
```

# bayerDither8x8

> **bayerDither8x8**(`inputColor`, `levels?`, `scale?`, `screenCoord?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/retro/bayerDither.ts:254](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/retro/bayerDither.ts#L254)

Apply 8x8 Bayer matrix ordered dithering.
Fine dither pattern - smoother gradients while maintaining retro feel.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### levels?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `2`

Number of color levels per channel (default: 2 = binary)

### scale?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Scale of dither pattern (default: 1)

### screenCoord?

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Screen coordinates (use UV * textureSize for per-sprite)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Dithered color

## Example

```ts
// 8-level dithering for smoother retro effect
bayerDither8x8(color, 8, 1, uv().mul(textureSize))
```

# bloom

> **bloom**(`inputColor`, `bloomTex`, `uv`, `intensity?`, `tint?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/bloom.ts:63](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/bloom.ts#L63)

Apply bloom effect using pre-blurred bright texture.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Original scene color

### bloomTex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Pre-extracted and blurred bloom texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Bloom intensity (default: 1)

### tint?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Bloom color tint (default: white)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with bloom applied

## Example

```ts
const final = bloom(sceneColor, bloomBlurredTexture, uv, 1.2, [1, 0.95, 0.9])
```

# bloomAnamorphic

> **bloomAnamorphic**(`inputColor`, `bloomTex`, `uv`, `intensity?`, `tint?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/bloom.ts:123](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/bloom.ts#L123)

Anamorphic bloom - horizontal streak effect.
Common in film and sci-fi aesthetics.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color

### bloomTex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Horizontally blurred bloom texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Streak intensity

### tint?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Streak color tint (often slightly colored)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with anamorphic bloom

# bloomSimple

> **bloomSimple**(`tex`, `uv`, `threshold?`, `radius?`, `intensity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/bloom.ts:150](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/bloom.ts#L150)

Simple single-pass bloom approximation.
Samples in a star pattern for quick glow effect.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### threshold?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.7`

Brightness threshold

### radius?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.01`

Glow radius

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Glow intensity

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with bloom approximation

# bloomThreshold

> **bloomThreshold**(`inputColor`, `threshold?`, `softThreshold?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/bloom.ts:25](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/bloom.ts#L25)

Extract bright areas for bloom effect.
Returns only pixels above a brightness threshold.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color (vec4)

### threshold?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.8`

Brightness threshold (0-1, default: 0.8)

### softThreshold?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.1`

Soft threshold knee (0-1, default: 0.1)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Extracted bright areas

## Example

```ts
const brights = bloomThreshold(inputColor, 0.8)
const blurred = blurKawase(brights, uv, ...)
const final = inputColor.add(blurred)
```

# blurBox

> **blurBox**(`tex`, `uv`, `radius?`, `samples?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/blurBox.ts:19](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/blurBox.ts#L19)

Simple box blur with uniform weights.
Faster than Gaussian but produces more blocky results.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### radius?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.01`

Blur radius in UV space

### samples?

`number` = `3`

Number of samples per axis (default: 3)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Blurred color

## Example

```ts
const blurred = blurBox(texture, uv, 0.01, 5)
```

# blurBox3x3

> **blurBox3x3**(`tex`, `uv`, `texelSize?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/blurBox.ts:80](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/blurBox.ts#L80)

Fast 3x3 box blur.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### texelSize?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Size of one texel

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Blurred color

# blurBoxDirectional

> **blurBoxDirectional**(`tex`, `uv`, `direction?`, `radius?`, `samples?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/blurBox.ts:51](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/blurBox.ts#L51)

Directional box blur.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### direction?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Blur direction

### radius?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.01`

Blur radius

### samples?

`number` = `5`

Number of samples

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Blurred color

# blurBoxSmooth

> **blurBoxSmooth**(`tex`, `uv`, `radius?`, `softness?`, `samples?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/blurBox.ts:114](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/blurBox.ts#L114)

Variable-size box blur with smooth edges.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### radius?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.01`

Blur radius

### softness?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Edge softness (0 = sharp box, 1 = smooth falloff)

### samples?

`number` = `5`

Number of samples per axis

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Blurred color

# blurFocus

> **blurFocus**(`tex`, `uv`, `center?`, `focusRadius?`, `blurAmount?`, `samples?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/blurRadial.ts:141](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/blurRadial.ts#L141)

Focus blur - sharp in center, blurred at edges.
Simulates depth of field or tilt-shift effect.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### center?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Focus center point

### focusRadius?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.2`

Radius of sharp focus area

### blurAmount?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.02`

Maximum blur at edges

### samples?

`number` = `5`

Blur quality

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Focus-blurred color

# blurGaussian

> **blurGaussian**(`tex`, `uv`, `direction?`, `radius?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/blurGaussian.ts:21](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/blurGaussian.ts#L21)

Gaussian blur using a 5-tap kernel.
Provides smooth, natural-looking blur with minimal samples.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### direction?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Blur direction (use [1,0] for horizontal, [0,1] for vertical)

### radius?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.01`

Blur radius in UV space (default: 0.01)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Blurred color

## Example

```ts
// Two-pass Gaussian blur (horizontal then vertical)
const blurH = blurGaussian(texture, uv, [1, 0], 0.01)
const blurV = blurGaussian(blurH, uv, [0, 1], 0.01)
```

# blurGaussian2Pass

> **blurGaussian2Pass**(`tex`, `uv`, `radius?`, `texelSize?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/blurGaussian.ts:96](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/blurGaussian.ts#L96)

Simple two-pass Gaussian blur helper.
Applies horizontal then vertical blur.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### radius?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.01`

Blur radius

### texelSize?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Size of one texel (for proper scaling)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Blurred color

# blurGaussian9

> **blurGaussian9**(`tex`, `uv`, `direction?`, `radius?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/blurGaussian.ts:59](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/blurGaussian.ts#L59)

Higher quality 9-tap Gaussian blur.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### direction?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Blur direction

### radius?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.01`

Blur radius

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Blurred color

# blurKawase

> **blurKawase**(`tex`, `uv`, `offset?`, `texelSize?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/blurKawase.ts:23](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/blurKawase.ts#L23)

Kawase blur - fast, iterative blur technique.
Used in many games for efficient bloom/blur effects.
Each iteration doubles the effective blur radius.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### offset?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0`

Current iteration offset (increases each pass)

### texelSize?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Size of one texel in UV space

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Blurred color for this iteration

## Example

```ts
// Multi-pass Kawase blur
let blurred = blurKawase(texture, uv, 0, [1/width, 1/height])
blurred = blurKawase(blurred, uv, 1, [1/width, 1/height])
blurred = blurKawase(blurred, uv, 2, [1/width, 1/height])
```

# blurKawaseDown

> **blurKawaseDown**(`tex`, `uv`, `texelSize?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/blurKawase.ts:87](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/blurKawase.ts#L87)

Dual Kawase blur downscale pass.
Used in dual-filter blur approach for efficient large blurs.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### texelSize?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Texel size at current resolution

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Downscaled blurred color

# blurKawaseMulti

> **blurKawaseMulti**(`tex`, `uv`, `iterations?`, `texelSize?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/blurKawase.ts:150](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/blurKawase.ts#L150)

Multi-iteration Kawase blur in a single pass (approximation).
Useful when multiple render passes aren't available.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### iterations?

`number` = `3`

Number of blur iterations to simulate

### texelSize?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Texel size

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Blurred color

# blurKawaseSimple

> **blurKawaseSimple**(`tex`, `uv`, `radius?`, `texelSize?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/blurKawase.ts:55](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/blurKawase.ts#L55)

Single-pass approximation of multi-iteration Kawase blur.
Samples at multiple offsets in one pass.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### radius?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `2`

Blur radius

### texelSize?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Texel size

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Blurred color

# blurKawaseUp

> **blurKawaseUp**(`tex`, `uv`, `texelSize?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/blurKawase.ts:116](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/blurKawase.ts#L116)

Dual Kawase blur upscale pass.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### texelSize?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Texel size at current resolution

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Upscaled blurred color

# blurMotion

> **blurMotion**(`tex`, `uv`, `direction`, `strength?`, `samples?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/blurMotion.ts:21](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/blurMotion.ts#L21)

Directional motion blur.
Simulates motion in a specific direction.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### direction

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/)

Motion direction (vec2)

### strength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.05`

Blur strength/length (default: 0.05)

### samples?

`number` = `8`

Number of blur samples (default: 8)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Motion-blurred color

## Example

```ts
// Horizontal motion blur
const blurred = blurMotion(texture, uv, [1, 0], 0.05)
```

# blurMotionObject

> **blurMotionObject**(`tex`, `uv`, `velocity`, `maxBlur?`, `samples?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/blurMotion.ts:90](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/blurMotion.ts#L90)

Object motion blur with depth consideration.
Samples more in the direction of motion.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### velocity

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/)

Velocity at this pixel

### maxBlur?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.1`

Maximum blur length

### samples?

`number` = `8`

Number of samples

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Motion-blurred color

# blurMotionVelocity

> **blurMotionVelocity**(`tex`, `uv`, `velocity`, `scale?`, `samples?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/blurMotion.ts:57](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/blurMotion.ts#L57)

Velocity-based motion blur.
Blur strength and direction based on velocity vector.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### velocity

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/)

Velocity vector (direction and magnitude)

### scale?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Velocity to blur scale (default: 1)

### samples?

`number` = `8`

Number of samples

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Velocity-blurred color

## Example

```ts
const blurred = blurMotionVelocity(texture, uv, velocityTexture.rg)
```

# blurRadial

> **blurRadial**(`tex`, `uv`, `center?`, `strength?`, `samples?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/blurRadial.ts:20](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/blurRadial.ts#L20)

Radial blur (zoom blur) emanating from a center point.
Creates a motion blur effect as if zooming in/out.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### center?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Center point of the blur (default: [0.5, 0.5])

### strength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.1`

Blur strength (default: 0.1)

### samples?

`number` = `8`

Number of blur samples (default: 8)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Radially blurred color

## Example

```ts
const zoomed = blurRadial(texture, uv, [0.5, 0.5], 0.1)
```

# blurRadialDistance

> **blurRadialDistance**(`tex`, `uv`, `center?`, `strength?`, `samples?`, `falloff?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/blurRadial.ts:57](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/blurRadial.ts#L57)

Radial blur with distance-based intensity.
Blur strength increases with distance from center.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### center?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Center point

### strength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.1`

Base blur strength

### samples?

`number` = `8`

Number of samples

### falloff?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `2`

How much blur increases with distance

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Radially blurred color

# blurShake

> **blurShake**(`tex`, `uv`, `intensity?`, `samples?`, `seed?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/blurMotion.ts:132](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/blurMotion.ts#L132)

Camera shake blur effect.
Simulates the blur from camera vibration.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.01`

Shake intensity

### samples?

`number` = `5`

Number of samples

### seed?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0`

Random seed for shake pattern

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Shake-blurred color

# blurSpin

> **blurSpin**(`tex`, `uv`, `center?`, `angle?`, `samples?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/blurRadial.ts:97](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/blurRadial.ts#L97)

Spin blur - circular motion blur around a center point.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### center?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Center of rotation

### angle?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.1`

Total rotation angle in radians

### samples?

`number` = `8`

Number of samples

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Spin-blurred color

# brightness

> **brightness**(`inputColor`, `amount`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/color/brightness.ts:20](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/color/brightness.ts#L20)

Adjust brightness by adding a value to all color channels.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### amount

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Brightness adjustment (-1 to 1, 0 = no change)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with adjusted brightness

## Examples

```ts
// Brighten by 20%
brightness(texture(tex, uv()), 0.2)
```

```ts
// Darken
brightness(texture(tex, uv()), -0.3)
```

# brightnessClamped

> **brightnessClamped**(`inputColor`, `amount`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/color/brightness.ts:53](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/color/brightness.ts#L53)

Adjust brightness with clamping to prevent overflow.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### amount

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Brightness adjustment (-1 to 1)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with adjusted brightness, clamped to 0-1

# brightnessMultiply

> **brightnessMultiply**(`inputColor`, `factor`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/color/brightness.ts:40](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/color/brightness.ts#L40)

Adjust brightness multiplicatively (exposure-like).

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### factor

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Brightness factor (1 = no change, >1 = brighter, <1 = darker)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with adjusted brightness

## Example

```ts
// Double brightness
brightnessMultiply(texture(tex, uv()), 2)
```

# c64Palette

> **c64Palette**(`inputColor`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/retro/consolePalettes.ts:230](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/retro/consolePalettes.ts#L230)

Commodore 64 palette approximation.
16 fixed colors with characteristic look.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color mapped to C64-like palette

# cgaPalette

> **cgaPalette**(`inputColor`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/retro/consolePalettes.ts:206](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/retro/consolePalettes.ts#L206)

CGA 4-color palette (Mode 4, Palette 1).
Classic PC palette: black, cyan, magenta, white.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color mapped to CGA palette

# chromaticAberration

> **chromaticAberration**(`tex`, `uv`, `amount?`, `angle?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/analog/chromaticAberration.ts:19](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/analog/chromaticAberration.ts#L19)

Chromatic aberration effect - separates RGB channels.
Simulates lens imperfection or analog video artifacts.

## Parameters

### tex

[`TextureNode`](https://threejs.org/docs/)\<`"vec4"`\>

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### amount?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.005`

Separation amount in UV space (default: 0.005)

### angle?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0`

Separation angle in radians (default: 0 = horizontal)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with chromatic aberration

## Example

```ts
const aberrated = chromaticAberration(texture, uv, 0.005)
```

# chromaticAberrationCustom

> **chromaticAberrationCustom**(`tex`, `uv`, `redOffset?`, `blueOffset?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/analog/chromaticAberration.ts:86](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/analog/chromaticAberration.ts#L86)

Asymmetric chromatic aberration with separate RGB offsets.

## Parameters

### tex

[`TextureNode`](https://threejs.org/docs/)\<`"vec4"`\>

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### redOffset?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Red channel offset

### blueOffset?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Blue channel offset

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with custom chromatic aberration

# chromaticAberrationPulse

> **chromaticAberrationPulse**(`tex`, `uv`, `time`, `baseAmount?`, `pulseAmount?`, `speed?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/analog/chromaticAberration.ts:114](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/analog/chromaticAberration.ts#L114)

Pulsing/animated chromatic aberration.

## Parameters

### tex

[`TextureNode`](https://threejs.org/docs/)\<`"vec4"`\>

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### time

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Animation time

### baseAmount?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.002`

Base aberration amount

### pulseAmount?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.003`

Additional pulse amount

### speed?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `2`

Animation speed

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Animated chromatic aberration

# chromaticAberrationRadial

> **chromaticAberrationRadial**(`tex`, `uv`, `amount?`, `center?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/analog/chromaticAberration.ts:50](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/analog/chromaticAberration.ts#L50)

Radial chromatic aberration - increases toward edges.
More realistic lens distortion simulation.

## Parameters

### tex

[`TextureNode`](https://threejs.org/docs/)\<`"vec4"`\>

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### amount?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.01`

Maximum aberration at edges

### center?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Center point of the effect

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with radial chromatic aberration

# colorBleeding

> **colorBleeding**(`tex`, `uv`, `amount?`, `samples?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/analog/videoArtifacts.ts:16](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/analog/videoArtifacts.ts#L16)

Color bleeding/smearing effect.
Simulates horizontal color bleeding in composite video signals.

## Parameters

### tex

[`TextureNode`](https://threejs.org/docs/)\<`"vec4"`\>

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### amount?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.003`

Bleed amount (default: 0.003)

### samples?

`number` = `4`

Number of samples (default: 4)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with bleeding effect

# colorRemap

> **colorRemap**(`inputColor`, `gradientTex`, `strength?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/color/colorRemap.ts:28](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/color/colorRemap.ts#L28)

Remap colors using a gradient texture (LUT) based on luminance.
The gradient texture should be a horizontal strip where left = dark, right = bright.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### gradientTex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Horizontal gradient texture for color lookup

### strength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Effect strength (0 = original, 1 = fully remapped)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color remapped through gradient

## Examples

```ts
// Remap colors through a fire gradient
colorRemap(texture(tex, uv()), fireGradientTexture)
```

```ts
// Partial remap with uniform
colorRemap(texture(tex, uv()), gradientTex, strengthUniform)
```

# colorRemapCustom

> **colorRemapCustom**(`inputColor`, `gradientTex`, `lookupValue`, `strength?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/color/colorRemap.ts:62](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/color/colorRemap.ts#L62)

Remap colors using a custom channel for lookup instead of luminance.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### gradientTex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Horizontal gradient texture for color lookup

### lookupValue

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Custom value for gradient lookup (0-1)

### strength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Effect strength (0 = original, 1 = fully remapped)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color remapped through gradient

## Example

```ts
// Remap based on red channel
colorRemapCustom(texture(tex, uv()), gradientTex, inputColor.r)
```

# colorReplace

> **colorReplace**(`inputColor`, `targetColor`, `replaceColor`, `tolerance?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/retro/colorReplace.ts:23](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/retro/colorReplace.ts#L23)

Replace a target color with a new color.
Uses smooth tolerance for anti-aliased sprites (smooth falloff at edges).

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### targetColor

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/)

Color to find and replace (RGB tuple or vec3 node)

### replaceColor

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/)

Color to replace with (RGB tuple or vec3 node)

### tolerance?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.1`

Match tolerance (default: 0.1)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with replacement applied

## Examples

```ts
// Swap red for blue
colorReplace(color, [1, 0, 0], [0, 0, 1], 0.1)
```

```ts
// Create team color variants with uniform
colorReplace(color, baseColor, teamColorUniform, 0.15)
```

# colorReplaceHard

> **colorReplaceHard**(`inputColor`, `targetColor`, `replaceColor`, `tolerance?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/retro/colorReplace.ts:64](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/retro/colorReplace.ts#L64)

Replace a target color with a new color using hard cutoff (no blending).
Good for pixel art with exact color matching.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### targetColor

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/)

Color to find and replace (RGB tuple or vec3 node)

### replaceColor

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/)

Color to replace with (RGB tuple or vec3 node)

### tolerance?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.01`

Match tolerance (default: 0.01)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with replacement applied

## Example

```ts
// Exact color swap for pixel art
colorReplaceHard(color, [1, 0, 0], [0, 0, 1], 0.01)
```

# colorReplaceMultiple

> **colorReplaceMultiple**(`inputColor`, `sourceColors`, `targetColors`, `tolerance?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/retro/colorReplace.ts:110](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/retro/colorReplace.ts#L110)

Replace multiple colors at once (palette swap).
Each source color maps to a corresponding target color.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### sourceColors

\[`number`, `number`, `number`\][]

Array of colors to find (RGB tuples)

### targetColors

\[`number`, `number`, `number`\][]

Array of colors to replace with (RGB tuples)

### tolerance?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.1`

Match tolerance (default: 0.1)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with all replacements applied

## Example

```ts
// Swap entire character palette
colorReplaceMultiple(
  color,
  [[1, 0, 0], [0, 1, 0], [0, 0, 1]],  // Source: red, green, blue
  [[1, 0.5, 0], [0, 0.5, 0], [0.5, 0, 1]],  // Target: orange, dark green, purple
  0.15
)
```

# contrast

> **contrast**(`inputColor`, `amount`, `midpoint?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/color/contrast.ts:21](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/color/contrast.ts#L21)

Adjust contrast by scaling color values around a midpoint.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### amount

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Contrast factor (1 = no change, >1 = more contrast, <1 = less contrast)

### midpoint?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Center point for scaling (default: 0.5)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with adjusted contrast

## Examples

```ts
// Increase contrast
contrast(texture(tex, uv()), 1.5)
```

```ts
// Decrease contrast (flatten)
contrast(texture(tex, uv()), 0.5)
```

# contrastSCurve

> **contrastSCurve**(`inputColor`, `amount`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/color/contrast.ts:44](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/color/contrast.ts#L44)

Apply S-curve contrast (smoother, more natural-looking).
Uses smoothstep for a sigmoid-like curve.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### amount

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Contrast intensity (0 = no change, 1 = maximum)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with S-curve contrast

# crtBloom

> **crtBloom**(`tex`, `uv`, `intensity?`, `spread?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/display/crtEffects.ts:97](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/crtEffects.ts#L97)

CRT bloom/phosphor glow effect.
Simulates the characteristic glow of phosphor displays.

## Parameters

### tex

[`TextureNode`](https://threejs.org/docs/)\<`"vec4"`\>

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.3`

Bloom intensity (default: 0.3)

### spread?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.002`

Glow spread (default: 0.002)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with phosphor bloom

# crtColorBleed

> **crtColorBleed**(`tex`, `uv`, `amount?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/display/crtEffects.ts:135](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/crtEffects.ts#L135)

CRT color bleeding/smearing effect.
Simulates horizontal color bleeding in composite video.

## Parameters

### tex

[`TextureNode`](https://threejs.org/docs/)\<`"vec4"`\>

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### amount?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.002`

Bleeding amount (default: 0.002)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with bleeding effect

# crtComplete

> **crtComplete**(`tex`, `uv`, `options?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/display/crtEffects.ts:174](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/crtEffects.ts#L174)

## Parameters

### tex

[`TextureNode`](https://threejs.org/docs/)\<`"vec4"`\>

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

### options?

[`CRTOptions`](/three-flatland/api/nodes/src/interfaces/crtoptions/) = `{}`

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

# crtConvergence

> **crtConvergence**(`tex`, `uv`, `redOffset?`, `blueOffset?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/display/crtEffects.ts:223](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/crtEffects.ts#L223)

CRT convergence error simulation.
Misaligns RGB channels slightly like poorly calibrated CRTs.

## Parameters

### tex

[`TextureNode`](https://threejs.org/docs/)\<`"vec4"`\>

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### redOffset?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Red channel offset

### blueOffset?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Blue channel offset

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with convergence error

# crtCurvature

> **crtCurvature**(`uv`, `curvature?`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/display/crtEffects.ts:18](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/crtEffects.ts#L18)

CRT barrel/curvature distortion.
Simulates the curved glass of CRT monitors.

## Parameters

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Input UV coordinates

### curvature?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.1`

Curvature amount (default: 0.1)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Distorted UV coordinates

## Example

```ts
const curvedUV = crtCurvature(uv, 0.15)
const color = texture(tex, curvedUV)
```

# crtCurvatureWithCorners

> **crtCurvatureWithCorners**(`uv`, `curvature?`, `cornerDarkness?`): `object`

Defined in: [packages/nodes/src/display/crtEffects.ts:41](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/crtEffects.ts#L41)

CRT curvature with corner darkening.

## Parameters

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### curvature?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.1`

Curvature amount

### cornerDarkness?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.1`

How much corners darken (default: 0.1)

## Returns

`object`

Object with distorted UV and corner mask

### cornerMask

> **cornerMask**: [`Node`](https://threejs.org/docs/)\<`"float"`\>

### uv

> **uv**: [`Node`](https://threejs.org/docs/)\<`"vec2"`\> = `curved`

# crtVignette

> **crtVignette**(`inputColor`, `uv`, `intensity?`, `curvature?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/display/crtEffects.ts:70](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/crtEffects.ts#L70)

CRT vignette - darkens edges like old CRT displays.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.3`

Vignette strength (default: 0.3)

### curvature?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `2`

Edge curvature (default: 2)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with CRT vignette

# directionalLight2D

> **directionalLight2D**(`lightDir`, `lightColor?`, `intensity?`): [`Light2DResult`](/three-flatland/api/nodes/src/interfaces/light2dresult/)

Defined in: [packages/nodes/src/lighting/lights.ts:140](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/lights.ts#L140)

Calculate directional light (like sunlight) - infinite distance, uniform direction.

## Parameters

### lightDir

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/)

Direction the light is coming FROM (will be negated)

### lightColor?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Light color

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Light intensity

## Returns

[`Light2DResult`](/three-flatland/api/nodes/src/interfaces/light2dresult/)

Light2DResult with no distance attenuation

## Example

```ts
// Sun coming from top-right
const sun = directionalLight2D([1, 1], [1, 0.95, 0.9], 1.0)
```

# dissolve

> **dissolve**(`inputColor`, `inputUV`, `options`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/alpha/dissolve.ts:44](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/alpha/dissolve.ts#L44)

Dissolve effect using a noise texture.
Creates a burning/disintegration effect with a glowing edge.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### inputUV

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

The UV coordinates

### options

[`DissolveOptions`](/three-flatland/api/nodes/src/interfaces/dissolveoptions/)

Dissolve configuration

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with dissolve effect applied

## Examples

```ts
// Basic dissolve
dissolve(texture(tex, uv()), uv(), {
  progress: 0.5,
  noiseTex: noiseTexture,
})
```

```ts
// Dissolve with custom edge color
dissolve(texture(tex, uv()), uv(), {
  progress: dissolveUniform,
  noiseTex: noiseTexture,
  edgeColor: [0, 1, 0.5],
  edgeWidth: 0.15,
})
```

# dissolveDirectional

> **dissolveDirectional**(`inputColor`, `inputUV`, `progress`, `noiseTex`, `direction?`, `noiseStrength?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/alpha/dissolve.ts:173](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/alpha/dissolve.ts#L173)

Directional dissolve (wipe effect with noise).
Combines a directional gradient with noise for a more organic wipe.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### inputUV

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

The UV coordinates

### progress

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Dissolve progress (0-1)

### noiseTex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Noise texture

### direction?

`"up"` \| `"down"` \| `"left"` \| `"right"`

Wipe direction: 'left', 'right', 'up', 'down'

### noiseStrength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.3`

How much noise affects the wipe (0-1)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with directional dissolve effect

# dissolvePixelated

> **dissolvePixelated**(`inputColor`, `inputUV`, `progress`, `noiseTex`, `pixelCount?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/alpha/dissolve.ts:136](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/alpha/dissolve.ts#L136)

Pixelated dissolve effect - blocks disappear together in a pixel grid.
Creates a retro/8-bit style dissolve effect perfect for pixel art.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### inputUV

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

The UV coordinates (raw, not frame-mapped)

### progress

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Dissolve progress (0-1)

### noiseTex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Noise texture for dissolve pattern

### pixelCount?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `16`

Number of pixels in the grid (default: 16)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with pixelated dissolve effect

## Examples

```ts
// Basic pixelated dissolve
dissolvePixelated(color, uv(), dissolveProgress, noiseTexture)
```

```ts
// Coarser 8x8 pixel grid
dissolvePixelated(color, uv(), dissolveProgress, noiseTexture, 8)
```

# dissolveSimple

> **dissolveSimple**(`inputColor`, `inputUV`, `progress`, `noiseTex`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/alpha/dissolve.ts:98](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/alpha/dissolve.ts#L98)

Simple dissolve without edge glow.
More performant when edge effect isn't needed.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### inputUV

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

The UV coordinates

### progress

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Dissolve progress (0-1)

### noiseTex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Noise texture for dissolve pattern

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with simple dissolve effect

# distortBarrel

> **distortBarrel**(`uv`, `strength?`, `zoom?`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/distortion/distort.ts:124](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/distortion/distort.ts#L124)

Barrel distortion - simulates lens distortion.
Commonly used for CRT screen curvature simulation.

## Parameters

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Input UV coordinates (should be 0-1)

### strength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.1`

Distortion strength (positive = barrel, negative = pincushion)

### zoom?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Zoom adjustment to compensate for distortion (default: 1)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Distorted UV coordinates

## Example

```ts
// CRT-like barrel distortion
const curved = distortBarrel(uv, 0.2)
```

# distortBulge

> **distortBulge**(`uv`, `center?`, `strength?`, `radius?`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/distortion/distort.ts:50](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/distortion/distort.ts#L50)

Bulge distortion - pushes pixels away from center.

## Parameters

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Input UV coordinates

### center?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Bulge center point

### strength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.3`

Bulge strength (positive = bulge out)

### radius?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Effect radius in UV space

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Distorted UV coordinates

## Example

```ts
const bulged = distortBulge(uv, [0.5, 0.5], 0.3, 0.4)
```

# distortDisplace

> **distortDisplace**(`uv`, `displacement`, `strength?`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/distortion/distort.ts:223](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/distortion/distort.ts#L223)

Displacement map distortion - use a texture to distort UVs.

## Parameters

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Input UV coordinates

### displacement

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Displacement values (vec2 or from texture.rg)

### strength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.1`

Displacement strength

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Displaced UV coordinates

# distortNoise

> **distortNoise**(`uv`, `strength?`, `scale?`, `time?`, `speed?`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/distortion/distortNoise.ts:92](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/distortion/distortNoise.ts#L92)

Apply noise-based distortion to UV coordinates.
Uses simple value noise for displacement.

## Parameters

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Input UV coordinates

### strength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.02`

Distortion strength in UV space

### scale?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `10`

Noise scale (higher = finer detail)

### time?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0`

Animation time for moving noise

### speed?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Animation speed

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Noise-distorted UV coordinates

## Example

```ts
const distorted = distortNoise(uv, 0.03, 5, time)
```

# distortPerlin

> **distortPerlin**(`uv`, `strength?`, `scale?`, `time?`, `octaves?`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/distortion/distortNoise.ts:126](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/distortion/distortNoise.ts#L126)

Apply Perlin noise distortion for smoother, more organic displacement.

## Parameters

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Input UV coordinates

### strength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.02`

Distortion strength

### scale?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `5`

Noise scale

### time?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0`

Animation time

### octaves?

`number` = `1`

Number of noise octaves for detail (default: 1)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Perlin-distorted UV coordinates

## Example

```ts
const distorted = distortPerlin(uv, 0.02, 8, time, 2)
```

# distortPinch

> **distortPinch**(`uv`, `center?`, `strength?`, `radius?`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/distortion/distort.ts:17](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/distortion/distort.ts#L17)

Pinch distortion - pulls pixels toward center.

## Parameters

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Input UV coordinates

### center?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Pinch center point (default: [0.5, 0.5])

### strength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Pinch strength (positive = pinch in, negative = expand)

### radius?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Effect radius in UV space

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Distorted UV coordinates

## Example

```ts
const pinched = distortPinch(uv, [0.5, 0.5], 0.5, 0.5)
```

# distortPixelate

> **distortPixelate**(`uv`, `pixelSize?`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/distortion/distort.ts:158](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/distortion/distort.ts#L158)

Pixelate distortion - snaps UV to grid for chunky pixel effect.
Use for transitions or stylized rendering.

## Parameters

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Input UV coordinates

### pixelSize?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.05`

Size of each "pixel" in UV space (default: 0.05)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Pixelated UV coordinates

## Example

```ts
const pixelated = distortPixelate(uv, 0.02)
const color = texture(tex, pixelated)
```

# distortPixelateCount

> **distortPixelateCount**(`uv`, `pixelCount?`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/distortion/distort.ts:174](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/distortion/distort.ts#L174)

Pixelate with pixel count (more intuitive API).

## Parameters

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Input UV coordinates

### pixelCount?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `64`

Number of pixels across (default: 64)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Pixelated UV coordinates

# distortShatter

> **distortShatter**(`uv`, `fragments?`, `offset?`, `seed?`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/distortion/distort.ts:191](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/distortion/distort.ts#L191)

Shatter/fragment distortion - breaks image into polygonal pieces.
Creates a crystalline/broken glass effect.

## Parameters

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Input UV coordinates

### fragments?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `10`

Number of fragment divisions (default: 10)

### offset?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.02`

Maximum offset for each fragment (default: 0.02)

### seed?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0`

Random seed for fragment pattern

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Shattered UV coordinates

# distortSimplex

> **distortSimplex**(`uv`, `strength?`, `scale?`, `time?`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/distortion/distortNoise.ts:172](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/distortion/distortNoise.ts#L172)

Simplex-like noise distortion (approximation).
Faster than Perlin with similar quality.

## Parameters

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Input UV coordinates

### strength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.02`

Distortion strength

### scale?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `5`

Noise scale

### time?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0`

Animation time

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Simplex-distorted UV coordinates

# distortSpherize

> **distortSpherize**(`uv`, `center?`, `strength?`, `radius?`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/distortion/distort.ts:245](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/distortion/distort.ts#L245)

Spherize distortion - wraps UV onto a sphere surface.

## Parameters

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Input UV coordinates

### center?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Effect center

### strength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Spherize strength (0-1)

### radius?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Effect radius

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Spherized UV coordinates

# distortTurbulence

> **distortTurbulence**(`uv`, `strength?`, `scale?`, `time?`, `octaves?`, `lacunarity?`, `persistence?`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/distortion/distortNoise.ts:241](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/distortion/distortNoise.ts#L241)

Turbulent noise distortion with multiple octaves.
Creates a more chaotic, organic distortion pattern.

## Parameters

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Input UV coordinates

### strength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.03`

Distortion strength

### scale?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `4`

Base noise scale

### time?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0`

Animation time

### octaves?

`number` = `4`

Number of noise layers

### lacunarity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `2`

Frequency multiplier per octave (default: 2)

### persistence?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Amplitude multiplier per octave (default: 0.5)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Turbulence-distorted UV coordinates

# distortTwirl

> **distortTwirl**(`uv`, `center?`, `angle?`, `radius?`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/distortion/distort.ts:83](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/distortion/distort.ts#L83)

Twirl/swirl distortion - rotates pixels around center.

## Parameters

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Input UV coordinates

### center?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Twirl center point

### angle?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `...`

Maximum rotation angle in radians at center

### radius?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Effect radius (distortion fades to zero at edge)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Distorted UV coordinates

## Example

```ts
const twirled = distortTwirl(uv, [0.5, 0.5], Math.PI, 0.4)
```

# dmgPalette

> **dmgPalette**(`inputColor`, `contrast?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/retro/consolePalettes.ts:40](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/retro/consolePalettes.ts#L40)

Convert color to DMG Game Boy palette.
Uses the iconic green shades of the original DMG-01.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color (vec4)

### contrast?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Palette contrast adjustment (default: 1)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color mapped to DMG palette

## Example

```ts
const gameboy = dmgPalette(inputColor)
```

# dotMatrix

> **dotMatrix**(`input`, `uv`, `resolution?`, `pixelFill?`, `backgroundColor?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/display/lcd.ts:77](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/lcd.ts#L77)

Game Boy DMG-style dot matrix display.
Simulates the distinctive square-pixel LCD look of the original Game Boy.

When input is a TextureNode (has .sample()), it pixelates by snapping UVs
to pixel centers. When input is a computed color, applies pixel grid only.

Pixel edges are slightly soft to simulate the slow LCD crystal response
time characteristic of Game Boy hardware.

## Parameters

### input

[`Node`](https://threejs.org/docs/)\<`"vec4"`\> \| [`TextureNode`](https://threejs.org/docs/)\<`"vec4"`\>

Input color (TSLNode) or texture node (for pixelated sampling)

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### resolution?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `160`

Pixel resolution (default: 160 for GB)

### pixelFill?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.85`

Fill ratio of pixel within cell (default: 0.85)

### backgroundColor?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Color of LCD background between pixels

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with dot matrix effect

# eagle

> **eagle**(`tex`, `uv`, `texelSize?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/upscale/eagle.ts:18](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/upscale/eagle.ts#L18)

Eagle pixel art upscaling algorithm.
Simple 2x upscaler that enhances diagonal lines.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture (pixel art)

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### texelSize?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Size of one texel in source texture

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Upscaled color

## Example

```ts
const upscaled = eagle(texture, uv, [1/256, 1/256])
```

# fadeEdge

> **fadeEdge**(`inputColor`, `inputUV`, `edgeWidth?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/alpha/fadeEdge.ts:21](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/alpha/fadeEdge.ts#L21)

Fade alpha towards the edges of UV space using smoothstep.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### inputUV

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

The UV coordinates

### edgeWidth?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.1`

Width of the fade region (0-0.5, default: 0.1)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with edge-faded alpha

## Examples

```ts
// Fade edges with default width
fadeEdge(texture(tex, uv()), uv())
```

```ts
// Wide fade edge
fadeEdge(texture(tex, uv()), uv(), 0.3)
```

# fadeEdgeHorizontal

> **fadeEdgeHorizontal**(`inputColor`, `inputUV`, `edgeWidth?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/alpha/fadeEdge.ts:84](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/alpha/fadeEdge.ts#L84)

Fade alpha only on horizontal edges.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### inputUV

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

The UV coordinates

### edgeWidth?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.1`

Width of the fade region

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with horizontally faded alpha

# fadeEdgeRadial

> **fadeEdgeRadial**(`inputColor`, `inputUV`, `innerRadius?`, `outerRadius?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/alpha/fadeEdge.ts:57](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/alpha/fadeEdge.ts#L57)

Fade alpha in a circular pattern from center.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### inputUV

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

The UV coordinates

### innerRadius?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.3`

Radius where fade starts (0-1)

### outerRadius?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Radius where fully transparent (0-1)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with radial-faded alpha

## Example

```ts
// Circular fade from 0.3 to 0.5 radius
fadeEdgeRadial(texture(tex, uv()), uv(), 0.3, 0.5)
```

# fadeEdgeVertical

> **fadeEdgeVertical**(`inputColor`, `inputUV`, `edgeWidth?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/alpha/fadeEdge.ts:106](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/alpha/fadeEdge.ts#L106)

Fade alpha only on vertical edges.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### inputUV

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

The UV coordinates

### edgeWidth?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.1`

Width of the fade region

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with vertically faded alpha

# filmGrain

> **filmGrain**(`inputColor`, `uv`, `time`, `intensity?`, `luminanceInfluence?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/bloom.ts:231](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/bloom.ts#L231)

Film grain effect.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### time

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Animation time (for grain variation)

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.1`

Grain intensity (default: 0.1)

### luminanceInfluence?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

How much luminance affects grain (default: 0.5)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with film grain

# flash

> **flash**(`inputColor`, `progress`, `flashColor?`, `intensity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/flash.ts:19](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/flash.ts#L19)

Apply a flash effect - temporary color overlay that fades out.
Useful for damage feedback, power-ups, or emphasis.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Base color (vec4)

### progress

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Flash progress (0 = start, 1 = end/invisible)

### flashColor?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Color of the flash (default: white)

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Flash intensity at peak (default: 1)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with flash overlay

## Example

```ts
// Trigger flash on hit, animate progress from 0 to 1
const flashed = flash(inputColor, flashProgress, [1, 1, 1])
```

# flashAdditive

> **flashAdditive**(`inputColor`, `progress`, `flashColor?`, `intensity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/flash.ts:78](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/flash.ts#L78)

Additive flash that brightens without fully replacing color.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Base color

### progress

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Flash progress

### flashColor?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Color to add

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.8`

Flash intensity

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with additive flash

# flashAlpha

> **flashAlpha**(`inputColor`, `progress`, `flashColor?`, `alphaFlash?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/flash.ts:104](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/flash.ts#L104)

Flash that affects alpha as well (sprite becomes visible/invisible).

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Base color

### progress

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Flash progress

### flashColor?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Color of flash

### alphaFlash?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

How much to affect alpha (0 = none, 1 = fully visible at flash)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with alpha flash

# flashDamage

> **flashDamage**(`inputColor`, `progress`, `intensity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/flash.ts:130](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/flash.ts#L130)

Damage flash effect - quick red flash common in games.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Base color

### progress

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Flash progress (0 = hit, 1 = recovered)

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.7`

Flash intensity

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with damage flash

# flashHeal

> **flashHeal**(`inputColor`, `progress`, `intensity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/flash.ts:146](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/flash.ts#L146)

Healing flash effect - green glow.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Base color

### progress

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Flash progress

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.6`

Flash intensity

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with healing flash

# flashPowerUp

> **flashPowerUp**(`inputColor`, `progress`, `intensity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/flash.ts:162](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/flash.ts#L162)

Power-up flash with golden glow.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Base color

### progress

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Flash progress

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.8`

Flash intensity

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with power-up flash

# flashSmooth

> **flashSmooth**(`inputColor`, `progress`, `flashColor?`, `peakTime?`, `intensity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/flash.ts:47](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/flash.ts#L47)

Flash with smooth in and out transition.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Base color

### progress

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Flash progress (0-1)

### flashColor?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Color of flash

### peakTime?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.2`

When flash is brightest (0-1, default: 0.2)

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Peak intensity

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with smooth flash

# gbcPalette

> **gbcPalette**(`inputColor`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/retro/consolePalettes.ts:170](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/retro/consolePalettes.ts#L170)

Game Boy Color palette simulation.
15-bit color (5 bits per channel) with GBC's characteristic color response.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color quantized to GBC palette

# ghost

> **ghost**(`tex`, `uv`, `offsets`, `baseOpacity?`, `fadeWithDistance?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/afterimage.ts:108](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/afterimage.ts#L108)

Multiple ghost/clone effect at offset positions.
Creates several semi-transparent copies at fixed offsets.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### offsets

\[`number`, `number`\][]

Array of offset positions for ghosts

### baseOpacity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.3`

Opacity of each ghost (default: 0.3)

### fadeWithDistance?

`boolean` = `true`

Fade ghosts based on offset distance

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with ghost clones

## Example

```ts
const ghosts = ghost(texture, uv, [[0.02, 0], [0.04, 0], [0.06, 0]], 0.3)
```

# ghostSpeed

> **ghostSpeed**(`tex`, `uv`, `velocity`, `maxGhosts?`, `spacing?`, `opacity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/afterimage.ts:189](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/afterimage.ts#L189)

Speed ghost effect - ghosts that appear based on movement speed.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### velocity

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/)

Movement velocity

### maxGhosts?

`number` = `5`

Maximum number of ghosts at full speed

### spacing?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.015`

Base spacing between ghosts

### opacity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Ghost opacity

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with speed-based ghosts

# ghostTrail

> **ghostTrail**(`tex`, `uv`, `direction`, `count?`, `spacing?`, `opacity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/afterimage.ts:150](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/afterimage.ts#L150)

Directional ghost trail - creates ghosts along a direction.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### direction

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/)

Direction of ghost trail

### count?

`number` = `3`

Number of ghosts

### spacing?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.02`

Space between ghosts

### opacity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.4`

Ghost opacity

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with directional ghosts

# glowSelective

> **glowSelective**(`inputColor`, `targetColor`, `glowColor?`, `tolerance?`, `intensity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/bloom.ts:90](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/bloom.ts#L90)

Selective glow based on color matching.
Only applies glow to pixels matching a specific color.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color

### targetColor

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/)

Color to glow

### glowColor?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Color of the glow

### tolerance?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.2`

Color matching tolerance (default: 0.2)

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Glow intensity

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with selective glow

# grayscale

> **grayscale**(`inputColor`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/color/saturate.ts:49](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/color/saturate.ts#L49)

Convert color to grayscale using luminance weights.
Shorthand for saturate(color, 0).

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Grayscale color

## Example

```ts
grayscale(texture(tex, uv()))
```

# hq2x

> **hq2x**(`tex`, `uv`, `texelSize?`, `threshold?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/upscale/hq2x.ts:22](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/upscale/hq2x.ts#L22)

HQ2x-style pixel art upscaling (simplified GPU implementation).
High quality 2x upscaling that preserves edges while smoothing.

Note: This is a simplified approximation of the full HQ2x algorithm,
which requires lookup tables that are impractical for real-time GPU shaders.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture (pixel art)

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### texelSize?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Size of one texel in source texture

### threshold?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.05`

Color difference threshold (default: 0.05)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Upscaled color

## Example

```ts
const upscaled = hq2x(texture, uv, [1/256, 1/256])
```

# hq3x

> **hq3x**(`tex`, `uv`, `texelSize?`, `threshold?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/upscale/hq2x.ts:117](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/upscale/hq2x.ts#L117)

HQ3x-style upscaling (simplified).

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### texelSize?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Source texel size

### threshold?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.05`

Color difference threshold

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Upscaled color

# hq4x

> **hq4x**(`tex`, `uv`, `texelSize?`, `threshold?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/upscale/hq2x.ts:197](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/upscale/hq2x.ts#L197)

HQ4x-style upscaling (simplified).

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### texelSize?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Source texel size

### threshold?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.05`

Color difference threshold

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Upscaled color

# hueShift

> **hueShift**(`inputColor`, `angle`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/color/hueShift.ts:21](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/color/hueShift.ts#L21)

Shift the hue of a color using a rotation matrix in RGB space.
This is more efficient than RGB->HSV->RGB conversion.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### angle

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Hue shift angle in radians (0 to 2*PI for full cycle)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with shifted hue

## Examples

```ts
// Shift hue by 90 degrees
hueShift(texture(tex, uv()), Math.PI / 2)
```

```ts
// Animate rainbow effect
hueShift(texture(tex, uv()), timeUniform)
```

# hueShiftNormalized

> **hueShiftNormalized**(`inputColor`, `amount`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/color/hueShift.ts:63](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/color/hueShift.ts#L63)

Shift hue by a normalized amount (0-1 maps to 0-360 degrees).

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### amount

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Hue shift amount (0-1, wraps around)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with shifted hue

## Example

```ts
// Shift hue by 25%
hueShiftNormalized(texture(tex, uv()), 0.25)
```

# interlacing

> **interlacing**(`inputColor`, `uv`, `resolution?`, `field?`, `blendFactor?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/analog/videoArtifacts.ts:51](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/analog/videoArtifacts.ts#L51)

Interlacing effect.
Simulates interlaced video display with field alternation.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### resolution?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `480`

Vertical resolution

### field?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0`

Current field (0 or 1, alternate each frame)

### blendFactor?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

How much to blend inactive lines (default: 0.5)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with interlacing

# lcdBacklightBleed

> **lcdBacklightBleed**(`inputColor`, `uv`, `intensity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/display/lcd.ts:186](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/lcd.ts#L186)

LCD backlight bleed effect.
Simulates uneven backlight distribution.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.1`

Bleed intensity (default: 0.1)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with backlight bleed

# lcdGBC

> **lcdGBC**(`inputColor`, `uv`, `resolution?`, `gridIntensity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/display/lcd.ts:250](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/lcd.ts#L250)

Game Boy Color LCD simulation.
Slightly different grid pattern than GBA.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### resolution?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `160`

Display resolution

### gridIntensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.2`

Grid visibility

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with GBC LCD effect

# lcdGhosting

> **lcdGhosting**(`currentTex`, `previousTex`, `uv`, `persistence?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/display/lcd.ts:128](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/lcd.ts#L128)

LCD ghosting/motion blur effect.
Simulates the slow pixel response time of LCD displays.

## Parameters

### currentTex

[`TextureNode`](https://threejs.org/docs/)\<`"vec4"`\>

Current frame texture

### previousTex

[`TextureNode`](https://threejs.org/docs/)\<`"vec4"`\>

Previous frame texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### persistence?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.6`

Ghost persistence (default: 0.6)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with ghosting effect

# lcdGrid

> **lcdGrid**(`inputColor`, `uv`, `resolution?`, `gridIntensity?`, `subpixelIntensity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/display/lcd.ts:20](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/lcd.ts#L20)

LCD pixel grid effect.
Simulates the visible pixel structure of LCD/TFT displays like GBA.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color (vec4)

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### resolution?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `240`

Display resolution (default: 240 for GBA)

### gridIntensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.15`

Grid line darkness (default: 0.15)

### subpixelIntensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.1`

Subpixel structure visibility (default: 0.1)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with LCD grid effect

## Example

```ts
const gba = lcdGrid(inputColor, uv, 240, 0.15)
```

# lcdMotionGhost

> **lcdMotionGhost**(`tex`, `uv`, `velocity`, `persistence?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/display/lcd.ts:163](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/lcd.ts#L163)

Simple LCD persistence effect (single texture version).
Creates motion blur by blending with offset samples.

## Parameters

### tex

[`TextureNode`](https://threejs.org/docs/)\<`"vec4"`\>

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### velocity

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Motion direction and speed

### persistence?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.4`

Ghost amount

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with motion ghosting

# lcdPocket

> **lcdPocket**(`inputColor`, `uv`, `resolution?`, `contrast?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/display/lcd.ts:211](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/lcd.ts#L211)

Game Boy Pocket LCD effect.
Gray-scale LCD simulation with distinctive look.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color (will be converted to grayscale)

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### resolution?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `160`

Pixel resolution

### contrast?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1.2`

Display contrast

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with GB Pocket LCD effect

# litCelShaded

> **litCelShaded**(`normal`, `lightDir`, `surfaceColor`, `lightColor?`, `attenuation?`, `bands?`, `shadowColor?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/lighting/lit.ts:128](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/lit.ts#L128)

Calculate cel-shaded (toon) lighting with hard bands.

## Parameters

### normal

[`Node`](https://threejs.org/docs/)\<`"vec3"`\>

Surface normal

### lightDir

[`Node`](https://threejs.org/docs/)\<`"vec3"`\>

Direction to light

### surfaceColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Base surface color

### lightColor?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Light color

### attenuation?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Light attenuation

### bands?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `3`

Number of shading bands (default: 3)

### shadowColor?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/)

Color of shadowed areas (default: darker version of surface)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Cel-shaded color (vec4)

## Example

```ts
const toon = litCelShaded(normal, light.direction, inputColor, light.color, light.attenuation, 3)
```

# litDiffuse

> **litDiffuse**(`normal`, `lightDir`, `surfaceColor`, `lightColor`, `attenuation?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/lighting/lit.ts:20](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/lit.ts#L20)

Calculate diffuse (Lambertian) lighting.
Basic directional shading based on surface normal and light direction.

## Parameters

### normal

[`Node`](https://threejs.org/docs/)\<`"vec3"`\>

Surface normal (normalized vec3 in tangent space)

### lightDir

[`Node`](https://threejs.org/docs/)\<`"vec3"`\>

Direction to light (normalized vec3)

### surfaceColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Base surface color (vec4)

### lightColor

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/)

Light color (vec3)

### attenuation?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Light attenuation factor (0-1)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Lit surface color (vec4)

## Example

```ts
const lit = litDiffuse(normal, light.direction, inputColor, light.color, light.attenuation)
```

# litRim

> **litRim**(`normal`, `viewDir?`, `rimColor?`, `rimPower?`, `rimStrength?`): [`Node`](https://threejs.org/docs/)\<`"vec3"`\>

Defined in: [packages/nodes/src/lighting/lit.ts:94](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/lit.ts#L94)

Calculate rim/fresnel lighting effect.
Creates a glow around edges when viewed from an angle.

## Parameters

### normal

[`Node`](https://threejs.org/docs/)\<`"vec3"`\>

Surface normal

### viewDir?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Direction to camera/viewer

### rimColor?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Rim light color

### rimPower?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `2`

Rim falloff exponent (higher = tighter rim)

### rimStrength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Rim intensity multiplier

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec3"`\>

Rim light color (vec3, add to other lighting)

## Example

```ts
const rim = litRim(normal, [0, 0, 1], [0.5, 0.8, 1], 3, 1)
```

# litSpecular

> **litSpecular**(`normal`, `lightDir`, `viewDir?`, `lightColor?`, `attenuation?`, `shininess?`, `specularStrength?`): [`Node`](https://threejs.org/docs/)\<`"vec3"`\>

Defined in: [packages/nodes/src/lighting/lit.ts:54](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/lit.ts#L54)

Calculate specular highlights (Blinn-Phong model).

## Parameters

### normal

[`Node`](https://threejs.org/docs/)\<`"vec3"`\>

Surface normal

### lightDir

[`Node`](https://threejs.org/docs/)\<`"vec3"`\>

Direction to light

### viewDir?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Direction to camera/viewer (default: straight up/forward)

### lightColor?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Light color

### attenuation?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Light attenuation

### shininess?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `32`

Specular power/tightness (higher = smaller, sharper highlight)

### specularStrength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Specular intensity multiplier

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec3"`\>

Specular highlight color (vec3, add to diffuse result)

## Example

```ts
const spec = litSpecular(normal, light.direction, viewDir, light.color, light.attenuation, 32, 0.5)
```

# litSprite

> **litSprite**(`normal`, `surfaceColor`, `light`, `ambient?`, `options?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/lighting/lit.ts:282](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/lit.ts#L282)

## Parameters

### normal

[`Node`](https://threejs.org/docs/)\<`"vec3"`\>

### surfaceColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

### light

[`Light2DResult`](/three-flatland/api/nodes/src/interfaces/light2dresult/)

### ambient?

[`Light2DResult`](/three-flatland/api/nodes/src/interfaces/light2dresult/)

### options?

[`LitSpriteOptions`](/three-flatland/api/nodes/src/interfaces/litspriteoptions/) = `{}`

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

# litSpriteMulti

> **litSpriteMulti**(`normal`, `surfaceColor`, `lights`, `ambient?`, `options?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/lighting/lit.ts:177](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/lit.ts#L177)

Combined sprite lighting with multiple lights.
Accumulates diffuse (and optionally specular) contributions from all lights,
adds ambient, and optionally applies rim lighting.

## Parameters

### normal

[`Node`](https://threejs.org/docs/)\<`"vec3"`\>

Surface normal (normalized vec3)

### surfaceColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Base surface color (vec4)

### lights

[`Light2DResult`](/three-flatland/api/nodes/src/interfaces/light2dresult/)[]

Array of Light2DResult from point/spot/directional lights

### ambient?

[`Light2DResult`](/three-flatland/api/nodes/src/interfaces/light2dresult/)

Optional ambient Light2DResult

### options?

[`LitSpriteOptions`](/three-flatland/api/nodes/src/interfaces/litspriteoptions/) = `{}`

Additional lighting options

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Fully lit color (vec4)

## Example

```ts
const result = litSpriteMulti(normal, baseColor, [torch1, torch2], ambient, {
  specular: true,
  shininess: 32,
})
```

# md9bitPalette

> **md9bitPalette**(`inputColor`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/retro/consolePalettes.ts:127](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/retro/consolePalettes.ts#L127)

Convert color to Sega Genesis/Mega Drive 9-bit palette.
VDP outputs 512 possible colors (3 bits per channel).

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color quantized to 9-bit color space

# normalFromHeight

> **normalFromHeight**(`heightTex`, `uv`, `strength?`, `texelSize?`): [`Node`](https://threejs.org/docs/)\<`"vec3"`\>

Defined in: [packages/nodes/src/lighting/normalFromHeight.ts:20](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/normalFromHeight.ts#L20)

Generate a normal map from a heightmap texture.
Uses Sobel-like sampling to compute surface normals from grayscale height data.

## Parameters

### heightTex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Heightmap texture (grayscale, white = high, black = low)

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates to sample

### strength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Normal strength multiplier (default: 1)

### texelSize?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/)

Size of one texel in UV space, or calculated from texture dimensions

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec3"`\>

Normal vector in tangent space (vec3, -1 to 1 range)

## Example

```ts
// Generate normals from heightmap
const normals = normalFromHeight(heightmap, spriteUV, 2.0)
```

# normalFromHeightSmooth

> **normalFromHeightSmooth**(`heightTex`, `uv`, `strength?`, `scale?`): [`Node`](https://threejs.org/docs/)\<`"vec3"`\>

Defined in: [packages/nodes/src/lighting/normalFromHeight.ts:64](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/normalFromHeight.ts#L64)

Generate a normal map from a heightmap with adjustable detail.
Uses a larger sampling kernel for smoother normals.

## Parameters

### heightTex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Heightmap texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### strength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Normal strength multiplier

### scale?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `2`

Sampling scale (higher = smoother but less detail)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec3"`\>

Normal vector in tangent space

# ntscComposite

> **ntscComposite**(`tex`, `uv`, `artifactIntensity?`, `bleedAmount?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/analog/videoArtifacts.ts:80](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/analog/videoArtifacts.ts#L80)

NTSC composite video artifact simulation.
Simplified version of composite video encoding artifacts.

## Parameters

### tex

[`TextureNode`](https://threejs.org/docs/)\<`"vec4"`\>

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### artifactIntensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.3`

Artifact visibility (default: 0.3)

### bleedAmount?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.002`

Color bleed amount (default: 0.002)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with NTSC artifacts

# outline

> **outline**(`inputColor`, `inputUV`, `tex`, `options?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/sprite/outline.ts:37](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/sprite/outline.ts#L37)

Add an outline effect by sampling neighboring pixels.
Detects edges based on alpha differences and draws outline around opaque areas.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (typically texture sample result)

### inputUV

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

The UV coordinates

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

The texture to sample for neighbor detection

### options?

[`OutlineOptions`](/three-flatland/api/nodes/src/interfaces/outlineoptions/) = `{}`

Outline configuration

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with outline applied

## Examples

```ts
// Basic white outline
outline(texture(tex, uv()), uv(), tex, { color: [1, 1, 1, 1] })
```

```ts
// Glowing outline with custom thickness
outline(texture(tex, uv()), uv(), tex, {
  color: [0, 1, 0, 1],
  thickness: 0.02,
  textureSize: [64, 64]
})
```

# outline8

> **outline8**(`inputColor`, `inputUV`, `tex`, `options?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/sprite/outline.ts:90](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/sprite/outline.ts#L90)

Add an outline effect with 8-directional sampling for smoother edges.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (typically texture sample result)

### inputUV

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

The UV coordinates

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

The texture to sample for neighbor detection

### options?

[`OutlineOptions`](/three-flatland/api/nodes/src/interfaces/outlineoptions/) = `{}`

Outline configuration

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with outline applied

# palettize

> **palettize**(`inputColor`, `paletteTex`, `strength?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/retro/palettize.ts:31](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/retro/palettize.ts#L31)

Map colors to nearest match in a palette texture.
Palette should be a 1D horizontal texture (Nx1 pixels).

This function samples the palette by computing the luminance of the input color
and using it to index into the palette texture.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### paletteTex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Palette texture (horizontal strip)

### strength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Effect strength (0 = original, 1 = fully palettized)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color snapped to palette

## Examples

```ts
// Apply GameBoy palette
palettize(color, gbPaletteTexture)
```

```ts
// Partial palette effect
palettize(color, retroPalette, 0.5)
```

# palettizeDithered

> **palettizeDithered**(`inputColor`, `paletteTex`, `paletteSize`, `dither?`, `screenCoord?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/retro/palettize.ts:106](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/retro/palettize.ts#L106)

Map colors to palette with dithering for smoother transitions.
Uses Bayer matrix dithering to blend between palette colors.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### paletteTex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Palette texture (horizontal strip)

### paletteSize

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Number of colors in palette

### dither?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Dither strength between palette colors (0-1, default: 0.5)

### screenCoord?

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Screen coordinates for dithering pattern

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color snapped to palette with dithering

## Examples

```ts
// GameBoy 4-color palette with dithering
palettizeDithered(color, gbPalette, 4, 0.5, uv().mul(textureSize))
```

```ts
// C64 palette with strong dithering
palettizeDithered(color, c64Palette, 16, 0.8, screenCoord)
```

# palettizeNearest

> **palettizeNearest**(`inputColor`, `paletteTex`, `paletteSize`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/retro/palettize.ts:151](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/retro/palettize.ts#L151)

Find nearest color in palette by comparing RGB distance.
More accurate than luminance-based but more expensive.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### paletteTex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Palette texture (horizontal strip)

### paletteSize

`number`

Number of colors in palette (max 16)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color snapped to nearest palette color

## Example

```ts
// Find nearest color in 8-color palette
palettizeNearest(color, palette8, 8)
```

# phosphorApertureGrille

> **phosphorApertureGrille**(`inputColor`, `uv`, `resolution?`, `intensity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/display/phosphorMask.ts:18](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/phosphorMask.ts#L18)

Aperture grille phosphor mask (Trinitron-style).
Vertical RGB stripes like Sony Trinitron CRTs.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color (vec4)

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### resolution?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `640`

Horizontal resolution (default: 640)

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.3`

Mask intensity (default: 0.3)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with aperture grille effect

## Example

```ts
const trinitron = phosphorApertureGrille(inputColor, uv, 640, 0.25)
```

# phosphorMask

> **phosphorMask**(`inputColor`, `uv`, `maskType?`, `resolution?`, `intensity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/display/phosphorMask.ts:177](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/phosphorMask.ts#L177)

Customizable phosphor mask with configurable pattern.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### maskType?

`"slot"` \| `"aperture"` \| `"shadow"`

Type: 'aperture', 'slot', or 'shadow'

### resolution?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `640`

Resolution scale

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.3`

Mask intensity

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with phosphor mask

# phosphorShadowMask

> **phosphorShadowMask**(`inputColor`, `uv`, `resolution?`, `intensity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/display/phosphorMask.ts:99](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/phosphorMask.ts#L99)

Shadow mask phosphor pattern.
Triangular/delta arrangement of phosphor dots.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### resolution?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `300`

Resolution scale

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.3`

Mask intensity

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with shadow mask effect

# phosphorSimple

> **phosphorSimple**(`inputColor`, `screenCoord`, `scale?`, `intensity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/display/phosphorMask.ts:146](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/phosphorMask.ts#L146)

Simple RGB stripe mask (lightweight version).

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color

### screenCoord

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Screen coordinates (gl_FragCoord.xy or similar)

### scale?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Stripe scale (pixels per color)

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.2`

Effect intensity

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with RGB stripes

# phosphorSlotMask

> **phosphorSlotMask**(`inputColor`, `uv`, `resolutionX?`, `resolutionY?`, `intensity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/display/phosphorMask.ts:57](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/phosphorMask.ts#L57)

Slot mask phosphor pattern.
Staggered RGB pattern common in many CRT TVs.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### resolutionX?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `640`

Horizontal resolution

### resolutionY?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `480`

Vertical resolution

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.3`

Mask intensity

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with slot mask effect

# pixelate

> **pixelate**(`inputUV`, `resolution`, `pivot?`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/sprite/pixelate.ts:25](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/sprite/pixelate.ts#L25)

Pixelate UV coordinates by snapping to a pixel grid.

## Parameters

### inputUV

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

The UV coordinates to transform

### resolution

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/)

Pixel grid resolution as [width, height] or vec2 node

### pivot?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Center point for pixelation (default: [0.5, 0.5] = center)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Pixelated UV coordinates (snapped to grid centers)

## Examples

```ts
// Pixelate to 16x16 grid (centered)
pixelate(uv(), [16, 16])
```

```ts
// Animate pixelation with uniform (stays centered)
pixelate(uv(), resolutionUniform)
```

```ts
// Pixelate from top-left corner
pixelate(uv(), [16, 16], [0, 1])
```

# pixelateBySize

> **pixelateBySize**(`inputUV`, `pixelSize`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/sprite/pixelate.ts:48](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/sprite/pixelate.ts#L48)

Pixelate UV coordinates with a single pixel size value.

## Parameters

### inputUV

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

The UV coordinates to transform

### pixelSize

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Size of pixels (higher = more pixelated)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Pixelated UV coordinates

## Example

```ts
// Pixelate with 8 pixel size
pixelateBySize(uv(), 8)
```

# pocketPalette

> **pocketPalette**(`inputColor`, `contrast?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/retro/consolePalettes.ts:73](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/retro/consolePalettes.ts#L73)

Convert color to Game Boy Pocket palette.
Uses gray shades instead of green.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color

### contrast?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Contrast adjustment

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color mapped to Pocket palette

# pointLight2D

> **pointLight2D**(`surfacePos`, `lightPos`, `lightColor?`, `intensity?`, `distance?`, `decay?`): [`Light2DResult`](/three-flatland/api/nodes/src/interfaces/light2dresult/)

Defined in: [packages/nodes/src/lighting/lights.ts:34](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/lights.ts#L34)

Calculate 2D point light contribution at a surface position.
Provides direction, color, and distance-based attenuation.

## Parameters

### surfacePos

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/)

Position of the surface being lit (vec2 in world/screen space)

### lightPos

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/)

Position of the light source (vec2)

### lightColor?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Light color as [r, g, b] (0-1 range)

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Light intensity multiplier (default: 1)

### distance?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `100`

Maximum light distance (default: 100)

### decay?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `2`

Decay exponent controlling attenuation curve shape (default: 2 for quadratic)

## Returns

[`Light2DResult`](/three-flatland/api/nodes/src/interfaces/light2dresult/)

Light2DResult with direction, color, and attenuation

## Example

```ts
const light = pointLight2D(fragPos, [100, 100], [1, 0.9, 0.8], 2.0, 200)
const diffuse = litDiffuse(normal, light.direction, inputColor, light.color, light.attenuation)
```

# posterize

> **posterize**(`inputColor`, `bands`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/retro/posterize.ts:25](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/retro/posterize.ts#L25)

Posterize color to create flat, comic-book style bands.
This is semantically equivalent to quantize but with artist-friendly naming.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### bands

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Number of color bands (2-16 typical)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Posterized color

## Examples

```ts
// Create comic-book style with 4 bands
posterize(texture(tex, uv()), 4)
```

```ts
// Subtle posterization with 8 bands
posterize(color, 8)
```

```ts
// Dynamic posterization with uniform
posterize(color, bandsUniform)
```

# posterizeGamma

> **posterizeGamma**(`inputColor`, `bands`, `gamma?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/retro/posterize.ts:52](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/retro/posterize.ts#L52)

Posterize with gamma correction for more perceptually uniform bands.
Applies gamma before quantization and inverse gamma after.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### bands

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Number of color bands (2-16 typical)

### gamma?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `2.2`

Gamma value (default: 2.2 for sRGB)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Posterized color with gamma correction

## Examples

```ts
// Gamma-corrected posterization
posterizeGamma(color, 4)
```

```ts
// Custom gamma
posterizeGamma(color, 4, 1.8)
```

# ppuPalette

> **ppuPalette**(`inputColor`, `saturation?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/retro/consolePalettes.ts:100](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/retro/consolePalettes.ts#L100)

Convert color to NES/Famicom PPU palette (2C02).
Maps to the closest of 54 available colors.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color

### saturation?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Color saturation (default: 1)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color approximating NES PPU output

# pulse

> **pulse**(`inputColor`, `time`, `speed?`, `minBrightness?`, `maxBrightness?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/pulse.ts:18](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/pulse.ts#L18)

Apply pulsing glow effect that modulates brightness over time.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Base color (vec4)

### time

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Animation time

### speed?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `2`

Pulse speed (default: 2)

### minBrightness?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.8`

Minimum brightness multiplier (default: 0.8)

### maxBrightness?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1.2`

Maximum brightness multiplier (default: 1.2)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Pulsing color

## Example

```ts
const pulsing = pulse(inputColor, time, 2, 0.8, 1.2)
```

# pulseGlow

> **pulseGlow**(`inputColor`, `time`, `glowColor?`, `speed?`, `intensity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/pulse.ts:47](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/pulse.ts#L47)

Pulsing glow that adds color rather than multiplying.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Base color

### time

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Animation time

### glowColor?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Color to pulse

### speed?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `2`

Pulse speed

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Maximum glow intensity

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with pulsing glow

# pulseHeartbeat

> **pulseHeartbeat**(`inputColor`, `time`, `speed?`, `intensity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/pulse.ts:74](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/pulse.ts#L74)

Heartbeat-style pulse with quick beat and pause.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Base color

### time

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Animation time

### speed?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Animation speed

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.3`

Pulse intensity

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with heartbeat pulse

# pulseRadial

> **pulseRadial**(`inputColor`, `uv`, `time`, `center?`, `speed?`, `intensity?`, `glowColor?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/pulse.ts:110](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/pulse.ts#L110)

Radial pulse emanating from center.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Base color

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### time

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Animation time

### center?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Pulse center (default: [0.5, 0.5])

### speed?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Pulse speed

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Pulse intensity

### glowColor?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Color of the pulse wave

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with radial pulse

# pulseRainbow

> **pulseRainbow**(`inputColor`, `time`, `speed?`, `saturation?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/pulse.ts:146](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/pulse.ts#L146)

Color cycling pulse effect.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Base color

### time

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Animation time

### speed?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Color cycle speed

### saturation?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Color saturation (default: 0.5)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with cycling hue

# quantize

> **quantize**(`inputColor`, `levels`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/retro/quantize.ts:25](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/retro/quantize.ts#L25)

Quantize color to discrete levels per channel.
Creates a retro/pixel art look by reducing the number of possible colors.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### levels

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Number of levels per channel (2-256)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Quantized color

## Examples

```ts
// 8 levels per channel (512 colors)
quantize(texture(tex, uv()), 8)
```

```ts
// Binary colors per channel (8 colors total)
quantize(color, 2)
```

```ts
// Using a uniform for dynamic control
quantize(color, levelsUniform)
```

# quantizeRGB

> **quantizeRGB**(`inputColor`, `rLevels`, `gLevels`, `bLevels`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/retro/quantize.ts:54](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/retro/quantize.ts#L54)

Quantize color with different levels for each RGB channel.
Useful for specific retro palettes like 3-3-2 (8-bit color).

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### rLevels

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Number of levels for red channel

### gLevels

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Number of levels for green channel

### bLevels

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Number of levels for blue channel

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Quantized color

## Examples

```ts
// 8-bit color (3-3-2 format: 8R, 8G, 4B)
quantizeRGB(color, 8, 8, 4)
```

```ts
// 16-bit high color (5-6-5 format)
quantizeRGB(color, 32, 64, 32)
```

# sai2x

> **sai2x**(`tex`, `uv`, `texelSize?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/upscale/eagle.ts:137](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/upscale/eagle.ts#L137)

2xSaI (2x Scale and Interpolation) algorithm.
Advanced pixel art scaler with smooth interpolation.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### texelSize?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Source texel size

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Upscaled color

# sampleSprite

> **sampleSprite**(`tex`, `frame`, `options?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\> \| [`TextureNode`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/sprite/sampleSprite.ts:34](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/sprite/sampleSprite.ts#L34)

Sample a sprite from a texture with frame-based UV mapping.
Works with both animated sprites (pass uniform) and static sprites (pass fixed frame).

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

The sprite texture to sample

### frame

[`Vec4Input`](/three-flatland/api/nodes/src/type-aliases/vec4input/)

Frame bounds as [x, y, width, height] in UV space (0-1), or a vec4 uniform

### options?

Optional settings

#### alphaTest?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\> \| [`TextureNode`](https://threejs.org/docs/)\<`"vec4"`\>

Sampled color (vec4)

## Examples

```ts
// Static sprite (full texture)
const color = sampleSprite(texture, [0, 0, 1, 1])
```

```ts
// Static sprite (specific frame)
const frame = spriteSheet.getFrame('idle_0')
const color = sampleSprite(texture, [frame.x, frame.y, frame.width, frame.height])
```

```ts
// Animated sprite (frame uniform updates each tick)
const frameUniform = uniform(new Vector4(0, 0, 0.125, 0.125))
const color = sampleSprite(texture, frameUniform)
```

```ts
// With alpha discard
const color = sampleSprite(texture, frame, { alphaTest: 0.01 })
```

# saturate

> **saturate**(`inputColor`, `amount`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/color/saturate.ts:25](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/color/saturate.ts#L25)

Adjust saturation by mixing with grayscale (luminance).

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### amount

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Saturation amount (0 = grayscale, 1 = original, >1 = oversaturated)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with adjusted saturation

## Examples

```ts
// Desaturate to grayscale (petrified effect)
saturate(texture(tex, uv()), 0)
```

```ts
// Boost saturation
saturate(texture(tex, uv()), 1.5)
```

# scale2x

> **scale2x**(`tex`, `uv`, `texelSize?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/upscale/scale2x.ts:19](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/upscale/scale2x.ts#L19)

Scale2x (AdvMAME2x) pixel art upscaling algorithm.
Simple edge-detection based upscaling that preserves pixel art edges.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture (pixel art)

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### texelSize?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Size of one texel in the source texture

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Upscaled color

## Example

```ts
// For a 256x256 texture upscaled to 512x512
const upscaled = scale2x(texture, uv, [1/256, 1/256])
```

# scale3x

> **scale3x**(`tex`, `uv`, `texelSize?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/upscale/scale2x.ts:100](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/upscale/scale2x.ts#L100)

Scale3x (AdvMAME3x) pixel art upscaling algorithm.
3x upscaling variant with more refined edge detection.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### texelSize?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Source texel size

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Upscaled color

# scanlines

> **scanlines**(`inputColor`, `uv`, `resolution?`, `intensity?`, `offset?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/display/scanlines.ts:19](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/scanlines.ts#L19)

Apply CRT scanline effect.
Darkens alternating horizontal lines to simulate CRT display.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color (vec4)

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### resolution?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `240`

Vertical resolution (number of scanlines, default: 240)

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.3`

Scanline darkness (0-1, default: 0.3)

### offset?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0`

Line offset for interlacing simulation (default: 0)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with scanline effect

## Example

```ts
const crt = scanlines(inputColor, uv, 240, 0.3)
```

# scanlinesGlow

> **scanlinesGlow**(`inputColor`, `uv`, `resolution?`, `lineIntensity?`, `glowIntensity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/display/scanlines.ts:86](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/scanlines.ts#L86)

Scanlines with bloom/glow between lines.
Simulates phosphor glow bleeding between scanlines.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### resolution?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `240`

Vertical resolution

### lineIntensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.3`

Scanline darkness

### glowIntensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.1`

Glow between lines

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with scanlines and glow

# scanlinesGrid

> **scanlinesGrid**(`inputColor`, `uv`, `resolutionX?`, `resolutionY?`, `intensity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/display/scanlines.ts:156](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/scanlines.ts#L156)

Combined horizontal and vertical scanlines (shadow mask simulation).

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### resolutionX?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `320`

Horizontal resolution

### resolutionY?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `240`

Vertical resolution

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.2`

Effect intensity

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with grid pattern

# scanlinesInterlaced

> **scanlinesInterlaced**(`inputColor`, `uv`, `resolution?`, `field?`, `intensity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/display/scanlines.ts:123](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/scanlines.ts#L123)

Interlaced scanlines for authentic interlaced display simulation.
Alternates which lines are visible each frame.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### resolution?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `240`

Vertical resolution

### field?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0`

Current field (0 or 1, alternate each frame)

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Scanline intensity

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with interlaced scanlines

# scanlinesSmooth

> **scanlinesSmooth**(`inputColor`, `uv`, `resolution?`, `intensity?`, `phase?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/display/scanlines.ts:53](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/scanlines.ts#L53)

Smooth scanlines with sine wave pattern.
More authentic CRT look with gradual brightness variation.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### resolution?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `240`

Vertical resolution

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.2`

Effect intensity

### phase?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0`

Phase offset (use for animation/interlacing)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with smooth scanlines

# shadow2D

> **shadow2D**(`position`, `lightPos`, `occluderTex`, `occluderSize`, `shadowStrength?`): [`Node`](https://threejs.org/docs/)\<`"float"`\>

Defined in: [packages/nodes/src/lighting/shadows.ts:115](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/shadows.ts#L115)

Calculate hard 2D shadow from a light source.
Checks if a point is in shadow by sampling an occluder texture.

## Parameters

### position

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/)

World/screen position of the surface

### lightPos

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/)

Position of the light source

### occluderTex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Texture containing occluder data (alpha channel)

### occluderSize

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/)

Size of the occluder texture in world units

### shadowStrength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.7`

Shadow intensity (default: 0.7)

## Returns

[`Node`](https://threejs.org/docs/)\<`"float"`\>

Shadow factor (0 = full shadow, 1 = no shadow)

## Example

```ts
const shadow = shadow2D(fragPos, lightPos, occluderMap, [512, 512])
finalColor = finalColor.mul(shadow)
```

# shadowDrop

> **shadowDrop**(`spriteTex`, `uv`, `shadowOffset?`, `shadowColor?`, `shadowAlpha?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/lighting/shadows.ts:22](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/shadows.ts#L22)

Create a drop shadow effect.
Samples the sprite's alpha at an offset position to create shadow.

## Parameters

### spriteTex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source sprite texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Current UV coordinates

### shadowOffset?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Shadow offset in UV space (default: [0.02, -0.02])

### shadowColor?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Shadow color (default: [0, 0, 0])

### shadowAlpha?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Shadow opacity (default: 0.5)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Shadow color with alpha (vec4), composite with original

## Example

```ts
// Create shadow behind sprite
const shadow = shadowDrop(texture, uv, [0.03, -0.03], [0, 0, 0], 0.4)
// Mix: show shadow where sprite alpha is 0, original where alpha is 1
```

# shadowDropSoft

> **shadowDropSoft**(`spriteTex`, `uv`, `shadowOffset?`, `shadowColor?`, `shadowAlpha?`, `softness?`, `samples?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/lighting/shadows.ts:56](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/shadows.ts#L56)

Create a soft drop shadow with blur.
Samples multiple offset positions to create a softer shadow.

## Parameters

### spriteTex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source sprite texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Current UV coordinates

### shadowOffset?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Shadow offset in UV space

### shadowColor?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Shadow color

### shadowAlpha?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Shadow opacity

### softness?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.01`

Blur amount in UV space (default: 0.01)

### samples?

`number` = `4`

Number of blur samples (default: 4)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Soft shadow color with alpha

# shadowSDF2D

> **shadowSDF2D**(`surfaceWorldPos`, `lightWorldPos`, `sdfTexture`, `worldSize`, `worldOffset`, `options?`): [`Node`](https://threejs.org/docs/)\<`"float"`\>

Defined in: [packages/nodes/src/lighting/shadows.ts:271](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/shadows.ts#L271)

Sphere-trace a 2D hard shadow ray through an SDF texture.

Walks along the line from the shaded surface point toward the light,
sampling the SDF at each step to advance by the guaranteed-clear
distance. Binary result: `0` if the ray hits an occluder along the
way, `1` if it reaches the light cleanly. Soft shadow edges come
from (a) the separable gaussian blur pass applied in `SDFGenerator`
and (b) the IQ soft-shadow accumulation along the trace — primarily,
not from texture filtering. The SDF sample filter is selectable via
`shadowFilter` (`auto|nearest|linear`): nearest for crisp / pixel-
snapped shadows (avoids the eps-threshold halo), linear for smoother
non-snapped edges. `auto` picks nearest when shadow pixel-snap is on,
linear otherwise. Either way the blur + penumbra math carry the bulk
of the softness.

The classic IQ penumbra term `min(k · h / t)` was removed because
it accumulates at every step of the walk, which in closed 2D scenes
(dungeons, corridors — casters scattered everywhere) produces a
uniform global darkening: every ray walks near *something*, so
`h/t` always drops below 1 somewhere, `shadow` always ends below 1,
and `shadowStrength` linearly amplifies that scene-wide. The
`softness` option is retained for API stability (now ignored); a
future PCSS-style two-phase trace could reintroduce real
distance-aware penumbra widening without the false-proximity issue.

The SDF texture is assumed to be produced by `SDFGenerator` and
encodes SIGNED **world-space** distance on the `.r` channel — negative
inside occluders, positive outside. Signed distance lets the trace
detect "stepped into an occluder" mid-walk without needing the
hardcoded caster-escape offset the unsigned variant required. World-
space distances keep the sphere-trace isotropic on non-square
viewports. `worldSize` / `worldOffset` are still consumed here to
transform the fragment/ray world position into the SDF's UV space for
sampling.

## Parameters

### surfaceWorldPos

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

World-space position of the shaded fragment.

### lightWorldPos

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

World-space position of the light.

### sdfTexture

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

SDF texture captured at build time. Must come
                       from `SDFGenerator` (UV-space distances in .r).

### worldSize

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Camera frustum size (Node — uniform, updated
                       each frame from the camera bounds).

### worldOffset

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Camera frustum offset (Node — uniform).

### options?

#### eps?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

World-space hit threshold. Default 0.5.

#### fragmentCastsShadow?

[`Node`](https://threejs.org/docs/)\<`"bool"`\>

When provided, gates the `nearCaster` escape path: the ray only
  skips past an occluder it's sitting on if THIS fragment is itself
  a shadow caster. Without this gate, a floor fragment that happens
  to lie under a sprite's rasterized silhouette (seeded in the SDF)
  would incorrectly escape and render as lit — leaving a bright
  alpha-blended halo wherever a sprite's anti-aliased edge overlaps
  the floor. Pass `readCastShadowFlag()` here from the caller's
  light shader.

#### maxShadowDistance?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Maximum world-space distance from the receiver at which shadow
still applies. A ray that hits an occluder at `t = t_hit` has
its shadow scaled by `1 - t_hit / maxShadowDistance`, clamped to
[0, 1]. Default 0 means no distance falloff (shadow is binary at
every distance). Set >0 to hide point-light cone-fan artifacts
far from the caster — close-range shadows stay solid, long-range
shadows fade to lit.

#### softness?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Retained for API stability; currently ignored.
                        Soft edges come from SDF blur + linear sampling,
                        not per-ray integration. Will re-enable once a
                        PCSS-style trace lands.

#### startOffset?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

World-space distance to push the ray origin forward when the
  fragment itself sits inside a caster silhouette (signed SDF < 0).
  Must clear the caster's radius — too small and the first samples
  land inside the caster (self-shadow) or in the Voronoi-seam zone
  near the silhouette (shadow-edge ringing). Default 40 world units
  matches the old unsigned-SDF escape calibration; scenes with
  smaller/larger casters should tune accordingly.

#### steps?

`number`

Compile-time loop count. Default 32.

## Returns

[`Node`](https://threejs.org/docs/)\<`"float"`\>

Node<'float'> in [0, 1]. 0 = fully shadowed, 1 = fully lit.

# shadowSoft2D

> **shadowSoft2D**(`position`, `lightPos`, `occluderTex`, `occluderSize`, `lightRadius?`, `shadowStrength?`): [`Node`](https://threejs.org/docs/)\<`"float"`\>

Defined in: [packages/nodes/src/lighting/shadows.ts:157](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/shadows.ts#L157)

Calculate soft 2D shadow with penumbra.
Samples multiple rays for a softer shadow edge.

## Parameters

### position

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/)

World/screen position of the surface

### lightPos

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/)

Position of the light source

### occluderTex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Texture containing occluder data

### occluderSize

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/)

Size of the occluder texture in world units

### lightRadius?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `10`

Radius of the light source for soft shadows

### shadowStrength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.7`

Shadow intensity

## Returns

[`Node`](https://threejs.org/docs/)\<`"float"`\>

Soft shadow factor

# shimmer

> **shimmer**(`inputColor`, `uv`, `time`, `angle?`, `speed?`, `intensity?`, `shimmerColor?`, `width?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/shimmer.ts:22](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/shimmer.ts#L22)

Add shimmer/shine effect - a moving highlight across the surface.
Creates a metallic or glossy appearance.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Base color (vec4)

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### time

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Animation time

### angle?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.785`

Shimmer angle in radians (default: 0.785 = 45°)

### speed?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Animation speed (default: 1)

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Shimmer brightness (default: 0.5)

### shimmerColor?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Color of the shimmer highlight

### width?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.1`

Width of shimmer band (default: 0.1)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with shimmer effect

## Example

```ts
const shiny = shimmer(inputColor, uv, time, Math.PI/4, 1, 0.5, [1, 1, 1])
```

# shimmerHolographic

> **shimmerHolographic**(`inputColor`, `uv`, `time`, `speed?`, `intensity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/shimmer.ts:114](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/shimmer.ts#L114)

Holographic shimmer with rainbow effect.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Base color

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### time

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Animation time

### speed?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Animation speed

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.4`

Effect intensity

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with holographic shimmer

# shimmerMetallic

> **shimmerMetallic**(`inputColor`, `uv`, `time?`, `intensity?`, `shineColor?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/shimmer.ts:155](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/shimmer.ts#L155)

Metallic shine effect based on viewing angle simulation.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Base color

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### time?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0`

Animation time (for subtle movement)

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Shine intensity

### shineColor?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Color of metallic highlight

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with metallic shine

# shimmerWave

> **shimmerWave**(`inputColor`, `uv`, `time`, `waves?`, `speed?`, `intensity?`, `shimmerColor?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/shimmer.ts:71](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/shimmer.ts#L71)

Wave shimmer effect - multiple shimmering waves.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Base color

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### time

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Animation time

### waves?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `3`

Number of shimmer waves (default: 3)

### speed?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Animation speed

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.3`

Shimmer intensity

### shimmerColor?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Shimmer color

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with wave shimmer

# signalInterference

> **signalInterference**(`inputColor`, `uv`, `time`, `barHeight?`, `intensity?`, `speed?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/analog/videoArtifacts.ts:226](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/analog/videoArtifacts.ts#L226)

Signal interference bars.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### time

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Animation time

### barHeight?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.1`

Height of interference bars (default: 0.1)

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.3`

Interference intensity

### speed?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Bar movement speed

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with interference

# snesPalette

> **snesPalette**(`inputColor`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/retro/consolePalettes.ts:190](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/retro/consolePalettes.ts#L190)

SNES/Super Famicom 15-bit palette.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color quantized to SNES palette

# sparkle

> **sparkle**(`inputColor`, `uv`, `time`, `density?`, `intensity?`, `sparkleColor?`, `speed?`, `threshold?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/sparkle.ts:30](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/sparkle.ts#L30)

Add sparkle/glitter effect to a color.
Creates randomly appearing bright spots that twinkle over time.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Base color (vec4)

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### time

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Animation time

### density?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `50`

Sparkle density (higher = more sparkles, default: 50)

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `2`

Sparkle brightness (default: 2)

### sparkleColor?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Color of sparkles (default: white)

### speed?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `3`

Animation speed (default: 3)

### threshold?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.97`

Sparkle appearance threshold (default: 0.97)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with sparkle effect

## Example

```ts
const sparkly = sparkle(inputColor, uv, time, 40, 2, [1, 1, 1])
```

# sparkleRainbow

> **sparkleRainbow**(`inputColor`, `uv`, `time`, `density?`, `intensity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/sparkle.ts:148](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/sparkle.ts#L148)

Rainbow sparkle effect with color cycling.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Base color

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### time

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Animation time

### density?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `40`

Sparkle density

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1.5`

Sparkle brightness

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with rainbow sparkle effect

# sparkleStar

> **sparkleStar**(`inputColor`, `uv`, `time`, `density?`, `intensity?`, `sparkleColor?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/sparkle.ts:90](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/sparkle.ts#L90)

Animated star sparkle with 4-point star shape.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Base color

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### time

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Animation time

### density?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `30`

Sparkle density

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1.5`

Sparkle brightness

### sparkleColor?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Color of sparkles

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with star sparkle effect

# speedLines

> **speedLines**(`inputColor`, `uv`, `center?`, `density?`, `speed?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/blurMotion.ts:177](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/blurMotion.ts#L177)

Directional speed lines effect.
Creates manga/anime style motion lines.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Base color

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### center?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Focus point

### density?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `50`

Line density

### speed?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0`

Animation speed (use time input)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with speed lines

# spotLight2D

> **spotLight2D**(`surfacePos`, `lightPos`, `lightDir`, `lightColor?`, `intensity?`, `distance?`, `innerAngle?`, `outerAngle?`): [`Light2DResult`](/three-flatland/api/nodes/src/interfaces/light2dresult/)

Defined in: [packages/nodes/src/lighting/lights.ts:83](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/lights.ts#L83)

Calculate 2D spot light contribution with cone falloff.

## Parameters

### surfacePos

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/)

Position of the surface being lit

### lightPos

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/)

Position of the light source

### lightDir

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/)

Direction the spotlight is pointing (normalized vec2)

### lightColor?

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/) = `...`

Light color

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Light intensity

### distance?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `100`

Maximum light distance

### innerAngle?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.3`

Inner cone angle in radians (full intensity)

### outerAngle?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.6`

Outer cone angle in radians (falloff to zero)

## Returns

[`Light2DResult`](/three-flatland/api/nodes/src/interfaces/light2dresult/)

Light2DResult with cone attenuation applied

## Example

```ts
const spot = spotLight2D(fragPos, [100, 100], [0, -1], [1, 1, 0.9], 1.5, 150, 0.3, 0.6)
```

# spriteUV

> **spriteUV**(`frame`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/sprite/sampleSprite.ts:91](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/sprite/sampleSprite.ts#L91)

Get the UV coordinates for a sprite frame.
Useful when you need the UV separately (e.g., for outline effects that sample neighbors).

## Parameters

### frame

[`Vec4Input`](/three-flatland/api/nodes/src/type-aliases/vec4input/)

Frame bounds as [x, y, width, height] in UV space (0-1), or a vec4 uniform

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Transformed UV coordinates for the frame

## Example

```ts
const frameUV = spriteUV(frameUniform)
const color = texture(tex, frameUV)
return outline8(color, frameUV, tex, { color: [0, 1, 0, 1] })
```

# staticNoise

> **staticNoise**(`inputColor`, `uv`, `time`, `intensity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/analog/videoArtifacts.ts:160](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/analog/videoArtifacts.ts#L160)

TV static noise effect.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color (can mix with static)

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### time

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Animation time

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Static intensity (0 = no static, 1 = full static)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with static noise

# superEagle

> **superEagle**(`tex`, `uv`, `texelSize?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/upscale/eagle.ts:85](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/upscale/eagle.ts#L85)

SuperEagle - enhanced Eagle algorithm.
Better diagonal handling and smoother results.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### texelSize?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Source texel size

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Upscaled color

# tint

> **tint**(`inputColor`, `tintColor`, `strength?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/color/tint.ts:21](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/color/tint.ts#L21)

Apply a color tint by multiplying with the input color.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### tintColor

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/)

Tint color as [r, g, b] (0-1 range) or TSL node

### strength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Tint strength (0 = no tint, 1 = full tint, default: 1)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Tinted color

## Examples

```ts
// Apply red tint
tint(texture(tex, uv()), [1, 0, 0])
```

```ts
// Partial tint with uniform
tint(texture(tex, uv()), tintColorUniform, 0.5)
```

# tintAdditive

> **tintAdditive**(`inputColor`, `addColor`, `strength?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/color/tint.ts:49](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/color/tint.ts#L49)

Apply an additive color tint (adds color rather than multiplying).
Useful for "flash" effects like damage feedback.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

The input color (vec4 with alpha)

### addColor

[`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/)

Color to add as [r, g, b] (0-1 range) or TSL node

### strength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Effect strength (0 = no effect, 1 = full effect)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with additive tint

## Example

```ts
// Flash white on hit
tintAdditive(texture(tex, uv()), [1, 1, 1], hitFlashUniform)
```

# trail

> **trail**(`tex`, `uv`, `direction`, `length?`, `samples?`, `falloff?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/trail.ts:22](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/trail.ts#L22)

Create motion trail effect by sampling previous positions.
Samples the texture at offset positions to create a trailing effect.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Current UV coordinates

### direction

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/)

Trail direction (normalized vec2 or [x, y])

### length?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.1`

Trail length in UV space (default: 0.1)

### samples?

`number` = `4`

Number of trail samples (default: 4)

### falloff?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `2`

How quickly trail fades (default: 2)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with motion trail

## Example

```ts
// Horizontal motion trail
const trailed = trail(texture, uv, [1, 0], 0.1, 4)
```

# trailAdditive

> **trailAdditive**(`tex`, `uv`, `direction`, `length?`, `samples?`, `intensity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/trail.ts:64](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/trail.ts#L64)

Motion trail with additive blending for glowing trails.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### direction

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/)

Trail direction

### length?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.1`

Trail length

### samples?

`number` = `4`

Number of samples

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Trail intensity

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with additive trail

# trailBlur

> **trailBlur**(`tex`, `uv`, `direction`, `length?`, `samples?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/trail.ts:101](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/trail.ts#L101)

Speed lines / motion blur in a direction.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### direction

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/)

Motion direction

### length?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.05`

Blur length

### samples?

`number` = `8`

Number of blur samples

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Motion-blurred color

# trailVelocity

> **trailVelocity**(`tex`, `uv`, `velocity`, `maxLength?`, `samples?`, `opacity?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/vfx/trail.ts:141](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/vfx/trail.ts#L141)

Create echo/ghost trail using velocity-based offset.

## Parameters

### tex

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### velocity

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/)

Current velocity (determines direction and intensity)

### maxLength?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.15`

Maximum trail length

### samples?

`number` = `4`

Number of echo samples

### opacity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.6`

Trail opacity

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with velocity-based trail

# uvFlip

> **uvFlip**(`inputUV`, `flipX?`, `flipY?`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/sprite/uvFlip.ts:21](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/sprite/uvFlip.ts#L21)

Flip UV coordinates horizontally and/or vertically.

## Parameters

### inputUV

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

The UV coordinates to transform

### flipX?

`boolean` \| [`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Whether to flip horizontally (true/1 = flip, false/0 = normal)

### flipY?

`boolean` \| [`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Whether to flip vertically (true/1 = flip, false/0 = normal)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Flipped UV coordinates

## Examples

```ts
// Flip horizontally
uvFlip(uv(), true, false)
```

```ts
// Flip based on uniform
uvFlip(uv(), flipXUniform, flipYUniform)
```

# uvOffset

> **uvOffset**(`inputUV`, `offset`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/sprite/uvOffset.ts:20](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/sprite/uvOffset.ts#L20)

Offset UV coordinates by a given amount.

## Parameters

### inputUV

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

The UV coordinates to transform

### offset

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/)

Offset amount as [x, y] or vec2 node

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Offset UV coordinates

## Examples

```ts
// Offset UV by 0.1 in both directions
uvOffset(uv(), [0.1, 0.1])
```

```ts
// Animate UV offset with uniform
uvOffset(uv(), offsetUniform)
```

# uvRotate

> **uvRotate**(`inputUV`, `angle`, `pivot?`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/sprite/uvRotate.ts:21](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/sprite/uvRotate.ts#L21)

Rotate UV coordinates around a pivot point.

## Parameters

### inputUV

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

The UV coordinates to transform

### angle

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Rotation angle in radians (or float node)

### pivot?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Pivot point for rotation (default: [0.5, 0.5] = center)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Rotated UV coordinates

## Examples

```ts
// Rotate UV by 45 degrees around center
uvRotate(uv(), Math.PI / 4)
```

```ts
// Animate rotation with uniform
uvRotate(uv(), angleUniform, [0.5, 0.5])
```

# uvScale

> **uvScale**(`inputUV`, `scale`, `pivot?`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/sprite/uvScale.ts:21](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/sprite/uvScale.ts#L21)

Scale UV coordinates around a pivot point.

## Parameters

### inputUV

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

The UV coordinates to transform

### scale

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/)

Scale factor as [x, y] or vec2 node

### pivot?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Pivot point for scaling (default: [0.5, 0.5] = center)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Scaled UV coordinates

## Examples

```ts
// Scale UV by 2x around center
uvScale(uv(), [2, 2])
```

```ts
// Scale with uniform for animation
uvScale(uv(), scaleUniform, [0.5, 0.5])
```

# vbPalette

> **vbPalette**(`inputColor`, `contrast?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/retro/consolePalettes.ts:144](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/retro/consolePalettes.ts#L144)

Convert color to Virtual Boy palette.
Red and black only, 4 shades.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color

### contrast?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Contrast adjustment

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color mapped to Virtual Boy palette

# vhsDistortion

> **vhsDistortion**(`tex`, `uv`, `time`, `intensity?`, `noiseAmount?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/analog/videoArtifacts.ts:117](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/analog/videoArtifacts.ts#L117)

VHS tape distortion effect.
Simulates tracking errors and tape degradation.

## Parameters

### tex

[`TextureNode`](https://threejs.org/docs/)\<`"vec4"`\>

Source texture

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### time

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Animation time

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.02`

Distortion intensity (default: 0.02)

### noiseAmount?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.1`

Noise visibility (default: 0.1)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with VHS distortion

# vignette

> **vignette**(`inputColor`, `uv`, `intensity?`, `softness?`, `roundness?`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/blur/bloom.ts:199](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/blur/bloom.ts#L199)

Vignette effect - darkens edges of the screen.

## Parameters

### inputColor

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Input color

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

UV coordinates

### intensity?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Vignette strength (default: 0.5)

### softness?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.5`

Edge softness (default: 0.5)

### roundness?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Vignette shape roundness (default: 1)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Color with vignette

# waveHorizontal

> **waveHorizontal**(`uv`, `amplitude?`, `frequency?`, `time?`, `speed?`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/distortion/wave.ts:20](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/distortion/wave.ts#L20)

Apply horizontal wave distortion to UV coordinates.
Creates a wavy effect like looking through water or heat haze.

## Parameters

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Input UV coordinates

### amplitude?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.02`

Wave amplitude in UV space (default: 0.02)

### frequency?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `10`

Wave frequency (default: 10)

### time?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0`

Animation time for moving waves

### speed?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Animation speed multiplier (default: 1)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Distorted UV coordinates

## Example

```ts
const distortedUV = waveHorizontal(uv, 0.02, 10, time)
const color = texture(tex, distortedUV)
```

# waveRadial

> **waveRadial**(`uv`, `center?`, `amplitude?`, `frequency?`, `time?`, `speed?`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/distortion/wave.ts:81](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/distortion/wave.ts#L81)

Apply radial wave distortion emanating from center.
Creates a pulsing distortion effect.

## Parameters

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Input UV coordinates

### center?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Center point of the wave effect (default: [0.5, 0.5])

### amplitude?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.02`

Wave amplitude

### frequency?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `10`

Wave frequency

### time?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0`

Animation time

### speed?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Animation speed

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Distorted UV coordinates

## Example

```ts
const distortedUV = waveRadial(uv, [0.5, 0.5], 0.03, 15, time)
```

# waveRipple

> **waveRipple**(`uv`, `center?`, `amplitude?`, `frequency?`, `time?`, `decay?`, `speed?`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/distortion/wave.ts:123](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/distortion/wave.ts#L123)

Apply ripple distortion from a point (like a droplet in water).
Creates expanding circular waves that fade with distance.

## Parameters

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Input UV coordinates

### center?

[`Vec2Input`](/three-flatland/api/nodes/src/type-aliases/vec2input/) = `...`

Center point of the ripple

### amplitude?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.03`

Wave amplitude

### frequency?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `20`

Wave frequency

### time?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0`

Animation time (controls ripple expansion)

### decay?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `2`

How quickly ripples fade with distance (default: 2)

### speed?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Animation speed

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Distorted UV coordinates

## Example

```ts
// Ripple from click position
const distortedUV = waveRipple(uv, clickPos, 0.05, 20, time, 3)
```

# waveVertical

> **waveVertical**(`uv`, `amplitude?`, `frequency?`, `time?`, `speed?`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/distortion/wave.ts:48](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/distortion/wave.ts#L48)

Apply vertical wave distortion to UV coordinates.

## Parameters

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Input UV coordinates

### amplitude?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.02`

Wave amplitude in UV space

### frequency?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `10`

Wave frequency

### time?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0`

Animation time

### speed?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `1`

Animation speed multiplier

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Distorted UV coordinates

# waveWater

> **waveWater**(`uv`, `amplitude?`, `time?`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/distortion/wave.ts:159](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/distortion/wave.ts#L159)

Combine multiple wave effects for complex water-like distortion.

## Parameters

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Input UV coordinates

### amplitude?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0.01`

Overall amplitude

### time?

[`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/) = `0`

Animation time

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Complex wave-distorted UV coordinates

# CRTOptions

Defined in: [packages/nodes/src/display/crtEffects.ts:159](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/crtEffects.ts#L159)

Complete CRT effect combining curvature, scanlines, and mask.

## Param

Source texture

## Param

UV coordinates

## Param

CRT effect options

## Properties

### bloomIntensity?

> `optional` **bloomIntensity?**: [`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Defined in: [packages/nodes/src/display/crtEffects.ts:169](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/crtEffects.ts#L169)

Phosphor bloom intensity (default: 0.2)

***

### colorBleed?

> `optional` **colorBleed?**: [`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Defined in: [packages/nodes/src/display/crtEffects.ts:171](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/crtEffects.ts#L171)

Color bleed amount (default: 0.001)

***

### curvature?

> `optional` **curvature?**: [`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Defined in: [packages/nodes/src/display/crtEffects.ts:161](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/crtEffects.ts#L161)

Barrel curvature amount (default: 0.1)

***

### scanlineIntensity?

> `optional` **scanlineIntensity?**: [`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Defined in: [packages/nodes/src/display/crtEffects.ts:163](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/crtEffects.ts#L163)

Scanline intensity (default: 0.2)

***

### scanlineRes?

> `optional` **scanlineRes?**: [`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Defined in: [packages/nodes/src/display/crtEffects.ts:165](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/crtEffects.ts#L165)

Scanline resolution (default: 240)

***

### vignetteIntensity?

> `optional` **vignetteIntensity?**: [`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Defined in: [packages/nodes/src/display/crtEffects.ts:167](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/display/crtEffects.ts#L167)

Vignette intensity (default: 0.3)

# DissolveOptions

Defined in: [packages/nodes/src/alpha/dissolve.ts:6](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/alpha/dissolve.ts#L6)

## Properties

### edgeColor?

> `optional` **edgeColor?**: [`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/)

Defined in: [packages/nodes/src/alpha/dissolve.ts:12](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/alpha/dissolve.ts#L12)

Edge glow color as [r, g, b] (default: [1, 0.5, 0] = orange)

***

### edgeWidth?

> `optional` **edgeWidth?**: [`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Defined in: [packages/nodes/src/alpha/dissolve.ts:14](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/alpha/dissolve.ts#L14)

Width of the glowing edge (default: 0.1)

***

### noiseScale?

> `optional` **noiseScale?**: [`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Defined in: [packages/nodes/src/alpha/dissolve.ts:16](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/alpha/dissolve.ts#L16)

Scale of noise UV (default: 1)

***

### noiseTex

> **noiseTex**: [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Defined in: [packages/nodes/src/alpha/dissolve.ts:10](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/alpha/dissolve.ts#L10)

Noise texture for dissolve pattern

***

### progress

> **progress**: [`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Defined in: [packages/nodes/src/alpha/dissolve.ts:8](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/alpha/dissolve.ts#L8)

Dissolve progress (0 = fully visible, 1 = fully dissolved)

# Light2DResult

Defined in: [packages/nodes/src/lighting/lights.ts:9](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/lights.ts#L9)

Light data structure returned by light calculation nodes.
Contains direction, intensity, and attenuation for use in lighting calculations.

## Properties

### attenuation

> **attenuation**: [`Node`](https://threejs.org/docs/)\<`"float"`\>

Defined in: [packages/nodes/src/lighting/lights.ts:15](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/lights.ts#L15)

Distance attenuation factor (0-1)

***

### color

> **color**: [`Node`](https://threejs.org/docs/)\<`"vec3"`\>

Defined in: [packages/nodes/src/lighting/lights.ts:13](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/lights.ts#L13)

Light color multiplied by intensity

***

### direction

> **direction**: [`Node`](https://threejs.org/docs/)\<`"vec3"`\>

Defined in: [packages/nodes/src/lighting/lights.ts:11](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/lights.ts#L11)

Direction from surface to light (normalized vec3)

# LitSpriteOptions

Defined in: [packages/nodes/src/lighting/lit.ts:263](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/lit.ts#L263)

Combined sprite lighting with diffuse, specular, and optional rim.
Convenience function that combines common lighting components.

## Param

Surface normal

## Param

Base surface color

## Param

Light result from pointLight2D, directionalLight2D, etc.

## Param

Ambient light result

## Param

Additional lighting options

## Example

```ts
const lit = litSprite(normal, inputColor, pointLight, ambient, {
  specular: true,
  shininess: 32,
  rim: true,
  rimColor: [0.5, 0.8, 1]
})
```

## Properties

### rim?

> `optional` **rim?**: `boolean`

Defined in: [packages/nodes/src/lighting/lit.ts:271](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/lit.ts#L271)

Enable rim lighting

***

### rimColor?

> `optional` **rimColor?**: [`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/)

Defined in: [packages/nodes/src/lighting/lit.ts:273](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/lit.ts#L273)

Rim light color

***

### rimPower?

> `optional` **rimPower?**: [`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Defined in: [packages/nodes/src/lighting/lit.ts:275](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/lit.ts#L275)

Rim power (default: 2)

***

### rimStrength?

> `optional` **rimStrength?**: [`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Defined in: [packages/nodes/src/lighting/lit.ts:277](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/lit.ts#L277)

Rim strength (default: 1)

***

### shininess?

> `optional` **shininess?**: [`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Defined in: [packages/nodes/src/lighting/lit.ts:267](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/lit.ts#L267)

Specular shininess (default: 32)

***

### specular?

> `optional` **specular?**: `boolean`

Defined in: [packages/nodes/src/lighting/lit.ts:265](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/lit.ts#L265)

Enable specular highlights

***

### specularStrength?

> `optional` **specularStrength?**: [`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Defined in: [packages/nodes/src/lighting/lit.ts:269](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/lit.ts#L269)

Specular strength (default: 0.5)

***

### viewDir?

> `optional` **viewDir?**: [`Vec3Input`](/three-flatland/api/nodes/src/type-aliases/vec3input/)

Defined in: [packages/nodes/src/lighting/lit.ts:279](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/lighting/lit.ts#L279)

View direction for specular/rim (default: [0, 0, 1])

# OutlineOptions

Defined in: [packages/nodes/src/sprite/outline.ts:6](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/sprite/outline.ts#L6)

## Properties

### color?

> `optional` **color?**: [`Vec4Input`](/three-flatland/api/nodes/src/type-aliases/vec4input/)

Defined in: [packages/nodes/src/sprite/outline.ts:8](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/sprite/outline.ts#L8)

Outline color as [r, g, b, a] (0-1 range) or vec4 node

***

### textureSize?

> `optional` **textureSize?**: [`Node`](https://threejs.org/docs/)\<`"vec2"`\> \| \[`number`, `number`\]

Defined in: [packages/nodes/src/sprite/outline.ts:12](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/sprite/outline.ts#L12)

Texture size for proper UV offset calculation as [width, height]

***

### thickness?

> `optional` **thickness?**: [`FloatInput`](/three-flatland/api/nodes/src/type-aliases/floatinput/)

Defined in: [packages/nodes/src/sprite/outline.ts:10](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/sprite/outline.ts#L10)

Outline thickness in UV space (default: 0.01)

# ColorInput

> **ColorInput** = `number` \| \[`number`, `number`, `number`\] \| [`Node`](https://threejs.org/docs/)\<`"color"`\> \| [`Node`](https://threejs.org/docs/)\<`"vec3"`\>

Defined in: [packages/nodes/src/types.ts:26](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/types.ts#L26)

Color input type - accepts hex, RGB tuple, or color/vec3 Node

# FloatInput

> **FloatInput** = `number` \| [`Node`](https://threejs.org/docs/)\<`"float"`\>

Defined in: [packages/nodes/src/types.ts:6](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/types.ts#L6)

Input that can be either a literal number or a float Node.

# Vec2Input

> **Vec2Input** = \[`number`, `number`\] \| [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/nodes/src/types.ts:11](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/types.ts#L11)

Vec2 input type - accepts tuple or vec2 Node

# Vec3Input

> **Vec3Input** = \[`number`, `number`, `number`\] \| [`Node`](https://threejs.org/docs/)\<`"vec3"`\>

Defined in: [packages/nodes/src/types.ts:16](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/types.ts#L16)

Vec3 input type - accepts tuple or vec3 Node

# Vec4Input

> **Vec4Input** = \[`number`, `number`, `number`, `number`\] \| [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/nodes/src/types.ts:21](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/nodes/src/types.ts#L21)

Vec4 input type - accepts tuple or vec4 Node

# presets/src

## Variables

- [DefaultLightEffect](/three-flatland/api/presets/src/variables/defaultlighteffect/)
- [NormalMapProvider](/three-flatland/api/presets/src/variables/normalmapprovider/)

# DefaultLightEffect

> `const` **DefaultLightEffect**: `DefaultLightEffectClass`

Defined in: [packages/presets/src/lighting/DefaultLightEffect.ts:493](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/presets/src/lighting/DefaultLightEffect.ts#L493)

# NormalMapProvider

> `const` **NormalMapProvider**: [`MaterialEffectClass`](/three-flatland/api/three-flatland/src/type-aliases/materialeffectclass/)\<\{ `normalMap`: () => [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`; \}\>

Defined in: [packages/presets/src/lighting/NormalMapProvider.ts:36](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/presets/src/lighting/NormalMapProvider.ts#L36)

Provides the 'normal' and 'elevation' channels from a pre-baked
normal atlas.

Atlas encoding (see `@three-flatland/normals/bakeNormalMap`):
  R = nx ∈ [-1, 1]           → mapped from [0, 255]
  G = ny ∈ [-1, 1]           → mapped from [0, 255]
  B = elevation ∈ [0, 1]     → mapped from [0, 255]
  A = source alpha

The provider reconstructs `nz = sqrt(max(0, 1 − nx² − ny²))` at
runtime — outward-facing tangent-space convention means nz ≥ 0 always,
so the sign is implicit and one texture channel is freed for elevation.

Instance-flip correction: sampled `normal.xy` is multiplied by the
existing `instanceFlip` attribute so a `flipX`/`flipY` sprite responds
to lights from the geometrically-correct side.

Elevation drives `DefaultLightEffect`'s per-fragment light direction
(`L.z = lightHeight − elevation`). Different normalMap textures
produce different materials and therefore different batches.

## Example

```typescript
import { NormalMapProvider } from '@three-flatland/presets'

const provider = new NormalMapProvider()
provider.normalMap = myNormalMapTexture
sprite.addEffect(provider)
```

# three-flatland/src

## Classes

- [AnimatedSprite2D](/three-flatland/api/three-flatland/src/classes/animatedsprite2d/)
- [AnimationController](/three-flatland/api/three-flatland/src/classes/animationcontroller/)
- [EffectMaterial](/three-flatland/api/three-flatland/src/classes/effectmaterial/)
- [Flatland](/three-flatland/api/three-flatland/src/classes/flatland/)
- [ForwardPlusLighting](/three-flatland/api/three-flatland/src/classes/forwardpluslighting/)
- [GlobalUniforms](/three-flatland/api/three-flatland/src/classes/globaluniforms/)
- [Layer](/three-flatland/api/three-flatland/src/classes/layer/)
- [LDtkLoader](/three-flatland/api/three-flatland/src/classes/ldtkloader/)
- [Light2D](/three-flatland/api/three-flatland/src/classes/light2d/)
- [LightEffect](/three-flatland/api/three-flatland/src/classes/lighteffect/)
- [MaterialEffect](/three-flatland/api/three-flatland/src/classes/materialeffect/)
- [PassEffect](/three-flatland/api/three-flatland/src/classes/passeffect/)
- [Sprite2D](/three-flatland/api/three-flatland/src/classes/sprite2d/)
- [Sprite2DMaterial](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/)
- [SpriteGroup](/three-flatland/api/three-flatland/src/classes/spritegroup/)
- [SpriteSheetLoader](/three-flatland/api/three-flatland/src/classes/spritesheetloader/)
- [TextureConfig](/three-flatland/api/three-flatland/src/classes/textureconfig/)
- [TextureLoader](/three-flatland/api/three-flatland/src/classes/textureloader/)
- [TiledLoader](/three-flatland/api/three-flatland/src/classes/tiledloader/)
- [TileLayer](/three-flatland/api/three-flatland/src/classes/tilelayer/)
- [TileMap2D](/three-flatland/api/three-flatland/src/classes/tilemap2d/)
- [Tileset](/three-flatland/api/three-flatland/src/classes/tileset/)

## Interfaces

- [AnimatedSprite2DOptions](/three-flatland/api/three-flatland/src/interfaces/animatedsprite2doptions/)
- [Animation](/three-flatland/api/three-flatland/src/interfaces/animation/)
- [AnimationFrame](/three-flatland/api/three-flatland/src/interfaces/animationframe/)
- [AnimationSetDefinition](/three-flatland/api/three-flatland/src/interfaces/animationsetdefinition/)
- [AnimationState](/three-flatland/api/three-flatland/src/interfaces/animationstate/)
- [BatchKey](/three-flatland/api/three-flatland/src/interfaces/batchkey/)
- [ChannelNodeContext](/three-flatland/api/three-flatland/src/interfaces/channelnodecontext/)
- [ChannelNodeMap](/three-flatland/api/three-flatland/src/interfaces/channelnodemap/)
- [ChunkCoord](/three-flatland/api/three-flatland/src/interfaces/chunkcoord/)
- [ColorTransformContext](/three-flatland/api/three-flatland/src/interfaces/colortransformcontext/)
- [DevtoolsProviderHandle](/three-flatland/api/three-flatland/src/interfaces/devtoolsproviderhandle/)
- [EffectField](/three-flatland/api/three-flatland/src/interfaces/effectfield/)
- [EffectMaterialOptions](/three-flatland/api/three-flatland/src/interfaces/effectmaterialoptions/)
- [EffectNodeContext](/three-flatland/api/three-flatland/src/interfaces/effectnodecontext/)
- [FlatlandOptions](/three-flatland/api/three-flatland/src/interfaces/flatlandoptions/)
- [InstanceAttributeConfig](/three-flatland/api/three-flatland/src/interfaces/instanceattributeconfig/)
- [LayerConfig](/three-flatland/api/three-flatland/src/interfaces/layerconfig/)
- [LDtkLoaderOptions](/three-flatland/api/three-flatland/src/interfaces/ldtkloaderoptions/)
- [Light2DOptions](/three-flatland/api/three-flatland/src/interfaces/light2doptions/)
- [Light2DUniforms](/three-flatland/api/three-flatland/src/interfaces/light2duniforms/)
- [LightEffectBuildContext](/three-flatland/api/three-flatland/src/interfaces/lighteffectbuildcontext/)
- [LightEffectRuntimeContext](/three-flatland/api/three-flatland/src/interfaces/lighteffectruntimecontext/)
- [NormalRegion](/three-flatland/api/three-flatland/src/interfaces/normalregion/)
- [NormalSourceDescriptor](/three-flatland/api/three-flatland/src/interfaces/normalsourcedescriptor/)
- [ObjectLayerData](/three-flatland/api/three-flatland/src/interfaces/objectlayerdata/)
- [OcclusionPassOptions](/three-flatland/api/three-flatland/src/interfaces/occlusionpassoptions/)
- [PassEffectContext](/three-flatland/api/three-flatland/src/interfaces/passeffectcontext/)
- [PlayOptions](/three-flatland/api/three-flatland/src/interfaces/playoptions/)
- [RenderStats](/three-flatland/api/three-flatland/src/interfaces/renderstats/)
- [Sprite2DMaterialOptions](/three-flatland/api/three-flatland/src/interfaces/sprite2dmaterialoptions/)
- [Sprite2DOptions](/three-flatland/api/three-flatland/src/interfaces/sprite2doptions/)
- [SpriteFrame](/three-flatland/api/three-flatland/src/interfaces/spriteframe/)
- [SpriteFrameRect](/three-flatland/api/three-flatland/src/interfaces/spriteframerect/)
- [SpriteGroupOptions](/three-flatland/api/three-flatland/src/interfaces/spritegroupoptions/)
- [SpriteSheet](/three-flatland/api/three-flatland/src/interfaces/spritesheet/)
- [SpriteSheetJSONArray](/three-flatland/api/three-flatland/src/interfaces/spritesheetjsonarray/)
- [SpriteSheetJSONHash](/three-flatland/api/three-flatland/src/interfaces/spritesheetjsonhash/)
- [SpriteSheetLoaderOptions](/three-flatland/api/three-flatland/src/interfaces/spritesheetloaderoptions/)
- [TextureLoaderOptions](/three-flatland/api/three-flatland/src/interfaces/textureloaderoptions/)
- [TextureOptions](/three-flatland/api/three-flatland/src/interfaces/textureoptions/)
- [TileAnimationFrame](/three-flatland/api/three-flatland/src/interfaces/tileanimationframe/)
- [TileDefinition](/three-flatland/api/three-flatland/src/interfaces/tiledefinition/)
- [TiledLoaderOptions](/three-flatland/api/three-flatland/src/interfaces/tiledloaderoptions/)
- [TileInstance](/three-flatland/api/three-flatland/src/interfaces/tileinstance/)
- [TileLayerData](/three-flatland/api/three-flatland/src/interfaces/tilelayerdata/)
- [TileLayerOptions](/three-flatland/api/three-flatland/src/interfaces/tilelayeroptions/)
- [TileMap2DOptions](/three-flatland/api/three-flatland/src/interfaces/tilemap2doptions/)
- [TileMapData](/three-flatland/api/three-flatland/src/interfaces/tilemapdata/)
- [TileMapObject](/three-flatland/api/three-flatland/src/interfaces/tilemapobject/)
- [TileNormalCustomData](/three-flatland/api/three-flatland/src/interfaces/tilenormalcustomdata/)
- [TilesetCell](/three-flatland/api/three-flatland/src/interfaces/tilesetcell/)
- [TilesetData](/three-flatland/api/three-flatland/src/interfaces/tilesetdata/)

## Type Aliases

- [BlendMode](/three-flatland/api/three-flatland/src/type-aliases/blendmode/)
- [ChannelName](/three-flatland/api/three-flatland/src/type-aliases/channelname/)
- [CollisionShape](/three-flatland/api/three-flatland/src/type-aliases/collisionshape/)
- [ColorTransformFn](/three-flatland/api/three-flatland/src/type-aliases/colortransformfn/)
- [EffectConstants](/three-flatland/api/three-flatland/src/type-aliases/effectconstants/)
- [EffectSchema](/three-flatland/api/three-flatland/src/type-aliases/effectschema/)
- [EffectSchemaValue](/three-flatland/api/three-flatland/src/type-aliases/effectschemavalue/)
- [EffectValues](/three-flatland/api/three-flatland/src/type-aliases/effectvalues/)
- [InstanceAttributeType](/three-flatland/api/three-flatland/src/type-aliases/instanceattributetype/)
- [LayerName](/three-flatland/api/three-flatland/src/type-aliases/layername/)
- [LayerType](/three-flatland/api/three-flatland/src/type-aliases/layertype/)
- [LayerValue](/three-flatland/api/three-flatland/src/type-aliases/layervalue/)
- [Light2DType](/three-flatland/api/three-flatland/src/type-aliases/light2dtype/)
- [LightEffectClass](/three-flatland/api/three-flatland/src/type-aliases/lighteffectclass/)
- [MaterialEffectClass](/three-flatland/api/three-flatland/src/type-aliases/materialeffectclass/)
- [NormalBump](/three-flatland/api/three-flatland/src/type-aliases/normalbump/)
- [NormalDirection](/three-flatland/api/three-flatland/src/type-aliases/normaldirection/)
- [ObservableStrategy](/three-flatland/api/three-flatland/src/type-aliases/observablestrategy/)
- [PassEffectClass](/three-flatland/api/three-flatland/src/type-aliases/passeffectclass/)
- [PassEffectFn](/three-flatland/api/three-flatland/src/type-aliases/passeffectfn/)
- [Snapshot](/three-flatland/api/three-flatland/src/type-aliases/snapshot/)
- [SortMode](/three-flatland/api/three-flatland/src/type-aliases/sortmode/)
- [SpriteSortFunction](/three-flatland/api/three-flatland/src/type-aliases/spritesortfunction/)
- [TexturePreset](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/)
- [TileLookupFn](/three-flatland/api/three-flatland/src/type-aliases/tilelookupfn/)
- [UniformKeys](/three-flatland/api/three-flatland/src/type-aliases/uniformkeys/)
- [WithRequiredChannels](/three-flatland/api/three-flatland/src/type-aliases/withrequiredchannels/)

## Variables

- [channelDefaults](/three-flatland/api/three-flatland/src/variables/channeldefaults/)
- [DEFAULT\_BATCH\_SIZE](/three-flatland/api/three-flatland/src/variables/default_batch_size/)
- [EFFECT\_BIT\_OFFSET](/three-flatland/api/three-flatland/src/variables/effect_bit_offset/)
- [Layers](/three-flatland/api/three-flatland/src/variables/layers/)
- [LIT\_FLAG\_MASK](/three-flatland/api/three-flatland/src/variables/lit_flag_mask/)
- [MAX\_LIGHTS\_PER\_TILE](/three-flatland/api/three-flatland/src/variables/max_lights_per_tile/)
- [observable](/three-flatland/api/three-flatland/src/variables/observable/)
- [RECEIVE\_SHADOWS\_MASK](/three-flatland/api/three-flatland/src/variables/receive_shadows_mask/)
- [TEXTURE\_PRESETS](/three-flatland/api/three-flatland/src/variables/texture_presets/)
- [TILE\_SIZE](/three-flatland/api/three-flatland/src/variables/tile_size/)
- [VERSION](/three-flatland/api/three-flatland/src/variables/version/)

## Functions

- [applyHierarchicalPresets](/three-flatland/api/three-flatland/src/functions/applyhierarchicalpresets/)
- [applyTextureOptions](/three-flatland/api/three-flatland/src/functions/applytextureoptions/)
- [computeTier](/three-flatland/api/three-flatland/src/functions/computetier/)
- [concatAnimations](/three-flatland/api/three-flatland/src/functions/concatanimations/)
- [createAnimation](/three-flatland/api/three-flatland/src/functions/createanimation/)
- [createAnimationFromPattern](/three-flatland/api/three-flatland/src/functions/createanimationfrompattern/)
- [createAnimationsFromNaming](/three-flatland/api/three-flatland/src/functions/createanimationsfromnaming/)
- [createDevtoolsProvider](/three-flatland/api/three-flatland/src/functions/createdevtoolsprovider/)
- [createLightEffect](/three-flatland/api/three-flatland/src/functions/createlighteffect/)
- [createMaterialEffect](/three-flatland/api/three-flatland/src/functions/creatematerialeffect/)
- [createPassEffect](/three-flatland/api/three-flatland/src/functions/createpasseffect/)
- [decodeSortKey](/three-flatland/api/three-flatland/src/functions/decodesortkey/)
- [encodeSortKey](/three-flatland/api/three-flatland/src/functions/encodesortkey/)
- [framesToRegions](/three-flatland/api/three-flatland/src/functions/framestoregions/)
- [getPackedComponent](/three-flatland/api/three-flatland/src/functions/getpackedcomponent/)
- [isDevtoolsActive](/three-flatland/api/three-flatland/src/functions/isdevtoolsactive/)
- [isLight2D](/three-flatland/api/three-flatland/src/functions/islight2d/)
- [readCastShadowFlag](/three-flatland/api/three-flatland/src/functions/readcastshadowflag/)
- [readEnableBits](/three-flatland/api/three-flatland/src/functions/readenablebits/)
- [readFlip](/three-flatland/api/three-flatland/src/functions/readflip/)
- [readLitFlag](/three-flatland/api/three-flatland/src/functions/readlitflag/)
- [readReceiveShadowsFlag](/three-flatland/api/three-flatland/src/functions/readreceiveshadowsflag/)
- [readShadowRadius](/three-flatland/api/three-flatland/src/functions/readshadowradius/)
- [readSystemFlags](/three-flatland/api/three-flatland/src/functions/readsystemflags/)
- [registerDebugArray](/three-flatland/api/three-flatland/src/functions/registerdebugarray/)
- [registerDebugTexture](/three-flatland/api/three-flatland/src/functions/registerdebugtexture/)
- [resolveTextureOptions](/three-flatland/api/three-flatland/src/functions/resolvetextureoptions/)
- [reverseAnimation](/three-flatland/api/three-flatland/src/functions/reverseanimation/)
- [shallowEqual](/three-flatland/api/three-flatland/src/functions/shallowequal/)
- [tilesetToRegions](/three-flatland/api/three-flatland/src/functions/tilesettoregions/)
- [tileToRegions](/three-flatland/api/three-flatland/src/functions/tiletoregions/)
- [touchDebugArray](/three-flatland/api/three-flatland/src/functions/touchdebugarray/)
- [touchDebugTexture](/three-flatland/api/three-flatland/src/functions/touchdebugtexture/)
- [unregisterDebugArray](/three-flatland/api/three-flatland/src/functions/unregisterdebugarray/)
- [unregisterDebugTexture](/three-flatland/api/three-flatland/src/functions/unregisterdebugtexture/)
- [uvToWorld](/three-flatland/api/three-flatland/src/functions/uvtoworld/)
- [wholeTextureRegion](/three-flatland/api/three-flatland/src/functions/wholetextureregion/)
- [worldToUV](/three-flatland/api/three-flatland/src/functions/worldtouv/)
- [wrapWithLightFlags](/three-flatland/api/three-flatland/src/functions/wrapwithlightflags/)

# AnimatedSprite2D

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:66](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L66)

A 2D sprite with animation support.

## Example

```typescript
const player = new AnimatedSprite2D({
  spriteSheet: sheet,
  animationSet: {
    animations: {
      idle: { frames: ['player_idle_0', 'player_idle_1'], fps: 8 },
      walk: { frames: ['player_walk_0', 'player_walk_1', 'player_walk_2'], fps: 12 },
    }
  },
  animation: 'idle',
});

// In update loop
player.update(deltaMs);

// Change animation
player.play('walk');
```

## Extends

- [`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/)

## Constructors

### Constructor

> **new AnimatedSprite2D**(`options?`): `AnimatedSprite2D`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:77](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L77)

Create a new AnimatedSprite2D.
Can be called with no arguments for R3F compatibility - set spriteSheet via property.

#### Parameters

##### options?

[`AnimatedSprite2DOptions`](/three-flatland/api/three-flatland/src/interfaces/animatedsprite2doptions/)

#### Returns

`AnimatedSprite2D`

#### Overrides

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`constructor`](/three-flatland/api/three-flatland/src/classes/sprite2d/#constructor)

## Properties

### \_idx

> **\_idx**: `number` = `0`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:287](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L287)

Index into the backing arrays (0 when standalone, eid when enrolled).

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`_idx`](/three-flatland/api/three-flatland/src/classes/sprite2d/#_idx)

***

### animations

> **animations**: [`AnimationClip`](https://threejs.org/docs/)[]

Defined in: [three.js/core/Object3D:animations](https://threejs.org/docs/#api/en/core/Object3D.animations)

Array with object's animation clips.

#### Default Value

`[]`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`animations`](/three-flatland/api/three-flatland/src/classes/sprite2d/#animations)

***

### castShadow

> **castShadow**: `boolean`

Defined in: [three.js/core/Object3D:castShadow](https://threejs.org/docs/#api/en/core/Object3D.castShadow)

Whether the object gets rendered into shadow map.

#### Default Value

`false`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`castShadow`](/three-flatland/api/three-flatland/src/classes/sprite2d/#castshadow)

***

### children

> **children**: [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

Defined in: [three.js/core/Object3D:children](https://threejs.org/docs/#api/en/core/Object3D.children)

Array with object's children.

#### See

THREE.Object3DGroup \| Group for info on manually grouping objects.

#### Default Value

`[]`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`children`](/three-flatland/api/three-flatland/src/classes/sprite2d/#children)

***

### controller

> `readonly` **controller**: [`AnimationController`](/three-flatland/api/three-flatland/src/classes/animationcontroller/)

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:68](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L68)

Animation controller

***

### count

> **count**: `number`

Defined in: [three.js/objects/Mesh:count](https://threejs.org/docs/#api/en/objects/Mesh.count)

The number of instances of this mesh.
Can only be used with WebGPURenderer.

#### Default

```ts
1
```

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`count`](/three-flatland/api/three-flatland/src/classes/sprite2d/#count)

***

### customDepthMaterial?

> `optional` **customDepthMaterial?**: [`Material`](https://threejs.org/docs/#api/en/materials/Material)

Defined in: [three.js/core/Object3D:customDepthMaterial](https://threejs.org/docs/#api/en/core/Object3D.customDepthMaterial)

Custom depth material to be used when rendering to the depth map.

#### Remarks

Can only be used in context of meshes.
When shadow-casting with a THREE.DirectionalLight \| DirectionalLight or THREE.SpotLight \| SpotLight,
if you are modifying vertex positions in the vertex shader you must specify a customDepthMaterial for proper shadows.

#### Default Value

`undefined`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`customDepthMaterial`](/three-flatland/api/three-flatland/src/classes/sprite2d/#customdepthmaterial)

***

### customDistanceMaterial?

> `optional` **customDistanceMaterial?**: [`Material`](https://threejs.org/docs/#api/en/materials/Material)

Defined in: [three.js/core/Object3D:customDistanceMaterial](https://threejs.org/docs/#api/en/core/Object3D.customDistanceMaterial)

Same as [customDepthMaterial](/three-flatland/api/three-flatland/src/classes/flatland/#customdepthmaterial), but used with THREE.Object3DPointLight \| PointLight.

#### Default Value

`undefined`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`customDistanceMaterial`](/three-flatland/api/three-flatland/src/classes/sprite2d/#customdistancematerial)

***

### frustumCulled

> **frustumCulled**: `boolean`

Defined in: [three.js/core/Object3D:frustumCulled](https://threejs.org/docs/#api/en/core/Object3D.frustumCulled)

When this is set, it checks every frame if the object is in the frustum of the camera before rendering the object.
If set to `false` the object gets rendered every frame even if it is not in the frustum of the camera.

#### Default Value

`true`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`frustumCulled`](/three-flatland/api/three-flatland/src/classes/sprite2d/#frustumculled)

***

### geometry

> **geometry**: [`PlaneGeometry`](https://threejs.org/docs/#api/en/geometries/PlaneGeometry)

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:81](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L81)

An instance of THREE.BufferGeometry \| BufferGeometry (or derived classes), defining the object's structure.

#### Default Value

THREE.BufferGeometry \| \`new THREE.BufferGeometry()\`.

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`geometry`](/three-flatland/api/three-flatland/src/classes/sprite2d/#geometry)

***

### id

> `readonly` **id**: `number`

Defined in: [three.js/core/Object3D:id](https://threejs.org/docs/#api/en/core/Object3D.id)

Unique number for this [Object3D](https://threejs.org/docs/#api/en/core/Object3D) instance.

#### Remarks

Note that ids are assigned in chronological order: 1, 2, 3, ..., incrementing by one for each new object.
Expects a `Integer`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`id`](/three-flatland/api/three-flatland/src/classes/sprite2d/#id)

***

### isMesh

> `readonly` **isMesh**: `true`

Defined in: [three.js/objects/Mesh:isMesh](https://threejs.org/docs/#api/en/objects/Mesh.isMesh)

Read-only flag to check if a given object is of type [Mesh](https://threejs.org/docs/#api/en/objects/Mesh).

#### Remarks

This is a _constant_ value

#### Default Value

`true`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`isMesh`](/three-flatland/api/three-flatland/src/classes/sprite2d/#ismesh)

***

### isObject3D

> `readonly` **isObject3D**: `true`

Defined in: [three.js/core/Object3D:isObject3D](https://threejs.org/docs/#api/en/core/Object3D.isObject3D)

Flag to check if a given object is of type [Object3D](https://threejs.org/docs/#api/en/core/Object3D).

#### Remarks

This is a _constant_ value

#### Default Value

`true`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`isObject3D`](/three-flatland/api/three-flatland/src/classes/sprite2d/#isobject3d)

***

### layers

> **layers**: [`Layers`](https://threejs.org/docs/#api/en/core/Layers)

Defined in: [three.js/core/Object3D:layers](https://threejs.org/docs/#api/en/core/Object3D.layers)

The layer membership of the object.

#### Remarks

The object is only visible if it has at least one layer in common with the THREE.Object3DCamera \| Camera in use.
This property can also be used to filter out unwanted objects in ray-intersection tests when using THREE.Raycaster \| Raycaster.

#### Default Value

`new THREE.Layers()`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`layers`](/three-flatland/api/three-flatland/src/classes/sprite2d/#layers)

***

### material

> **material**: [`Sprite2DMaterial`](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/)

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:82](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L82)

An instance of material derived from the THREE.Material \| Material base class or an array of materials, defining the object's appearance.

#### Default Value

THREE.MeshBasicMaterial \| \`new THREE.MeshBasicMaterial()\`.

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`material`](/three-flatland/api/three-flatland/src/classes/sprite2d/#material)

***

### matrix

> **matrix**: [`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Defined in: [three.js/core/Object3D:matrix](https://threejs.org/docs/#api/en/core/Object3D.matrix)

The local transform matrix.

#### Default Value

`new THREE.Matrix4()`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`matrix`](/three-flatland/api/three-flatland/src/classes/sprite2d/#matrix)

***

### matrixAutoUpdate

> **matrixAutoUpdate**: `boolean`

Defined in: [three.js/core/Object3D:matrixAutoUpdate](https://threejs.org/docs/#api/en/core/Object3D.matrixAutoUpdate)

When this is set, it calculates the matrix of position, (rotation or quaternion) and
scale every frame and also recalculates the matrixWorld property.

#### Default Value

[DEFAULT\_MATRIX\_AUTO\_UPDATE](/three-flatland/api/three-flatland/src/classes/flatland/#default_matrix_auto_update) - that is `(true)`.

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`matrixAutoUpdate`](/three-flatland/api/three-flatland/src/classes/sprite2d/#matrixautoupdate)

***

### matrixWorld

> **matrixWorld**: [`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Defined in: [three.js/core/Object3D:matrixWorld](https://threejs.org/docs/#api/en/core/Object3D.matrixWorld)

The global transform of the object.

#### Remarks

If the [Object3D](https://threejs.org/docs/#api/en/core/Object3D) has no parent, then it's identical to the local transform THREE.Object3D.matrix \| .matrix.

#### Default Value

`new THREE.Matrix4()`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`matrixWorld`](/three-flatland/api/three-flatland/src/classes/sprite2d/#matrixworld)

***

### matrixWorldAutoUpdate

> **matrixWorldAutoUpdate**: `boolean`

Defined in: [three.js/core/Object3D:matrixWorldAutoUpdate](https://threejs.org/docs/#api/en/core/Object3D.matrixWorldAutoUpdate)

If set, then the renderer checks every frame if the object and its children need matrix updates.
When it isn't, then you have to maintain all matrices in the object and its children yourself.

#### Default Value

[DEFAULT\_MATRIX\_WORLD\_AUTO\_UPDATE](/three-flatland/api/three-flatland/src/classes/flatland/#default_matrix_world_auto_update) - that is `(true)`.

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`matrixWorldAutoUpdate`](/three-flatland/api/three-flatland/src/classes/sprite2d/#matrixworldautoupdate)

***

### matrixWorldNeedsUpdate

> **matrixWorldNeedsUpdate**: `boolean`

Defined in: [three.js/core/Object3D:matrixWorldNeedsUpdate](https://threejs.org/docs/#api/en/core/Object3D.matrixWorldNeedsUpdate)

When this is set, it calculates the matrixWorld in that frame and resets this property to false.

#### Default Value

`false`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`matrixWorldNeedsUpdate`](/three-flatland/api/three-flatland/src/classes/sprite2d/#matrixworldneedsupdate)

***

### modelViewMatrix

> `readonly` **modelViewMatrix**: [`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Defined in: [three.js/core/Object3D:modelViewMatrix](https://threejs.org/docs/#api/en/core/Object3D.modelViewMatrix)

#### Default Value

`new THREE.Matrix4()`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`modelViewMatrix`](/three-flatland/api/three-flatland/src/classes/sprite2d/#modelviewmatrix)

***

### morphTargetDictionary?

> `optional` **morphTargetDictionary?**: `object`

Defined in: [three.js/objects/Mesh:morphTargetDictionary](https://threejs.org/docs/#api/en/objects/Mesh.morphTargetDictionary)

A dictionary of morphTargets based on the `morphTarget.name` property.

#### Index Signature

\[`key`: `string`\]: `number`

#### Default Value

`undefined`, _but rebuilt by [.updateMorphTargets()](https://threejs.org/docs/)._

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`morphTargetDictionary`](/three-flatland/api/three-flatland/src/classes/sprite2d/#morphtargetdictionary)

***

### morphTargetInfluences?

> `optional` **morphTargetInfluences?**: `number`[]

Defined in: [three.js/objects/Mesh:morphTargetInfluences](https://threejs.org/docs/#api/en/objects/Mesh.morphTargetInfluences)

An array of weights typically from `0-1` that specify how much of the morph is applied.

#### Default Value

`undefined`, _but reset to a blank array by [.updateMorphTargets()](https://threejs.org/docs/)._

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`morphTargetInfluences`](/three-flatland/api/three-flatland/src/classes/sprite2d/#morphtargetinfluences)

***

### name

> **name**: `string`

Defined in: [three.js/core/Object3D:name](https://threejs.org/docs/#api/en/core/Object3D.name)

Optional name of the object

#### Remarks

_(doesn't need to be unique)_.

#### Default Value

`""`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`name`](/three-flatland/api/three-flatland/src/classes/sprite2d/#name)

***

### normalMatrix

> `readonly` **normalMatrix**: [`Matrix3`](https://threejs.org/docs/#api/en/math/Matrix3)

Defined in: [three.js/core/Object3D:normalMatrix](https://threejs.org/docs/#api/en/core/Object3D.normalMatrix)

#### Default Value

`new THREE.Matrix3()`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`normalMatrix`](/three-flatland/api/three-flatland/src/classes/sprite2d/#normalmatrix)

***

### occlusionTest?

> `optional` **occlusionTest?**: `boolean`

Defined in: [three.js/renderers/common/Backend:occlusionTest](https://threejs.org/docs/#api/en/renderers/common/Backend.occlusionTest)

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`occlusionTest`](/three-flatland/api/three-flatland/src/classes/sprite2d/#occlusiontest)

***

### parent

> **parent**: [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `null`

Defined in: [three.js/core/Object3D:parent](https://threejs.org/docs/#api/en/core/Object3D.parent)

Object's parent in the [scene graph](https://en.wikipedia.org/wiki/Scene_graph).

#### Remarks

An object can have at most one parent.

#### Default Value

`null`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`parent`](/three-flatland/api/three-flatland/src/classes/sprite2d/#parent)

***

### pivot

> **pivot**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3) \| `null`

Defined in: [three.js/core/Object3D:pivot](https://threejs.org/docs/#api/en/core/Object3D.pivot)

The pivot point for rotation and scale transformations.
When set, rotation and scale are applied around this point
instead of the object's origin.

#### Default

```ts
null
```

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`pivot`](/three-flatland/api/three-flatland/src/classes/sprite2d/#pivot)

***

### pixelPerfect

> **pixelPerfect**: `boolean` = `false`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:106](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L106)

Pixel-perfect mode

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`pixelPerfect`](/three-flatland/api/three-flatland/src/classes/sprite2d/#pixelperfect)

***

### position

> `readonly` **position**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:position](https://threejs.org/docs/#api/en/core/Object3D.position)

Object's local position.

#### Default Value

`new THREE.Vector3()` - that is `(0, 0, 0)`.

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`position`](/three-flatland/api/three-flatland/src/classes/sprite2d/#position)

***

### quaternion

> `readonly` **quaternion**: [`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

Defined in: [three.js/core/Object3D:quaternion](https://threejs.org/docs/#api/en/core/Object3D.quaternion)

Object's local rotation as a THREE.Quaternion \| Quaternion.

#### Default Value

`new THREE.Quaternion()` - that is `(0,  0, 0, 1)`.

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`quaternion`](/three-flatland/api/three-flatland/src/classes/sprite2d/#quaternion)

***

### receiveShadow

> **receiveShadow**: `boolean`

Defined in: [three.js/core/Object3D:receiveShadow](https://threejs.org/docs/#api/en/core/Object3D.receiveShadow)

Whether the material receives shadows.

#### Default Value

`false`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`receiveShadow`](/three-flatland/api/three-flatland/src/classes/sprite2d/#receiveshadow)

***

### renderOrder

> **renderOrder**: `number`

Defined in: [three.js/core/Object3D:renderOrder](https://threejs.org/docs/#api/en/core/Object3D.renderOrder)

This value allows the default rendering order of [scene graph](https://en.wikipedia.org/wiki/Scene_graph)
objects to be overridden although opaque and transparent objects remain sorted independently.

#### Remarks

When this property is set for an instance of [Group](https://threejs.org/docs/#api/en/objects/Group), all descendants objects will be sorted and rendered together.
Sorting is from lowest to highest renderOrder.

#### Default Value

`0`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`renderOrder`](/three-flatland/api/three-flatland/src/classes/sprite2d/#renderorder)

***

### rotation

> `readonly` **rotation**: [`Euler`](https://threejs.org/docs/#api/en/math/Euler)

Defined in: [three.js/core/Object3D:rotation](https://threejs.org/docs/#api/en/core/Object3D.rotation)

Object's local rotation ([Euler angles](https://en.wikipedia.org/wiki/Euler_angles)), in radians.

#### Default Value

`new THREE.Euler()` - that is `(0, 0, 0, Euler.DEFAULT_ORDER)`.

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`rotation`](/three-flatland/api/three-flatland/src/classes/sprite2d/#rotation)

***

### scale

> `readonly` **scale**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:scale](https://threejs.org/docs/#api/en/core/Object3D.scale)

The object's local scale.

#### Default Value

`new THREE.Vector3( 1, 1, 1 )`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`scale`](/three-flatland/api/three-flatland/src/classes/sprite2d/#scale)

***

### static

> **static**: `boolean`

Defined in: [three.js/core/Object3D:static](https://threejs.org/docs/#api/en/core/Object3D.static)

Whether the 3D object is supposed to be static or not. If set to `true`, it means
the 3D object is not going to be changed after the initial renderer. This includes
geometry and material settings. A static 3D object can be processed by the renderer
slightly faster since certain state checks can be bypassed.

Only relevant in context of WebGPURenderer.

#### Default

```ts
false
```

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`static`](/three-flatland/api/three-flatland/src/classes/sprite2d/#static)

***

### type

> `readonly` **type**: `string`

Defined in: [three.js/objects/Mesh:type](https://threejs.org/docs/#api/en/objects/Mesh.type)

#### Default Value

`Mesh`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`type`](/three-flatland/api/three-flatland/src/classes/sprite2d/#type)

***

### up

> **up**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:up](https://threejs.org/docs/#api/en/core/Object3D.up)

This is used by the [lookAt](https://threejs.org/docs/) method, for example, to determine the orientation of the result.

#### Default Value

[Object3D.DEFAULT\_UP](/three-flatland/api/three-flatland/src/classes/flatland/#default_up) - that is `(0, 1, 0)`.

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`up`](/three-flatland/api/three-flatland/src/classes/sprite2d/#up)

***

### userData

> **userData**: `Record`\<`string`, `any`\>

Defined in: [three.js/core/Object3D:userData](https://threejs.org/docs/#api/en/core/Object3D.userData)

An object that can be used to store custom data about the [Object3D](https://threejs.org/docs/#api/en/core/Object3D).

#### Remarks

It should not hold references to _functions_ as these **will not** be cloned.

#### Default

`{}`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`userData`](/three-flatland/api/three-flatland/src/classes/sprite2d/#userdata)

***

### uuid

> **uuid**: `string`

Defined in: [three.js/core/Object3D:uuid](https://threejs.org/docs/#api/en/core/Object3D.uuid)

[UUID](http://en.wikipedia.org/wiki/Universally_unique_identifier) of this object instance.

#### Remarks

This gets automatically assigned and shouldn't be edited.

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`uuid`](/three-flatland/api/three-flatland/src/classes/sprite2d/#uuid)

***

### visible

> **visible**: `boolean`

Defined in: [three.js/core/Object3D:visible](https://threejs.org/docs/#api/en/core/Object3D.visible)

Object gets rendered if `true`.

#### Default Value

`true`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`visible`](/three-flatland/api/three-flatland/src/classes/sprite2d/#visible)

***

### DEFAULT\_MATRIX\_AUTO\_UPDATE

> `static` **DEFAULT\_MATRIX\_AUTO\_UPDATE**: `boolean`

Defined in: [three.js/core/Object3D:DEFAULT_MATRIX_AUTO_UPDATE](https://threejs.org/docs/#api/en/core/Object3D.DEFAULT_MATRIX_AUTO_UPDATE)

The default setting for [matrixAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixautoupdate) for newly created Object3Ds.

#### Default Value

`true`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`DEFAULT_MATRIX_AUTO_UPDATE`](/three-flatland/api/three-flatland/src/classes/sprite2d/#default_matrix_auto_update)

***

### DEFAULT\_MATRIX\_WORLD\_AUTO\_UPDATE

> `static` **DEFAULT\_MATRIX\_WORLD\_AUTO\_UPDATE**: `boolean`

Defined in: [three.js/core/Object3D:DEFAULT_MATRIX_WORLD_AUTO_UPDATE](https://threejs.org/docs/#api/en/core/Object3D.DEFAULT_MATRIX_WORLD_AUTO_UPDATE)

The default setting for [matrixWorldAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldautoupdate) for newly created Object3Ds.

#### Default Value

`true`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`DEFAULT_MATRIX_WORLD_AUTO_UPDATE`](/three-flatland/api/three-flatland/src/classes/sprite2d/#default_matrix_world_auto_update)

***

### DEFAULT\_UP

> `static` **DEFAULT\_UP**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:DEFAULT_UP](https://threejs.org/docs/#api/en/core/Object3D.DEFAULT_UP)

The default [up](/three-flatland/api/three-flatland/src/classes/flatland/#up) direction for objects, also used as the default position for THREE.DirectionalLight \| DirectionalLight,
THREE.HemisphereLight \| HemisphereLight and THREE.Spotlight \| Spotlight (which creates lights shining from the top down).

#### Default Value

`new THREE.Vector3( 0, 1, 0)`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`DEFAULT_UP`](/three-flatland/api/three-flatland/src/classes/sprite2d/#default_up)

## Accessors

### alpha

#### Get Signature

> **get** **alpha**(): `number`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:793](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L793)

Get alpha/opacity.

##### Returns

`number`

#### Set Signature

> **set** **alpha**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:800](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L800)

Set alpha/opacity (0-1).

##### Parameters

###### value

`number`

##### Returns

`void`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`alpha`](/three-flatland/api/three-flatland/src/classes/sprite2d/#alpha)

***

### anchor

#### Get Signature

> **get** **anchor**(): [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:739](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L739)

Get the anchor point. Returns the stored Vector2 (like Object3D.position).

##### Returns

[`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

#### Set Signature

> **set** **anchor**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:746](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L746)

Set the anchor point. Accepts [x, y] array or Vector2.

##### Parameters

###### value

\[`number`, `number`\] \| [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

##### Returns

`void`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`anchor`](/three-flatland/api/three-flatland/src/classes/sprite2d/#anchor)

***

### animation

#### Set Signature

> **set** **animation**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:162](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L162)

Set the current animation by name (R3F compatible).
Plays the animation if found.

##### Parameters

###### value

`string` \| `null`

##### Returns

`void`

***

### animationSet

#### Set Signature

> **set** **animationSet**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:152](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L152)

Set animation set definition (R3F compatible).
Loads animations from the definition.

##### Parameters

###### value

[`AnimationSetDefinition`](/three-flatland/api/three-flatland/src/interfaces/animationsetdefinition/) \| `null`

##### Returns

`void`

***

### castsShadow

#### Get Signature

> **get** **castsShadow**(): `boolean`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:219](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L219)

Whether this sprite contributes its silhouette to the shadow-caster
occlusion pre-pass. Stored as bit 2 of `_systemFlags`. Default: `false`
— most sprites don't cast; opt in by setting to `true`.

Consumed by the occlusion pre-pass shader, which masks the sprite's
alpha by this bit before the SDF seed. Flipping it takes effect on
the next frame with zero CPU rebuild (same model as `receiveShadows`).

##### Returns

`boolean`

#### Set Signature

> **set** **castsShadow**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:223](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L223)

##### Parameters

###### value

`boolean`

##### Returns

`void`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`castsShadow`](/three-flatland/api/three-flatland/src/classes/sprite2d/#castsshadow)

***

### currentAnimation

#### Get Signature

> **get** **currentAnimation**(): `string` \| `null`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:333](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L333)

Get current animation name.

##### Returns

`string` \| `null`

***

### flipX

#### Get Signature

> **get** **flipX**(): `boolean`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:819](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L819)

Get flipX state.

##### Returns

`boolean`

#### Set Signature

> **set** **flipX**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:826](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L826)

Set flipX state.

##### Parameters

###### value

`boolean`

##### Returns

`void`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`flipX`](/three-flatland/api/three-flatland/src/classes/sprite2d/#flipx)

***

### flipY

#### Get Signature

> **get** **flipY**(): `boolean`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:841](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L841)

Get flipY state.

##### Returns

`boolean`

#### Set Signature

> **set** **flipY**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:848](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L848)

Set flipY state.

##### Parameters

###### value

`boolean`

##### Returns

`void`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`flipY`](/three-flatland/api/three-flatland/src/classes/sprite2d/#flipy)

***

### frame

#### Get Signature

> **get** **frame**(): [`SpriteFrame`](/three-flatland/api/three-flatland/src/interfaces/spriteframe/) \| `null`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:691](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L691)

Get the current frame.

##### Returns

[`SpriteFrame`](/three-flatland/api/three-flatland/src/interfaces/spriteframe/) \| `null`

#### Set Signature

> **set** **frame**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:698](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L698)

Set the current frame (R3F prop compatibility).

##### Parameters

###### value

[`SpriteFrame`](/three-flatland/api/three-flatland/src/interfaces/spriteframe/) \| `null`

##### Returns

`void`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`frame`](/three-flatland/api/three-flatland/src/classes/sprite2d/#frame)

***

### height

#### Get Signature

> **get** **height**(): `number`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:940](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L940)

Get the height of the sprite in world units.

##### Returns

`number`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`height`](/three-flatland/api/three-flatland/src/classes/sprite2d/#height)

***

### layer

#### Get Signature

> **get** **layer**(): `number`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:880](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L880)

Get render layer (primary sort key).

##### Returns

`number`

#### Set Signature

> **set** **layer**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:887](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L887)

Set render layer (primary sort key).

##### Parameters

###### value

`number`

##### Returns

`void`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`layer`](/three-flatland/api/three-flatland/src/classes/sprite2d/#layer)

***

### lit

#### Get Signature

> **get** **lit**(): `boolean`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:114](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L114)

Whether this sprite receives lighting from Flatland's LightEffect.
Stored as bit 0 of `_systemFlags` so lit/unlit sprites with the same
texture share the same material and batch together.
Default: `true` — set `lit = false` to opt out.

##### Returns

`boolean`

#### Set Signature

> **set** **lit**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:118](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L118)

##### Parameters

###### value

`boolean`

##### Returns

`void`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`lit`](/three-flatland/api/three-flatland/src/classes/sprite2d/#lit)

***

### receiveShadows

#### Get Signature

> **get** **receiveShadows**(): `boolean`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:141](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L141)

Whether this sprite receives shadows from the SDF shadow pipeline.
Stored as bit 1 of `_systemFlags`.
Default: `true` — set `receiveShadows = false` to opt out.

##### Returns

`boolean`

#### Set Signature

> **set** **receiveShadows**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:145](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L145)

##### Parameters

###### value

`boolean`

##### Returns

`void`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`receiveShadows`](/three-flatland/api/three-flatland/src/classes/sprite2d/#receiveshadows)

***

### shadowRadius

#### Get Signature

> **get** **shadowRadius**(): `number` \| `undefined`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:193](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L193)

Per-sprite occluder radius (world units) consumed by shadow-casting
LightEffects — e.g. DefaultLightEffect's SDF sphere-tracer
uses it as the self-silhouette escape distance so a tracer launched
from inside the caster steps out cleanly.

Returns `undefined` while in auto-resolve mode (default), in which
case `transformSyncSystem` writes `max(|scale.x|, |scale.y|)` into
the per-instance attribute each frame — covering animation frames
and runtime scale changes without manual updates. Assign a number
to override (useful when the visible body is tighter than the
quad's bounds, or when an off-center anchor pushes the silhouette).
Assign `undefined` to return to auto-resolve.

##### Returns

`number` \| `undefined`

#### Set Signature

> **set** **shadowRadius**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:197](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L197)

##### Parameters

###### value

`number` \| `undefined`

##### Returns

`void`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`shadowRadius`](/three-flatland/api/three-flatland/src/classes/sprite2d/#shadowradius)

***

### speed

#### Get Signature

> **get** **speed**(): `number`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:340](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L340)

Get playback speed.

##### Returns

`number`

#### Set Signature

> **set** **speed**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:347](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L347)

Set playback speed.

##### Parameters

###### value

`number`

##### Returns

`void`

***

### spriteSheet

#### Get Signature

> **get** **spriteSheet**(): [`SpriteSheet`](/three-flatland/api/three-flatland/src/interfaces/spritesheet/) \| `null`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:129](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L129)

Get the spritesheet.

##### Returns

[`SpriteSheet`](/three-flatland/api/three-flatland/src/interfaces/spritesheet/) \| `null`

#### Set Signature

> **set** **spriteSheet**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:136](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L136)

Set a new spritesheet.

##### Parameters

###### value

[`SpriteSheet`](/three-flatland/api/three-flatland/src/interfaces/spritesheet/) \| `null`

##### Returns

`void`

***

### texture

#### Get Signature

> **get** **texture**(): [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:605](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L605)

Get the current texture.

##### Returns

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

#### Set Signature

> **set** **texture**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:612](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L612)

Set a new texture.

##### Parameters

###### value

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

##### Returns

`void`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`texture`](/three-flatland/api/three-flatland/src/classes/sprite2d/#texture)

***

### tint

#### Get Signature

> **get** **tint**(): [`Color`](https://threejs.org/docs/#api/en/math/Color)

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:772](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L772)

Get tint color. Returns a stored Color reference (like Material.color).
Mutating the returned Color triggers ECS sync via onChange callback.

##### Returns

[`Color`](https://threejs.org/docs/#api/en/math/Color)

#### Set Signature

> **set** **tint**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:779](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L779)

Set tint color. Accepts Color, hex string, hex number, or [r, g, b] array (0-1).

##### Parameters

###### value

`string` \| `number` \| \[`number`, `number`, `number`\] \| [`Color`](https://threejs.org/docs/#api/en/math/Color)

##### Returns

`void`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`tint`](/three-flatland/api/three-flatland/src/classes/sprite2d/#tint)

***

### width

#### Get Signature

> **get** **width**(): `number`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:933](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L933)

Get the width of the sprite in world units.

##### Returns

`number`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`width`](/three-flatland/api/three-flatland/src/classes/sprite2d/#width)

***

### zIndex

#### Get Signature

> **get** **zIndex**(): `number`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:897](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L897)

Get z-index within layer (secondary sort key).

##### Returns

`number`

#### Set Signature

> **set** **zIndex**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:919](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L919)

Set z-index within layer (secondary sort key).

Hot path. Every moving sprite in a y-sorted scene calls this every
frame, so the cost has to stay near-zero per call.

The raw SoA write is unconditional — `transformSyncSystem` reads
`_zIndexArr` directly and bakes the value into the instance matrix
for the GPU depth test. That alone is enough for alphaTest+depthWrite
materials (GPU resolves order via the baked-in Z, no CPU sort needed).

For non-gated materials, we flip the batch's `_sortDirty` flag so
`batchSortSystem` knows to re-sort this batch on its next pass. This
replaced the prior `Changed(SpriteZIndex)` channel — Koota's change
tracker enumerated every flip every frame even when the gate trivially
skipped the sort, costing ~7ms/frame in a 12k-sprite demo. The
per-batch boolean costs one ref read + one write.

##### Parameters

###### value

`number`

##### Returns

`void`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`zIndex`](/three-flatland/api/three-flatland/src/classes/sprite2d/#zindex)

## Methods

### \_setupInstanceAttributes()

> **\_setupInstanceAttributes**(): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:1003](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L1003)

Set up instance attributes on the geometry for single-sprite rendering.
Uses one interleaved buffer (mirroring SpriteBatch) so batched and
standalone paths share the same shader attribute shape. Also
allocates buffers for custom attributes from the material's schema
(pure effect data — `effectBuf0`, `effectBuf1`, ...).

#### Returns

`void`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`_setupInstanceAttributes`](/three-flatland/api/three-flatland/src/classes/sprite2d/#_setupinstanceattributes)

***

### add()

> **add**(...`object`): `this`

Defined in: [three.js/core/Object3D:add](https://threejs.org/docs/#api/en/core/Object3D.add)

Adds another [Object3D](https://threejs.org/docs/#api/en/core/Object3D) as child of this [Object3D](https://threejs.org/docs/#api/en/core/Object3D).

#### Parameters

##### object

...[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

#### Returns

`this`

#### Remarks

An arbitrary number of objects may be added
Any current parent on an object passed in here will be removed, since an [Object3D](https://threejs.org/docs/#api/en/core/Object3D) can have at most one parent.

#### See

 - [attach](https://threejs.org/docs/)
 - THREE.Group \| Group for info on manually grouping objects.

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`add`](/three-flatland/api/three-flatland/src/classes/sprite2d/#add)

***

### addAnimation()

> **addAnimation**(`animation`): `this`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:211](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L211)

Add an animation.

#### Parameters

##### animation

[`Animation`](/three-flatland/api/three-flatland/src/interfaces/animation/)

#### Returns

`this`

***

### addAnimationFromFrames()

> **addAnimationFromFrames**(`name`, `frameNames`, `options?`): `this`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:219](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L219)

Add animation from frame names.

#### Parameters

##### name

`string`

##### frameNames

`string`[]

##### options?

###### fps?

`number`

###### loop?

`boolean`

###### pingPong?

`boolean`

#### Returns

`this`

***

### addEffect()

> **addEffect**(`effect`): `this`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:1105](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L1105)

Add an effect instance to this sprite.
Auto-registers the effect type on the material if not already registered.
Sets the enable bit and writes effect data to packed buffers.

#### Parameters

##### effect

[`MaterialEffect`](/three-flatland/api/three-flatland/src/classes/materialeffect/)

#### Returns

`this`

#### Example

```typescript
const dissolve = new DissolveEffect()
dissolve.progress = 0.5
sprite.addEffect(dissolve)
```

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`addEffect`](/three-flatland/api/three-flatland/src/classes/sprite2d/#addeffect)

***

### addEventListener()

> **addEventListener**\<`T`\>(`type`, `listener`): `void`

Defined in: [three.js/core/EventDispatcher:addEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.addEventListener)

Adds a listener to an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### type

`T`

The type of event to listen to.

##### listener

[`EventListener`](https://threejs.org/docs/)\<[`Object3DEventMap`](https://threejs.org/docs/)\[`T`\], `T`, `AnimatedSprite2D`\>

The function that gets called when the event is fired.

#### Returns

`void`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`addEventListener`](/three-flatland/api/three-flatland/src/classes/sprite2d/#addeventlistener)

***

### applyMatrix4()

> **applyMatrix4**(`matrix`): `void`

Defined in: [three.js/core/Object3D:applyMatrix4](https://threejs.org/docs/#api/en/core/Object3D.applyMatrix4)

Applies the matrix transform to the object and updates the object's position, rotation and scale.

#### Parameters

##### matrix

[`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

#### Returns

`void`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`applyMatrix4`](/three-flatland/api/three-flatland/src/classes/sprite2d/#applymatrix4)

***

### applyQuaternion()

> **applyQuaternion**(`quaternion`): `this`

Defined in: [three.js/core/Object3D:applyQuaternion](https://threejs.org/docs/#api/en/core/Object3D.applyQuaternion)

Applies the rotation represented by the quaternion to the object.

#### Parameters

##### quaternion

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

#### Returns

`this`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`applyQuaternion`](/three-flatland/api/three-flatland/src/classes/sprite2d/#applyquaternion)

***

### attach()

> **attach**(`object`): `this`

Defined in: [three.js/core/Object3D:attach](https://threejs.org/docs/#api/en/core/Object3D.attach)

Adds a [Object3D](https://threejs.org/docs/#api/en/core/Object3D) as a child of this, while maintaining the object's world transform.

#### Parameters

##### object

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)

#### Returns

`this`

#### Remarks

Note: This method does not support scene graphs having non-uniformly-scaled nodes(s).

#### See

[add](https://threejs.org/docs/)

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`attach`](/three-flatland/api/three-flatland/src/classes/sprite2d/#attach)

***

### clear()

> **clear**(): `this`

Defined in: [three.js/core/Object3D:clear](https://threejs.org/docs/#api/en/core/Object3D.clear)

Removes all child objects.

#### Returns

`this`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`clear`](/three-flatland/api/three-flatland/src/classes/sprite2d/#clear)

***

### clone()

> **clone**(`recursive?`): `this`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:363](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L363)

Clone the animated sprite.

#### Parameters

##### recursive?

`boolean`

#### Returns

`this`

#### Overrides

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`clone`](/three-flatland/api/three-flatland/src/classes/sprite2d/#clone)

***

### copy()

> **copy**(`object`, `recursive?`): `this`

Defined in: [three.js/core/Object3D:copy](https://threejs.org/docs/#api/en/core/Object3D.copy)

Copies the given object into this object.

#### Parameters

##### object

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)

##### recursive?

`boolean`

If set to `true`, descendants of the object are copied next to the existing ones. If set to
`false`, descendants are left unchanged. Default is `true`.

#### Returns

`this`

#### Remarks

Event listeners and user-defined callbacks (.onAfterRender and .onBeforeRender) are not copied.

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`copy`](/three-flatland/api/three-flatland/src/classes/sprite2d/#copy)

***

### dispatchEvent()

> **dispatchEvent**\<`T`\>(`event`): `void`

Defined in: [three.js/core/EventDispatcher:dispatchEvent](https://threejs.org/docs/#api/en/core/EventDispatcher.dispatchEvent)

Fire an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### event

[`BaseEvent`](https://threejs.org/docs/)\<`T`\> & [`Object3DEventMap`](https://threejs.org/docs/)\[`T`\]

The event that gets fired.

#### Returns

`void`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`dispatchEvent`](/three-flatland/api/three-flatland/src/classes/sprite2d/#dispatchevent)

***

### dispose()

> **dispose**(): `void`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:417](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L417)

Dispose of resources.

#### Returns

`void`

#### Overrides

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`dispose`](/three-flatland/api/three-flatland/src/classes/sprite2d/#dispose)

***

### flip()

> **flip**(`horizontal`, `vertical`): `this`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:863](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L863)

Flip the sprite.

#### Parameters

##### horizontal

`boolean`

##### vertical

`boolean`

#### Returns

`this`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`flip`](/three-flatland/api/three-flatland/src/classes/sprite2d/#flip)

***

### getAnimationDuration()

> **getAnimationDuration**(`name?`): `number`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:354](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L354)

Get animation duration.

#### Parameters

##### name?

`string`

#### Returns

`number`

***

### getObjectById()

> **getObjectById**(`id`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

Defined in: [three.js/core/Object3D:getObjectById](https://threejs.org/docs/#api/en/core/Object3D.getObjectById)

Searches through an object and its children, starting with the object itself, and returns the first with a matching id.

#### Parameters

##### id

`number`

Unique number of the object instance. Expects a `Integer`

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

#### Remarks

Note that ids are assigned in chronological order: 1, 2, 3, ..., incrementing by one for each new object.

#### See

id

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`getObjectById`](/three-flatland/api/three-flatland/src/classes/sprite2d/#getobjectbyid)

***

### getObjectByName()

> **getObjectByName**(`name`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

Defined in: [three.js/core/Object3D:getObjectByName](https://threejs.org/docs/#api/en/core/Object3D.getObjectByName)

Searches through an object and its children, starting with the object itself, and returns the first with a matching name.

#### Parameters

##### name

`string`

String to match to the children's Object3D.name property.

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

#### Remarks

Note that for most objects the name is an empty string by default
You will have to set it manually to make use of this method.

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`getObjectByName`](/three-flatland/api/three-flatland/src/classes/sprite2d/#getobjectbyname)

***

### getObjectByProperty()

> **getObjectByProperty**(`name`, `value`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

Defined in: [three.js/core/Object3D:getObjectByProperty](https://threejs.org/docs/#api/en/core/Object3D.getObjectByProperty)

Searches through an object and its children, starting with the object itself,
and returns the first with a property that matches the value given.

#### Parameters

##### name

`string`

the property name to search for.

##### value

`any`

value of the given property.

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`getObjectByProperty`](/three-flatland/api/three-flatland/src/classes/sprite2d/#getobjectbyproperty)

***

### getObjectsByProperty()

> **getObjectsByProperty**(`name`, `value`, `optionalTarget?`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

Defined in: [three.js/core/Object3D:getObjectsByProperty](https://threejs.org/docs/#api/en/core/Object3D.getObjectsByProperty)

Searches through an object and its children, starting with the object itself,
and returns the first with a property that matches the value given.

#### Parameters

##### name

`string`

The property name to search for.

##### value

`any`

Value of the given property.

##### optionalTarget?

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

target to set the result. Otherwise a new Array is instantiated. If set, you must clear
this array prior to each call (i.e., array.length = 0;).

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`getObjectsByProperty`](/three-flatland/api/three-flatland/src/classes/sprite2d/#getobjectsbyproperty)

***

### getVertexPosition()

> **getVertexPosition**(`index`, `target`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/objects/Mesh:getVertexPosition](https://threejs.org/docs/#api/en/objects/Mesh.getVertexPosition)

Get the local-space position of the vertex at the given index,
taking into account the current animation state of both morph targets and skinning.

#### Parameters

##### index

`number`

Expects a `Integer`

##### target

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`getVertexPosition`](/three-flatland/api/three-flatland/src/classes/sprite2d/#getvertexposition)

***

### getWorldDirection()

> **getWorldDirection**(`target`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:getWorldDirection](https://threejs.org/docs/#api/en/core/Object3D.getWorldDirection)

Returns a vector representing the direction of object's positive z-axis in world space.

#### Parameters

##### target

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

The result will be copied into this Vector3.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`getWorldDirection`](/three-flatland/api/three-flatland/src/classes/sprite2d/#getworlddirection)

***

### getWorldPosition()

> **getWorldPosition**(`target`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:getWorldPosition](https://threejs.org/docs/#api/en/core/Object3D.getWorldPosition)

Returns a vector representing the position of the object in world space.

#### Parameters

##### target

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

The result will be copied into this Vector3.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`getWorldPosition`](/three-flatland/api/three-flatland/src/classes/sprite2d/#getworldposition)

***

### getWorldPosition2D()

> **getWorldPosition2D**(): [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:1083](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L1083)

Get world position (convenience method).

#### Returns

[`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`getWorldPosition2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/#getworldposition2d)

***

### getWorldQuaternion()

> **getWorldQuaternion**(`target`): [`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

Defined in: [three.js/core/Object3D:getWorldQuaternion](https://threejs.org/docs/#api/en/core/Object3D.getWorldQuaternion)

Returns a quaternion representing the rotation of the object in world space.

#### Parameters

##### target

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

The result will be copied into this Quaternion.

#### Returns

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`getWorldQuaternion`](/three-flatland/api/three-flatland/src/classes/sprite2d/#getworldquaternion)

***

### getWorldScale()

> **getWorldScale**(`target`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:getWorldScale](https://threejs.org/docs/#api/en/core/Object3D.getWorldScale)

Returns a vector of the scaling factors applied to the object for each axis in world space.

#### Parameters

##### target

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

The result will be copied into this Vector3.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`getWorldScale`](/three-flatland/api/three-flatland/src/classes/sprite2d/#getworldscale)

***

### gotoFrame()

> **gotoFrame**(`index`): `this`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:289](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L289)

Go to a specific frame.

#### Parameters

##### index

`number`

#### Returns

`this`

***

### hasEventListener()

> **hasEventListener**\<`T`\>(`type`, `listener`): `boolean`

Defined in: [three.js/core/EventDispatcher:hasEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.hasEventListener)

Checks if listener is added to an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### type

`T`

The type of event to listen to.

##### listener

[`EventListener`](https://threejs.org/docs/)\<[`Object3DEventMap`](https://threejs.org/docs/)\[`T`\], `T`, `AnimatedSprite2D`\>

The function that gets called when the event is fired.

#### Returns

`boolean`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`hasEventListener`](/three-flatland/api/three-flatland/src/classes/sprite2d/#haseventlistener)

***

### isPlaying()

> **isPlaying**(`name?`): `boolean`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:326](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L326)

Check if an animation is playing.

#### Parameters

##### name?

`string`

#### Returns

`boolean`

***

### loadAnimationSet()

> **loadAnimationSet**(`definition`): `this`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:171](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L171)

Load animations from an animation set definition.

#### Parameters

##### definition

[`AnimationSetDefinition`](/three-flatland/api/three-flatland/src/interfaces/animationsetdefinition/)

#### Returns

`this`

***

### localToWorld()

> **localToWorld**(`vector`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:localToWorld](https://threejs.org/docs/#api/en/core/Object3D.localToWorld)

Converts the vector from this object's local space to world space.

#### Parameters

##### vector

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A vector representing a position in this object's local space.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`localToWorld`](/three-flatland/api/three-flatland/src/classes/sprite2d/#localtoworld)

***

### lookAt()

#### Call Signature

> **lookAt**(`vector`): `void`

Defined in: [three.js/core/Object3D:lookAt](https://threejs.org/docs/#api/en/core/Object3D.lookAt)

Rotates the object to face a point in world space.

##### Parameters

###### vector

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A vector representing a position in world space to look at.

##### Returns

`void`

##### Remarks

This method does not support objects having non-uniformly-scaled parent(s).

##### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`lookAt`](/three-flatland/api/three-flatland/src/classes/sprite2d/#lookat)

#### Call Signature

> **lookAt**(`x`, `y`, `z`): `void`

Defined in: [three.js/core/Object3D:lookAt](https://threejs.org/docs/#api/en/core/Object3D.lookAt)

Rotates the object to face a point in world space.

##### Parameters

###### x

`number`

Expects a `Float`

###### y

`number`

Expects a `Float`

###### z

`number`

Expects a `Float`

##### Returns

`void`

##### Remarks

This method does not support objects having non-uniformly-scaled parent(s).

##### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`lookAt`](/three-flatland/api/three-flatland/src/classes/sprite2d/#lookat)

***

### onAfterRender()

> **onAfterRender**(`renderer`, `scene`, `camera`, `geometry`, `material`, `group`): `void`

Defined in: [three.js/core/Object3D:onAfterRender](https://threejs.org/docs/#api/en/core/Object3D.onAfterRender)

An optional callback that is executed immediately after a 3D object is rendered.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### material

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, geometry, material, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`onAfterRender`](/three-flatland/api/three-flatland/src/classes/sprite2d/#onafterrender)

***

### onAfterShadow()

> **onAfterShadow**(`renderer`, `scene`, `camera`, `shadowCamera`, `geometry`, `depthMaterial`, `group`): `void`

Defined in: [three.js/core/Object3D:onAfterShadow](https://threejs.org/docs/#api/en/core/Object3D.onAfterShadow)

An optional callback that is executed immediately after a 3D object is rendered to a shadow map.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### shadowCamera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### depthMaterial

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, shadowCamera, geometry,
depthMaterial, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`onAfterShadow`](/three-flatland/api/three-flatland/src/classes/sprite2d/#onaftershadow)

***

### onBeforeRender()

> **onBeforeRender**(`renderer`, `scene`, `camera`, `geometry`, `material`, `group`): `void`

Defined in: [three.js/core/Object3D:onBeforeRender](https://threejs.org/docs/#api/en/core/Object3D.onBeforeRender)

An optional callback that is executed immediately before a 3D object is rendered.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### material

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, geometry, material, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`onBeforeRender`](/three-flatland/api/three-flatland/src/classes/sprite2d/#onbeforerender)

***

### onBeforeShadow()

> **onBeforeShadow**(`renderer`, `scene`, `camera`, `shadowCamera`, `geometry`, `depthMaterial`, `group`): `void`

Defined in: [three.js/core/Object3D:onBeforeShadow](https://threejs.org/docs/#api/en/core/Object3D.onBeforeShadow)

An optional callback that is executed immediately before a 3D object is rendered to a shadow map.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### shadowCamera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### depthMaterial

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, shadowCamera, geometry,
depthMaterial, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`onBeforeShadow`](/three-flatland/api/three-flatland/src/classes/sprite2d/#onbeforeshadow)

***

### pause()

> **pause**(): `this`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:265](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L265)

Pause the current animation.

#### Returns

`this`

***

### play()

> **play**(`name`, `options?`): `this`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:250](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L250)

Play an animation.

#### Parameters

##### name

`string`

##### options?

[`PlayOptions`](/three-flatland/api/three-flatland/src/interfaces/playoptions/)

#### Returns

`this`

***

### raycast()

> **raycast**(`raycaster`, `intersects`): `void`

Defined in: [three.js/core/Object3D:raycast](https://threejs.org/docs/#api/en/core/Object3D.raycast)

Abstract (empty) method to get intersections between a casted ray and this object

#### Parameters

##### raycaster

[`Raycaster`](https://threejs.org/docs/#api/en/core/Raycaster)

##### intersects

[`Intersection`](https://threejs.org/docs/)\<[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>\>[]

#### Returns

`void`

#### Remarks

Subclasses such as THREE.Mesh \| Mesh, THREE.Line \| Line, and THREE.Points \| Points implement this method in order to use raycasting.

#### See

THREE.Raycaster \| Raycaster

#### Default Value

`() => {}`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`raycast`](/three-flatland/api/three-flatland/src/classes/sprite2d/#raycast)

***

### remove()

> **remove**(...`object`): `this`

Defined in: [three.js/core/Object3D:remove](https://threejs.org/docs/#api/en/core/Object3D.remove)

Removes a [Object3D](https://threejs.org/docs/#api/en/core/Object3D) as child of this [Object3D](https://threejs.org/docs/#api/en/core/Object3D).

#### Parameters

##### object

...[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

#### Returns

`this`

#### Remarks

An arbitrary number of objects may be removed.

#### See

THREE.Group \| Group for info on manually grouping objects.

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`remove`](/three-flatland/api/three-flatland/src/classes/sprite2d/#remove)

***

### removeEffect()

> **removeEffect**(`effect`): `this`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:1214](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L1214)

Remove an effect instance from this sprite.
Clears the enable bit and resets effect data to defaults.
The effect type remains registered on the material (no shader change).

#### Parameters

##### effect

[`MaterialEffect`](/three-flatland/api/three-flatland/src/classes/materialeffect/)

#### Returns

`this`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`removeEffect`](/three-flatland/api/three-flatland/src/classes/sprite2d/#removeeffect)

***

### removeEventListener()

> **removeEventListener**\<`T`\>(`type`, `listener`): `void`

Defined in: [three.js/core/EventDispatcher:removeEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.removeEventListener)

Removes a listener from an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### type

`T`

The type of the listener that gets removed.

##### listener

[`EventListener`](https://threejs.org/docs/)\<[`Object3DEventMap`](https://threejs.org/docs/)\[`T`\], `T`, `AnimatedSprite2D`\>

The listener function that gets removed.

#### Returns

`void`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`removeEventListener`](/three-flatland/api/three-flatland/src/classes/sprite2d/#removeeventlistener)

***

### removeFromParent()

> **removeFromParent**(): `this`

Defined in: [three.js/core/Object3D:removeFromParent](https://threejs.org/docs/#api/en/core/Object3D.removeFromParent)

Removes this object from its current parent.

#### Returns

`this`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`removeFromParent`](/three-flatland/api/three-flatland/src/classes/sprite2d/#removefromparent)

***

### resume()

> **resume**(): `this`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:273](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L273)

Resume a paused animation.

#### Returns

`this`

***

### rotateOnAxis()

> **rotateOnAxis**(`axis`, `angle`): `this`

Defined in: [three.js/core/Object3D:rotateOnAxis](https://threejs.org/docs/#api/en/core/Object3D.rotateOnAxis)

Rotate an object along an axis in object space.

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in object space.

##### angle

`number`

The angle in radians. Expects a `Float`

#### Returns

`this`

#### Remarks

The axis is assumed to be normalized.

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`rotateOnAxis`](/three-flatland/api/three-flatland/src/classes/sprite2d/#rotateonaxis)

***

### rotateOnWorldAxis()

> **rotateOnWorldAxis**(`axis`, `angle`): `this`

Defined in: [three.js/core/Object3D:rotateOnWorldAxis](https://threejs.org/docs/#api/en/core/Object3D.rotateOnWorldAxis)

Rotate an object along an axis in world space.

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in world space.

##### angle

`number`

The angle in radians. Expects a `Float`

#### Returns

`this`

#### Remarks

The axis is assumed to be normalized
Method Assumes no rotated parent.

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`rotateOnWorldAxis`](/three-flatland/api/three-flatland/src/classes/sprite2d/#rotateonworldaxis)

***

### rotateX()

> **rotateX**(`angle`): `this`

Defined in: [three.js/core/Object3D:rotateX](https://threejs.org/docs/#api/en/core/Object3D.rotateX)

Rotates the object around _x_ axis in local space.

#### Parameters

##### angle

`number`

#### Returns

`this`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`rotateX`](/three-flatland/api/three-flatland/src/classes/sprite2d/#rotatex)

***

### rotateY()

> **rotateY**(`angle`): `this`

Defined in: [three.js/core/Object3D:rotateY](https://threejs.org/docs/#api/en/core/Object3D.rotateY)

Rotates the object around _y_ axis in local space.

#### Parameters

##### angle

`number`

#### Returns

`this`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`rotateY`](/three-flatland/api/three-flatland/src/classes/sprite2d/#rotatey)

***

### rotateZ()

> **rotateZ**(`angle`): `this`

Defined in: [three.js/core/Object3D:rotateZ](https://threejs.org/docs/#api/en/core/Object3D.rotateZ)

Rotates the object around _z_ axis in local space.

#### Parameters

##### angle

`number`

#### Returns

`this`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`rotateZ`](/three-flatland/api/three-flatland/src/classes/sprite2d/#rotatez)

***

### setAnchor()

> **setAnchor**(`x`, `y`): `this`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:763](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L763)

Set the anchor point (0-1).
(0, 0) = top-left, (0.5, 0.5) = center, (0.5, 1) = bottom-center

The anchor offset is baked into the matrix transform — no
geometry rebuild. Writing `_anchor.set(...)` triggers the
observable.vector2 callback which marks the matrix dirty; the next
`updateMatrix` picks up the new value.

#### Parameters

##### x

`number`

##### y

`number`

#### Returns

`this`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`setAnchor`](/three-flatland/api/three-flatland/src/classes/sprite2d/#setanchor)

***

### setFrame()

> **setFrame**(`frame`): `this`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:708](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L708)

Set the current frame.
Note: Does not modify scale - call updateSize() manually if needed after first frame.

#### Parameters

##### frame

[`SpriteFrame`](/three-flatland/api/three-flatland/src/interfaces/spriteframe/)

#### Returns

`this`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`setFrame`](/three-flatland/api/three-flatland/src/classes/sprite2d/#setframe)

***

### setRotationFromAxisAngle()

> **setRotationFromAxisAngle**(`axis`, `angle`): `void`

Defined in: [three.js/core/Object3D:setRotationFromAxisAngle](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromAxisAngle)

Calls THREE.Quaternion.setFromAxisAngle \| setFromAxisAngle(axis, angle) on the [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in object space.

##### angle

`number`

Angle in radians. Expects a `Float`

#### Returns

`void`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`setRotationFromAxisAngle`](/three-flatland/api/three-flatland/src/classes/sprite2d/#setrotationfromaxisangle)

***

### setRotationFromEuler()

> **setRotationFromEuler**(`euler`): `void`

Defined in: [three.js/core/Object3D:setRotationFromEuler](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromEuler)

Calls THREE.Quaternion.setFromEuler \| setFromEuler(euler) on the [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### euler

[`Euler`](https://threejs.org/docs/#api/en/math/Euler)

Euler angle specifying rotation amount.

#### Returns

`void`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`setRotationFromEuler`](/three-flatland/api/three-flatland/src/classes/sprite2d/#setrotationfromeuler)

***

### setRotationFromMatrix()

> **setRotationFromMatrix**(`m`): `void`

Defined in: [three.js/core/Object3D:setRotationFromMatrix](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromMatrix)

Calls THREE.Quaternion.setFromRotationMatrix \| setFromRotationMatrix(m) on the [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### m

[`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Rotate the quaternion by the rotation component of the matrix.

#### Returns

`void`

#### Remarks

Note that this assumes that the upper 3x3 of m is a pure rotation matrix (i.e, unscaled).

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`setRotationFromMatrix`](/three-flatland/api/three-flatland/src/classes/sprite2d/#setrotationfrommatrix)

***

### setRotationFromQuaternion()

> **setRotationFromQuaternion**(`q`): `void`

Defined in: [three.js/core/Object3D:setRotationFromQuaternion](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromQuaternion)

Copy the given THREE.Quaternion \| Quaternion into [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### q

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

Normalized Quaternion.

#### Returns

`void`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`setRotationFromQuaternion`](/three-flatland/api/three-flatland/src/classes/sprite2d/#setrotationfromquaternion)

***

### stop()

> **stop**(): `this`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:281](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L281)

Stop the current animation.

#### Returns

`this`

***

### toJSON()

> **toJSON**(`meta?`): [`MeshJSON`](https://threejs.org/docs/)

Defined in: [three.js/objects/Mesh:toJSON](https://threejs.org/docs/#api/en/objects/Mesh.toJSON)

Convert the object to three.js [JSON Object/Scene format](https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4).

#### Parameters

##### meta?

[`JSONMeta`](https://threejs.org/docs/)

Object containing metadata such as materials, textures or images for the object.

#### Returns

[`MeshJSON`](https://threejs.org/docs/)

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`toJSON`](/three-flatland/api/three-flatland/src/classes/sprite2d/#tojson)

***

### translateOnAxis()

> **translateOnAxis**(`axis`, `distance`): `this`

Defined in: [three.js/core/Object3D:translateOnAxis](https://threejs.org/docs/#api/en/core/Object3D.translateOnAxis)

Translate an object by distance along an axis in object space

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in object space.

##### distance

`number`

The distance to translate. Expects a `Float`

#### Returns

`this`

#### Remarks

The axis is assumed to be normalized.

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`translateOnAxis`](/three-flatland/api/three-flatland/src/classes/sprite2d/#translateonaxis)

***

### translateX()

> **translateX**(`distance`): `this`

Defined in: [three.js/core/Object3D:translateX](https://threejs.org/docs/#api/en/core/Object3D.translateX)

Translates object along x axis in object space by distance units.

#### Parameters

##### distance

`number`

Expects a `Float`

#### Returns

`this`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`translateX`](/three-flatland/api/three-flatland/src/classes/sprite2d/#translatex)

***

### translateY()

> **translateY**(`distance`): `this`

Defined in: [three.js/core/Object3D:translateY](https://threejs.org/docs/#api/en/core/Object3D.translateY)

Translates object along _y_ axis in object space by distance units.

#### Parameters

##### distance

`number`

Expects a `Float`

#### Returns

`this`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`translateY`](/three-flatland/api/three-flatland/src/classes/sprite2d/#translatey)

***

### translateZ()

> **translateZ**(`distance`): `this`

Defined in: [three.js/core/Object3D:translateZ](https://threejs.org/docs/#api/en/core/Object3D.translateZ)

Translates object along _z_ axis in object space by distance units.

#### Parameters

##### distance

`number`

Expects a `Float`

#### Returns

`this`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`translateZ`](/three-flatland/api/three-flatland/src/classes/sprite2d/#translatez)

***

### traverse()

> **traverse**(`callback`): `void`

Defined in: [three.js/core/Object3D:traverse](https://threejs.org/docs/#api/en/core/Object3D.traverse)

Executes the callback on this object and all descendants.

#### Parameters

##### callback

(`object`) => `any`

A function with as first argument an [Object3D](https://threejs.org/docs/#api/en/core/Object3D) object.

#### Returns

`void`

#### Remarks

Note: Modifying the scene graph inside the callback is discouraged.

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`traverse`](/three-flatland/api/three-flatland/src/classes/sprite2d/#traverse)

***

### traverseAncestors()

> **traverseAncestors**(`callback`): `void`

Defined in: [three.js/core/Object3D:traverseAncestors](https://threejs.org/docs/#api/en/core/Object3D.traverseAncestors)

Executes the callback on all ancestors.

#### Parameters

##### callback

(`object`) => `any`

A function with as first argument an [Object3D](https://threejs.org/docs/#api/en/core/Object3D) object.

#### Returns

`void`

#### Remarks

Note: Modifying the scene graph inside the callback is discouraged.

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`traverseAncestors`](/three-flatland/api/three-flatland/src/classes/sprite2d/#traverseancestors)

***

### traverseVisible()

> **traverseVisible**(`callback`): `void`

Defined in: [three.js/core/Object3D:traverseVisible](https://threejs.org/docs/#api/en/core/Object3D.traverseVisible)

Like traverse, but the callback will only be executed for visible objects

#### Parameters

##### callback

(`object`) => `any`

A function with as first argument an [Object3D](https://threejs.org/docs/#api/en/core/Object3D) object.

#### Returns

`void`

#### Remarks

Descendants of invisible objects are not traversed.
Note: Modifying the scene graph inside the callback is discouraged.

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`traverseVisible`](/three-flatland/api/three-flatland/src/classes/sprite2d/#traversevisible)

***

### update()

> **update**(`deltaMs`): `void`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:302](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L302)

Update animation (call in render loop).

#### Parameters

##### deltaMs

`number`

Time since last frame in milliseconds

#### Returns

`void`

***

### updateMatrix()

> **updateMatrix**(): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:1421](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L1421)

Fast 2D matrix update — bypasses Three.js quaternion-based compose().

Three.js Object3D.updateMatrix() calls matrix.compose(position, quaternion, scale)
which does full 3D quaternion→matrix math (~20 multiplies). For 2D sprites we only
need position, scale, and optional Z-axis rotation — written directly to the matrix
elements.

Also bakes in the layer/zIndex Z offset without save/restore of position.z.

#### Returns

`void`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`updateMatrix`](/three-flatland/api/three-flatland/src/classes/sprite2d/#updatematrix)

***

### updateMatrixWorld()

> **updateMatrixWorld**(`force?`): `void`

Defined in: [three.js/core/Object3D:updateMatrixWorld](https://threejs.org/docs/#api/en/core/Object3D.updateMatrixWorld)

Updates the global transform of the object.
And will update the object descendants if [.matrixWorldNeedsUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldneedsupdate) is set to true or if the force parameter is set to `true`.

#### Parameters

##### force?

`boolean`

A boolean that can be used to bypass [.matrixWorldAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldautoupdate), to recalculate the world matrix of the object and descendants on the current frame.
Useful if you cannot wait for the renderer to update it on the next frame, assuming [.matrixWorldAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldautoupdate) set to `true`.

#### Returns

`void`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`updateMatrixWorld`](/three-flatland/api/three-flatland/src/classes/sprite2d/#updatematrixworld)

***

### updateMorphTargets()

> **updateMorphTargets**(): `void`

Defined in: [three.js/objects/Mesh:updateMorphTargets](https://threejs.org/docs/#api/en/objects/Mesh.updateMorphTargets)

Updates the morphTargets to have no influence on the object

#### Returns

`void`

#### Remarks

Resets the [morphTargetInfluences](/three-flatland/api/three-flatland/src/classes/animatedsprite2d/#morphtargetinfluences) and [morphTargetDictionary](https://threejs.org/docs/) properties.

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`updateMorphTargets`](/three-flatland/api/three-flatland/src/classes/sprite2d/#updatemorphtargets)

***

### updateWorldMatrix()

> **updateWorldMatrix**(`updateParents`, `updateChildren`): `void`

Defined in: [three.js/core/Object3D:updateWorldMatrix](https://threejs.org/docs/#api/en/core/Object3D.updateWorldMatrix)

Updates the global transform of the object.

#### Parameters

##### updateParents

`boolean`

Recursively updates global transform of ancestors.

##### updateChildren

`boolean`

Recursively updates global transform of descendants.

#### Returns

`void`

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`updateWorldMatrix`](/three-flatland/api/three-flatland/src/classes/sprite2d/#updateworldmatrix)

***

### worldToLocal()

> **worldToLocal**(`vector`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:worldToLocal](https://threejs.org/docs/#api/en/core/Object3D.worldToLocal)

Converts the vector from world space to this object's local space.

#### Parameters

##### vector

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A vector representing a position in world space.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/).[`worldToLocal`](/three-flatland/api/three-flatland/src/classes/sprite2d/#worldtolocal)

# AnimationController

Defined in: [packages/three-flatland/src/animation/AnimationController.ts:27](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/AnimationController.ts#L27)

Controls animation playback and state.

## Example

```typescript
const controller = new AnimationController();
controller.addAnimation({
  name: 'walk',
  frames: walkFrames,
  fps: 12,
  loop: true,
});
controller.play('walk');

// In update loop
controller.update(deltaMs, (frame) => {
  sprite.setFrame(frame);
});
```

## Constructors

### Constructor

> **new AnimationController**(): `AnimationController`

#### Returns

`AnimationController`

## Accessors

### currentAnimation

#### Get Signature

> **get** **currentAnimation**(): `string` \| `null`

Defined in: [packages/three-flatland/src/animation/AnimationController.ts:286](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/AnimationController.ts#L286)

Get current animation name.

##### Returns

`string` \| `null`

## Methods

### addAnimation()

> **addAnimation**(`animation`): `this`

Defined in: [packages/three-flatland/src/animation/AnimationController.ts:44](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/AnimationController.ts#L44)

Add an animation definition.

#### Parameters

##### animation

[`Animation`](/three-flatland/api/three-flatland/src/interfaces/animation/)

#### Returns

`this`

***

### addAnimations()

> **addAnimations**(`animations`): `this`

Defined in: [packages/three-flatland/src/animation/AnimationController.ts:52](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/AnimationController.ts#L52)

Add multiple animations.

#### Parameters

##### animations

[`Animation`](/three-flatland/api/three-flatland/src/interfaces/animation/)[]

#### Returns

`this`

***

### dispose()

> **dispose**(): `void`

Defined in: [packages/three-flatland/src/animation/AnimationController.ts:323](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/AnimationController.ts#L323)

Dispose of resources.

#### Returns

`void`

***

### getAnimation()

> **getAnimation**(`name`): [`Animation`](/three-flatland/api/three-flatland/src/interfaces/animation/) \| `undefined`

Defined in: [packages/three-flatland/src/animation/AnimationController.ts:73](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/AnimationController.ts#L73)

Get an animation by name.

#### Parameters

##### name

`string`

#### Returns

[`Animation`](/three-flatland/api/three-flatland/src/interfaces/animation/) \| `undefined`

***

### getAnimationDuration()

> **getAnimationDuration**(`name`): `number`

Defined in: [packages/three-flatland/src/animation/AnimationController.ts:308](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/AnimationController.ts#L308)

Get animation duration in milliseconds.

#### Parameters

##### name

`string`

#### Returns

`number`

***

### getAnimationNames()

> **getAnimationNames**(): `string`[]

Defined in: [packages/three-flatland/src/animation/AnimationController.ts:80](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/AnimationController.ts#L80)

Get all animation names.

#### Returns

`string`[]

***

### getCurrentFrame()

> **getCurrentFrame**(): [`SpriteFrame`](/three-flatland/api/three-flatland/src/interfaces/spriteframe/) \| `null`

Defined in: [packages/three-flatland/src/animation/AnimationController.ts:251](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/AnimationController.ts#L251)

Get current frame.

#### Returns

[`SpriteFrame`](/three-flatland/api/three-flatland/src/interfaces/spriteframe/) \| `null`

***

### getSpeed()

> **getSpeed**(): `number`

Defined in: [packages/three-flatland/src/animation/AnimationController.ts:293](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/AnimationController.ts#L293)

Get playback speed.

#### Returns

`number`

***

### getState()

> **getState**(): [`AnimationState`](/three-flatland/api/three-flatland/src/interfaces/animationstate/)

Defined in: [packages/three-flatland/src/animation/AnimationController.ts:261](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/AnimationController.ts#L261)

Get current animation state.

#### Returns

[`AnimationState`](/three-flatland/api/three-flatland/src/interfaces/animationstate/)

***

### gotoFrame()

> **gotoFrame**(`index`): `this`

Defined in: [packages/three-flatland/src/animation/AnimationController.ts:145](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/AnimationController.ts#L145)

Go to a specific frame.

#### Parameters

##### index

`number`

#### Returns

`this`

***

### isPlaying()

> **isPlaying**(`name?`): `boolean`

Defined in: [packages/three-flatland/src/animation/AnimationController.ts:276](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/AnimationController.ts#L276)

Check if an animation is playing.

#### Parameters

##### name?

`string`

#### Returns

`boolean`

***

### pause()

> **pause**(): `this`

Defined in: [packages/three-flatland/src/animation/AnimationController.ts:117](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/AnimationController.ts#L117)

Pause the current animation.

#### Returns

`this`

***

### play()

> **play**(`name`, `options?`): `this`

Defined in: [packages/three-flatland/src/animation/AnimationController.ts:87](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/AnimationController.ts#L87)

Play an animation.

#### Parameters

##### name

`string`

##### options?

[`PlayOptions`](/three-flatland/api/three-flatland/src/interfaces/playoptions/) = `{}`

#### Returns

`this`

***

### removeAnimation()

> **removeAnimation**(`name`): `this`

Defined in: [packages/three-flatland/src/animation/AnimationController.ts:62](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/AnimationController.ts#L62)

Remove an animation.

#### Parameters

##### name

`string`

#### Returns

`this`

***

### resume()

> **resume**(): `this`

Defined in: [packages/three-flatland/src/animation/AnimationController.ts:125](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/AnimationController.ts#L125)

Resume a paused animation.

#### Returns

`this`

***

### setSpeed()

> **setSpeed**(`speed`): `this`

Defined in: [packages/three-flatland/src/animation/AnimationController.ts:300](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/AnimationController.ts#L300)

Set playback speed.

#### Parameters

##### speed

`number`

#### Returns

`this`

***

### stop()

> **stop**(): `this`

Defined in: [packages/three-flatland/src/animation/AnimationController.ts:133](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/AnimationController.ts#L133)

Stop the current animation.

#### Returns

`this`

***

### update()

> **update**(`deltaMs`, `onFrame?`, `onEvent?`): `void`

Defined in: [packages/three-flatland/src/animation/AnimationController.ts:159](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/AnimationController.ts#L159)

Update animation state.

#### Parameters

##### deltaMs

`number`

Time since last update in milliseconds

##### onFrame?

`FrameCallback`

Callback when frame changes

##### onEvent?

`EventCallback`

Callback when frame event fires

#### Returns

`void`

# EffectMaterial

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:100](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L100)

Base material class with composable packed-buffer effect system.

Extends MeshBasicNodeMaterial and adds:
- Packed vec4 effect buffers with bitmask enable flags
- Effect registration with automatic slot assignment
- Shader rebuilding with effect chain composition

Subclasses override `_buildBaseColor()` to provide their own base color/UV
(e.g., Sprite2DMaterial provides sprite-specific UV flip, atlas, tint).

This base class can be extended for non-sprite materials that also need effects.

## Extends

- [`MeshBasicNodeMaterial`](https://threejs.org/docs/)

## Extended by

- [`Sprite2DMaterial`](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/)

## Constructors

### Constructor

> **new EffectMaterial**(`options?`): `EffectMaterial`

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:209](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L209)

#### Parameters

##### options?

[`EffectMaterialOptions`](/three-flatland/api/three-flatland/src/interfaces/effectmaterialoptions/) = `{}`

#### Returns

`EffectMaterial`

#### Overrides

`MeshBasicNodeMaterial.constructor`

## Properties

### allowOverride

> **allowOverride**: `boolean`

Defined in: [three.js/materials/Material:allowOverride](https://threejs.org/docs/#api/en/materials/Material.allowOverride)

Whether it's possible to override the material with [Scene#overrideMaterial](https://threejs.org/docs/) or not.

#### Default

```ts
true
```

#### Inherited from

`MeshBasicNodeMaterial.allowOverride`

***

### alphaHash

> **alphaHash**: `boolean`

Defined in: [three.js/materials/Material:alphaHash](https://threejs.org/docs/#api/en/materials/Material.alphaHash)

Enables alpha hashed transparency, an alternative to [Material#transparent](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#transparent) or
[Material#alphaTest](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#alphatest). The material will not be rendered if opacity is lower than
a random threshold. Randomization introduces some grain or noise, but approximates alpha
blending without the associated problems of sorting. Using TAA can reduce the resulting noise.

#### Default

```ts
false
```

#### Inherited from

`MeshBasicNodeMaterial.alphaHash`

***

### alphaMap

> **alphaMap**: [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

Defined in: [three.js/materials/MeshBasicMaterial:alphaMap](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.alphaMap)

The alpha map is a grayscale texture that controls the opacity across the
surface (black: fully transparent; white: fully opaque).

Only the color of the texture is used, ignoring the alpha channel if one
exists. For RGB and RGBA textures, the renderer will use the green channel
when sampling this texture due to the extra bit of precision provided for
green in DXT-compressed and uncompressed RGB 565 formats. Luminance-only and
luminance/alpha textures will also still work as expected.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.alphaMap`

***

### alphaTestNode

> **alphaTestNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:alphaTestNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.alphaTestNode)

The alpha test of node materials is by default inferred from the `alphaTest`
property. This node property allows to overwrite the default and define the
alpha test with a node instead.

If you don't want to overwrite the alpha test but modify the existing
value instead, use materialAlphaTest.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.alphaTestNode`

***

### alphaToCoverage

> **alphaToCoverage**: `boolean`

Defined in: [three.js/materials/Material:alphaToCoverage](https://threejs.org/docs/#api/en/materials/Material.alphaToCoverage)

Whether alpha to coverage should be enabled or not. Can only be used with MSAA-enabled contexts
(meaning when the renderer was created with *antialias* parameter set to `true`). Enabling this
will smooth aliasing on clip plane edges and alphaTest-clipped edges.

#### Default

```ts
false
```

#### Inherited from

`MeshBasicNodeMaterial.alphaToCoverage`

***

### aoMap

> **aoMap**: [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

Defined in: [three.js/materials/MeshBasicMaterial:aoMap](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.aoMap)

The red channel of this texture is used as the ambient occlusion map.
Requires a second set of UVs.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.aoMap`

***

### aoMapIntensity

> **aoMapIntensity**: `number`

Defined in: [three.js/materials/MeshBasicMaterial:aoMapIntensity](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.aoMapIntensity)

Intensity of the ambient occlusion effect. Range is `[0,1]`, where `0`
disables ambient occlusion. Where intensity is `1` and the AO map's
red channel is also `1`, ambient light is fully occluded on a surface.

#### Default

```ts
1
```

#### Inherited from

`MeshBasicNodeMaterial.aoMapIntensity`

***

### aoNode

> **aoNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:aoNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.aoNode)

The lighting of node materials might be influenced by ambient occlusion.
The default AO is inferred from an ambient occlusion map assigned to `aoMap`
and the respective `aoMapIntensity`. This node property allows to overwrite
the default and define the ambient occlusion with a custom node instead.

If you don't want to overwrite the diffuse color but modify the existing
values instead, use materialAO.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.aoNode`

***

### backdropAlphaNode

> **backdropAlphaNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:backdropAlphaNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.backdropAlphaNode)

This node allows to modulate the influence of `backdropNode` to the outgoing light.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.backdropAlphaNode`

***

### backdropNode

> **backdropNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:backdropNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.backdropNode)

This node can be used to implement a variety of filter-like effects. The idea is
to store the current rendering into a texture e.g. via `viewportSharedTexture()`, use it
to create an arbitrary effect and then assign the node composition to this property.
Everything behind the object using this material will now be affected by a filter.

```js
const material = new NodeMaterial()
material.transparent = true;

// everything behind the object will be monochromatic
material.backdropNode = saturation( viewportSharedTexture().rgb, 0 );
```

Backdrop computations are part of the lighting so only lit materials can use this property.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.backdropNode`

***

### blendAlpha

> **blendAlpha**: `number`

Defined in: [three.js/materials/Material:blendAlpha](https://threejs.org/docs/#api/en/materials/Material.blendAlpha)

Represents the alpha value of the constant blend color.

This property has only an effect when using custom blending with `ConstantAlpha` or `OneMinusConstantAlpha`.

#### Default

```ts
0
```

#### Inherited from

`MeshBasicNodeMaterial.blendAlpha`

***

### blendColor

> **blendColor**: [`Color`](https://threejs.org/docs/#api/en/math/Color)

Defined in: [three.js/materials/Material:blendColor](https://threejs.org/docs/#api/en/materials/Material.blendColor)

Represents the RGB values of the constant blend color.

This property has only an effect when using custom blending with `ConstantColor` or `OneMinusConstantColor`.

#### Default

```ts
(0,0,0)
```

#### Inherited from

`MeshBasicNodeMaterial.blendColor`

***

### blendDst

> **blendDst**: [`BlendingDstFactor`](https://threejs.org/docs/)

Defined in: [three.js/materials/Material:blendDst](https://threejs.org/docs/#api/en/materials/Material.blendDst)

Defines the blending destination factor.

#### Default

```ts
OneMinusSrcAlphaFactor
```

#### Inherited from

`MeshBasicNodeMaterial.blendDst`

***

### blendDstAlpha

> **blendDstAlpha**: [`BlendingDstFactor`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/Material:blendDstAlpha](https://threejs.org/docs/#api/en/materials/Material.blendDstAlpha)

Defines the blending destination alpha factor.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.blendDstAlpha`

***

### blendEquation

> **blendEquation**: [`BlendingEquation`](https://threejs.org/docs/)

Defined in: [three.js/materials/Material:blendEquation](https://threejs.org/docs/#api/en/materials/Material.blendEquation)

Defines the blending equation.

#### Default

```ts
AddEquation
```

#### Inherited from

`MeshBasicNodeMaterial.blendEquation`

***

### blendEquationAlpha

> **blendEquationAlpha**: [`BlendingEquation`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/Material:blendEquationAlpha](https://threejs.org/docs/#api/en/materials/Material.blendEquationAlpha)

Defines the blending equation of the alpha channel.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.blendEquationAlpha`

***

### blending

> **blending**: [`Blending`](https://threejs.org/docs/)

Defined in: [three.js/materials/Material:blending](https://threejs.org/docs/#api/en/materials/Material.blending)

Defines the blending type of the material.

It must be set to `CustomBlending` if custom blending properties like
[Material#blendSrc](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#blendsrc), [Material#blendDst](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#blenddst) or [Material#blendEquation](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#blendequation)
should have any effect.

#### Default

```ts
NormalBlending
```

#### Inherited from

`MeshBasicNodeMaterial.blending`

***

### blendSrc

> **blendSrc**: [`BlendingSrcFactor`](https://threejs.org/docs/)

Defined in: [three.js/materials/Material:blendSrc](https://threejs.org/docs/#api/en/materials/Material.blendSrc)

Defines the blending source factor.

#### Default

```ts
SrcAlphaFactor
```

#### Inherited from

`MeshBasicNodeMaterial.blendSrc`

***

### blendSrcAlpha

> **blendSrcAlpha**: [`BlendingSrcFactor`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/Material:blendSrcAlpha](https://threejs.org/docs/#api/en/materials/Material.blendSrcAlpha)

Defines the blending source alpha factor.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.blendSrcAlpha`

***

### castShadowNode

> **castShadowNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:castShadowNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.castShadowNode)

This node can be used to influence how an object using this node material
casts shadows. To apply a color to shadows, you can simply do:

```js
material.castShadowNode = vec4( 1, 0, 0, 1 );
```

Which can be nice to fake colored shadows of semi-transparent objects. It
is also common to use the property with `Fn` function so checks are performed
per fragment.

```js
materialCustomShadow.castShadowNode = Fn( () => {
	hash( vertexIndex ).greaterThan( 0.5 ).discard();
	return materialColor;
} )();
 ```

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.castShadowNode`

***

### castShadowPositionNode

> **castShadowPositionNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:castShadowPositionNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.castShadowPositionNode)

Allows to overwrite the geometry position used for shadow map projection which
is by default positionLocal, the vertex position in local space.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.castShadowPositionNode`

***

### clipIntersection

> **clipIntersection**: `boolean`

Defined in: [three.js/materials/Material:clipIntersection](https://threejs.org/docs/#api/en/materials/Material.clipIntersection)

Changes the behavior of clipping planes so that only their intersection is
clipped, rather than their union.

#### Default

```ts
false
```

#### Inherited from

`MeshBasicNodeMaterial.clipIntersection`

***

### clippingPlanes

> **clippingPlanes**: [`Plane`](https://threejs.org/docs/)[] \| `null`

Defined in: [three.js/materials/Material:clippingPlanes](https://threejs.org/docs/#api/en/materials/Material.clippingPlanes)

User-defined clipping planes specified as THREE.Plane objects in world
space. These planes apply to the objects this material is attached to.
Points in space whose signed distance to the plane is negative are clipped
(not rendered). This requires [WebGLRenderer#localClippingEnabled](https://threejs.org/docs/) to
be `true`.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.clippingPlanes`

***

### clipShadows

> **clipShadows**: `boolean`

Defined in: [three.js/materials/Material:clipShadows](https://threejs.org/docs/#api/en/materials/Material.clipShadows)

Defines whether to clip shadows according to the clipping planes specified
on this material.

#### Default

```ts
false
```

#### Inherited from

`MeshBasicNodeMaterial.clipShadows`

***

### color

> **color**: [`Color`](https://threejs.org/docs/#api/en/math/Color)

Defined in: [three.js/materials/MeshBasicMaterial:color](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.color)

Color of the material.

#### Default

```ts
(1,1,1)
```

#### Inherited from

`MeshBasicNodeMaterial.color`

***

### colorNode

> **colorNode**: [`Node`](https://threejs.org/docs/)\<`"vec3"`\> \| [`Node`](https://threejs.org/docs/)\<`"float"`\> \| [`Node`](https://threejs.org/docs/)\<`"color"`\> \| [`Node`](https://threejs.org/docs/)\<`"vec2"`\> \| [`Node`](https://threejs.org/docs/)\<`"vec4"`\> \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:colorNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.colorNode)

The diffuse color of node materials is by default inferred from the
`color` and `map` properties. This node property allows to overwrite the default
and define the diffuse color with a node instead.

```js
material.colorNode = color( 0xff0000 ); // define red color
```

If you don't want to overwrite the diffuse color but modify the existing
values instead, use materialColor.

```js
material.colorNode = materialColor.mul( color( 0xff0000 ) ); // give diffuse colors a red tint
```

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.colorNode`

***

### colorWrite

> **colorWrite**: `boolean`

Defined in: [three.js/materials/Material:colorWrite](https://threejs.org/docs/#api/en/materials/Material.colorWrite)

Whether to render the material's color.

This can be used in conjunction with Object3D#renderOder to create invisible
objects that occlude other objects.

#### Default

```ts
true
```

#### Inherited from

`MeshBasicNodeMaterial.colorWrite`

***

### combine

> **combine**: [`Combine`](https://threejs.org/docs/)

Defined in: [three.js/materials/MeshBasicMaterial:combine](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.combine)

How to combine the result of the surface's color with the environment map, if any.

When set to `MixOperation`, the [MeshBasicMaterial#reflectivity](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#reflectivity) is used to
blend between the two colors.

#### Default

```ts
MultiplyOperation
```

#### Inherited from

`MeshBasicNodeMaterial.combine`

***

### contextNode

> **contextNode**: [`ContextNode`](https://threejs.org/docs/)\<`unknown`\> \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:contextNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.contextNode)

This node can be used as a global context management component for this material.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.contextNode`

***

### defines?

> `optional` **defines?**: `Record`\<`string`, `unknown`\>

Defined in: [three.js/materials/Material:defines](https://threejs.org/docs/#api/en/materials/Material.defines)

#### Inherited from

`MeshBasicNodeMaterial.defines`

***

### depthFunc

> **depthFunc**: [`DepthModes`](https://threejs.org/docs/)

Defined in: [three.js/materials/Material:depthFunc](https://threejs.org/docs/#api/en/materials/Material.depthFunc)

Defines the depth function.

#### Default

```ts
LessEqualDepth
```

#### Inherited from

`MeshBasicNodeMaterial.depthFunc`

***

### depthNode

> **depthNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:depthNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.depthNode)

Allows to overwrite depth values in the fragment shader.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.depthNode`

***

### depthTest

> **depthTest**: `boolean`

Defined in: [three.js/materials/Material:depthTest](https://threejs.org/docs/#api/en/materials/Material.depthTest)

Whether to have depth test enabled when rendering this material.
When the depth test is disabled, the depth write will also be implicitly disabled.

#### Default

```ts
true
```

#### Inherited from

`MeshBasicNodeMaterial.depthTest`

***

### depthWrite

> **depthWrite**: `boolean`

Defined in: [three.js/materials/Material:depthWrite](https://threejs.org/docs/#api/en/materials/Material.depthWrite)

Whether rendering this material has any effect on the depth buffer.

When drawing 2D overlays it can be useful to disable the depth writing in
order to layer several things together without creating z-index artifacts.

#### Default

```ts
true
```

#### Inherited from

`MeshBasicNodeMaterial.depthWrite`

***

### dithering

> **dithering**: `boolean`

Defined in: [three.js/materials/Material:dithering](https://threejs.org/docs/#api/en/materials/Material.dithering)

Whether to apply dithering to the color to remove the appearance of banding.

#### Default

```ts
false
```

#### Inherited from

`MeshBasicNodeMaterial.dithering`

***

### envMap

> **envMap**: [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

Defined in: [three.js/materials/MeshBasicMaterial:envMap](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.envMap)

The environment map.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.envMap`

***

### envMapRotation

> **envMapRotation**: [`Euler`](https://threejs.org/docs/#api/en/math/Euler)

Defined in: [three.js/materials/MeshBasicMaterial:envMapRotation](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.envMapRotation)

The rotation of the environment map in radians.

#### Default

```ts
(0,0,0)
```

#### Inherited from

`MeshBasicNodeMaterial.envMapRotation`

***

### envNode

> **envNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:envNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.envNode)

The environment of node materials can be defined by an environment
map assigned to the `envMap` property or by `Scene.environment`
if the node material is a PBR material. This node property allows to overwrite
the default behavior and define the environment with a custom node.

```js
material.envNode = pmremTexture( renderTarget.texture );
```

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.envNode`

***

### fog

> **fog**: `boolean`

Defined in: [three.js/materials/nodes/NodeMaterial:fog](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.fog)

Whether this material is affected by fog or not.

#### Default

```ts
true
```

#### Inherited from

`MeshBasicNodeMaterial.fog`

***

### forceSinglePass

> **forceSinglePass**: `boolean`

Defined in: [three.js/materials/Material:forceSinglePass](https://threejs.org/docs/#api/en/materials/Material.forceSinglePass)

Whether double-sided, transparent objects should be rendered with a single pass or not.

The engine renders double-sided, transparent objects with two draw calls (back faces first,
then front faces) to mitigate transparency artifacts. There are scenarios however where this
approach produces no quality gains but still doubles draw calls e.g. when rendering flat
vegetation like grass sprites. In these cases, set the `forceSinglePass` flag to `true` to
disable the two pass rendering to avoid performance issues.

#### Default

```ts
false
```

#### Inherited from

`MeshBasicNodeMaterial.forceSinglePass`

***

### fragmentNode

> **fragmentNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:fragmentNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.fragmentNode)

This node property can be used if you need complete freedom in implementing
the fragment shader. Assigning a node will replace the built-in material
logic used in the fragment stage.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.fragmentNode`

***

### geometryNode

> **geometryNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:geometryNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.geometryNode)

This node property is intended for logic which modifies geometry data once or per animation step.
Apps usually place such logic randomly in initialization routines or in the animation loop.
`geometryNode` is intended as a dedicated API so there is an intended spot where geometry modifications
can be implemented.

The idea is to assign a `Fn` definition that holds the geometry modification logic. A typical example
would be a GPU based particle system that provides a node material for usage on app level. The particle
simulation would be implemented as compute shaders and managed inside a `Fn` function. This function is
eventually assigned to `geometryNode`.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.geometryNode`

***

### hardwareClipping

> **hardwareClipping**: `boolean`

Defined in: [three.js/materials/nodes/NodeMaterial:hardwareClipping](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.hardwareClipping)

Whether this material uses hardware clipping or not.
This property is managed by the engine and should not be
modified by apps.

#### Default

```ts
false
```

#### Inherited from

`MeshBasicNodeMaterial.hardwareClipping`

***

### isMaterial

> `readonly` **isMaterial**: `boolean`

Defined in: [three.js/materials/Material:isMaterial](https://threejs.org/docs/#api/en/materials/Material.isMaterial)

This flag can be used for type testing.

#### Default

```ts
true
```

#### Inherited from

`MeshBasicNodeMaterial.isMaterial`

***

### isMeshBasicNodeMaterial

> `readonly` **isMeshBasicNodeMaterial**: `boolean`

Defined in: [three.js/materials/nodes/MeshBasicNodeMaterial:isMeshBasicNodeMaterial](https://threejs.org/docs/#api/en/materials/nodes/MeshBasicNodeMaterial.isMeshBasicNodeMaterial)

This flag can be used for type testing.

#### Default

```ts
true
```

#### Inherited from

`MeshBasicNodeMaterial.isMeshBasicNodeMaterial`

***

### isNodeMaterial

> `readonly` **isNodeMaterial**: `boolean`

Defined in: [three.js/materials/nodes/NodeMaterial:isNodeMaterial](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.isNodeMaterial)

This flag can be used for type testing.

#### Default

```ts
true
```

#### Inherited from

`MeshBasicNodeMaterial.isNodeMaterial`

***

### lightMap

> **lightMap**: [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

Defined in: [three.js/materials/MeshBasicMaterial:lightMap](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.lightMap)

The light map. Requires a second set of UVs.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.lightMap`

***

### lightMapIntensity

> **lightMapIntensity**: `number`

Defined in: [three.js/materials/MeshBasicMaterial:lightMapIntensity](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.lightMapIntensity)

Intensity of the baked light.

#### Default

```ts
1
```

#### Inherited from

`MeshBasicNodeMaterial.lightMapIntensity`

***

### lights

> **lights**: `boolean`

Defined in: [three.js/materials/nodes/NodeMaterial:lights](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.lights)

Whether this material is affected by lights or not.

#### Default

```ts
false
```

#### Inherited from

`MeshBasicNodeMaterial.lights`

***

### lightsNode

> **lightsNode**: [`LightsNode`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:lightsNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.lightsNode)

Node materials which set their `lights` property to `true`
are affected by all lights of the scene. Sometimes selective
lighting is wanted which means only _some_ lights in the scene
affect a material. This can be achieved by creating an instance
of [LightsNode](https://threejs.org/docs/) with a list of selective
lights and assign the node to this property.

```js
const customLightsNode = lights( [ light1, light2 ] );
material.lightsNode = customLightsNode;
```

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.lightsNode`

***

### map

> **map**: [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

Defined in: [three.js/materials/MeshBasicMaterial:map](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.map)

The color map. May optionally include an alpha channel, typically combined
with [Material#transparent](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#transparent) or [Material#alphaTest](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#alphatest). The texture map
color is modulated by the diffuse `color`.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.map`

***

### maskNode

> **maskNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:maskNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.maskNode)

Discards the fragment if the mask value is `false`.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.maskNode`

***

### maskShadowNode

> **maskShadowNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:maskShadowNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.maskShadowNode)

This node can be used to implement a shadow mask for the material.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.maskShadowNode`

***

### mrtNode

> **mrtNode**: [`MRTNode`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:mrtNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.mrtNode)

MRT configuration is done on renderer or pass level. This node allows to
overwrite what values are written into MRT targets on material level. This
can be useful for implementing selective FX features that should only affect
specific objects.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.mrtNode`

***

### name

> **name**: `string`

Defined in: [three.js/materials/Material:name](https://threejs.org/docs/#api/en/materials/Material.name)

The name of the material.

#### Inherited from

`MeshBasicNodeMaterial.name`

***

### normalNode

> **normalNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:normalNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.normalNode)

The normals of node materials are by default inferred from the `normalMap`/`normalScale`
or `bumpMap`/`bumpScale` properties. This node property allows to overwrite the default
and define the normals with a node instead.

If you don't want to overwrite the normals but modify the existing values instead,
use materialNormal.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.normalNode`

***

### opacity

> **opacity**: `number`

Defined in: [three.js/materials/Material:opacity](https://threejs.org/docs/#api/en/materials/Material.opacity)

Defines how transparent the material is.
A value of `0.0` indicates fully transparent, `1.0` is fully opaque.

If the [Material#transparent](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#transparent) is not set to `true`,
the material will remain fully opaque and this value will only affect its color.

#### Default

```ts
1
```

#### Inherited from

`MeshBasicNodeMaterial.opacity`

***

### opacityNode

> **opacityNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:opacityNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.opacityNode)

The opacity of node materials is by default inferred from the `opacity`
and `alphaMap` properties. This node property allows to overwrite the default
and define the opacity with a node instead.

If you don't want to overwrite the opacity but modify the existing
value instead, use materialOpacity.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.opacityNode`

***

### outputNode

> **outputNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:outputNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.outputNode)

This node can be used to define the final output of the material.

TODO: Explain the differences to `fragmentNode`.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.outputNode`

***

### polygonOffset

> **polygonOffset**: `boolean`

Defined in: [three.js/materials/Material:polygonOffset](https://threejs.org/docs/#api/en/materials/Material.polygonOffset)

Whether to use polygon offset or not. When enabled, each fragment's depth value will
be offset after it is interpolated from the depth values of the appropriate vertices.
The offset is added before the depth test is performed and before the value is written
into the depth buffer.

Can be useful for rendering hidden-line images, for applying decals to surfaces, and for
rendering solids with highlighted edges.

#### Default

```ts
false
```

#### Inherited from

`MeshBasicNodeMaterial.polygonOffset`

***

### polygonOffsetFactor

> **polygonOffsetFactor**: `number`

Defined in: [three.js/materials/Material:polygonOffsetFactor](https://threejs.org/docs/#api/en/materials/Material.polygonOffsetFactor)

Specifies a scale factor that is used to create a variable depth offset for each polygon.

#### Default

```ts
0
```

#### Inherited from

`MeshBasicNodeMaterial.polygonOffsetFactor`

***

### polygonOffsetUnits

> **polygonOffsetUnits**: `number`

Defined in: [three.js/materials/Material:polygonOffsetUnits](https://threejs.org/docs/#api/en/materials/Material.polygonOffsetUnits)

Is multiplied by an implementation-specific value to create a constant depth offset.

#### Default

```ts
0
```

#### Inherited from

`MeshBasicNodeMaterial.polygonOffsetUnits`

***

### positionNode

> **positionNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:positionNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.positionNode)

The local vertex positions are computed based on multiple factors like the
attribute data, morphing or skinning. This node property allows to overwrite
the default and define local vertex positions with nodes instead.

If you don't want to overwrite the vertex positions but modify the existing
values instead, use positionLocal.

```js
material.positionNode = positionLocal.add( displace );
```

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.positionNode`

***

### precision

> **precision**: `"highp"` \| `"mediump"` \| `"lowp"` \| `null`

Defined in: [three.js/materials/Material:precision](https://threejs.org/docs/#api/en/materials/Material.precision)

Override the renderer's default precision for this material.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.precision`

***

### premultipliedAlpha

> **premultipliedAlpha**: `boolean`

Defined in: [three.js/materials/Material:premultipliedAlpha](https://threejs.org/docs/#api/en/materials/Material.premultipliedAlpha)

Whether to premultiply the alpha (transparency) value.

#### Default

```ts
false
```

#### Inherited from

`MeshBasicNodeMaterial.premultipliedAlpha`

***

### receivedShadowNode

> **receivedShadowNode**: (() => [`Node`](https://threejs.org/docs/)) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:receivedShadowNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.receivedShadowNode)

This node can be used to influence how an object using this node material
receive shadows.

```js
const totalShadows = float( 1 ).toVar();
material.receivedShadowNode = Fn( ( [ shadow ] ) => {
	totalShadows.mulAssign( shadow );
	//return float( 1 ); // bypass received shadows
	return shadow.mix( color( 0xff0000 ), 1 ); // modify shadow color
} );

@default null

#### Inherited from

`MeshBasicNodeMaterial.receivedShadowNode`

***

### receivedShadowPositionNode

> **receivedShadowPositionNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:receivedShadowPositionNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.receivedShadowPositionNode)

Allows to overwrite the position used for shadow map rendering which
is by default positionWorld, the vertex position
in world space.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.receivedShadowPositionNode`

***

### reflectivity

> **reflectivity**: `number`

Defined in: [three.js/materials/MeshBasicMaterial:reflectivity](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.reflectivity)

How much the environment map affects the surface.
The valid range is between `0` (no reflections) and `1` (full reflections).

#### Default

```ts
1
```

#### Inherited from

`MeshBasicNodeMaterial.reflectivity`

***

### refractionRatio

> **refractionRatio**: `number`

Defined in: [three.js/materials/MeshBasicMaterial:refractionRatio](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.refractionRatio)

The index of refraction (IOR) of air (approximately 1) divided by the
index of refraction of the material. It is used with environment mapping
modes CubeRefractionMapping and EquirectangularRefractionMapping.
The refraction ratio should not exceed `1`.

#### Default

```ts
0.98
```

#### Inherited from

`MeshBasicNodeMaterial.refractionRatio`

***

### shadowSide

> **shadowSide**: [`Side`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/Material:shadowSide](https://threejs.org/docs/#api/en/materials/Material.shadowSide)

Defines which side of faces cast shadows. If `null`, the side casting shadows
is determined as follows:

- When [Material#side](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#side) is set to `FrontSide`, the back side cast shadows.
- When [Material#side](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#side) is set to `BackSide`, the front side cast shadows.
- When [Material#side](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#side) is set to `DoubleSide`, both sides cast shadows.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.shadowSide`

***

### side

> **side**: [`Side`](https://threejs.org/docs/)

Defined in: [three.js/materials/Material:side](https://threejs.org/docs/#api/en/materials/Material.side)

Defines which side of faces will be rendered - front, back or both.

#### Default

```ts
FrontSide
```

#### Inherited from

`MeshBasicNodeMaterial.side`

***

### specularMap

> **specularMap**: [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

Defined in: [three.js/materials/MeshBasicMaterial:specularMap](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.specularMap)

Specular map used by the material.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.specularMap`

***

### stencilFail

> **stencilFail**: [`StencilOp`](https://threejs.org/docs/)

Defined in: [three.js/materials/Material:stencilFail](https://threejs.org/docs/#api/en/materials/Material.stencilFail)

Which stencil operation to perform when the comparison function returns `false`.

#### Default

```ts
KeepStencilOp
```

#### Inherited from

`MeshBasicNodeMaterial.stencilFail`

***

### stencilFunc

> **stencilFunc**: [`StencilFunc`](https://threejs.org/docs/)

Defined in: [three.js/materials/Material:stencilFunc](https://threejs.org/docs/#api/en/materials/Material.stencilFunc)

The stencil comparison function to use.

#### Default

```ts
AlwaysStencilFunc
```

#### Inherited from

`MeshBasicNodeMaterial.stencilFunc`

***

### stencilFuncMask

> **stencilFuncMask**: `number`

Defined in: [three.js/materials/Material:stencilFuncMask](https://threejs.org/docs/#api/en/materials/Material.stencilFuncMask)

The bit mask to use when comparing against the stencil buffer.

#### Default

```ts
0xff
```

#### Inherited from

`MeshBasicNodeMaterial.stencilFuncMask`

***

### stencilRef

> **stencilRef**: `number`

Defined in: [three.js/materials/Material:stencilRef](https://threejs.org/docs/#api/en/materials/Material.stencilRef)

The value to use when performing stencil comparisons or stencil operations.

#### Default

```ts
0
```

#### Inherited from

`MeshBasicNodeMaterial.stencilRef`

***

### stencilWrite

> **stencilWrite**: `boolean`

Defined in: [three.js/materials/Material:stencilWrite](https://threejs.org/docs/#api/en/materials/Material.stencilWrite)

Whether stencil operations are performed against the stencil buffer. In
order to perform writes or comparisons against the stencil buffer this
value must be `true`.

#### Default

```ts
false
```

#### Inherited from

`MeshBasicNodeMaterial.stencilWrite`

***

### stencilWriteMask

> **stencilWriteMask**: `number`

Defined in: [three.js/materials/Material:stencilWriteMask](https://threejs.org/docs/#api/en/materials/Material.stencilWriteMask)

The bit mask to use when writing to the stencil buffer.

#### Default

```ts
0xff
```

#### Inherited from

`MeshBasicNodeMaterial.stencilWriteMask`

***

### stencilZFail

> **stencilZFail**: [`StencilOp`](https://threejs.org/docs/)

Defined in: [three.js/materials/Material:stencilZFail](https://threejs.org/docs/#api/en/materials/Material.stencilZFail)

Which stencil operation to perform when the comparison function returns
`true` but the depth test fails.

#### Default

```ts
KeepStencilOp
```

#### Inherited from

`MeshBasicNodeMaterial.stencilZFail`

***

### stencilZPass

> **stencilZPass**: [`StencilOp`](https://threejs.org/docs/)

Defined in: [three.js/materials/Material:stencilZPass](https://threejs.org/docs/#api/en/materials/Material.stencilZPass)

Which stencil operation to perform when the comparison function returns
`true` and the depth test passes.

#### Default

```ts
KeepStencilOp
```

#### Inherited from

`MeshBasicNodeMaterial.stencilZPass`

***

### toneMapped

> **toneMapped**: `boolean`

Defined in: [three.js/materials/Material:toneMapped](https://threejs.org/docs/#api/en/materials/Material.toneMapped)

Defines whether this material is tone mapped according to the renderer's tone mapping setting.

It is ignored when rendering to a render target or using post processing or when using
`WebGPURenderer`. In all these cases, all materials are honored by tone mapping.

#### Default

```ts
true
```

#### Inherited from

`MeshBasicNodeMaterial.toneMapped`

***

### transparent

> **transparent**: `boolean`

Defined in: [three.js/materials/Material:transparent](https://threejs.org/docs/#api/en/materials/Material.transparent)

Defines whether this material is transparent. This has an effect on
rendering as transparent objects need special treatment and are rendered
after non-transparent objects.

When set to true, the extent to which the material is transparent is
controlled by [Material#opacity](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#opacity).

#### Default

```ts
false
```

#### Inherited from

`MeshBasicNodeMaterial.transparent`

***

### type

> **type**: `string`

Defined in: [three.js/materials/Material:type](https://threejs.org/docs/#api/en/materials/Material.type)

The type property is used for detecting the object type
in context of serialization/deserialization.

#### Inherited from

`MeshBasicNodeMaterial.type`

***

### userData

> **userData**: `Record`\<`string`, `any`\>

Defined in: [three.js/materials/Material:userData](https://threejs.org/docs/#api/en/materials/Material.userData)

An object that can be used to store custom data about the Material. It
should not hold references to functions as these will not be cloned.

#### Inherited from

`MeshBasicNodeMaterial.userData`

***

### uuid

> `readonly` **uuid**: `string`

Defined in: [three.js/materials/Material:uuid](https://threejs.org/docs/#api/en/materials/Material.uuid)

The UUID of the material.

#### Inherited from

`MeshBasicNodeMaterial.uuid`

***

### version

> `readonly` **version**: `number`

Defined in: [three.js/materials/Material:version](https://threejs.org/docs/#api/en/materials/Material.version)

This starts at `0` and counts how many times [Material#needsUpdate](https://threejs.org/docs/) is set to `true`.

#### Default

```ts
0
```

#### Inherited from

`MeshBasicNodeMaterial.version`

***

### vertexColors

> **vertexColors**: `boolean`

Defined in: [three.js/materials/Material:vertexColors](https://threejs.org/docs/#api/en/materials/Material.vertexColors)

If set to `true`, vertex colors should be used.

The engine supports RGB and RGBA vertex colors depending on whether a three (RGB) or
four (RGBA) component color buffer attribute is used.

#### Default

```ts
false
```

#### Inherited from

`MeshBasicNodeMaterial.vertexColors`

***

### vertexNode

> **vertexNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:vertexNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.vertexNode)

This node property can be used if you need complete freedom in implementing
the vertex shader. Assigning a node will replace the built-in material logic
used in the vertex stage.

#### Default

```ts
null
```

#### Inherited from

`MeshBasicNodeMaterial.vertexNode`

***

### visible

> **visible**: `boolean`

Defined in: [three.js/materials/Material:visible](https://threejs.org/docs/#api/en/materials/Material.visible)

Defines whether 3D objects using this material are visible.

#### Default

```ts
true
```

#### Inherited from

`MeshBasicNodeMaterial.visible`

***

### wireframe

> **wireframe**: `boolean`

Defined in: [three.js/materials/MeshBasicMaterial:wireframe](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.wireframe)

Renders the geometry as a wireframe.

#### Default

```ts
false
```

#### Inherited from

`MeshBasicNodeMaterial.wireframe`

***

### wireframeLinecap

> **wireframeLinecap**: `"round"` \| `"bevel"` \| `"miter"`

Defined in: [three.js/materials/MeshBasicMaterial:wireframeLinecap](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.wireframeLinecap)

Defines appearance of wireframe ends.

Can only be used with SVGRenderer.

#### Default

```ts
'round'
```

#### Inherited from

`MeshBasicNodeMaterial.wireframeLinecap`

***

### wireframeLinejoin

> **wireframeLinejoin**: `"round"` \| `"bevel"` \| `"miter"`

Defined in: [three.js/materials/MeshBasicMaterial:wireframeLinejoin](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.wireframeLinejoin)

Defines appearance of wireframe joints.

Can only be used with SVGRenderer.

#### Default

```ts
'round'
```

#### Inherited from

`MeshBasicNodeMaterial.wireframeLinejoin`

***

### wireframeLinewidth

> **wireframeLinewidth**: `number`

Defined in: [three.js/materials/MeshBasicMaterial:wireframeLinewidth](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.wireframeLinewidth)

Controls the thickness of the wireframe.

Can only be used with SVGRenderer.

#### Default

```ts
1
```

#### Inherited from

`MeshBasicNodeMaterial.wireframeLinewidth`

***

### MAX\_EFFECT\_FLOATS

> `readonly` `static` **MAX\_EFFECT\_FLOATS**: `12` = `12`

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:144](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L144)

Maximum total effect-data floats allowed across all registered
effects on this material. WebGPU allows 8 vertex-buffer bindings
per pipeline; SpriteBatch uses 5 fixed bindings (3 geometry +
instanceMatrix + interleaved core), leaving 3 for `effectBuf0/1/2`
× 4 floats = 12 floats. Exceeding this would force a 4th effectBuf
binding which WebGPU rejects at pipeline creation with a cryptic
"vertex buffer count exceeds maximum" error. `registerEffect`
throws clearly when the cap would be exceeded.

## Accessors

### alphaTest

#### Get Signature

> **get** **alphaTest**(): `number`

Defined in: [three.js/materials/Material:alphaTest](https://threejs.org/docs/#api/en/materials/Material.alphaTest)

Sets the alpha value to be used when running an alpha test. The material
will not be rendered if the opacity is lower than this value.

##### Default

```ts
0
```

##### Returns

`number`

#### Set Signature

> **set** **alphaTest**(`value`): `void`

Defined in: [three.js/materials/Material:alphaTest](https://threejs.org/docs/#api/en/materials/Material.alphaTest)

##### Parameters

###### value

`number`

##### Returns

`void`

#### Inherited from

`MeshBasicNodeMaterial.alphaTest`

***

### colorTransform

#### Get Signature

> **get** **colorTransform**(): [`ColorTransformFn`](/three-flatland/api/three-flatland/src/type-aliases/colortransformfn/) \| `null`

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:223](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L223)

Get the color transform function.

##### Returns

[`ColorTransformFn`](/three-flatland/api/three-flatland/src/type-aliases/colortransformfn/) \| `null`

#### Set Signature

> **set** **colorTransform**(`value`): `void`

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:231](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L231)

Set the color transform function.
Triggers shader rebuild.

##### Parameters

###### value

[`ColorTransformFn`](/three-flatland/api/three-flatland/src/type-aliases/colortransformfn/) \| `null`

##### Returns

`void`

***

### needsUpdate

#### Set Signature

> **set** **needsUpdate**(`value`): `void`

Defined in: [three.js/materials/Material:needsUpdate](https://threejs.org/docs/#api/en/materials/Material.needsUpdate)

Setting this property to `true` indicates the engine the material
needs to be recompiled.

##### Default

```ts
false
```

##### Parameters

###### value

`boolean`

##### Returns

`void`

#### Inherited from

`MeshBasicNodeMaterial.needsUpdate`

***

### requiredChannels

#### Get Signature

> **get** **requiredChannels**(): `ReadonlySet`\<`string`\>

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:243](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L243)

Get the required channels set.

##### Returns

`ReadonlySet`\<`string`\>

#### Set Signature

> **set** **requiredChannels**(`value`): `void`

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:251](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L251)

Set the required channels.
Triggers shader rebuild when channels change.

##### Parameters

###### value

`ReadonlySet`\<`string`\>

##### Returns

`void`

***

### type

#### Get Signature

> **get** `static` **type**(): `string`

Defined in: [three.js/materials/nodes/NodeMaterial:type](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.type)

##### Returns

`string`

#### Inherited from

`MeshBasicNodeMaterial.type`

## Methods

### addEventListener()

> **addEventListener**\<`T`\>(`type`, `listener`): `void`

Defined in: [three.js/core/EventDispatcher:addEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.addEventListener)

Adds a listener to an event type.

#### Type Parameters

##### T

`T` *extends* `"dispose"`

#### Parameters

##### type

`T`

The type of event to listen to.

##### listener

[`EventListener`](https://threejs.org/docs/)\<`object`\[`T`\], `T`, `EffectMaterial`\>

The function that gets called when the event is fired.

#### Returns

`void`

#### Inherited from

`MeshBasicNodeMaterial.addEventListener`

***

### build()

> **build**(`builder`): `void`

Defined in: [three.js/materials/nodes/NodeMaterial:build](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.build)

Builds this material with the given node builder.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

`void`

#### Inherited from

`MeshBasicNodeMaterial.build`

***

### clone()

> **clone**(): `this`

Defined in: [three.js/materials/Material:clone](https://threejs.org/docs/#api/en/materials/Material.clone)

Returns a new material with copied values from this instance.

#### Returns

`this`

A clone of this instance.

#### Inherited from

`MeshBasicNodeMaterial.clone`

***

### copy()

> **copy**(`source`): `this`

Defined in: [three.js/materials/nodes/NodeMaterial:copy](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.copy)

Copies the properties of the given node material to this instance.

#### Parameters

##### source

[`NodeMaterial`](https://threejs.org/docs/)

The material to copy.

#### Returns

`this`

A reference to this node material.

#### Inherited from

`MeshBasicNodeMaterial.copy`

***

### customProgramCacheKey()

> **customProgramCacheKey**(): `string`

Defined in: [three.js/materials/Material:customProgramCacheKey](https://threejs.org/docs/#api/en/materials/Material.customProgramCacheKey)

In case [Material#onBeforeCompile](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#onbeforecompile) is used, this callback can be used to identify
values of settings used in `onBeforeCompile()`, so three.js can reuse a cached
shader or recompile the shader for this material as needed.

This method can only be used when rendering with [WebGLRenderer](https://threejs.org/docs/#api/en/renderers/WebGLRenderer).

#### Returns

`string`

The custom program cache key.

#### Inherited from

`MeshBasicNodeMaterial.customProgramCacheKey`

***

### dispatchEvent()

> **dispatchEvent**\<`T`\>(`event`): `void`

Defined in: [three.js/core/EventDispatcher:dispatchEvent](https://threejs.org/docs/#api/en/core/EventDispatcher.dispatchEvent)

Fire an event type.

#### Type Parameters

##### T

`T` *extends* `"dispose"`

#### Parameters

##### event

[`BaseEvent`](https://threejs.org/docs/)\<`T`\> & `object`\[`T`\]

The event that gets fired.

#### Returns

`void`

#### Inherited from

`MeshBasicNodeMaterial.dispatchEvent`

***

### dispose()

> **dispose**(): `void`

Defined in: [three.js/materials/Material:dispose](https://threejs.org/docs/#api/en/materials/Material.dispose)

Frees the GPU-related resources allocated by this instance. Call this
method whenever this instance is no longer used in your app.

#### Returns

`void`

#### Fires

Material#dispose

#### Inherited from

`MeshBasicNodeMaterial.dispose`

***

### getEffectFieldLocation()

> **getEffectFieldLocation**(`effectName`, `fieldName`): \{ `bufferName`: `string`; `componentIndex`: `number`; `size`: `number`; \} \| `undefined`

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:640](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L640)

Locate an effect's schema field within the packed instance buffers.
Returns the `effectBufN` attribute that contains this field, the
float offset within a single instance's 4-float slice of that
buffer (0-3), and the field's float width. Returns `undefined`
if no registered effect declares the given field.

Used by instance-writing code (e.g. TileLayer, SpriteBatch) that
needs to poke per-instance effect values directly without going
through a MaterialEffect instance's property setter.

#### Parameters

##### effectName

`string`

##### fieldName

`string`

#### Returns

\{ `bufferName`: `string`; `componentIndex`: `number`; `size`: `number`; \} \| `undefined`

***

### getEffects()

> **getEffects**(): readonly *typeof* [`MaterialEffect`](/three-flatland/api/three-flatland/src/classes/materialeffect/)[]

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:366](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L366)

Get the list of registered effect classes.

#### Returns

readonly *typeof* [`MaterialEffect`](/three-flatland/api/three-flatland/src/classes/materialeffect/)[]

***

### getUsedEffectFloats()

> **getUsedEffectFloats**(): `number`

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:193](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L193)

Current per-instance effect-float usage (sum across all registered
effects). Complements [getMaxEffectFloats](/three-flatland/api/three-flatland/src/classes/effectmaterial/#getmaxeffectfloats).

#### Returns

`number`

***

### hasEffect()

> **hasEffect**(`effectClass`): `boolean`

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:359](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L359)

Check if an effect class is registered on this material.

#### Parameters

##### effectClass

*typeof* [`MaterialEffect`](/three-flatland/api/three-flatland/src/classes/materialeffect/)

#### Returns

`boolean`

***

### hasEventListener()

> **hasEventListener**\<`T`\>(`type`, `listener`): `boolean`

Defined in: [three.js/core/EventDispatcher:hasEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.hasEventListener)

Checks if listener is added to an event type.

#### Type Parameters

##### T

`T` *extends* `"dispose"`

#### Parameters

##### type

`T`

The type of event to listen to.

##### listener

[`EventListener`](https://threejs.org/docs/)\<`object`\[`T`\], `T`, `EffectMaterial`\>

The function that gets called when the event is fired.

#### Returns

`boolean`

#### Inherited from

`MeshBasicNodeMaterial.hasEventListener`

***

### onBeforeCompile()

> **onBeforeCompile**(`parameters`, `renderer`): `void`

Defined in: [three.js/materials/Material:onBeforeCompile](https://threejs.org/docs/#api/en/materials/Material.onBeforeCompile)

An optional callback that is executed immediately before the shader
program is compiled. This function is called with the shader source code
as a parameter. Useful for the modification of built-in materials.

This method can only be used when rendering with [WebGLRenderer](https://threejs.org/docs/#api/en/renderers/WebGLRenderer). The
recommended approach when customizing materials is to use `WebGPURenderer` with the new
Node Material system and [TSL](https://github.com/mrdoob/three.js/wiki/Three.js-Shading-Language).

#### Parameters

##### parameters

[`WebGLProgramParametersWithUniforms`](https://threejs.org/docs/)

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

A reference to the renderer.

#### Returns

`void`

#### Inherited from

`MeshBasicNodeMaterial.onBeforeCompile`

***

### onBeforeRender()

> **onBeforeRender**(`renderer`, `scene`, `camera`, `geometry`, `object`, `group`): `void`

Defined in: [three.js/materials/Material:onBeforeRender](https://threejs.org/docs/#api/en/materials/Material.onBeforeRender)

An optional callback that is executed immediately before the material is used to render a 3D object.

This method can only be used when rendering with [WebGLRenderer](https://threejs.org/docs/#api/en/renderers/WebGLRenderer).

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

The renderer.

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

The scene.

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

The camera that is used to render the scene.

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

The 3D object's geometry.

##### object

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)

The 3D object.

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

The geometry group data.

#### Returns

`void`

#### Inherited from

`MeshBasicNodeMaterial.onBeforeRender`

***

### registerEffect()

> **registerEffect**(`effectClass`, `constants?`): `boolean`

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:273](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L273)

Register an effect class on this material.
Assigns a bit index and packed buffer slots, then rebuilds the shader.
If the effect is already registered, this is a no-op.

#### Parameters

##### effectClass

*typeof* [`MaterialEffect`](/three-flatland/api/three-flatland/src/classes/materialeffect/)

The MaterialEffect subclass to register

##### constants?

`Record`\<`string`, `unknown`\>

Optional constants from the effect instance (for provider effects)

#### Returns

`boolean`

Whether the buffer tier changed (requiring batch rebuild).

***

### removeEventListener()

> **removeEventListener**\<`T`\>(`type`, `listener`): `void`

Defined in: [three.js/core/EventDispatcher:removeEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.removeEventListener)

Removes a listener from an event type.

#### Type Parameters

##### T

`T` *extends* `"dispose"`

#### Parameters

##### type

`T`

The type of the listener that gets removed.

##### listener

[`EventListener`](https://threejs.org/docs/)\<`object`\[`T`\], `T`, `EffectMaterial`\>

The listener function that gets removed.

#### Returns

`void`

#### Inherited from

`MeshBasicNodeMaterial.removeEventListener`

***

### setDefaultValues()

> **setDefaultValues**(`material`): `void`

Defined in: [three.js/materials/nodes/NodeMaterial:setDefaultValues](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setDefaultValues)

Most classic material types have a node pendant e.g. for `MeshBasicMaterial`
there is `MeshBasicNodeMaterial`. This utility method is intended for
defining all material properties of the classic type in the node type.

#### Parameters

##### material

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

The material to copy properties with their values to this node material.

#### Returns

`void`

#### Inherited from

`MeshBasicNodeMaterial.setDefaultValues`

***

### setup()

> **setup**(`builder`): `void`

Defined in: [three.js/materials/nodes/NodeMaterial:setup](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setup)

Setups the vertex and fragment stage of this node material.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

`void`

#### Inherited from

`MeshBasicNodeMaterial.setup`

***

### setupClipping()

> **setupClipping**(`builder`): [`ClippingNode`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupClipping](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupClipping)

Setups the clipping node.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

[`ClippingNode`](https://threejs.org/docs/)

The clipping node.

#### Inherited from

`MeshBasicNodeMaterial.setupClipping`

***

### setupDepth()

> **setupDepth**(`builder`): `void`

Defined in: [three.js/materials/nodes/NodeMaterial:setupDepth](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupDepth)

Setups the depth of this material.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

`void`

#### Inherited from

`MeshBasicNodeMaterial.setupDepth`

***

### setupDiffuseColor()

> **setupDiffuseColor**(`builder`): `void`

Defined in: [three.js/materials/nodes/NodeMaterial:setupDiffuseColor](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupDiffuseColor)

Setups the computation of the material's diffuse color.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

`void`

#### Inherited from

`MeshBasicNodeMaterial.setupDiffuseColor`

***

### setupEnvironment()

> **setupEnvironment**(`builder`): [`BasicEnvironmentNode`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/MeshBasicNodeMaterial:setupEnvironment](https://threejs.org/docs/#api/en/materials/nodes/MeshBasicNodeMaterial.setupEnvironment)

Overwritten since this type of material uses [BasicEnvironmentNode](https://threejs.org/docs/)
to implement the default environment mapping.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

[`BasicEnvironmentNode`](https://threejs.org/docs/) \| `null`

The environment node.

#### Inherited from

`MeshBasicNodeMaterial.setupEnvironment`

***

### setupFog()

> **setupFog**(`builder`, `outputNode`): [`Node`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupFog](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupFog)

Setup the fog.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

##### outputNode

[`Node`](https://threejs.org/docs/)

The existing output node.

#### Returns

[`Node`](https://threejs.org/docs/)

The output node.

#### Inherited from

`MeshBasicNodeMaterial.setupFog`

***

### setupHardwareClipping()

> **setupHardwareClipping**(`builder`): `void`

Defined in: [three.js/materials/nodes/NodeMaterial:setupHardwareClipping](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupHardwareClipping)

Setups the hardware clipping if available on the current device.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

`void`

#### Inherited from

`MeshBasicNodeMaterial.setupHardwareClipping`

***

### setupLighting()

> **setupLighting**(`builder`): [`Node`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupLighting](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupLighting)

Setups the outgoing light node.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

[`Node`](https://threejs.org/docs/)

The outgoing light node.

#### Inherited from

`MeshBasicNodeMaterial.setupLighting`

***

### setupLightingModel()

> **setupLightingModel**(): [`BasicLightingModel`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/MeshBasicNodeMaterial:setupLightingModel](https://threejs.org/docs/#api/en/materials/nodes/MeshBasicNodeMaterial.setupLightingModel)

Setups the lighting model.

#### Returns

[`BasicLightingModel`](https://threejs.org/docs/)

The lighting model.

#### Inherited from

`MeshBasicNodeMaterial.setupLightingModel`

***

### setupLightMap()

> **setupLightMap**(`builder`): [`Node`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupLightMap](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupLightMap)

Setups the light map node from the material.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

[`Node`](https://threejs.org/docs/)

The light map node.

#### Inherited from

`MeshBasicNodeMaterial.setupLightMap`

***

### setupLights()

> **setupLights**(`builder`): [`LightsNode`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupLights](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupLights)

Setups the lights node based on the scene, environment and material.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

[`LightsNode`](https://threejs.org/docs/)

The lights node.

#### Inherited from

`MeshBasicNodeMaterial.setupLights`

***

### setupModelViewProjection()

> **setupModelViewProjection**(): [`Node`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupModelViewProjection](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupModelViewProjection)

Setups the position in clip space.

#### Returns

[`Node`](https://threejs.org/docs/)

The position in view space.

#### Inherited from

`MeshBasicNodeMaterial.setupModelViewProjection`

***

### setupNormal()

> **setupNormal**(): [`Node`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupNormal](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupNormal)

Setups the normal node from the material.

#### Returns

[`Node`](https://threejs.org/docs/)

The normal node.

#### Inherited from

`MeshBasicNodeMaterial.setupNormal`

***

### setupObserver()

> **setupObserver**(`builder`): [`NodeMaterialObserver`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupObserver](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupObserver)

Setups a node material observer with the given builder.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

[`NodeMaterialObserver`](https://threejs.org/docs/)

The node material observer.

#### Inherited from

`MeshBasicNodeMaterial.setupObserver`

***

### setupOutgoingLight()

> **setupOutgoingLight**(): [`Node`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupOutgoingLight](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupOutgoingLight)

Setups the outgoing light node variable

#### Returns

[`Node`](https://threejs.org/docs/)

The outgoing light node.

#### Inherited from

`MeshBasicNodeMaterial.setupOutgoingLight`

***

### setupOutput()

> **setupOutput**(`builder`, `outputNode`): [`Node`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupOutput](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupOutput)

Setups the output node.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

##### outputNode

[`Node`](https://threejs.org/docs/)

The existing output node.

#### Returns

[`Node`](https://threejs.org/docs/)

The output node.

#### Inherited from

`MeshBasicNodeMaterial.setupOutput`

***

### setupPosition()

> **setupPosition**(`builder`): [`Node`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupPosition](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupPosition)

Setups the computation of the position in local space.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

[`Node`](https://threejs.org/docs/)

The position in local space.

#### Inherited from

`MeshBasicNodeMaterial.setupPosition`

***

### setupPositionView()

> **setupPositionView**(`builder`): [`Node`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupPositionView](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupPositionView)

Setups the position node in view space. This method exists
so derived node materials can modify the implementation e.g. sprite materials.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

[`Node`](https://threejs.org/docs/)

The position in view space.

#### Inherited from

`MeshBasicNodeMaterial.setupPositionView`

***

### setupPremultipliedAlpha()

> **setupPremultipliedAlpha**(`builder`, `outputNode`): [`Node`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupPremultipliedAlpha](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupPremultipliedAlpha)

Setups premultiplied alpha.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

##### outputNode

[`Node`](https://threejs.org/docs/)

The existing output node.

#### Returns

[`Node`](https://threejs.org/docs/)

The output node.

#### Inherited from

`MeshBasicNodeMaterial.setupPremultipliedAlpha`

***

### setupVariants()

> `abstract` **setupVariants**(`builder`): `void`

Defined in: [three.js/materials/nodes/NodeMaterial:setupVariants](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupVariants)

Abstract interface method that can be implemented by derived materials
to setup material-specific node variables.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

`void`

#### Inherited from

`MeshBasicNodeMaterial.setupVariants`

***

### setupVertex()

> **setupVertex**(`builder`): [`Node`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupVertex](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupVertex)

Setups the logic for the vertex stage.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

[`Node`](https://threejs.org/docs/)

The position in clip space.

#### Inherited from

`MeshBasicNodeMaterial.setupVertex`

***

### setValues()

> **setValues**(`values?`): `void`

Defined in: [three.js/materials/nodes/MeshBasicNodeMaterial:setValues](https://threejs.org/docs/#api/en/materials/nodes/MeshBasicNodeMaterial.setValues)

#### Parameters

##### values?

[`MeshBasicNodeMaterialParameters`](https://threejs.org/docs/)

#### Returns

`void`

#### Inherited from

`MeshBasicNodeMaterial.setValues`

***

### toJSON()

> **toJSON**(`meta?`): [`MaterialJSON`](https://threejs.org/docs/)

Defined in: [three.js/materials/Material:toJSON](https://threejs.org/docs/#api/en/materials/Material.toJSON)

Serializes the material into JSON.

#### Parameters

##### meta?

[`JSONMeta`](https://threejs.org/docs/)

An optional value holding meta information about the serialization.

#### Returns

[`MaterialJSON`](https://threejs.org/docs/)

A JSON object representing the serialized material.

#### See

ObjectLoader#parse

#### Inherited from

`MeshBasicNodeMaterial.toJSON`

***

### getMaxEffectFloats()

> `static` **getMaxEffectFloats**(): `number`

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:185](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L185)

Return the maximum number of per-instance effect floats this
material type supports. See [MAX\_EFFECT\_FLOATS](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#max_effect_floats).

#### Returns

`number`

# Flatland

Defined in: [packages/three-flatland/src/Flatland.ts:162](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L162)

Flatland - Unified 2D rendering pipeline for Three.js WebGPU.

Combines sprite batching, post-processing, render targets, and global uniforms
into a single high-level API. Implements WorldProvider — one ECS world per Flatland
instance, shared between sprite batching and post-processing passes.

## Examples

```typescript
// Basic usage - render to viewport
const flatland = new Flatland({ viewSize: 400 })
flatland.add(new Sprite2D({ texture }))

// Render loop
function animate() {
  flatland.render(renderer)
  requestAnimationFrame(animate)
}
```

```typescript
// Render to texture
import { RenderTarget } from 'three'

const target = new RenderTarget(512, 512)
const flatland = new Flatland({ renderTarget: target })
flatland.add(sprite)

// Use texture on 3D mesh
mesh.material.map = flatland.texture

// Render loop
flatland.render(renderer)  // Renders to target
renderer.render(scene3D, camera3D)  // Renders 3D with card
```

```tsx
// React Three Fiber usage
import { Canvas, extend, useFrame, useThree } from '@react-three/fiber/webgpu'
import { Flatland, Sprite2D } from 'three-flatland/react'

extend({ Flatland, Sprite2D })

function Scene() {
  const flatlandRef = useRef<Flatland>(null)
  const { gl } = useThree()

  useFrame(() => {
    flatlandRef.current?.render(gl)
  })

  return (
    <flatland ref={flatlandRef} viewSize={400} clearColor={0x1a1a2e}>
      <sprite2D texture={texture} position={[0, 0, 0]} />
    </flatland>
  )
}
```

## Extends

- [`Group`](https://threejs.org/docs/#api/en/objects/Group)

## Implements

- `WorldProvider`

## Constructors

### Constructor

> **new Flatland**(`options?`): `Flatland`

Defined in: [packages/three-flatland/src/Flatland.ts:264](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L264)

#### Parameters

##### options?

[`FlatlandOptions`](/three-flatland/api/three-flatland/src/interfaces/flatlandoptions/) = `{}`

#### Returns

`Flatland`

#### Overrides

`Group.constructor`

## Properties

### animations

> **animations**: [`AnimationClip`](https://threejs.org/docs/)[]

Defined in: [three.js/core/Object3D:animations](https://threejs.org/docs/#api/en/core/Object3D.animations)

Array with object's animation clips.

#### Default Value

`[]`

#### Inherited from

`Group.animations`

***

### autoClear

> **autoClear**: `boolean`

Defined in: [packages/three-flatland/src/Flatland.ts:200](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L200)

Auto-clear before render

***

### castShadow

> **castShadow**: `boolean`

Defined in: [three.js/core/Object3D:castShadow](https://threejs.org/docs/#api/en/core/Object3D.castShadow)

Whether the object gets rendered into shadow map.

#### Default Value

`false`

#### Inherited from

`Group.castShadow`

***

### children

> **children**: [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

Defined in: [three.js/core/Object3D:children](https://threejs.org/docs/#api/en/core/Object3D.children)

Array with object's children.

#### See

THREE.Object3DGroup \| Group for info on manually grouping objects.

#### Default Value

`[]`

#### Inherited from

`Group.children`

***

### clearAlpha

> **clearAlpha**: `number`

Defined in: [packages/three-flatland/src/Flatland.ts:206](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L206)

Clear alpha

***

### clearColor

> **clearColor**: [`Color`](https://threejs.org/docs/#api/en/math/Color)

Defined in: [packages/three-flatland/src/Flatland.ts:203](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L203)

Clear color

***

### count?

> `optional` **count?**: `number`

Defined in: [three.js/renderers/common/Backend:count](https://threejs.org/docs/#api/en/renderers/common/Backend.count)

#### Inherited from

`Group.count`

***

### customDepthMaterial?

> `optional` **customDepthMaterial?**: [`Material`](https://threejs.org/docs/#api/en/materials/Material)

Defined in: [three.js/core/Object3D:customDepthMaterial](https://threejs.org/docs/#api/en/core/Object3D.customDepthMaterial)

Custom depth material to be used when rendering to the depth map.

#### Remarks

Can only be used in context of meshes.
When shadow-casting with a THREE.DirectionalLight \| DirectionalLight or THREE.SpotLight \| SpotLight,
if you are modifying vertex positions in the vertex shader you must specify a customDepthMaterial for proper shadows.

#### Default Value

`undefined`

#### Inherited from

`Group.customDepthMaterial`

***

### customDistanceMaterial?

> `optional` **customDistanceMaterial?**: [`Material`](https://threejs.org/docs/#api/en/materials/Material)

Defined in: [three.js/core/Object3D:customDistanceMaterial](https://threejs.org/docs/#api/en/core/Object3D.customDistanceMaterial)

Same as [customDepthMaterial](/three-flatland/api/three-flatland/src/classes/flatland/#customdepthmaterial), but used with THREE.Object3DPointLight \| PointLight.

#### Default Value

`undefined`

#### Inherited from

`Group.customDistanceMaterial`

***

### frustumCulled

> **frustumCulled**: `boolean`

Defined in: [three.js/core/Object3D:frustumCulled](https://threejs.org/docs/#api/en/core/Object3D.frustumCulled)

When this is set, it checks every frame if the object is in the frustum of the camera before rendering the object.
If set to `false` the object gets rendered every frame even if it is not in the frustum of the camera.

#### Default Value

`true`

#### Inherited from

`Group.frustumCulled`

***

### globals

> `readonly` **globals**: [`GlobalUniforms`](/three-flatland/api/three-flatland/src/classes/globaluniforms/)

Defined in: [packages/three-flatland/src/Flatland.ts:170](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L170)

Global uniforms shared across all sprite materials

***

### id

> `readonly` **id**: `number`

Defined in: [three.js/core/Object3D:id](https://threejs.org/docs/#api/en/core/Object3D.id)

Unique number for this [Object3D](https://threejs.org/docs/#api/en/core/Object3D) instance.

#### Remarks

Note that ids are assigned in chronological order: 1, 2, 3, ..., incrementing by one for each new object.
Expects a `Integer`

#### Inherited from

`Group.id`

***

### isGroup

> `readonly` **isGroup**: `true`

Defined in: [three.js/objects/Group:isGroup](https://threejs.org/docs/#api/en/objects/Group.isGroup)

Read-only flag to check if a given object is of type [Group](https://threejs.org/docs/#api/en/objects/Group).

#### Remarks

This is a _constant_ value

#### Default Value

`true`

#### Inherited from

`Group.isGroup`

***

### isObject3D

> `readonly` **isObject3D**: `true`

Defined in: [three.js/core/Object3D:isObject3D](https://threejs.org/docs/#api/en/core/Object3D.isObject3D)

Flag to check if a given object is of type [Object3D](https://threejs.org/docs/#api/en/core/Object3D).

#### Remarks

This is a _constant_ value

#### Default Value

`true`

#### Inherited from

`Group.isObject3D`

***

### layers

> **layers**: [`Layers`](https://threejs.org/docs/#api/en/core/Layers)

Defined in: [three.js/core/Object3D:layers](https://threejs.org/docs/#api/en/core/Object3D.layers)

The layer membership of the object.

#### Remarks

The object is only visible if it has at least one layer in common with the THREE.Object3DCamera \| Camera in use.
This property can also be used to filter out unwanted objects in ray-intersection tests when using THREE.Raycaster \| Raycaster.

#### Default Value

`new THREE.Layers()`

#### Inherited from

`Group.layers`

***

### matrix

> **matrix**: [`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Defined in: [three.js/core/Object3D:matrix](https://threejs.org/docs/#api/en/core/Object3D.matrix)

The local transform matrix.

#### Default Value

`new THREE.Matrix4()`

#### Inherited from

`Group.matrix`

***

### matrixAutoUpdate

> **matrixAutoUpdate**: `boolean`

Defined in: [three.js/core/Object3D:matrixAutoUpdate](https://threejs.org/docs/#api/en/core/Object3D.matrixAutoUpdate)

When this is set, it calculates the matrix of position, (rotation or quaternion) and
scale every frame and also recalculates the matrixWorld property.

#### Default Value

[DEFAULT\_MATRIX\_AUTO\_UPDATE](/three-flatland/api/three-flatland/src/classes/flatland/#default_matrix_auto_update) - that is `(true)`.

#### Inherited from

`Group.matrixAutoUpdate`

***

### matrixWorld

> **matrixWorld**: [`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Defined in: [three.js/core/Object3D:matrixWorld](https://threejs.org/docs/#api/en/core/Object3D.matrixWorld)

The global transform of the object.

#### Remarks

If the [Object3D](https://threejs.org/docs/#api/en/core/Object3D) has no parent, then it's identical to the local transform THREE.Object3D.matrix \| .matrix.

#### Default Value

`new THREE.Matrix4()`

#### Inherited from

`Group.matrixWorld`

***

### matrixWorldAutoUpdate

> **matrixWorldAutoUpdate**: `boolean`

Defined in: [three.js/core/Object3D:matrixWorldAutoUpdate](https://threejs.org/docs/#api/en/core/Object3D.matrixWorldAutoUpdate)

If set, then the renderer checks every frame if the object and its children need matrix updates.
When it isn't, then you have to maintain all matrices in the object and its children yourself.

#### Default Value

[DEFAULT\_MATRIX\_WORLD\_AUTO\_UPDATE](/three-flatland/api/three-flatland/src/classes/flatland/#default_matrix_world_auto_update) - that is `(true)`.

#### Inherited from

`Group.matrixWorldAutoUpdate`

***

### matrixWorldNeedsUpdate

> **matrixWorldNeedsUpdate**: `boolean`

Defined in: [three.js/core/Object3D:matrixWorldNeedsUpdate](https://threejs.org/docs/#api/en/core/Object3D.matrixWorldNeedsUpdate)

When this is set, it calculates the matrixWorld in that frame and resets this property to false.

#### Default Value

`false`

#### Inherited from

`Group.matrixWorldNeedsUpdate`

***

### modelViewMatrix

> `readonly` **modelViewMatrix**: [`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Defined in: [three.js/core/Object3D:modelViewMatrix](https://threejs.org/docs/#api/en/core/Object3D.modelViewMatrix)

#### Default Value

`new THREE.Matrix4()`

#### Inherited from

`Group.modelViewMatrix`

***

### name

> **name**: `string`

Defined in: [three.js/core/Object3D:name](https://threejs.org/docs/#api/en/core/Object3D.name)

Optional name of the object

#### Remarks

_(doesn't need to be unique)_.

#### Default Value

`""`

#### Inherited from

`Group.name`

***

### normalMatrix

> `readonly` **normalMatrix**: [`Matrix3`](https://threejs.org/docs/#api/en/math/Matrix3)

Defined in: [three.js/core/Object3D:normalMatrix](https://threejs.org/docs/#api/en/core/Object3D.normalMatrix)

#### Default Value

`new THREE.Matrix3()`

#### Inherited from

`Group.normalMatrix`

***

### occlusionTest?

> `optional` **occlusionTest?**: `boolean`

Defined in: [three.js/renderers/common/Backend:occlusionTest](https://threejs.org/docs/#api/en/renderers/common/Backend.occlusionTest)

#### Inherited from

`Group.occlusionTest`

***

### parent

> **parent**: [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `null`

Defined in: [three.js/core/Object3D:parent](https://threejs.org/docs/#api/en/core/Object3D.parent)

Object's parent in the [scene graph](https://en.wikipedia.org/wiki/Scene_graph).

#### Remarks

An object can have at most one parent.

#### Default Value

`null`

#### Inherited from

`Group.parent`

***

### pivot

> **pivot**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3) \| `null`

Defined in: [three.js/core/Object3D:pivot](https://threejs.org/docs/#api/en/core/Object3D.pivot)

The pivot point for rotation and scale transformations.
When set, rotation and scale are applied around this point
instead of the object's origin.

#### Default

```ts
null
```

#### Inherited from

`Group.pivot`

***

### position

> `readonly` **position**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:position](https://threejs.org/docs/#api/en/core/Object3D.position)

Object's local position.

#### Default Value

`new THREE.Vector3()` - that is `(0, 0, 0)`.

#### Inherited from

`Group.position`

***

### quaternion

> `readonly` **quaternion**: [`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

Defined in: [three.js/core/Object3D:quaternion](https://threejs.org/docs/#api/en/core/Object3D.quaternion)

Object's local rotation as a THREE.Quaternion \| Quaternion.

#### Default Value

`new THREE.Quaternion()` - that is `(0,  0, 0, 1)`.

#### Inherited from

`Group.quaternion`

***

### receiveShadow

> **receiveShadow**: `boolean`

Defined in: [three.js/core/Object3D:receiveShadow](https://threejs.org/docs/#api/en/core/Object3D.receiveShadow)

Whether the material receives shadows.

#### Default Value

`false`

#### Inherited from

`Group.receiveShadow`

***

### renderOrder

> **renderOrder**: `number`

Defined in: [three.js/core/Object3D:renderOrder](https://threejs.org/docs/#api/en/core/Object3D.renderOrder)

This value allows the default rendering order of [scene graph](https://en.wikipedia.org/wiki/Scene_graph)
objects to be overridden although opaque and transparent objects remain sorted independently.

#### Remarks

When this property is set for an instance of [Group](https://threejs.org/docs/#api/en/objects/Group), all descendants objects will be sorted and rendered together.
Sorting is from lowest to highest renderOrder.

#### Default Value

`0`

#### Inherited from

`Group.renderOrder`

***

### rotation

> `readonly` **rotation**: [`Euler`](https://threejs.org/docs/#api/en/math/Euler)

Defined in: [three.js/core/Object3D:rotation](https://threejs.org/docs/#api/en/core/Object3D.rotation)

Object's local rotation ([Euler angles](https://en.wikipedia.org/wiki/Euler_angles)), in radians.

#### Default Value

`new THREE.Euler()` - that is `(0, 0, 0, Euler.DEFAULT_ORDER)`.

#### Inherited from

`Group.rotation`

***

### scale

> `readonly` **scale**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:scale](https://threejs.org/docs/#api/en/core/Object3D.scale)

The object's local scale.

#### Default Value

`new THREE.Vector3( 1, 1, 1 )`

#### Inherited from

`Group.scale`

***

### scene

> `readonly` **scene**: [`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

Defined in: [packages/three-flatland/src/Flatland.ts:164](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L164)

Internal scene containing sprites

***

### spriteGroup

> `readonly` **spriteGroup**: [`SpriteGroup`](/three-flatland/api/three-flatland/src/classes/spritegroup/)

Defined in: [packages/three-flatland/src/Flatland.ts:167](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L167)

Internal sprite group for batching

***

### static

> **static**: `boolean`

Defined in: [three.js/core/Object3D:static](https://threejs.org/docs/#api/en/core/Object3D.static)

Whether the 3D object is supposed to be static or not. If set to `true`, it means
the 3D object is not going to be changed after the initial renderer. This includes
geometry and material settings. A static 3D object can be processed by the renderer
slightly faster since certain state checks can be bypassed.

Only relevant in context of WebGPURenderer.

#### Default

```ts
false
```

#### Inherited from

`Group.static`

***

### type

> `readonly` **type**: `string`

Defined in: [three.js/core/Object3D:type](https://threejs.org/docs/#api/en/core/Object3D.type)

A Read-only _string_ to check `this` object type.

#### Remarks

This can be used to find a specific type of Object3D in a scene.
Sub-classes will update this value.

#### Default Value

`Object3D`

#### Inherited from

`Group.type`

***

### up

> **up**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:up](https://threejs.org/docs/#api/en/core/Object3D.up)

This is used by the [lookAt](https://threejs.org/docs/) method, for example, to determine the orientation of the result.

#### Default Value

[Object3D.DEFAULT\_UP](/three-flatland/api/three-flatland/src/classes/flatland/#default_up) - that is `(0, 1, 0)`.

#### Inherited from

`Group.up`

***

### userData

> **userData**: `Record`\<`string`, `any`\>

Defined in: [three.js/core/Object3D:userData](https://threejs.org/docs/#api/en/core/Object3D.userData)

An object that can be used to store custom data about the [Object3D](https://threejs.org/docs/#api/en/core/Object3D).

#### Remarks

It should not hold references to _functions_ as these **will not** be cloned.

#### Default

`{}`

#### Inherited from

`Group.userData`

***

### uuid

> **uuid**: `string`

Defined in: [three.js/core/Object3D:uuid](https://threejs.org/docs/#api/en/core/Object3D.uuid)

[UUID](http://en.wikipedia.org/wiki/Universally_unique_identifier) of this object instance.

#### Remarks

This gets automatically assigned and shouldn't be edited.

#### Inherited from

`Group.uuid`

***

### visible

> **visible**: `boolean`

Defined in: [three.js/core/Object3D:visible](https://threejs.org/docs/#api/en/core/Object3D.visible)

Object gets rendered if `true`.

#### Default Value

`true`

#### Inherited from

`Group.visible`

***

### DEFAULT\_MATRIX\_AUTO\_UPDATE

> `static` **DEFAULT\_MATRIX\_AUTO\_UPDATE**: `boolean`

Defined in: [three.js/core/Object3D:DEFAULT_MATRIX_AUTO_UPDATE](https://threejs.org/docs/#api/en/core/Object3D.DEFAULT_MATRIX_AUTO_UPDATE)

The default setting for [matrixAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixautoupdate) for newly created Object3Ds.

#### Default Value

`true`

#### Inherited from

`Group.DEFAULT_MATRIX_AUTO_UPDATE`

***

### DEFAULT\_MATRIX\_WORLD\_AUTO\_UPDATE

> `static` **DEFAULT\_MATRIX\_WORLD\_AUTO\_UPDATE**: `boolean`

Defined in: [three.js/core/Object3D:DEFAULT_MATRIX_WORLD_AUTO_UPDATE](https://threejs.org/docs/#api/en/core/Object3D.DEFAULT_MATRIX_WORLD_AUTO_UPDATE)

The default setting for [matrixWorldAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldautoupdate) for newly created Object3Ds.

#### Default Value

`true`

#### Inherited from

`Group.DEFAULT_MATRIX_WORLD_AUTO_UPDATE`

***

### DEFAULT\_UP

> `static` **DEFAULT\_UP**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:DEFAULT_UP](https://threejs.org/docs/#api/en/core/Object3D.DEFAULT_UP)

The default [up](/three-flatland/api/three-flatland/src/classes/flatland/#up) direction for objects, also used as the default position for THREE.DirectionalLight \| DirectionalLight,
THREE.HemisphereLight \| HemisphereLight and THREE.Spotlight \| Spotlight (which creates lights shining from the top down).

#### Default Value

`new THREE.Vector3( 0, 1, 0)`

#### Inherited from

`Group.DEFAULT_UP`

## Accessors

### camera

#### Get Signature

> **get** **camera**(): [`OrthographicCamera`](https://threejs.org/docs/#api/en/cameras/OrthographicCamera)

Defined in: [packages/three-flatland/src/Flatland.ts:375](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L375)

Get the camera.

##### Returns

[`OrthographicCamera`](https://threejs.org/docs/#api/en/cameras/OrthographicCamera)

#### Set Signature

> **set** **camera**(`value`): `void`

Defined in: [packages/three-flatland/src/Flatland.ts:382](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L382)

Set a custom camera.

##### Parameters

###### value

[`OrthographicCamera`](https://threejs.org/docs/#api/en/cameras/OrthographicCamera)

##### Returns

`void`

***

### lighting

#### Get Signature

> **get** **lighting**(): [`LightEffect`](/three-flatland/api/three-flatland/src/classes/lighteffect/) \| `null`

Defined in: [packages/three-flatland/src/Flatland.ts:765](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L765)

Get the active LightEffect.

##### Returns

[`LightEffect`](/three-flatland/api/three-flatland/src/classes/lighteffect/) \| `null`

***

### lights

#### Get Signature

> **get** **lights**(): readonly [`Light2D`](/three-flatland/api/three-flatland/src/classes/light2d/)[]

Defined in: [packages/three-flatland/src/Flatland.ts:758](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L758)

Get the active Light2D instances.

##### Returns

readonly [`Light2D`](/three-flatland/api/three-flatland/src/classes/light2d/)[]

***

### outputNode

#### Get Signature

> **get** **outputNode**(): [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [packages/three-flatland/src/Flatland.ts:441](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L441)

Get/set the output node for post-processing effects.
Set this to apply TSL effect chains.

##### Returns

[`Node`](https://threejs.org/docs/) \| `null`

#### Set Signature

> **set** **outputNode**(`value`): `void`

Defined in: [packages/three-flatland/src/Flatland.ts:445](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L445)

##### Parameters

###### value

[`Node`](https://threejs.org/docs/)

##### Returns

`void`

***

### passes

#### Get Signature

> **get** **passes**(): readonly [`PassEffect`](/three-flatland/api/three-flatland/src/classes/passeffect/)[]

Defined in: [packages/three-flatland/src/Flatland.ts:736](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L736)

Get the current post-processing passes.

##### Returns

readonly [`PassEffect`](/three-flatland/api/three-flatland/src/classes/passeffect/)[]

***

### passNode

#### Get Signature

> **get** **passNode**(): [`PassNode`](https://threejs.org/docs/) \| `null`

Defined in: [packages/three-flatland/src/Flatland.ts:433](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L433)

Get the pass node for composing effects.

##### Returns

[`PassNode`](https://threejs.org/docs/) \| `null`

***

### renderPipeline

#### Get Signature

> **get** **renderPipeline**(): [`RenderPipeline`](https://threejs.org/docs/) \| `null`

Defined in: [packages/three-flatland/src/Flatland.ts:426](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L426)

Get the render pipeline instance.

##### Returns

[`RenderPipeline`](https://threejs.org/docs/) \| `null`

***

### renderTarget

#### Get Signature

> **get** **renderTarget**(): [`RenderTarget`](https://threejs.org/docs/)\<[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\>\> \| `null`

Defined in: [packages/three-flatland/src/Flatland.ts:405](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L405)

Get the render target (null = viewport).

##### Returns

[`RenderTarget`](https://threejs.org/docs/)\<[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\>\> \| `null`

#### Set Signature

> **set** **renderTarget**(`value`): `void`

Defined in: [packages/three-flatland/src/Flatland.ts:412](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L412)

Set the render target.

##### Parameters

###### value

[`RenderTarget`](https://threejs.org/docs/)\<[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\>\> \| `null`

##### Returns

`void`

***

### texture

#### Get Signature

> **get** **texture**(): [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

Defined in: [packages/three-flatland/src/Flatland.ts:419](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L419)

Get the render target texture (or null if rendering to viewport).

##### Returns

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

***

### viewSize

#### Get Signature

> **get** **viewSize**(): `number`

Defined in: [packages/three-flatland/src/Flatland.ts:390](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L390)

Get the view size.

##### Returns

`number`

#### Set Signature

> **set** **viewSize**(`value`): `void`

Defined in: [packages/three-flatland/src/Flatland.ts:397](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L397)

Set the view size.

##### Parameters

###### value

`number`

##### Returns

`void`

***

### world

#### Get Signature

> **get** **world**(): `World`

Defined in: [packages/three-flatland/src/Flatland.ts:340](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L340)

The ECS world for this Flatland instance.
Delegates to SpriteGroup's lazy-initialized world.

##### Returns

`World`

#### Implementation of

`WorldProvider.world`

## Methods

### add()

> **add**(...`objects`): `this`

Defined in: [packages/three-flatland/src/Flatland.ts:460](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L460)

Add objects to Flatland.
Sprites are routed to the internal SpriteGroup for batching.
Other objects are added directly to the internal scene.

This overrides Group.add() to route children to the internal scene
rather than this Group, enabling proper rendering with Flatland's camera.

#### Parameters

##### objects

...[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

#### Returns

`this`

#### Overrides

`Group.add`

***

### addEventListener()

> **addEventListener**\<`T`\>(`type`, `listener`): `void`

Defined in: [three.js/core/EventDispatcher:addEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.addEventListener)

Adds a listener to an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### type

`T`

The type of event to listen to.

##### listener

[`EventListener`](https://threejs.org/docs/)\<[`Object3DEventMap`](https://threejs.org/docs/)\[`T`\], `T`, `Flatland`\>

The function that gets called when the event is fired.

#### Returns

`void`

#### Inherited from

`Group.addEventListener`

***

### addPass()

> **addPass**(`passEffect`, `order?`): `this`

Defined in: [packages/three-flatland/src/Flatland.ts:642](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L642)

Add a post-processing pass to the pipeline.
Passes are applied in insertion order (or explicit order). Automatically enables post-processing.

#### Parameters

##### passEffect

[`PassEffect`](/three-flatland/api/three-flatland/src/classes/passeffect/)

PassEffect instance to add

##### order?

`number`

Optional explicit order (default: auto-increment)

#### Returns

`this`

this (for chaining)

#### Example

```typescript
import { CRTEffect, VignetteEffect } from 'three-flatland'

const crt = new CRTEffect()
const vignette = new VignetteEffect()
flatland.addPass(crt).addPass(vignette)
crt.curvature = 0.3  // zero-cost uniform update
```

***

### applyMatrix4()

> **applyMatrix4**(`matrix`): `void`

Defined in: [three.js/core/Object3D:applyMatrix4](https://threejs.org/docs/#api/en/core/Object3D.applyMatrix4)

Applies the matrix transform to the object and updates the object's position, rotation and scale.

#### Parameters

##### matrix

[`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

#### Returns

`void`

#### Inherited from

`Group.applyMatrix4`

***

### applyQuaternion()

> **applyQuaternion**(`quaternion`): `this`

Defined in: [three.js/core/Object3D:applyQuaternion](https://threejs.org/docs/#api/en/core/Object3D.applyQuaternion)

Applies the rotation represented by the quaternion to the object.

#### Parameters

##### quaternion

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

#### Returns

`this`

#### Inherited from

`Group.applyQuaternion`

***

### attach()

> **attach**(`object`): `this`

Defined in: [three.js/core/Object3D:attach](https://threejs.org/docs/#api/en/core/Object3D.attach)

Adds a [Object3D](https://threejs.org/docs/#api/en/core/Object3D) as a child of this, while maintaining the object's world transform.

#### Parameters

##### object

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)

#### Returns

`this`

#### Remarks

Note: This method does not support scene graphs having non-uniformly-scaled nodes(s).

#### See

[add](https://threejs.org/docs/)

#### Inherited from

`Group.attach`

***

### clear()

> **clear**(): `this`

Defined in: [packages/three-flatland/src/Flatland.ts:564](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L564)

Remove all sprites and other objects from the internal scene.
Overrides Group.clear() to clear the internal scene.

#### Returns

`this`

#### Overrides

`Group.clear`

***

### clearPasses()

> **clearPasses**(): `this`

Defined in: [packages/three-flatland/src/Flatland.ts:713](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L713)

Remove all post-processing passes from the pipeline.
Disables post-processing if it was auto-initialized.

#### Returns

`this`

this (for chaining)

***

### clearRenderPipeline()

> **clearRenderPipeline**(): `void`

Defined in: [packages/three-flatland/src/Flatland.ts:607](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L607)

Clear the render pipeline setup.

#### Returns

`void`

***

### clone()

> **clone**(`recursive?`): `this`

Defined in: [packages/three-flatland/src/Flatland.ts:1378](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L1378)

Clone for devtools/serialization compatibility.
Flatland manages internal scene, camera, and render pipeline that
cannot be meaningfully cloned. Returns a Group with cloned children.

#### Parameters

##### recursive?

`boolean`

#### Returns

`this`

#### Overrides

`Group.clone`

***

### copy()

> **copy**(`object`, `recursive?`): `this`

Defined in: [three.js/core/Object3D:copy](https://threejs.org/docs/#api/en/core/Object3D.copy)

Copies the given object into this object.

#### Parameters

##### object

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)

##### recursive?

`boolean`

If set to `true`, descendants of the object are copied next to the existing ones. If set to
`false`, descendants are left unchanged. Default is `true`.

#### Returns

`this`

#### Remarks

Event listeners and user-defined callbacks (.onAfterRender and .onBeforeRender) are not copied.

#### Inherited from

`Group.copy`

***

### dispatchEvent()

> **dispatchEvent**\<`T`\>(`event`): `void`

Defined in: [three.js/core/EventDispatcher:dispatchEvent](https://threejs.org/docs/#api/en/core/EventDispatcher.dispatchEvent)

Fire an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### event

[`BaseEvent`](https://threejs.org/docs/)\<`T`\> & [`Object3DEventMap`](https://threejs.org/docs/)\[`T`\]

The event that gets fired.

#### Returns

`void`

#### Inherited from

`Group.dispatchEvent`

***

### dispose()

> **dispose**(): `void`

Defined in: [packages/three-flatland/src/Flatland.ts:1396](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L1396)

Dispose of all resources.

#### Returns

`void`

***

### getObjectById()

> **getObjectById**(`id`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

Defined in: [three.js/core/Object3D:getObjectById](https://threejs.org/docs/#api/en/core/Object3D.getObjectById)

Searches through an object and its children, starting with the object itself, and returns the first with a matching id.

#### Parameters

##### id

`number`

Unique number of the object instance. Expects a `Integer`

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

#### Remarks

Note that ids are assigned in chronological order: 1, 2, 3, ..., incrementing by one for each new object.

#### See

id

#### Inherited from

`Group.getObjectById`

***

### getObjectByName()

> **getObjectByName**(`name`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

Defined in: [three.js/core/Object3D:getObjectByName](https://threejs.org/docs/#api/en/core/Object3D.getObjectByName)

Searches through an object and its children, starting with the object itself, and returns the first with a matching name.

#### Parameters

##### name

`string`

String to match to the children's Object3D.name property.

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

#### Remarks

Note that for most objects the name is an empty string by default
You will have to set it manually to make use of this method.

#### Inherited from

`Group.getObjectByName`

***

### getObjectByProperty()

> **getObjectByProperty**(`name`, `value`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

Defined in: [three.js/core/Object3D:getObjectByProperty](https://threejs.org/docs/#api/en/core/Object3D.getObjectByProperty)

Searches through an object and its children, starting with the object itself,
and returns the first with a property that matches the value given.

#### Parameters

##### name

`string`

the property name to search for.

##### value

`any`

value of the given property.

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

#### Inherited from

`Group.getObjectByProperty`

***

### getObjectsByProperty()

> **getObjectsByProperty**(`name`, `value`, `optionalTarget?`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

Defined in: [three.js/core/Object3D:getObjectsByProperty](https://threejs.org/docs/#api/en/core/Object3D.getObjectsByProperty)

Searches through an object and its children, starting with the object itself,
and returns the first with a property that matches the value given.

#### Parameters

##### name

`string`

The property name to search for.

##### value

`any`

Value of the given property.

##### optionalTarget?

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

target to set the result. Otherwise a new Array is instantiated. If set, you must clear
this array prior to each call (i.e., array.length = 0;).

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

#### Inherited from

`Group.getObjectsByProperty`

***

### getWorldDirection()

> **getWorldDirection**(`target`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:getWorldDirection](https://threejs.org/docs/#api/en/core/Object3D.getWorldDirection)

Returns a vector representing the direction of object's positive z-axis in world space.

#### Parameters

##### target

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

The result will be copied into this Vector3.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Group.getWorldDirection`

***

### getWorldPosition()

> **getWorldPosition**(`target`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:getWorldPosition](https://threejs.org/docs/#api/en/core/Object3D.getWorldPosition)

Returns a vector representing the position of the object in world space.

#### Parameters

##### target

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

The result will be copied into this Vector3.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Group.getWorldPosition`

***

### getWorldQuaternion()

> **getWorldQuaternion**(`target`): [`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

Defined in: [three.js/core/Object3D:getWorldQuaternion](https://threejs.org/docs/#api/en/core/Object3D.getWorldQuaternion)

Returns a quaternion representing the rotation of the object in world space.

#### Parameters

##### target

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

The result will be copied into this Quaternion.

#### Returns

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

#### Inherited from

`Group.getWorldQuaternion`

***

### getWorldScale()

> **getWorldScale**(`target`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:getWorldScale](https://threejs.org/docs/#api/en/core/Object3D.getWorldScale)

Returns a vector of the scaling factors applied to the object for each axis in world space.

#### Parameters

##### target

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

The result will be copied into this Vector3.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Group.getWorldScale`

***

### hasEventListener()

> **hasEventListener**\<`T`\>(`type`, `listener`): `boolean`

Defined in: [three.js/core/EventDispatcher:hasEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.hasEventListener)

Checks if listener is added to an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### type

`T`

The type of event to listen to.

##### listener

[`EventListener`](https://threejs.org/docs/)\<[`Object3DEventMap`](https://threejs.org/docs/)\[`T`\], `T`, `Flatland`\>

The function that gets called when the event is fired.

#### Returns

`boolean`

#### Inherited from

`Group.hasEventListener`

***

### localToWorld()

> **localToWorld**(`vector`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:localToWorld](https://threejs.org/docs/#api/en/core/Object3D.localToWorld)

Converts the vector from this object's local space to world space.

#### Parameters

##### vector

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A vector representing a position in this object's local space.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Group.localToWorld`

***

### lookAt()

#### Call Signature

> **lookAt**(`vector`): `void`

Defined in: [three.js/core/Object3D:lookAt](https://threejs.org/docs/#api/en/core/Object3D.lookAt)

Rotates the object to face a point in world space.

##### Parameters

###### vector

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A vector representing a position in world space to look at.

##### Returns

`void`

##### Remarks

This method does not support objects having non-uniformly-scaled parent(s).

##### Inherited from

`Group.lookAt`

#### Call Signature

> **lookAt**(`x`, `y`, `z`): `void`

Defined in: [three.js/core/Object3D:lookAt](https://threejs.org/docs/#api/en/core/Object3D.lookAt)

Rotates the object to face a point in world space.

##### Parameters

###### x

`number`

Expects a `Float`

###### y

`number`

Expects a `Float`

###### z

`number`

Expects a `Float`

##### Returns

`void`

##### Remarks

This method does not support objects having non-uniformly-scaled parent(s).

##### Inherited from

`Group.lookAt`

***

### onAfterRender()

> **onAfterRender**(`renderer`, `scene`, `camera`, `geometry`, `material`, `group`): `void`

Defined in: [three.js/core/Object3D:onAfterRender](https://threejs.org/docs/#api/en/core/Object3D.onAfterRender)

An optional callback that is executed immediately after a 3D object is rendered.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### material

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, geometry, material, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

`Group.onAfterRender`

***

### onAfterShadow()

> **onAfterShadow**(`renderer`, `scene`, `camera`, `shadowCamera`, `geometry`, `depthMaterial`, `group`): `void`

Defined in: [three.js/core/Object3D:onAfterShadow](https://threejs.org/docs/#api/en/core/Object3D.onAfterShadow)

An optional callback that is executed immediately after a 3D object is rendered to a shadow map.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### shadowCamera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### depthMaterial

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, shadowCamera, geometry,
depthMaterial, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

`Group.onAfterShadow`

***

### onBeforeRender()

> **onBeforeRender**(`renderer`, `scene`, `camera`, `geometry`, `material`, `group`): `void`

Defined in: [three.js/core/Object3D:onBeforeRender](https://threejs.org/docs/#api/en/core/Object3D.onBeforeRender)

An optional callback that is executed immediately before a 3D object is rendered.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### material

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, geometry, material, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

`Group.onBeforeRender`

***

### onBeforeShadow()

> **onBeforeShadow**(`renderer`, `scene`, `camera`, `shadowCamera`, `geometry`, `depthMaterial`, `group`): `void`

Defined in: [three.js/core/Object3D:onBeforeShadow](https://threejs.org/docs/#api/en/core/Object3D.onBeforeShadow)

An optional callback that is executed immediately before a 3D object is rendered to a shadow map.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### shadowCamera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### depthMaterial

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, shadowCamera, geometry,
depthMaterial, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

`Group.onBeforeShadow`

***

### raycast()

> **raycast**(`raycaster`, `intersects`): `void`

Defined in: [three.js/core/Object3D:raycast](https://threejs.org/docs/#api/en/core/Object3D.raycast)

Abstract (empty) method to get intersections between a casted ray and this object

#### Parameters

##### raycaster

[`Raycaster`](https://threejs.org/docs/#api/en/core/Raycaster)

##### intersects

[`Intersection`](https://threejs.org/docs/)\<[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>\>[]

#### Returns

`void`

#### Remarks

Subclasses such as THREE.Mesh \| Mesh, THREE.Line \| Line, and THREE.Points \| Points implement this method in order to use raycasting.

#### See

THREE.Raycaster \| Raycaster

#### Default Value

`() => {}`

#### Inherited from

`Group.raycast`

***

### remove()

> **remove**(...`objects`): `this`

Defined in: [packages/three-flatland/src/Flatland.ts:525](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L525)

Remove objects from Flatland.
This overrides Group.remove() to properly remove from internal scene/spriteGroup.

#### Parameters

##### objects

...[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

#### Returns

`this`

#### Overrides

`Group.remove`

***

### removeEventListener()

> **removeEventListener**\<`T`\>(`type`, `listener`): `void`

Defined in: [three.js/core/EventDispatcher:removeEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.removeEventListener)

Removes a listener from an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### type

`T`

The type of the listener that gets removed.

##### listener

[`EventListener`](https://threejs.org/docs/)\<[`Object3DEventMap`](https://threejs.org/docs/)\[`T`\], `T`, `Flatland`\>

The listener function that gets removed.

#### Returns

`void`

#### Inherited from

`Group.removeEventListener`

***

### removeFromParent()

> **removeFromParent**(): `this`

Defined in: [three.js/core/Object3D:removeFromParent](https://threejs.org/docs/#api/en/core/Object3D.removeFromParent)

Removes this object from its current parent.

#### Returns

`this`

#### Inherited from

`Group.removeFromParent`

***

### removePass()

> **removePass**(`passEffect`): `this`

Defined in: [packages/three-flatland/src/Flatland.ts:691](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L691)

Remove a post-processing pass from the pipeline.

#### Parameters

##### passEffect

[`PassEffect`](/three-flatland/api/three-flatland/src/classes/passeffect/)

The same PassEffect instance passed to addPass()

#### Returns

`this`

this (for chaining)

***

### render()

> **render**(`renderer`): `void`

Defined in: [packages/three-flatland/src/Flatland.ts:1181](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L1181)

Render Flatland.

#### Parameters

##### renderer

[`WebGPURenderer`](https://threejs.org/docs/)

#### Returns

`void`

***

### resize()

> **resize**(`width`, `height`): `void`

Defined in: [packages/three-flatland/src/Flatland.ts:1358](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L1358)

Resize the rendering area.

#### Parameters

##### width

`number`

##### height

`number`

#### Returns

`void`

***

### rotateOnAxis()

> **rotateOnAxis**(`axis`, `angle`): `this`

Defined in: [three.js/core/Object3D:rotateOnAxis](https://threejs.org/docs/#api/en/core/Object3D.rotateOnAxis)

Rotate an object along an axis in object space.

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in object space.

##### angle

`number`

The angle in radians. Expects a `Float`

#### Returns

`this`

#### Remarks

The axis is assumed to be normalized.

#### Inherited from

`Group.rotateOnAxis`

***

### rotateOnWorldAxis()

> **rotateOnWorldAxis**(`axis`, `angle`): `this`

Defined in: [three.js/core/Object3D:rotateOnWorldAxis](https://threejs.org/docs/#api/en/core/Object3D.rotateOnWorldAxis)

Rotate an object along an axis in world space.

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in world space.

##### angle

`number`

The angle in radians. Expects a `Float`

#### Returns

`this`

#### Remarks

The axis is assumed to be normalized
Method Assumes no rotated parent.

#### Inherited from

`Group.rotateOnWorldAxis`

***

### rotateX()

> **rotateX**(`angle`): `this`

Defined in: [three.js/core/Object3D:rotateX](https://threejs.org/docs/#api/en/core/Object3D.rotateX)

Rotates the object around _x_ axis in local space.

#### Parameters

##### angle

`number`

#### Returns

`this`

#### Inherited from

`Group.rotateX`

***

### rotateY()

> **rotateY**(`angle`): `this`

Defined in: [three.js/core/Object3D:rotateY](https://threejs.org/docs/#api/en/core/Object3D.rotateY)

Rotates the object around _y_ axis in local space.

#### Parameters

##### angle

`number`

#### Returns

`this`

#### Inherited from

`Group.rotateY`

***

### rotateZ()

> **rotateZ**(`angle`): `this`

Defined in: [three.js/core/Object3D:rotateZ](https://threejs.org/docs/#api/en/core/Object3D.rotateZ)

Rotates the object around _z_ axis in local space.

#### Parameters

##### angle

`number`

#### Returns

`this`

#### Inherited from

`Group.rotateZ`

***

### setLighting()

> **setLighting**(`lightEffect`): `this`

Defined in: [packages/three-flatland/src/Flatland.ts:785](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L785)

Set the lighting effect for this Flatland instance.
The LightEffect produces a ColorTransformFn that is applied to all lit sprites.

#### Parameters

##### lightEffect

[`LightEffect`](/three-flatland/api/three-flatland/src/classes/lighteffect/) \| `null`

LightEffect instance (or null to disable lighting)

#### Returns

`this`

this (for chaining)

#### Example

```typescript
import { DefaultLightEffect } from '@three-flatland/presets'

const lighting = new DefaultLightEffect()
flatland.setLighting(lighting)
lighting.ambientIntensity = 0.4  // zero-cost uniform update
```

***

### setRenderPipeline()

> **setRenderPipeline**(`renderPipeline`, `passNode`): `void`

Defined in: [packages/three-flatland/src/Flatland.ts:597](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L597)

Initialize the render pipeline with a given RenderPipeline instance.
Users should create the RenderPipeline and pass node themselves for flexibility.

#### Parameters

##### renderPipeline

[`RenderPipeline`](https://threejs.org/docs/)

##### passNode

[`PassNode`](https://threejs.org/docs/)

#### Returns

`void`

#### Example

```typescript
import { RenderPipeline, pass } from 'three/webgpu'
import { crtComplete } from 'three-flatland'

const pipeline = new RenderPipeline(renderer)
const scenePass = pass(flatland.scene, flatland.camera)
pipeline.outputNode = crtComplete(scenePass, uv(), { curvature: 0.1 })

flatland.setRenderPipeline(pipeline, scenePass)
```

***

### setRotationFromAxisAngle()

> **setRotationFromAxisAngle**(`axis`, `angle`): `void`

Defined in: [three.js/core/Object3D:setRotationFromAxisAngle](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromAxisAngle)

Calls THREE.Quaternion.setFromAxisAngle \| setFromAxisAngle(axis, angle) on the [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in object space.

##### angle

`number`

Angle in radians. Expects a `Float`

#### Returns

`void`

#### Inherited from

`Group.setRotationFromAxisAngle`

***

### setRotationFromEuler()

> **setRotationFromEuler**(`euler`): `void`

Defined in: [three.js/core/Object3D:setRotationFromEuler](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromEuler)

Calls THREE.Quaternion.setFromEuler \| setFromEuler(euler) on the [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### euler

[`Euler`](https://threejs.org/docs/#api/en/math/Euler)

Euler angle specifying rotation amount.

#### Returns

`void`

#### Inherited from

`Group.setRotationFromEuler`

***

### setRotationFromMatrix()

> **setRotationFromMatrix**(`m`): `void`

Defined in: [three.js/core/Object3D:setRotationFromMatrix](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromMatrix)

Calls THREE.Quaternion.setFromRotationMatrix \| setFromRotationMatrix(m) on the [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### m

[`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Rotate the quaternion by the rotation component of the matrix.

#### Returns

`void`

#### Remarks

Note that this assumes that the upper 3x3 of m is a pure rotation matrix (i.e, unscaled).

#### Inherited from

`Group.setRotationFromMatrix`

***

### setRotationFromQuaternion()

> **setRotationFromQuaternion**(`q`): `void`

Defined in: [three.js/core/Object3D:setRotationFromQuaternion](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromQuaternion)

Copy the given THREE.Quaternion \| Quaternion into [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### q

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

Normalized Quaternion.

#### Returns

`void`

#### Inherited from

`Group.setRotationFromQuaternion`

***

### toJSON()

> **toJSON**(`meta?`): [`Object3DJSON`](https://threejs.org/docs/)

Defined in: [three.js/core/Object3D:toJSON](https://threejs.org/docs/#api/en/core/Object3D.toJSON)

Convert the object to three.js [JSON Object/Scene format](https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4).

#### Parameters

##### meta?

[`JSONMeta`](https://threejs.org/docs/)

Object containing metadata such as materials, textures or images for the object.

#### Returns

[`Object3DJSON`](https://threejs.org/docs/)

#### Inherited from

`Group.toJSON`

***

### translateOnAxis()

> **translateOnAxis**(`axis`, `distance`): `this`

Defined in: [three.js/core/Object3D:translateOnAxis](https://threejs.org/docs/#api/en/core/Object3D.translateOnAxis)

Translate an object by distance along an axis in object space

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in object space.

##### distance

`number`

The distance to translate. Expects a `Float`

#### Returns

`this`

#### Remarks

The axis is assumed to be normalized.

#### Inherited from

`Group.translateOnAxis`

***

### translateX()

> **translateX**(`distance`): `this`

Defined in: [three.js/core/Object3D:translateX](https://threejs.org/docs/#api/en/core/Object3D.translateX)

Translates object along x axis in object space by distance units.

#### Parameters

##### distance

`number`

Expects a `Float`

#### Returns

`this`

#### Inherited from

`Group.translateX`

***

### translateY()

> **translateY**(`distance`): `this`

Defined in: [three.js/core/Object3D:translateY](https://threejs.org/docs/#api/en/core/Object3D.translateY)

Translates object along _y_ axis in object space by distance units.

#### Parameters

##### distance

`number`

Expects a `Float`

#### Returns

`this`

#### Inherited from

`Group.translateY`

***

### translateZ()

> **translateZ**(`distance`): `this`

Defined in: [three.js/core/Object3D:translateZ](https://threejs.org/docs/#api/en/core/Object3D.translateZ)

Translates object along _z_ axis in object space by distance units.

#### Parameters

##### distance

`number`

Expects a `Float`

#### Returns

`this`

#### Inherited from

`Group.translateZ`

***

### traverse()

> **traverse**(`callback`): `void`

Defined in: [three.js/core/Object3D:traverse](https://threejs.org/docs/#api/en/core/Object3D.traverse)

Executes the callback on this object and all descendants.

#### Parameters

##### callback

(`object`) => `any`

A function with as first argument an [Object3D](https://threejs.org/docs/#api/en/core/Object3D) object.

#### Returns

`void`

#### Remarks

Note: Modifying the scene graph inside the callback is discouraged.

#### Inherited from

`Group.traverse`

***

### traverseAncestors()

> **traverseAncestors**(`callback`): `void`

Defined in: [three.js/core/Object3D:traverseAncestors](https://threejs.org/docs/#api/en/core/Object3D.traverseAncestors)

Executes the callback on all ancestors.

#### Parameters

##### callback

(`object`) => `any`

A function with as first argument an [Object3D](https://threejs.org/docs/#api/en/core/Object3D) object.

#### Returns

`void`

#### Remarks

Note: Modifying the scene graph inside the callback is discouraged.

#### Inherited from

`Group.traverseAncestors`

***

### traverseVisible()

> **traverseVisible**(`callback`): `void`

Defined in: [three.js/core/Object3D:traverseVisible](https://threejs.org/docs/#api/en/core/Object3D.traverseVisible)

Like traverse, but the callback will only be executed for visible objects

#### Parameters

##### callback

(`object`) => `any`

A function with as first argument an [Object3D](https://threejs.org/docs/#api/en/core/Object3D) object.

#### Returns

`void`

#### Remarks

Descendants of invisible objects are not traversed.
Note: Modifying the scene graph inside the callback is discouraged.

#### Inherited from

`Group.traverseVisible`

***

### updateMatrix()

> **updateMatrix**(): `void`

Defined in: [three.js/core/Object3D:updateMatrix](https://threejs.org/docs/#api/en/core/Object3D.updateMatrix)

Updates local transform.

#### Returns

`void`

#### Inherited from

`Group.updateMatrix`

***

### updateMatrixWorld()

> **updateMatrixWorld**(`force?`): `void`

Defined in: [three.js/core/Object3D:updateMatrixWorld](https://threejs.org/docs/#api/en/core/Object3D.updateMatrixWorld)

Updates the global transform of the object.
And will update the object descendants if [.matrixWorldNeedsUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldneedsupdate) is set to true or if the force parameter is set to `true`.

#### Parameters

##### force?

`boolean`

A boolean that can be used to bypass [.matrixWorldAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldautoupdate), to recalculate the world matrix of the object and descendants on the current frame.
Useful if you cannot wait for the renderer to update it on the next frame, assuming [.matrixWorldAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldautoupdate) set to `true`.

#### Returns

`void`

#### Inherited from

`Group.updateMatrixWorld`

***

### updateWorldMatrix()

> **updateWorldMatrix**(`updateParents`, `updateChildren`): `void`

Defined in: [three.js/core/Object3D:updateWorldMatrix](https://threejs.org/docs/#api/en/core/Object3D.updateWorldMatrix)

Updates the global transform of the object.

#### Parameters

##### updateParents

`boolean`

Recursively updates global transform of ancestors.

##### updateChildren

`boolean`

Recursively updates global transform of descendants.

#### Returns

`void`

#### Inherited from

`Group.updateWorldMatrix`

***

### worldToLocal()

> **worldToLocal**(`vector`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:worldToLocal](https://threejs.org/docs/#api/en/core/Object3D.worldToLocal)

Converts the vector from world space to this object's local space.

#### Parameters

##### vector

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A vector representing a position in world space.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Group.worldToLocal`

# ForwardPlusLighting

Defined in: [packages/three-flatland/src/lights/ForwardPlusLighting.ts:123](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/ForwardPlusLighting.ts#L123)

Forward+ tiled light culler for 2D scenes.

Subdivides the screen into [TILE\_SIZE](/three-flatland/api/three-flatland/src/variables/tile_size/)-pixel tiles and assigns
each light to every tile its bounding box overlaps. Per-fragment
shading then iterates only the lights bound to its tile (capped at
[MAX\_LIGHTS\_PER\_TILE](/three-flatland/api/three-flatland/src/variables/max_lights_per_tile/)) instead of every light in the scene —
the cost flips from O(total_lights) to O(lights_per_tile).

Tile data is uploaded each frame via a single [DataTexture](https://threejs.org/docs/#api/en/textures/DataTexture)
(light indices + per-tile meta scalars). Sprite-friendly extras:

- **Reservoir eviction** — when a tile saturates, lower-scored lights
  lose slots to higher-scored newcomers, keeping the visible set
  close to the "would-be-brightest-K" ideal.
- **Per-category fill quotas** — `castsShadow: false` lights compete
  only within their own [Light2D.category](/three-flatland/api/three-flatland/src/classes/light2d/#category) bucket, so a
  thousand cosmetic slime glows can't drown out hero torches. Tunable
  per-bucket via [setFillQuota](/three-flatland/api/three-flatland/src/classes/forwardpluslighting/#setfillquota) / [getFillQuota](/three-flatland/api/three-flatland/src/classes/forwardpluslighting/#getfillquota) /
  [resetFillQuotas](/three-flatland/api/three-flatland/src/classes/forwardpluslighting/#resetfillquotas).
- **Importance bias** — [Light2D.importance](/three-flatland/api/three-flatland/src/classes/light2d/#importance) multiplies the
  tile-rank score, letting hero lights resist eviction.

Owned by DefaultLightEffect (and other tiled-Forward+ effects);
end users rarely instantiate this directly.

## Constructors

### Constructor

> **new ForwardPlusLighting**(): `ForwardPlusLighting`

Defined in: [packages/three-flatland/src/lights/ForwardPlusLighting.ts:186](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/ForwardPlusLighting.ts#L186)

#### Returns

`ForwardPlusLighting`

## Properties

### ambientNode

> `readonly` **ambientNode**: [`UniformNode`](https://threejs.org/docs/)\<`"vec3"`, [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)\>

Defined in: [packages/three-flatland/src/lights/ForwardPlusLighting.ts:184](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/ForwardPlusLighting.ts#L184)

***

### screenSizeNode

> `readonly` **screenSizeNode**: [`UniformNode`](https://threejs.org/docs/)\<`"vec2"`, [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)\>

Defined in: [packages/three-flatland/src/lights/ForwardPlusLighting.ts:181](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/ForwardPlusLighting.ts#L181)

***

### tileCountXNode

> `readonly` **tileCountXNode**: [`UniformNode`](https://threejs.org/docs/)\<`"float"`, `number`\>

Defined in: [packages/three-flatland/src/lights/ForwardPlusLighting.ts:180](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/ForwardPlusLighting.ts#L180)

***

### worldOffsetNode

> `readonly` **worldOffsetNode**: [`UniformNode`](https://threejs.org/docs/)\<`"vec2"`, [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)\>

Defined in: [packages/three-flatland/src/lights/ForwardPlusLighting.ts:183](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/ForwardPlusLighting.ts#L183)

***

### worldSizeNode

> `readonly` **worldSizeNode**: [`UniformNode`](https://threejs.org/docs/)\<`"vec2"`, [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)\>

Defined in: [packages/three-flatland/src/lights/ForwardPlusLighting.ts:182](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/ForwardPlusLighting.ts#L182)

## Accessors

### tileCountX

#### Get Signature

> **get** **tileCountX**(): `number`

Defined in: [packages/three-flatland/src/lights/ForwardPlusLighting.ts:211](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/ForwardPlusLighting.ts#L211)

##### Returns

`number`

***

### tileTexture

#### Get Signature

> **get** **tileTexture**(): [`DataTexture`](https://threejs.org/docs/#api/en/textures/DataTexture)

Defined in: [packages/three-flatland/src/lights/ForwardPlusLighting.ts:207](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/ForwardPlusLighting.ts#L207)

##### Returns

[`DataTexture`](https://threejs.org/docs/#api/en/textures/DataTexture)

## Methods

### createTileLookup()

> **createTileLookup**(): (`tileIndex`, `slotIndex`) => [`Node`](https://threejs.org/docs/)\<`"int"`\>

Defined in: [packages/three-flatland/src/lights/ForwardPlusLighting.ts:607](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/ForwardPlusLighting.ts#L607)

#### Returns

(`tileIndex`, `slotIndex`) => [`Node`](https://threejs.org/docs/)\<`"int"`\>

***

### dispose()

> **dispose**(): `void`

Defined in: [packages/three-flatland/src/lights/ForwardPlusLighting.ts:625](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/ForwardPlusLighting.ts#L625)

#### Returns

`void`

***

### getFillQuota()

> **getFillQuota**(`category`): `number`

Defined in: [packages/three-flatland/src/lights/ForwardPlusLighting.ts:323](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/ForwardPlusLighting.ts#L323)

Read the per-tile quota currently configured for a fill-light
category. Mirrors [setFillQuota](/three-flatland/api/three-flatland/src/classes/forwardpluslighting/#setfillquota) — accepts either a string
(hashed) or a raw bucket index.

#### Parameters

##### category

`string` \| `number`

#### Returns

`number`

***

### init()

> **init**(`screenWidth`, `screenHeight`): `void`

Defined in: [packages/three-flatland/src/lights/ForwardPlusLighting.ts:215](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/ForwardPlusLighting.ts#L215)

#### Parameters

##### screenWidth

`number`

##### screenHeight

`number`

#### Returns

`void`

***

### resetFillQuotas()

> **resetFillQuotas**(): `void`

Defined in: [packages/three-flatland/src/lights/ForwardPlusLighting.ts:314](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/ForwardPlusLighting.ts#L314)

Reset every per-bucket fill quota back to the default
(`MAX_FILL_LIGHTS_PER_TILE`). Used by the declarative
`categoryQuotas` prop on light effects so that removing a key
from the prop record actually clears that bucket's override
(otherwise stale per-bucket values would linger across
re-renders).

#### Returns

`void`

***

### resize()

> **resize**(`screenWidth`, `screenHeight`): `void`

Defined in: [packages/three-flatland/src/lights/ForwardPlusLighting.ts:260](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/ForwardPlusLighting.ts#L260)

#### Parameters

##### screenWidth

`number`

##### screenHeight

`number`

#### Returns

`void`

***

### setFillQuota()

> **setFillQuota**(`category`, `quota`): `void`

Defined in: [packages/three-flatland/src/lights/ForwardPlusLighting.ts:298](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/ForwardPlusLighting.ts#L298)

Set the per-tile quota for a fill-light category. Lights in this
bucket will be capped at `quota` concurrent slots per tile; the
`(quota + 1)`-th and later in-range fills lose to score-based
eviction (or get rejected if the tile is otherwise full).

Raising a quota lets more fills of that type contribute exact
lighting in dense clusters at the cost of more shader-loop
iterations per fragment in saturated tiles. Lowering tightens
the cap (cheaper, dimmer dense areas). Setting to 0 disables
fills in that bucket entirely.

#### Parameters

##### category

`string` \| `number`

Either a category string (hashed via the same
  djb2 used by `Light2D.category`) or a raw bucket index 0..3.

##### quota

`number`

Slots per tile, clamped to `[0, MAX_LIGHTS_PER_TILE]`.

#### Returns

`void`

#### Example

```typescript
forwardPlus.setFillQuota('slime', 4) // up to 4 slime fills per tile
forwardPlus.setFillQuota('water', 0) // disable water fills entirely
```

***

### setWorldBounds()

> **setWorldBounds**(`worldSize`, `worldOffset`): `void`

Defined in: [packages/three-flatland/src/lights/ForwardPlusLighting.ts:269](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/ForwardPlusLighting.ts#L269)

#### Parameters

##### worldSize

[`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

##### worldOffset

[`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

#### Returns

`void`

***

### update()

> **update**(`lights`, `maxLights?`): `void`

Defined in: [packages/three-flatland/src/lights/ForwardPlusLighting.ts:330](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/ForwardPlusLighting.ts#L330)

#### Parameters

##### lights

[`Light2D`](/three-flatland/api/three-flatland/src/classes/light2d/)[]

##### maxLights?

`number` = `lights.length`

#### Returns

`void`

# GlobalUniforms

Defined in: [packages/three-flatland/src/GlobalUniforms.ts:30](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/GlobalUniforms.ts#L30)

Global uniforms shared across all sprite materials in a Flatland instance.

These uniforms are set once per frame and shared by all sprites.
They avoid per-sprite duplication and never cause shader recompilation.

## Example

```typescript
// Flatland creates and owns the global uniforms
const globals = flatland.globals

// Access TSL nodes in custom colorTransform
const material = new Sprite2DMaterial({
  colorTransform: (ctx) => {
    const tinted = ctx.color.rgb.mul(globals.globalTintNode)
    return tinted.toVec4(ctx.color.a)
  }
})

// Each frame, Flatland updates the values
// (or set them directly for manual control)
globals.time = performance.now() / 1000
globals.globalTint = new Color(0.8, 0.9, 1.0) // moonlight
```

## Constructors

### Constructor

> **new GlobalUniforms**(): `GlobalUniforms`

Defined in: [packages/three-flatland/src/GlobalUniforms.ts:82](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/GlobalUniforms.ts#L82)

#### Returns

`GlobalUniforms`

## Properties

### fogColorNode

> `readonly` **fogColorNode**: [`UniformNode`](https://threejs.org/docs/)\<`"color"`, [`Color`](https://threejs.org/docs/#api/en/math/Color)\>

Defined in: [packages/three-flatland/src/GlobalUniforms.ts:78](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/GlobalUniforms.ts#L78)

Fog color uniform node (vec3/color)

***

### fogRangeNode

> `readonly` **fogRangeNode**: [`UniformNode`](https://threejs.org/docs/)\<`"vec2"`, [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)\>

Defined in: [packages/three-flatland/src/GlobalUniforms.ts:80](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/GlobalUniforms.ts#L80)

Fog range uniform node (vec2 — near, far)

***

### globalTintNode

> `readonly` **globalTintNode**: [`UniformNode`](https://threejs.org/docs/)\<`"color"`, [`Color`](https://threejs.org/docs/#api/en/math/Color)\>

Defined in: [packages/three-flatland/src/GlobalUniforms.ts:70](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/GlobalUniforms.ts#L70)

Global tint uniform node (vec3/color)

***

### pixelRatioNode

> `readonly` **pixelRatioNode**: [`UniformNode`](https://threejs.org/docs/)\<`"float"`, `number`\>

Defined in: [packages/three-flatland/src/GlobalUniforms.ts:74](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/GlobalUniforms.ts#L74)

Pixel ratio uniform node (float)

***

### timeNode

> `readonly` **timeNode**: [`UniformNode`](https://threejs.org/docs/)\<`"float"`, `number`\>

Defined in: [packages/three-flatland/src/GlobalUniforms.ts:68](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/GlobalUniforms.ts#L68)

Time uniform node (float)

***

### viewportSizeNode

> `readonly` **viewportSizeNode**: [`UniformNode`](https://threejs.org/docs/)\<`"vec2"`, [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)\>

Defined in: [packages/three-flatland/src/GlobalUniforms.ts:72](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/GlobalUniforms.ts#L72)

Viewport size uniform node (vec2)

***

### windNode

> `readonly` **windNode**: [`UniformNode`](https://threejs.org/docs/)\<`"vec2"`, [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)\>

Defined in: [packages/three-flatland/src/GlobalUniforms.ts:76](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/GlobalUniforms.ts#L76)

Wind uniform node (vec2 — direction * strength)

## Accessors

### effectiveTime

#### Get Signature

> **get** **effectiveTime**(): `number`

Defined in: [packages/three-flatland/src/GlobalUniforms.ts:117](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/GlobalUniforms.ts#L117)

Get the current effective time value (what the shader sees).

##### Returns

`number`

***

### fogColor

#### Get Signature

> **get** **fogColor**(): [`Color`](https://threejs.org/docs/#api/en/math/Color)

Defined in: [packages/three-flatland/src/GlobalUniforms.ts:167](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/GlobalUniforms.ts#L167)

##### Returns

[`Color`](https://threejs.org/docs/#api/en/math/Color)

#### Set Signature

> **set** **fogColor**(`value`): `void`

Defined in: [packages/three-flatland/src/GlobalUniforms.ts:171](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/GlobalUniforms.ts#L171)

##### Parameters

###### value

[`Color`](https://threejs.org/docs/#api/en/math/Color)

##### Returns

`void`

***

### fogRange

#### Get Signature

> **get** **fogRange**(): [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

Defined in: [packages/three-flatland/src/GlobalUniforms.ts:175](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/GlobalUniforms.ts#L175)

##### Returns

[`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

#### Set Signature

> **set** **fogRange**(`value`): `void`

Defined in: [packages/three-flatland/src/GlobalUniforms.ts:179](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/GlobalUniforms.ts#L179)

##### Parameters

###### value

[`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

##### Returns

`void`

***

### globalTint

#### Get Signature

> **get** **globalTint**(): [`Color`](https://threejs.org/docs/#api/en/math/Color)

Defined in: [packages/three-flatland/src/GlobalUniforms.ts:134](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/GlobalUniforms.ts#L134)

##### Returns

[`Color`](https://threejs.org/docs/#api/en/math/Color)

#### Set Signature

> **set** **globalTint**(`value`): `void`

Defined in: [packages/three-flatland/src/GlobalUniforms.ts:138](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/GlobalUniforms.ts#L138)

##### Parameters

###### value

[`Color`](https://threejs.org/docs/#api/en/math/Color)

##### Returns

`void`

***

### pixelRatio

#### Get Signature

> **get** **pixelRatio**(): `number`

Defined in: [packages/three-flatland/src/GlobalUniforms.ts:150](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/GlobalUniforms.ts#L150)

##### Returns

`number`

#### Set Signature

> **set** **pixelRatio**(`value`): `void`

Defined in: [packages/three-flatland/src/GlobalUniforms.ts:154](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/GlobalUniforms.ts#L154)

##### Parameters

###### value

`number`

##### Returns

`void`

***

### time

#### Get Signature

> **get** **time**(): `number` \| `undefined`

Defined in: [packages/three-flatland/src/GlobalUniforms.ts:103](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/GlobalUniforms.ts#L103)

Get/set time.
- `undefined` = auto mode (accumulates elapsed time via updateTime())
- `number` = manual mode (exact value used for shader time)

Setting back to `undefined` resumes auto-accumulation from where it left off.

##### Returns

`number` \| `undefined`

#### Set Signature

> **set** **time**(`value`): `void`

Defined in: [packages/three-flatland/src/GlobalUniforms.ts:107](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/GlobalUniforms.ts#L107)

##### Parameters

###### value

`number` \| `undefined`

##### Returns

`void`

***

### viewportSize

#### Get Signature

> **get** **viewportSize**(): [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

Defined in: [packages/three-flatland/src/GlobalUniforms.ts:142](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/GlobalUniforms.ts#L142)

##### Returns

[`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

#### Set Signature

> **set** **viewportSize**(`value`): `void`

Defined in: [packages/three-flatland/src/GlobalUniforms.ts:146](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/GlobalUniforms.ts#L146)

##### Parameters

###### value

[`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

##### Returns

`void`

***

### wind

#### Get Signature

> **get** **wind**(): [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

Defined in: [packages/three-flatland/src/GlobalUniforms.ts:159](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/GlobalUniforms.ts#L159)

##### Returns

[`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

#### Set Signature

> **set** **wind**(`value`): `void`

Defined in: [packages/three-flatland/src/GlobalUniforms.ts:163](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/GlobalUniforms.ts#L163)

##### Parameters

###### value

[`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

##### Returns

`void`

## Methods

### updateTime()

> **updateTime**(`delta`): `void`

Defined in: [packages/three-flatland/src/GlobalUniforms.ts:127](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/GlobalUniforms.ts#L127)

Advance auto-time by delta seconds.
Called by Flatland each frame. In auto mode, this accumulates
and updates the time node. In manual mode, this is a no-op
(the manual value is already set via the setter).

#### Parameters

##### delta

`number`

#### Returns

`void`

# Layer

Defined in: [packages/three-flatland/src/pipeline/LayerManager.ts:8](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/LayerManager.ts#L8)

A managed layer containing sprites.

## Constructors

### Constructor

> **new Layer**(`config`): `Layer`

Defined in: [packages/three-flatland/src/pipeline/LayerManager.ts:44](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/LayerManager.ts#L44)

#### Parameters

##### config

[`LayerConfig`](/three-flatland/api/three-flatland/src/interfaces/layerconfig/)

#### Returns

`Layer`

## Properties

### blendMode

> **blendMode**: [`BlendMode`](/three-flatland/api/three-flatland/src/type-aliases/blendmode/)

Defined in: [packages/three-flatland/src/pipeline/LayerManager.ts:27](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/LayerManager.ts#L27)

Blend mode for this layer.

***

### name

> `readonly` **name**: `string`

Defined in: [packages/three-flatland/src/pipeline/LayerManager.ts:12](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/LayerManager.ts#L12)

Layer name.

***

### onVisibilityChange?

> `optional` **onVisibilityChange?**: (`visible`) => `void`

Defined in: [packages/three-flatland/src/pipeline/LayerManager.ts:42](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/LayerManager.ts#L42)

Callback when visibility changes.

#### Parameters

##### visible

`boolean`

#### Returns

`void`

***

### sortMode

> **sortMode**: [`SortMode`](/three-flatland/api/three-flatland/src/type-aliases/sortmode/)

Defined in: [packages/three-flatland/src/pipeline/LayerManager.ts:32](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/LayerManager.ts#L32)

Sort mode for sprites in this layer.

***

### value

> `readonly` **value**: `number`

Defined in: [packages/three-flatland/src/pipeline/LayerManager.ts:17](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/LayerManager.ts#L17)

Layer value (render order).

## Accessors

### count

#### Get Signature

> **get** **count**(): `number`

Defined in: [packages/three-flatland/src/pipeline/LayerManager.ts:62](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/LayerManager.ts#L62)

Get sprite count.

##### Returns

`number`

***

### sprites

#### Get Signature

> **get** **sprites**(): `ReadonlySet`\<[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/)\>

Defined in: [packages/three-flatland/src/pipeline/LayerManager.ts:55](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/LayerManager.ts#L55)

Get sprites in this layer.

##### Returns

`ReadonlySet`\<[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/)\>

***

### visible

#### Get Signature

> **get** **visible**(): `boolean`

Defined in: [packages/three-flatland/src/pipeline/LayerManager.ts:69](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/LayerManager.ts#L69)

Get visibility.

##### Returns

`boolean`

#### Set Signature

> **set** **visible**(`value`): `void`

Defined in: [packages/three-flatland/src/pipeline/LayerManager.ts:76](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/LayerManager.ts#L76)

Set visibility.

##### Parameters

###### value

`boolean`

##### Returns

`void`

## Methods

### \[iterator\]()

> **\[iterator\]**(): `Iterator`\<[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/)\>

Defined in: [packages/three-flatland/src/pipeline/LayerManager.ts:121](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/LayerManager.ts#L121)

Iterate over sprites in this layer.

#### Returns

`Iterator`\<[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/)\>

***

### add()

> **add**(`sprite`): `void`

Defined in: [packages/three-flatland/src/pipeline/LayerManager.ts:91](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/LayerManager.ts#L91)

Add a sprite to this layer.

#### Parameters

##### sprite

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/)

#### Returns

`void`

***

### clear()

> **clear**(): `void`

Defined in: [packages/three-flatland/src/pipeline/LayerManager.ts:114](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/LayerManager.ts#L114)

Clear all sprites from this layer.

#### Returns

`void`

***

### has()

> **has**(`sprite`): `boolean`

Defined in: [packages/three-flatland/src/pipeline/LayerManager.ts:107](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/LayerManager.ts#L107)

Check if layer contains a sprite.

#### Parameters

##### sprite

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/)

#### Returns

`boolean`

***

### remove()

> **remove**(`sprite`): `void`

Defined in: [packages/three-flatland/src/pipeline/LayerManager.ts:100](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/LayerManager.ts#L100)

Remove a sprite from this layer.

#### Parameters

##### sprite

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/)

#### Returns

`void`

# LDtkLoader

Defined in: [packages/three-flatland/src/loaders/LDtkLoader.ts:204](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/LDtkLoader.ts#L204)

Loader for LDtk JSON format.

Extends Three.js's Loader class for compatibility with R3F's useLoader.
Supports:
- Single level or multi-level projects
- Tile layers (Tiles, AutoLayer, IntGrid)
- Entity layers
- IntGrid collision data
- Tile flip flags
- Custom field data

## Example

```typescript
// Three.js usage - static API
const mapData = await LDtkLoader.load('/maps/world.ldtk', 'Level_0')

// Override for this load
const mapData = await LDtkLoader.load('/maps/world.ldtk', 'Level_0', { texture: 'smooth' })

// R3F usage - works with useLoader (loads first level)
import { LDtkLoader } from 'three-flatland/react';
const mapData = useLoader(LDtkLoader, '/maps/world.ldtk');

// Override preset via extension
const mapData = useLoader(LDtkLoader, '/maps/world.ldtk', (loader) => {
  loader.preset = 'smooth';
  loader.levelId = 'Level_1';  // Specify level to load
});

// Set loader-level default
LDtkLoader.options = 'pixel-art'
```

## Extends

- [`Loader`](https://threejs.org/docs/#api/en/loaders/Loader)\<[`TileMapData`](/three-flatland/api/three-flatland/src/interfaces/tilemapdata/)\>

## Constructors

### Constructor

> **new LDtkLoader**(`manager?`): `LDtkLoader`

Defined in: [three.js/loaders/Loader:LDtkLoader](https://threejs.org/docs/#api/en/loaders/Loader.LDtkLoader)

#### Parameters

##### manager?

[`LoadingManager`](https://threejs.org/docs/)

#### Returns

`LDtkLoader`

#### Inherited from

`Loader<TileMapData>.constructor`

## Properties

### crossOrigin

> **crossOrigin**: `string`

Defined in: [three.js/loaders/Loader:crossOrigin](https://threejs.org/docs/#api/en/loaders/Loader.crossOrigin)

#### Default

```ts
'anonymous'
```

#### Inherited from

`Loader.crossOrigin`

***

### forceRuntime

> **forceRuntime**: `boolean` = `false`

Defined in: [packages/three-flatland/src/loaders/LDtkLoader.ts:244](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/LDtkLoader.ts#L244)

Generate this tilemap's tileset normal maps in the browser on
every load instead of loading pre-baked sidecars. The in-memory
bake runs on every load; sidecar probes and "no baked sibling"
warns are skipped. Not a dev-iteration knob.
See [BakedAssetLoaderOptions.forceRuntime](/three-flatland/api/three-flatland/src/interfaces/spritesheetloaderoptions/#forceruntime).

***

### levelId

> **levelId**: `string` \| `number` \| `undefined` = `undefined`

Defined in: [packages/three-flatland/src/loaders/LDtkLoader.ts:230](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/LDtkLoader.ts#L230)

Level ID to load (for R3F useLoader).
If undefined, loads the first level.

#### Example

```tsx
const mapData = useLoader(LDtkLoader, '/maps/world.ldtk', (loader) => {
  loader.levelId = 'Level_1';
});
```

***

### manager

> **manager**: [`LoadingManager`](https://threejs.org/docs/)

Defined in: [three.js/loaders/Loader:manager](https://threejs.org/docs/#api/en/loaders/Loader.manager)

#### Inherited from

`Loader.manager`

***

### normals

> **normals**: `LDtkNormalsOption` = `false`

Defined in: [packages/three-flatland/src/loaders/LDtkLoader.ts:235](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/LDtkLoader.ts#L235)

Normal-map generation. See [LDtkLoaderOptions.normals](/three-flatland/api/three-flatland/src/interfaces/ldtkloaderoptions/#normals).

***

### path

> **path**: `string`

Defined in: [three.js/loaders/Loader:path](https://threejs.org/docs/#api/en/loaders/Loader.path)

#### Default

```ts
''
```

#### Inherited from

`Loader.path`

***

### preset

> **preset**: [`TexturePreset`](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/) \| [`TextureOptions`](/three-flatland/api/three-flatland/src/interfaces/textureoptions/) \| `undefined` = `undefined`

Defined in: [packages/three-flatland/src/loaders/LDtkLoader.ts:217](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/LDtkLoader.ts#L217)

Instance-level preset override.
Set via R3F's useLoader extension callback.

***

### requestHeader

> **requestHeader**: `object`

Defined in: [three.js/loaders/Loader:requestHeader](https://threejs.org/docs/#api/en/loaders/Loader.requestHeader)

#### Index Signature

\[`header`: `string`\]: `string`

#### Default

```ts
{}
```

#### Inherited from

`Loader.requestHeader`

***

### resourcePath

> **resourcePath**: `string`

Defined in: [three.js/loaders/Loader:resourcePath](https://threejs.org/docs/#api/en/loaders/Loader.resourcePath)

#### Default

```ts
''
```

#### Inherited from

`Loader.resourcePath`

***

### withCredentials

> **withCredentials**: `boolean`

Defined in: [three.js/loaders/Loader:withCredentials](https://threejs.org/docs/#api/en/loaders/Loader.withCredentials)

#### Default

```ts
false
```

#### Inherited from

`Loader.withCredentials`

***

### DEFAULT\_MATERIAL\_NAME

> `static` **DEFAULT\_MATERIAL\_NAME**: `string`

Defined in: [three.js/loaders/Loader:DEFAULT_MATERIAL_NAME](https://threejs.org/docs/#api/en/loaders/Loader.DEFAULT_MATERIAL_NAME)

#### Inherited from

`Loader.DEFAULT_MATERIAL_NAME`

***

### options

> `static` **options**: [`TexturePreset`](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/) \| [`TextureOptions`](/three-flatland/api/three-flatland/src/interfaces/textureoptions/) \| `undefined` = `undefined`

Defined in: [packages/three-flatland/src/loaders/LDtkLoader.ts:211](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/LDtkLoader.ts#L211)

Texture options for this loader class.
When undefined, falls through to TextureConfig.options.

## Methods

### abort()

> **abort**(): `this`

Defined in: [three.js/loaders/Loader:abort](https://threejs.org/docs/#api/en/loaders/Loader.abort)

#### Returns

`this`

#### Inherited from

`Loader.abort`

***

### load()

> **load**(`url`, `onLoad`, `onProgress?`, `onError?`): `void`

Defined in: [three.js/loaders/Loader:load](https://threejs.org/docs/#api/en/loaders/Loader.load)

#### Parameters

##### url

`string`

##### onLoad

(`data`) => `void`

##### onProgress?

(`event`) => `void`

##### onError?

(`err`) => `void`

#### Returns

`void`

#### Inherited from

`Loader.load`

***

### loadAsync()

> **loadAsync**(`url`): `Promise`\<[`TileMapData`](/three-flatland/api/three-flatland/src/interfaces/tilemapdata/)\>

Defined in: [packages/three-flatland/src/loaders/LDtkLoader.ts:250](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/LDtkLoader.ts#L250)

Load an LDtk level asynchronously (for R3F useLoader compatibility).
Presets and levelId are automatically applied from instance properties.

#### Parameters

##### url

`string`

#### Returns

`Promise`\<[`TileMapData`](/three-flatland/api/three-flatland/src/interfaces/tilemapdata/)\>

#### Overrides

`Loader.loadAsync`

***

### setCrossOrigin()

> **setCrossOrigin**(`crossOrigin`): `this`

Defined in: [three.js/loaders/Loader:setCrossOrigin](https://threejs.org/docs/#api/en/loaders/Loader.setCrossOrigin)

#### Parameters

##### crossOrigin

`string`

#### Returns

`this`

#### Inherited from

`Loader.setCrossOrigin`

***

### setPath()

> **setPath**(`path`): `this`

Defined in: [three.js/loaders/Loader:setPath](https://threejs.org/docs/#api/en/loaders/Loader.setPath)

#### Parameters

##### path

`string`

#### Returns

`this`

#### Inherited from

`Loader.setPath`

***

### setRequestHeader()

> **setRequestHeader**(`requestHeader`): `this`

Defined in: [three.js/loaders/Loader:setRequestHeader](https://threejs.org/docs/#api/en/loaders/Loader.setRequestHeader)

#### Parameters

##### requestHeader

#### Returns

`this`

#### Inherited from

`Loader.setRequestHeader`

***

### setResourcePath()

> **setResourcePath**(`resourcePath`): `this`

Defined in: [three.js/loaders/Loader:setResourcePath](https://threejs.org/docs/#api/en/loaders/Loader.setResourcePath)

#### Parameters

##### resourcePath

`string`

#### Returns

`this`

#### Inherited from

`Loader.setResourcePath`

***

### setWithCredentials()

> **setWithCredentials**(`value`): `this`

Defined in: [three.js/loaders/Loader:setWithCredentials](https://threejs.org/docs/#api/en/loaders/Loader.setWithCredentials)

#### Parameters

##### value

`boolean`

#### Returns

`this`

#### Inherited from

`Loader.setWithCredentials`

***

### clearCache()

> `static` **clearCache**(): `void`

Defined in: [packages/three-flatland/src/loaders/LDtkLoader.ts:739](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/LDtkLoader.ts#L739)

Clear the cache.

#### Returns

`void`

***

### getLevelIds()

> `static` **getLevelIds**(`url`): `Promise`\<`string`[]\>

Defined in: [packages/three-flatland/src/loaders/LDtkLoader.ts:731](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/LDtkLoader.ts#L731)

Get all level identifiers from a project.

#### Parameters

##### url

`string`

#### Returns

`Promise`\<`string`[]\>

***

### load()

> `static` **load**(`url`, `levelId?`, `options?`): `Promise`\<[`TileMapData`](/three-flatland/api/three-flatland/src/interfaces/tilemapdata/)\>

Defined in: [packages/three-flatland/src/loaders/LDtkLoader.ts:266](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/LDtkLoader.ts#L266)

Load a single level from an LDtk project (static method for Three.js usage).

#### Parameters

##### url

`string`

##### levelId?

`string` \| `number`

##### options?

[`LDtkLoaderOptions`](/three-flatland/api/three-flatland/src/interfaces/ldtkloaderoptions/)

#### Returns

`Promise`\<[`TileMapData`](/three-flatland/api/three-flatland/src/interfaces/tilemapdata/)\>

***

### loadProject()

> `static` **loadProject**(`url`): `Promise`\<`LDtkProject`\>

Defined in: [packages/three-flatland/src/loaders/LDtkLoader.ts:298](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/LDtkLoader.ts#L298)

Load the LDtk project file.

#### Parameters

##### url

`string`

#### Returns

`Promise`\<`LDtkProject`\>

# Light2D

Defined in: [packages/three-flatland/src/lights/Light2D.ts:115](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L115)

2D Light for use with Flatland.

Light2D is a scene graph object that can be added to Flatland
and automatically collected for use in sprite lighting.

## Example

```typescript
// Point light (torch, lamp)
const torch = new Light2D({
  type: 'point',
  position: [100, 100],
  color: 'orange',
  intensity: 1.5,
  distance: 200,
})
flatland.add(torch)

// Directional light (sun)
const sun = new Light2D({
  type: 'directional',
  direction: [1, -1],
  color: 0xffffcc,
  intensity: 0.8,
})
flatland.add(sun)

// Ambient light (base illumination)
const ambient = new Light2D({
  type: 'ambient',
  color: 0x222233,
  intensity: 0.3,
})
flatland.add(ambient)
```

## Extends

- [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)

## Constructors

### Constructor

> **new Light2D**(`options?`): `Light2D`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:202](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L202)

#### Parameters

##### options?

[`Light2DOptions`](/three-flatland/api/three-flatland/src/interfaces/light2doptions/) = `{}`

#### Returns

`Light2D`

#### Overrides

`Object3D.constructor`

## Properties

### angle

> **angle**: `number`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:151](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L151)

Cone angle for spot lights (radians).

***

### animations

> **animations**: [`AnimationClip`](https://threejs.org/docs/)[]

Defined in: [three.js/core/Object3D:animations](https://threejs.org/docs/#api/en/core/Object3D.animations)

Array with object's animation clips.

#### Default Value

`[]`

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`animations`](/three-flatland/api/three-flatland/src/classes/flatland/#animations)

***

### castShadow

> **castShadow**: `boolean`

Defined in: [three.js/core/Object3D:castShadow](https://threejs.org/docs/#api/en/core/Object3D.castShadow)

Whether the object gets rendered into shadow map.

#### Default Value

`false`

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`castShadow`](/three-flatland/api/three-flatland/src/classes/flatland/#castshadow)

***

### castsShadow

> **castsShadow**: `boolean` = `true`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:176](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L176)

Whether this light casts shadows. When false, the shader skips the
SDF shadow trace for this light — useful for cosmetic/atmospheric
lights (slime glows, ambient fills) that don't need occlusion.

Currently only respected by `DefaultLightEffect`.

***

### children

> **children**: [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

Defined in: [three.js/core/Object3D:children](https://threejs.org/docs/#api/en/core/Object3D.children)

Array with object's children.

#### See

THREE.Object3DGroup \| Group for info on manually grouping objects.

#### Default Value

`[]`

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`children`](/three-flatland/api/three-flatland/src/classes/flatland/#children)

***

### count?

> `optional` **count?**: `number`

Defined in: [three.js/renderers/common/Backend:count](https://threejs.org/docs/#api/en/renderers/common/Backend.count)

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`count`](/three-flatland/api/three-flatland/src/classes/flatland/#count)

***

### customDepthMaterial?

> `optional` **customDepthMaterial?**: [`Material`](https://threejs.org/docs/#api/en/materials/Material)

Defined in: [three.js/core/Object3D:customDepthMaterial](https://threejs.org/docs/#api/en/core/Object3D.customDepthMaterial)

Custom depth material to be used when rendering to the depth map.

#### Remarks

Can only be used in context of meshes.
When shadow-casting with a THREE.DirectionalLight \| DirectionalLight or THREE.SpotLight \| SpotLight,
if you are modifying vertex positions in the vertex shader you must specify a customDepthMaterial for proper shadows.

#### Default Value

`undefined`

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`customDepthMaterial`](/three-flatland/api/three-flatland/src/classes/flatland/#customdepthmaterial)

***

### customDistanceMaterial?

> `optional` **customDistanceMaterial?**: [`Material`](https://threejs.org/docs/#api/en/materials/Material)

Defined in: [three.js/core/Object3D:customDistanceMaterial](https://threejs.org/docs/#api/en/core/Object3D.customDistanceMaterial)

Same as [customDepthMaterial](/three-flatland/api/three-flatland/src/classes/flatland/#customdepthmaterial), but used with THREE.Object3DPointLight \| PointLight.

#### Default Value

`undefined`

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`customDistanceMaterial`](/three-flatland/api/three-flatland/src/classes/flatland/#customdistancematerial)

***

### decay

> **decay**: `number`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:162](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L162)

Decay exponent controlling attenuation curve shape.
1 = linear, 2 = quadratic (default), higher = sharper center.

***

### distance

> **distance**: `number`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:146](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L146)

Maximum light distance for point/spot lights.
0 = no cutoff (infinite range). The lighting system will
determine an effective max distance for culling purposes.

***

### enabled

> **enabled**: `boolean` = `true`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:167](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L167)

Whether this light is enabled.

***

### frustumCulled

> **frustumCulled**: `boolean`

Defined in: [three.js/core/Object3D:frustumCulled](https://threejs.org/docs/#api/en/core/Object3D.frustumCulled)

When this is set, it checks every frame if the object is in the frustum of the camera before rendering the object.
If set to `false` the object gets rendered every frame even if it is not in the frustum of the camera.

#### Default Value

`true`

#### Inherited from

`Object3D.frustumCulled`

***

### id

> `readonly` **id**: `number`

Defined in: [three.js/core/Object3D:id](https://threejs.org/docs/#api/en/core/Object3D.id)

Unique number for this [Object3D](https://threejs.org/docs/#api/en/core/Object3D) instance.

#### Remarks

Note that ids are assigned in chronological order: 1, 2, 3, ..., incrementing by one for each new object.
Expects a `Integer`

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`id`](/three-flatland/api/three-flatland/src/classes/flatland/#id)

***

### importance

> **importance**: `number` = `1`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:183](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L183)

Multiplicative bias applied to this light's tile-ranking score
during Forward+ tile assignment. See [Light2DOptions.importance](/three-flatland/api/three-flatland/src/interfaces/light2doptions/#importance)
for full semantics. Default `1.0` — neutral.

***

### intensity

> **intensity**: `number`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:134](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L134)

Light intensity.

***

### isObject3D

> `readonly` **isObject3D**: `true`

Defined in: [three.js/core/Object3D:isObject3D](https://threejs.org/docs/#api/en/core/Object3D.isObject3D)

Flag to check if a given object is of type [Object3D](https://threejs.org/docs/#api/en/core/Object3D).

#### Remarks

This is a _constant_ value

#### Default Value

`true`

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`isObject3D`](/three-flatland/api/three-flatland/src/classes/flatland/#isobject3d)

***

### layers

> **layers**: [`Layers`](https://threejs.org/docs/#api/en/core/Layers)

Defined in: [three.js/core/Object3D:layers](https://threejs.org/docs/#api/en/core/Object3D.layers)

The layer membership of the object.

#### Remarks

The object is only visible if it has at least one layer in common with the THREE.Object3DCamera \| Camera in use.
This property can also be used to filter out unwanted objects in ray-intersection tests when using THREE.Raycaster \| Raycaster.

#### Default Value

`new THREE.Layers()`

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`layers`](/three-flatland/api/three-flatland/src/classes/flatland/#layers)

***

### lightType

> **lightType**: [`Light2DType`](/three-flatland/api/three-flatland/src/type-aliases/light2dtype/)

Defined in: [packages/three-flatland/src/lights/Light2D.ts:124](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L124)

Light type.

***

### matrix

> **matrix**: [`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Defined in: [three.js/core/Object3D:matrix](https://threejs.org/docs/#api/en/core/Object3D.matrix)

The local transform matrix.

#### Default Value

`new THREE.Matrix4()`

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`matrix`](/three-flatland/api/three-flatland/src/classes/flatland/#matrix)

***

### matrixAutoUpdate

> **matrixAutoUpdate**: `boolean`

Defined in: [three.js/core/Object3D:matrixAutoUpdate](https://threejs.org/docs/#api/en/core/Object3D.matrixAutoUpdate)

When this is set, it calculates the matrix of position, (rotation or quaternion) and
scale every frame and also recalculates the matrixWorld property.

#### Default Value

[DEFAULT\_MATRIX\_AUTO\_UPDATE](/three-flatland/api/three-flatland/src/classes/flatland/#default_matrix_auto_update) - that is `(true)`.

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`matrixAutoUpdate`](/three-flatland/api/three-flatland/src/classes/flatland/#matrixautoupdate)

***

### matrixWorld

> **matrixWorld**: [`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Defined in: [three.js/core/Object3D:matrixWorld](https://threejs.org/docs/#api/en/core/Object3D.matrixWorld)

The global transform of the object.

#### Remarks

If the [Object3D](https://threejs.org/docs/#api/en/core/Object3D) has no parent, then it's identical to the local transform THREE.Object3D.matrix \| .matrix.

#### Default Value

`new THREE.Matrix4()`

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`matrixWorld`](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworld)

***

### matrixWorldAutoUpdate

> **matrixWorldAutoUpdate**: `boolean`

Defined in: [three.js/core/Object3D:matrixWorldAutoUpdate](https://threejs.org/docs/#api/en/core/Object3D.matrixWorldAutoUpdate)

If set, then the renderer checks every frame if the object and its children need matrix updates.
When it isn't, then you have to maintain all matrices in the object and its children yourself.

#### Default Value

[DEFAULT\_MATRIX\_WORLD\_AUTO\_UPDATE](/three-flatland/api/three-flatland/src/classes/flatland/#default_matrix_world_auto_update) - that is `(true)`.

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`matrixWorldAutoUpdate`](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldautoupdate)

***

### matrixWorldNeedsUpdate

> **matrixWorldNeedsUpdate**: `boolean`

Defined in: [three.js/core/Object3D:matrixWorldNeedsUpdate](https://threejs.org/docs/#api/en/core/Object3D.matrixWorldNeedsUpdate)

When this is set, it calculates the matrixWorld in that frame and resets this property to false.

#### Default Value

`false`

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`matrixWorldNeedsUpdate`](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldneedsupdate)

***

### modelViewMatrix

> `readonly` **modelViewMatrix**: [`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Defined in: [three.js/core/Object3D:modelViewMatrix](https://threejs.org/docs/#api/en/core/Object3D.modelViewMatrix)

#### Default Value

`new THREE.Matrix4()`

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`modelViewMatrix`](/three-flatland/api/three-flatland/src/classes/flatland/#modelviewmatrix)

***

### name

> **name**: `string`

Defined in: [three.js/core/Object3D:name](https://threejs.org/docs/#api/en/core/Object3D.name)

Optional name of the object

#### Remarks

_(doesn't need to be unique)_.

#### Default Value

`""`

#### Inherited from

`Object3D.name`

***

### normalMatrix

> `readonly` **normalMatrix**: [`Matrix3`](https://threejs.org/docs/#api/en/math/Matrix3)

Defined in: [three.js/core/Object3D:normalMatrix](https://threejs.org/docs/#api/en/core/Object3D.normalMatrix)

#### Default Value

`new THREE.Matrix3()`

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`normalMatrix`](/three-flatland/api/three-flatland/src/classes/flatland/#normalmatrix)

***

### occlusionTest?

> `optional` **occlusionTest?**: `boolean`

Defined in: [three.js/renderers/common/Backend:occlusionTest](https://threejs.org/docs/#api/en/renderers/common/Backend.occlusionTest)

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`occlusionTest`](/three-flatland/api/three-flatland/src/classes/flatland/#occlusiontest)

***

### parent

> **parent**: [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `null`

Defined in: [three.js/core/Object3D:parent](https://threejs.org/docs/#api/en/core/Object3D.parent)

Object's parent in the [scene graph](https://en.wikipedia.org/wiki/Scene_graph).

#### Remarks

An object can have at most one parent.

#### Default Value

`null`

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`parent`](/three-flatland/api/three-flatland/src/classes/flatland/#parent)

***

### penumbra

> **penumbra**: `number`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:156](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L156)

Penumbra for spot lights (0-1).

***

### pivot

> **pivot**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3) \| `null`

Defined in: [three.js/core/Object3D:pivot](https://threejs.org/docs/#api/en/core/Object3D.pivot)

The pivot point for rotation and scale transformations.
When set, rotation and scale are applied around this point
instead of the object's origin.

#### Default

```ts
null
```

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`pivot`](/three-flatland/api/three-flatland/src/classes/flatland/#pivot)

***

### position

> `readonly` **position**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:position](https://threejs.org/docs/#api/en/core/Object3D.position)

Object's local position.

#### Default Value

`new THREE.Vector3()` - that is `(0, 0, 0)`.

#### Inherited from

`Object3D.position`

***

### quaternion

> `readonly` **quaternion**: [`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

Defined in: [three.js/core/Object3D:quaternion](https://threejs.org/docs/#api/en/core/Object3D.quaternion)

Object's local rotation as a THREE.Quaternion \| Quaternion.

#### Default Value

`new THREE.Quaternion()` - that is `(0,  0, 0, 1)`.

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`quaternion`](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion)

***

### receiveShadow

> **receiveShadow**: `boolean`

Defined in: [three.js/core/Object3D:receiveShadow](https://threejs.org/docs/#api/en/core/Object3D.receiveShadow)

Whether the material receives shadows.

#### Default Value

`false`

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`receiveShadow`](/three-flatland/api/three-flatland/src/classes/flatland/#receiveshadow)

***

### renderOrder

> **renderOrder**: `number`

Defined in: [three.js/core/Object3D:renderOrder](https://threejs.org/docs/#api/en/core/Object3D.renderOrder)

This value allows the default rendering order of [scene graph](https://en.wikipedia.org/wiki/Scene_graph)
objects to be overridden although opaque and transparent objects remain sorted independently.

#### Remarks

When this property is set for an instance of [Group](https://threejs.org/docs/#api/en/objects/Group), all descendants objects will be sorted and rendered together.
Sorting is from lowest to highest renderOrder.

#### Default Value

`0`

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`renderOrder`](/three-flatland/api/three-flatland/src/classes/flatland/#renderorder)

***

### rotation

> `readonly` **rotation**: [`Euler`](https://threejs.org/docs/#api/en/math/Euler)

Defined in: [three.js/core/Object3D:rotation](https://threejs.org/docs/#api/en/core/Object3D.rotation)

Object's local rotation ([Euler angles](https://en.wikipedia.org/wiki/Euler_angles)), in radians.

#### Default Value

`new THREE.Euler()` - that is `(0, 0, 0, Euler.DEFAULT_ORDER)`.

#### Inherited from

`Object3D.rotation`

***

### scale

> `readonly` **scale**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:scale](https://threejs.org/docs/#api/en/core/Object3D.scale)

The object's local scale.

#### Default Value

`new THREE.Vector3( 1, 1, 1 )`

#### Inherited from

`Object3D.scale`

***

### static

> **static**: `boolean`

Defined in: [three.js/core/Object3D:static](https://threejs.org/docs/#api/en/core/Object3D.static)

Whether the 3D object is supposed to be static or not. If set to `true`, it means
the 3D object is not going to be changed after the initial renderer. This includes
geometry and material settings. A static 3D object can be processed by the renderer
slightly faster since certain state checks can be bypassed.

Only relevant in context of WebGPURenderer.

#### Default

```ts
false
```

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`static`](/three-flatland/api/three-flatland/src/classes/flatland/#static)

***

### type

> `readonly` **type**: `"Light2D"` = `'Light2D'`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:119](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L119)

Type identifier for Three.js.

#### Overrides

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`type`](/three-flatland/api/three-flatland/src/classes/flatland/#type)

***

### up

> **up**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:up](https://threejs.org/docs/#api/en/core/Object3D.up)

This is used by the [lookAt](https://threejs.org/docs/) method, for example, to determine the orientation of the result.

#### Default Value

[Object3D.DEFAULT\_UP](/three-flatland/api/three-flatland/src/classes/flatland/#default_up) - that is `(0, 1, 0)`.

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`up`](/three-flatland/api/three-flatland/src/classes/flatland/#up)

***

### userData

> **userData**: `Record`\<`string`, `any`\>

Defined in: [three.js/core/Object3D:userData](https://threejs.org/docs/#api/en/core/Object3D.userData)

An object that can be used to store custom data about the [Object3D](https://threejs.org/docs/#api/en/core/Object3D).

#### Remarks

It should not hold references to _functions_ as these **will not** be cloned.

#### Default

`{}`

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`userData`](/three-flatland/api/three-flatland/src/classes/flatland/#userdata)

***

### uuid

> **uuid**: `string`

Defined in: [three.js/core/Object3D:uuid](https://threejs.org/docs/#api/en/core/Object3D.uuid)

[UUID](http://en.wikipedia.org/wiki/Universally_unique_identifier) of this object instance.

#### Remarks

This gets automatically assigned and shouldn't be edited.

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`uuid`](/three-flatland/api/three-flatland/src/classes/flatland/#uuid)

***

### visible

> **visible**: `boolean`

Defined in: [three.js/core/Object3D:visible](https://threejs.org/docs/#api/en/core/Object3D.visible)

Object gets rendered if `true`.

#### Default Value

`true`

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`visible`](/three-flatland/api/three-flatland/src/classes/flatland/#visible)

***

### DEFAULT\_MATRIX\_AUTO\_UPDATE

> `static` **DEFAULT\_MATRIX\_AUTO\_UPDATE**: `boolean`

Defined in: [three.js/core/Object3D:DEFAULT_MATRIX_AUTO_UPDATE](https://threejs.org/docs/#api/en/core/Object3D.DEFAULT_MATRIX_AUTO_UPDATE)

The default setting for [matrixAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixautoupdate) for newly created Object3Ds.

#### Default Value

`true`

#### Inherited from

`Object3D.DEFAULT_MATRIX_AUTO_UPDATE`

***

### DEFAULT\_MATRIX\_WORLD\_AUTO\_UPDATE

> `static` **DEFAULT\_MATRIX\_WORLD\_AUTO\_UPDATE**: `boolean`

Defined in: [three.js/core/Object3D:DEFAULT_MATRIX_WORLD_AUTO_UPDATE](https://threejs.org/docs/#api/en/core/Object3D.DEFAULT_MATRIX_WORLD_AUTO_UPDATE)

The default setting for [matrixWorldAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldautoupdate) for newly created Object3Ds.

#### Default Value

`true`

#### Inherited from

`Object3D.DEFAULT_MATRIX_WORLD_AUTO_UPDATE`

***

### DEFAULT\_UP

> `static` **DEFAULT\_UP**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:DEFAULT_UP](https://threejs.org/docs/#api/en/core/Object3D.DEFAULT_UP)

The default [up](/three-flatland/api/three-flatland/src/classes/flatland/#up) direction for objects, also used as the default position for THREE.DirectionalLight \| DirectionalLight,
THREE.HemisphereLight \| HemisphereLight and THREE.Spotlight \| Spotlight (which creates lights shining from the top down).

#### Default Value

`new THREE.Vector3( 0, 1, 0)`

#### Inherited from

`Object3D.DEFAULT_UP`

## Accessors

### category

#### Get Signature

> **get** **category**(): `string` \| `undefined`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:242](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L242)

User-facing category string. See [Light2DOptions.category](/three-flatland/api/three-flatland/src/interfaces/light2doptions/#category).

##### Returns

`string` \| `undefined`

#### Set Signature

> **set** **category**(`value`): `void`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:246](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L246)

##### Parameters

###### value

`string` \| `undefined`

##### Returns

`void`

***

### color

#### Get Signature

> **get** **color**(): [`Color`](https://threejs.org/docs/#api/en/math/Color)

Defined in: [packages/three-flatland/src/lights/Light2D.ts:257](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L257)

Get light color.

##### Returns

[`Color`](https://threejs.org/docs/#api/en/math/Color)

#### Set Signature

> **set** **color**(`value`): `void`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:264](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L264)

Set light color.

##### Parameters

###### value

[`ColorRepresentation`](https://threejs.org/docs/)

##### Returns

`void`

***

### direction

#### Get Signature

> **get** **direction**(): [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

Defined in: [packages/three-flatland/src/lights/Light2D.ts:275](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L275)

Get light direction (for directional/spot lights).

##### Returns

[`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

#### Set Signature

> **set** **direction**(`value`): `void`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:282](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L282)

Set light direction (normalized automatically).

##### Parameters

###### value

\[`number`, `number`\] \| [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

##### Returns

`void`

***

### position2D

#### Get Signature

> **get** **position2D**(): [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

Defined in: [packages/three-flatland/src/lights/Light2D.ts:294](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L294)

Get the 2D position from Object3D position.

##### Returns

[`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

#### Set Signature

> **set** **position2D**(`value`): `void`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:301](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L301)

Set the 2D position (updates Object3D.position.x/y).

##### Parameters

###### value

\[`number`, `number`\] \| [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

##### Returns

`void`

## Methods

### add()

> **add**(...`object`): `this`

Defined in: [three.js/core/Object3D:add](https://threejs.org/docs/#api/en/core/Object3D.add)

Adds another [Object3D](https://threejs.org/docs/#api/en/core/Object3D) as child of this [Object3D](https://threejs.org/docs/#api/en/core/Object3D).

#### Parameters

##### object

...[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

#### Returns

`this`

#### Remarks

An arbitrary number of objects may be added
Any current parent on an object passed in here will be removed, since an [Object3D](https://threejs.org/docs/#api/en/core/Object3D) can have at most one parent.

#### See

 - [attach](https://threejs.org/docs/)
 - THREE.Group \| Group for info on manually grouping objects.

#### Inherited from

`Object3D.add`

***

### addEventListener()

> **addEventListener**\<`T`\>(`type`, `listener`): `void`

Defined in: [three.js/core/EventDispatcher:addEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.addEventListener)

Adds a listener to an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### type

`T`

The type of event to listen to.

##### listener

[`EventListener`](https://threejs.org/docs/)\<[`Object3DEventMap`](https://threejs.org/docs/)\[`T`\], `T`, `Light2D`\>

The function that gets called when the event is fired.

#### Returns

`void`

#### Inherited from

`Object3D.addEventListener`

***

### applyMatrix4()

> **applyMatrix4**(`matrix`): `void`

Defined in: [three.js/core/Object3D:applyMatrix4](https://threejs.org/docs/#api/en/core/Object3D.applyMatrix4)

Applies the matrix transform to the object and updates the object's position, rotation and scale.

#### Parameters

##### matrix

[`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

#### Returns

`void`

#### Inherited from

`Object3D.applyMatrix4`

***

### applyQuaternion()

> **applyQuaternion**(`quaternion`): `this`

Defined in: [three.js/core/Object3D:applyQuaternion](https://threejs.org/docs/#api/en/core/Object3D.applyQuaternion)

Applies the rotation represented by the quaternion to the object.

#### Parameters

##### quaternion

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

#### Returns

`this`

#### Inherited from

`Object3D.applyQuaternion`

***

### attach()

> **attach**(`object`): `this`

Defined in: [three.js/core/Object3D:attach](https://threejs.org/docs/#api/en/core/Object3D.attach)

Adds a [Object3D](https://threejs.org/docs/#api/en/core/Object3D) as a child of this, while maintaining the object's world transform.

#### Parameters

##### object

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)

#### Returns

`this`

#### Remarks

Note: This method does not support scene graphs having non-uniformly-scaled nodes(s).

#### See

[add](https://threejs.org/docs/)

#### Inherited from

`Object3D.attach`

***

### clear()

> **clear**(): `this`

Defined in: [three.js/core/Object3D:clear](https://threejs.org/docs/#api/en/core/Object3D.clear)

Removes all child objects.

#### Returns

`this`

#### Inherited from

`Object3D.clear`

***

### clone()

> **clone**(): `this`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:332](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L332)

Clone this light.

#### Returns

`this`

#### Overrides

`Object3D.clone`

***

### copy()

> **copy**(`object`, `recursive?`): `this`

Defined in: [three.js/core/Object3D:copy](https://threejs.org/docs/#api/en/core/Object3D.copy)

Copies the given object into this object.

#### Parameters

##### object

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)

##### recursive?

`boolean`

If set to `true`, descendants of the object are copied next to the existing ones. If set to
`false`, descendants are left unchanged. Default is `true`.

#### Returns

`this`

#### Remarks

Event listeners and user-defined callbacks (.onAfterRender and .onBeforeRender) are not copied.

#### Inherited from

`Object3D.copy`

***

### dispatchEvent()

> **dispatchEvent**\<`T`\>(`event`): `void`

Defined in: [three.js/core/EventDispatcher:dispatchEvent](https://threejs.org/docs/#api/en/core/EventDispatcher.dispatchEvent)

Fire an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### event

[`BaseEvent`](https://threejs.org/docs/)\<`T`\> & [`Object3DEventMap`](https://threejs.org/docs/)\[`T`\]

The event that gets fired.

#### Returns

`void`

#### Inherited from

`Object3D.dispatchEvent`

***

### dispose()

> **dispose**(): `void`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:354](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L354)

Dispose of resources.

#### Returns

`void`

***

### getObjectById()

> **getObjectById**(`id`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

Defined in: [three.js/core/Object3D:getObjectById](https://threejs.org/docs/#api/en/core/Object3D.getObjectById)

Searches through an object and its children, starting with the object itself, and returns the first with a matching id.

#### Parameters

##### id

`number`

Unique number of the object instance. Expects a `Integer`

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

#### Remarks

Note that ids are assigned in chronological order: 1, 2, 3, ..., incrementing by one for each new object.

#### See

id

#### Inherited from

`Object3D.getObjectById`

***

### getObjectByName()

> **getObjectByName**(`name`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

Defined in: [three.js/core/Object3D:getObjectByName](https://threejs.org/docs/#api/en/core/Object3D.getObjectByName)

Searches through an object and its children, starting with the object itself, and returns the first with a matching name.

#### Parameters

##### name

`string`

String to match to the children's Object3D.name property.

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

#### Remarks

Note that for most objects the name is an empty string by default
You will have to set it manually to make use of this method.

#### Inherited from

`Object3D.getObjectByName`

***

### getObjectByProperty()

> **getObjectByProperty**(`name`, `value`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

Defined in: [three.js/core/Object3D:getObjectByProperty](https://threejs.org/docs/#api/en/core/Object3D.getObjectByProperty)

Searches through an object and its children, starting with the object itself,
and returns the first with a property that matches the value given.

#### Parameters

##### name

`string`

the property name to search for.

##### value

`any`

value of the given property.

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

#### Inherited from

`Object3D.getObjectByProperty`

***

### getObjectsByProperty()

> **getObjectsByProperty**(`name`, `value`, `optionalTarget?`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

Defined in: [three.js/core/Object3D:getObjectsByProperty](https://threejs.org/docs/#api/en/core/Object3D.getObjectsByProperty)

Searches through an object and its children, starting with the object itself,
and returns the first with a property that matches the value given.

#### Parameters

##### name

`string`

The property name to search for.

##### value

`any`

Value of the given property.

##### optionalTarget?

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

target to set the result. Otherwise a new Array is instantiated. If set, you must clear
this array prior to each call (i.e., array.length = 0;).

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

#### Inherited from

`Object3D.getObjectsByProperty`

***

### getUniforms()

> **getUniforms**(): [`Light2DUniforms`](/three-flatland/api/three-flatland/src/interfaces/light2duniforms/)

Defined in: [packages/three-flatland/src/lights/Light2D.ts:312](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L312)

Get uniforms for shader use.

#### Returns

[`Light2DUniforms`](/three-flatland/api/three-flatland/src/interfaces/light2duniforms/)

***

### getWorldDirection()

> **getWorldDirection**(`target`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:getWorldDirection](https://threejs.org/docs/#api/en/core/Object3D.getWorldDirection)

Returns a vector representing the direction of object's positive z-axis in world space.

#### Parameters

##### target

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

The result will be copied into this Vector3.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Object3D.getWorldDirection`

***

### getWorldPosition()

> **getWorldPosition**(`target`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:getWorldPosition](https://threejs.org/docs/#api/en/core/Object3D.getWorldPosition)

Returns a vector representing the position of the object in world space.

#### Parameters

##### target

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

The result will be copied into this Vector3.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Object3D.getWorldPosition`

***

### getWorldQuaternion()

> **getWorldQuaternion**(`target`): [`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

Defined in: [three.js/core/Object3D:getWorldQuaternion](https://threejs.org/docs/#api/en/core/Object3D.getWorldQuaternion)

Returns a quaternion representing the rotation of the object in world space.

#### Parameters

##### target

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

The result will be copied into this Quaternion.

#### Returns

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

#### Inherited from

`Object3D.getWorldQuaternion`

***

### getWorldScale()

> **getWorldScale**(`target`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:getWorldScale](https://threejs.org/docs/#api/en/core/Object3D.getWorldScale)

Returns a vector of the scaling factors applied to the object for each axis in world space.

#### Parameters

##### target

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

The result will be copied into this Vector3.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Object3D.getWorldScale`

***

### hasEventListener()

> **hasEventListener**\<`T`\>(`type`, `listener`): `boolean`

Defined in: [three.js/core/EventDispatcher:hasEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.hasEventListener)

Checks if listener is added to an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### type

`T`

The type of event to listen to.

##### listener

[`EventListener`](https://threejs.org/docs/)\<[`Object3DEventMap`](https://threejs.org/docs/)\[`T`\], `T`, `Light2D`\>

The function that gets called when the event is fired.

#### Returns

`boolean`

#### Inherited from

`Object3D.hasEventListener`

***

### localToWorld()

> **localToWorld**(`vector`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:localToWorld](https://threejs.org/docs/#api/en/core/Object3D.localToWorld)

Converts the vector from this object's local space to world space.

#### Parameters

##### vector

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A vector representing a position in this object's local space.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Object3D.localToWorld`

***

### lookAt()

#### Call Signature

> **lookAt**(`vector`): `void`

Defined in: [three.js/core/Object3D:lookAt](https://threejs.org/docs/#api/en/core/Object3D.lookAt)

Rotates the object to face a point in world space.

##### Parameters

###### vector

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A vector representing a position in world space to look at.

##### Returns

`void`

##### Remarks

This method does not support objects having non-uniformly-scaled parent(s).

##### Inherited from

`Object3D.lookAt`

#### Call Signature

> **lookAt**(`x`, `y`, `z`): `void`

Defined in: [three.js/core/Object3D:lookAt](https://threejs.org/docs/#api/en/core/Object3D.lookAt)

Rotates the object to face a point in world space.

##### Parameters

###### x

`number`

Expects a `Float`

###### y

`number`

Expects a `Float`

###### z

`number`

Expects a `Float`

##### Returns

`void`

##### Remarks

This method does not support objects having non-uniformly-scaled parent(s).

##### Inherited from

`Object3D.lookAt`

***

### onAfterRender()

> **onAfterRender**(`renderer`, `scene`, `camera`, `geometry`, `material`, `group`): `void`

Defined in: [three.js/core/Object3D:onAfterRender](https://threejs.org/docs/#api/en/core/Object3D.onAfterRender)

An optional callback that is executed immediately after a 3D object is rendered.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### material

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, geometry, material, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

`Object3D.onAfterRender`

***

### onAfterShadow()

> **onAfterShadow**(`renderer`, `scene`, `camera`, `shadowCamera`, `geometry`, `depthMaterial`, `group`): `void`

Defined in: [three.js/core/Object3D:onAfterShadow](https://threejs.org/docs/#api/en/core/Object3D.onAfterShadow)

An optional callback that is executed immediately after a 3D object is rendered to a shadow map.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### shadowCamera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### depthMaterial

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, shadowCamera, geometry,
depthMaterial, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

`Object3D.onAfterShadow`

***

### onBeforeRender()

> **onBeforeRender**(`renderer`, `scene`, `camera`, `geometry`, `material`, `group`): `void`

Defined in: [three.js/core/Object3D:onBeforeRender](https://threejs.org/docs/#api/en/core/Object3D.onBeforeRender)

An optional callback that is executed immediately before a 3D object is rendered.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### material

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, geometry, material, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

`Object3D.onBeforeRender`

***

### onBeforeShadow()

> **onBeforeShadow**(`renderer`, `scene`, `camera`, `shadowCamera`, `geometry`, `depthMaterial`, `group`): `void`

Defined in: [three.js/core/Object3D:onBeforeShadow](https://threejs.org/docs/#api/en/core/Object3D.onBeforeShadow)

An optional callback that is executed immediately before a 3D object is rendered to a shadow map.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### shadowCamera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### depthMaterial

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, shadowCamera, geometry,
depthMaterial, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

`Object3D.onBeforeShadow`

***

### raycast()

> **raycast**(`raycaster`, `intersects`): `void`

Defined in: [three.js/core/Object3D:raycast](https://threejs.org/docs/#api/en/core/Object3D.raycast)

Abstract (empty) method to get intersections between a casted ray and this object

#### Parameters

##### raycaster

[`Raycaster`](https://threejs.org/docs/#api/en/core/Raycaster)

##### intersects

[`Intersection`](https://threejs.org/docs/)\<[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>\>[]

#### Returns

`void`

#### Remarks

Subclasses such as THREE.Mesh \| Mesh, THREE.Line \| Line, and THREE.Points \| Points implement this method in order to use raycasting.

#### See

THREE.Raycaster \| Raycaster

#### Default Value

`() => {}`

#### Inherited from

`Object3D.raycast`

***

### remove()

> **remove**(...`object`): `this`

Defined in: [three.js/core/Object3D:remove](https://threejs.org/docs/#api/en/core/Object3D.remove)

Removes a [Object3D](https://threejs.org/docs/#api/en/core/Object3D) as child of this [Object3D](https://threejs.org/docs/#api/en/core/Object3D).

#### Parameters

##### object

...[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

#### Returns

`this`

#### Remarks

An arbitrary number of objects may be removed.

#### See

THREE.Group \| Group for info on manually grouping objects.

#### Inherited from

`Object3D.remove`

***

### removeEventListener()

> **removeEventListener**\<`T`\>(`type`, `listener`): `void`

Defined in: [three.js/core/EventDispatcher:removeEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.removeEventListener)

Removes a listener from an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### type

`T`

The type of the listener that gets removed.

##### listener

[`EventListener`](https://threejs.org/docs/)\<[`Object3DEventMap`](https://threejs.org/docs/)\[`T`\], `T`, `Light2D`\>

The listener function that gets removed.

#### Returns

`void`

#### Inherited from

`Object3D.removeEventListener`

***

### removeFromParent()

> **removeFromParent**(): `this`

Defined in: [three.js/core/Object3D:removeFromParent](https://threejs.org/docs/#api/en/core/Object3D.removeFromParent)

Removes this object from its current parent.

#### Returns

`this`

#### Inherited from

`Object3D.removeFromParent`

***

### rotateOnAxis()

> **rotateOnAxis**(`axis`, `angle`): `this`

Defined in: [three.js/core/Object3D:rotateOnAxis](https://threejs.org/docs/#api/en/core/Object3D.rotateOnAxis)

Rotate an object along an axis in object space.

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in object space.

##### angle

`number`

The angle in radians. Expects a `Float`

#### Returns

`this`

#### Remarks

The axis is assumed to be normalized.

#### Inherited from

`Object3D.rotateOnAxis`

***

### rotateOnWorldAxis()

> **rotateOnWorldAxis**(`axis`, `angle`): `this`

Defined in: [three.js/core/Object3D:rotateOnWorldAxis](https://threejs.org/docs/#api/en/core/Object3D.rotateOnWorldAxis)

Rotate an object along an axis in world space.

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in world space.

##### angle

`number`

The angle in radians. Expects a `Float`

#### Returns

`this`

#### Remarks

The axis is assumed to be normalized
Method Assumes no rotated parent.

#### Inherited from

`Object3D.rotateOnWorldAxis`

***

### rotateX()

> **rotateX**(`angle`): `this`

Defined in: [three.js/core/Object3D:rotateX](https://threejs.org/docs/#api/en/core/Object3D.rotateX)

Rotates the object around _x_ axis in local space.

#### Parameters

##### angle

`number`

#### Returns

`this`

#### Inherited from

`Object3D.rotateX`

***

### rotateY()

> **rotateY**(`angle`): `this`

Defined in: [three.js/core/Object3D:rotateY](https://threejs.org/docs/#api/en/core/Object3D.rotateY)

Rotates the object around _y_ axis in local space.

#### Parameters

##### angle

`number`

#### Returns

`this`

#### Inherited from

`Object3D.rotateY`

***

### rotateZ()

> **rotateZ**(`angle`): `this`

Defined in: [three.js/core/Object3D:rotateZ](https://threejs.org/docs/#api/en/core/Object3D.rotateZ)

Rotates the object around _z_ axis in local space.

#### Parameters

##### angle

`number`

#### Returns

`this`

#### Inherited from

`Object3D.rotateZ`

***

### setRotationFromAxisAngle()

> **setRotationFromAxisAngle**(`axis`, `angle`): `void`

Defined in: [three.js/core/Object3D:setRotationFromAxisAngle](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromAxisAngle)

Calls THREE.Quaternion.setFromAxisAngle \| setFromAxisAngle(axis, angle) on the [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in object space.

##### angle

`number`

Angle in radians. Expects a `Float`

#### Returns

`void`

#### Inherited from

`Object3D.setRotationFromAxisAngle`

***

### setRotationFromEuler()

> **setRotationFromEuler**(`euler`): `void`

Defined in: [three.js/core/Object3D:setRotationFromEuler](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromEuler)

Calls THREE.Quaternion.setFromEuler \| setFromEuler(euler) on the [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### euler

[`Euler`](https://threejs.org/docs/#api/en/math/Euler)

Euler angle specifying rotation amount.

#### Returns

`void`

#### Inherited from

`Object3D.setRotationFromEuler`

***

### setRotationFromMatrix()

> **setRotationFromMatrix**(`m`): `void`

Defined in: [three.js/core/Object3D:setRotationFromMatrix](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromMatrix)

Calls THREE.Quaternion.setFromRotationMatrix \| setFromRotationMatrix(m) on the [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### m

[`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Rotate the quaternion by the rotation component of the matrix.

#### Returns

`void`

#### Remarks

Note that this assumes that the upper 3x3 of m is a pure rotation matrix (i.e, unscaled).

#### Inherited from

`Object3D.setRotationFromMatrix`

***

### setRotationFromQuaternion()

> **setRotationFromQuaternion**(`q`): `void`

Defined in: [three.js/core/Object3D:setRotationFromQuaternion](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromQuaternion)

Copy the given THREE.Quaternion \| Quaternion into [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### q

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

Normalized Quaternion.

#### Returns

`void`

#### Inherited from

`Object3D.setRotationFromQuaternion`

***

### toJSON()

> **toJSON**(`meta?`): [`Object3DJSON`](https://threejs.org/docs/)

Defined in: [three.js/core/Object3D:toJSON](https://threejs.org/docs/#api/en/core/Object3D.toJSON)

Convert the object to three.js [JSON Object/Scene format](https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4).

#### Parameters

##### meta?

[`JSONMeta`](https://threejs.org/docs/)

Object containing metadata such as materials, textures or images for the object.

#### Returns

[`Object3DJSON`](https://threejs.org/docs/)

#### Inherited from

`Object3D.toJSON`

***

### translateOnAxis()

> **translateOnAxis**(`axis`, `distance`): `this`

Defined in: [three.js/core/Object3D:translateOnAxis](https://threejs.org/docs/#api/en/core/Object3D.translateOnAxis)

Translate an object by distance along an axis in object space

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in object space.

##### distance

`number`

The distance to translate. Expects a `Float`

#### Returns

`this`

#### Remarks

The axis is assumed to be normalized.

#### Inherited from

`Object3D.translateOnAxis`

***

### translateX()

> **translateX**(`distance`): `this`

Defined in: [three.js/core/Object3D:translateX](https://threejs.org/docs/#api/en/core/Object3D.translateX)

Translates object along x axis in object space by distance units.

#### Parameters

##### distance

`number`

Expects a `Float`

#### Returns

`this`

#### Inherited from

`Object3D.translateX`

***

### translateY()

> **translateY**(`distance`): `this`

Defined in: [three.js/core/Object3D:translateY](https://threejs.org/docs/#api/en/core/Object3D.translateY)

Translates object along _y_ axis in object space by distance units.

#### Parameters

##### distance

`number`

Expects a `Float`

#### Returns

`this`

#### Inherited from

`Object3D.translateY`

***

### translateZ()

> **translateZ**(`distance`): `this`

Defined in: [three.js/core/Object3D:translateZ](https://threejs.org/docs/#api/en/core/Object3D.translateZ)

Translates object along _z_ axis in object space by distance units.

#### Parameters

##### distance

`number`

Expects a `Float`

#### Returns

`this`

#### Inherited from

`Object3D.translateZ`

***

### traverse()

> **traverse**(`callback`): `void`

Defined in: [three.js/core/Object3D:traverse](https://threejs.org/docs/#api/en/core/Object3D.traverse)

Executes the callback on this object and all descendants.

#### Parameters

##### callback

(`object`) => `any`

A function with as first argument an [Object3D](https://threejs.org/docs/#api/en/core/Object3D) object.

#### Returns

`void`

#### Remarks

Note: Modifying the scene graph inside the callback is discouraged.

#### Inherited from

`Object3D.traverse`

***

### traverseAncestors()

> **traverseAncestors**(`callback`): `void`

Defined in: [three.js/core/Object3D:traverseAncestors](https://threejs.org/docs/#api/en/core/Object3D.traverseAncestors)

Executes the callback on all ancestors.

#### Parameters

##### callback

(`object`) => `any`

A function with as first argument an [Object3D](https://threejs.org/docs/#api/en/core/Object3D) object.

#### Returns

`void`

#### Remarks

Note: Modifying the scene graph inside the callback is discouraged.

#### Inherited from

`Object3D.traverseAncestors`

***

### traverseVisible()

> **traverseVisible**(`callback`): `void`

Defined in: [three.js/core/Object3D:traverseVisible](https://threejs.org/docs/#api/en/core/Object3D.traverseVisible)

Like traverse, but the callback will only be executed for visible objects

#### Parameters

##### callback

(`object`) => `any`

A function with as first argument an [Object3D](https://threejs.org/docs/#api/en/core/Object3D) object.

#### Returns

`void`

#### Remarks

Descendants of invisible objects are not traversed.
Note: Modifying the scene graph inside the callback is discouraged.

#### Inherited from

`Object3D.traverseVisible`

***

### updateMatrix()

> **updateMatrix**(): `void`

Defined in: [three.js/core/Object3D:updateMatrix](https://threejs.org/docs/#api/en/core/Object3D.updateMatrix)

Updates local transform.

#### Returns

`void`

#### Inherited from

`Object3D.updateMatrix`

***

### updateMatrixWorld()

> **updateMatrixWorld**(`force?`): `void`

Defined in: [three.js/core/Object3D:updateMatrixWorld](https://threejs.org/docs/#api/en/core/Object3D.updateMatrixWorld)

Updates the global transform of the object.
And will update the object descendants if [.matrixWorldNeedsUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldneedsupdate) is set to true or if the force parameter is set to `true`.

#### Parameters

##### force?

`boolean`

A boolean that can be used to bypass [.matrixWorldAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldautoupdate), to recalculate the world matrix of the object and descendants on the current frame.
Useful if you cannot wait for the renderer to update it on the next frame, assuming [.matrixWorldAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldautoupdate) set to `true`.

#### Returns

`void`

#### Inherited from

`Object3D.updateMatrixWorld`

***

### updateWorldMatrix()

> **updateWorldMatrix**(`updateParents`, `updateChildren`): `void`

Defined in: [three.js/core/Object3D:updateWorldMatrix](https://threejs.org/docs/#api/en/core/Object3D.updateWorldMatrix)

Updates the global transform of the object.

#### Parameters

##### updateParents

`boolean`

Recursively updates global transform of ancestors.

##### updateChildren

`boolean`

Recursively updates global transform of descendants.

#### Returns

`void`

#### Inherited from

`Object3D.updateWorldMatrix`

***

### worldToLocal()

> **worldToLocal**(`vector`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:worldToLocal](https://threejs.org/docs/#api/en/core/Object3D.worldToLocal)

Converts the vector from world space to this object's local space.

#### Parameters

##### vector

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A vector representing a position in world space.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Object3D.worldToLocal`

# LightEffect

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:144](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L144)

Base class for lighting effects applied to Flatland sprites.

Mirrors the PassEffect pattern: class-based, schema-driven, with property
accessors. Uses TSL `uniform()` nodes for zero-cost runtime parameter updates.

LightEffect produces a `ColorTransformFn` that is automatically assigned to
all lit sprites. The transform runs in the material shader, reading light data
from shared DataTextures managed by LightStore.

Subclasses may also override lifecycle methods (init/update/resize/dispose)
to manage GPU resources like Forward+ tiling or Radiance Cascades.

## Example

```typescript
class DefaultLightEffect extends LightEffect {
  static readonly lightName = 'defaultLight'
  static readonly lightSchema = { ambientIntensity: 0.2 } as const
  static readonly needsShadows = false
  declare ambientIntensity: number

  static buildLightFn({ uniforms, lightStore }: LightEffectBuildContext): ColorTransformFn {
    // build shader using lightStore.readLightData()
  }
}
```

## Constructors

### Constructor

> **new LightEffect**(): `LightEffect`

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:265](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L265)

#### Returns

`LightEffect`

## Properties

### name

> `readonly` **name**: `string`

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:233](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L233)

Effect name (from static).

***

### lightName

> `readonly` `static` **lightName**: `string`

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:150](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L150)

Unique light effect name. Must be overridden by subclass.

***

### lightSchema

> `readonly` `static` **lightSchema**: [`EffectSchema`](/three-flatland/api/three-flatland/src/type-aliases/effectschema/)

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:152](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L152)

Per-effect data schema with default values. Must be overridden by subclass.

***

### needsShadows

> `readonly` `static` **needsShadows**: `boolean` = `false`

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:154](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L154)

Whether this effect needs the shadow/SDF pipeline.

***

### requires

> `readonly` `static` **requires**: readonly keyof [`ChannelNodeMap`](/three-flatland/api/three-flatland/src/interfaces/channelnodemap/)[] = `[]`

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:156](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L156)

Per-fragment channels this effect requires (e.g., ['normal']).

## Accessors

### dirty

#### Get Signature

> **get** **dirty**(): `boolean`

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:391](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L391)

Whether this effect has been marked dirty since last clearDirty().

##### Returns

`boolean`

***

### enabled

#### Get Signature

> **get** **enabled**(): `boolean`

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:375](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L375)

Whether this effect is enabled.

##### Returns

`boolean`

#### Set Signature

> **set** **enabled**(`value`): `void`

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:380](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L380)

Toggle enabled state. Structural change — marks lighting dirty.

##### Parameters

###### value

`boolean`

##### Returns

`void`

## Methods

### build()

> **build**(`lightStore`, `worldSizeNode`, `worldOffsetNode`, `sdfTexture?`): [`ColorTransformFn`](/three-flatland/api/three-flatland/src/type-aliases/colortransformfn/)

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:456](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L456)

Build the ColorTransformFn for standalone use (no Flatland, no ECS).

Returns the lighting function that can be assigned directly to a
sprite material's `colorTransform`. For batched sprites, wrap with
`wrapWithLightFlags()` to gate per-instance.

#### Parameters

##### lightStore

`LightStore`

##### worldSizeNode

[`UniformNode`](https://threejs.org/docs/)\<`"vec2"`, [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)\>

##### worldOffsetNode

[`UniformNode`](https://threejs.org/docs/)\<`"vec2"`, [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)\>

##### sdfTexture?

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

#### Returns

[`ColorTransformFn`](/three-flatland/api/three-flatland/src/type-aliases/colortransformfn/)

#### Example

```typescript
const lightStore = new LightStore()
const lighting = new DefaultLightEffect()
const lightFn = lighting.build(lightStore)

sprite.material.colorTransform = lightFn
sprite.material.requiredChannels = new Set(DefaultLightEffect.requires)
```

***

### clearDirty()

> **clearDirty**(): `void`

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:396](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L396)

Clear the dirty flag. Called by lighting systems after processing.

#### Returns

`void`

***

### dispose()

> **dispose**(): `void`

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:495](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L495)

Dispose GPU resources owned by this effect.
Override in subclasses that own ForwardPlusLighting or other GPU resources.

#### Returns

`void`

***

### init()

> **init**(`_ctx`): `void`

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:405](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L405)

Initialize GPU resources. Called lazily on first render.

#### Parameters

##### \_ctx

[`LightEffectRuntimeContext`](/three-flatland/api/three-flatland/src/interfaces/lighteffectruntimecontext/)

#### Returns

`void`

***

### resize()

> **resize**(`_width`, `_height`): `void`

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:411](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L411)

Handle resize.

#### Parameters

##### \_width

`number`

##### \_height

`number`

#### Returns

`void`

***

### update()

> **update**(`_ctx`): `void`

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:408](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L408)

Per-frame GPU passes (tiling, SDF, radiance cascades).

#### Parameters

##### \_ctx

[`LightEffectRuntimeContext`](/three-flatland/api/three-flatland/src/interfaces/lighteffectruntimecontext/)

#### Returns

`void`

***

### buildLightFn()

> `static` **buildLightFn**(`_context`): [`ColorTransformFn`](/three-flatland/api/three-flatland/src/type-aliases/colortransformfn/)

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:172](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L172)

Build the lighting ColorTransformFn. Must be overridden by subclass.
Called once when the effect is attached to Flatland. The returned function
closes over uniform nodes for zero-cost parameter updates.

#### Parameters

##### \_context

[`LightEffectBuildContext`](/three-flatland/api/three-flatland/src/interfaces/lighteffectbuildcontext/)

#### Returns

[`ColorTransformFn`](/three-flatland/api/three-flatland/src/type-aliases/colortransformfn/)

# MaterialEffect

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:152](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L152)

Base class for per-sprite shader effects.

Each MaterialEffect subclass defines:
- `effectName` — unique name for the effect
- `effectSchema` — per-sprite data schema with default values
- `buildNode()` — TSL node builder for the effect shader

Each MaterialEffect instance:
- Has typed property accessors for each schema field
- Uses the snapshot pattern for pre-enrollment staging
- Dual-writes to ECS traits and packed GPU buffers

## Examples

```typescript
class DissolveEffect extends MaterialEffect {
  static readonly effectName = 'dissolve'
  static readonly effectSchema = { progress: 0 } as const
  declare progress: number

  static buildNode({ inputColor, attrs }: EffectNodeContext) {
    return mix(inputColor, vec4(0, 0, 0, 0), attrs.progress)
  }
}
```

```typescript
const DissolveEffect = createMaterialEffect({
  name: 'dissolve',
  schema: { progress: 0 },
  node({ inputColor, attrs }) {
    return mix(inputColor, vec4(0, 0, 0, 0), attrs.progress)
  },
})
```

## Constructors

### Constructor

> **new MaterialEffect**(): `MaterialEffect`

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:274](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L274)

#### Returns

`MaterialEffect`

## Properties

### id

> `readonly` **id**: `number`

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:252](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L252)

Unique instance ID (like Three.js object ids).

***

### name

> `readonly` **name**: `string`

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:255](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L255)

Effect name (from static).

***

### \_nextId

> `static` **\_nextId**: `number` = `0`

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:249](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L249)

Auto-incrementing unique ID for debugging.

***

### channelNode

> `static` **channelNode**: ((`channelName`, `context`) => [`Node`](https://threejs.org/docs/)) \| `null` = `null`

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:164](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L164)

Channel node builder — produces TSL nodes for declared channels.

***

### effectName

> `readonly` `static` **effectName**: `string`

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:158](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L158)

Unique effect name. Must be overridden by subclass.

***

### effectSchema

> `readonly` `static` **effectSchema**: [`EffectSchema`](/three-flatland/api/three-flatland/src/type-aliases/effectschema/)

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:160](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L160)

Per-sprite data schema with default values. Must be overridden by subclass.

***

### provides

> `readonly` `static` **provides**: readonly keyof [`ChannelNodeMap`](/three-flatland/api/three-flatland/src/interfaces/channelnodemap/)[] = `[]`

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:162](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L162)

Per-fragment channels this effect provides (e.g., ['normal']).

## Methods

### buildNode()

> `static` **buildNode**(`_context`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:181](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L181)

TSL node builder. Must be overridden by subclass (class-based path).
The factory path sets this via static assignment.

#### Parameters

##### \_context

[`EffectNodeContext`](/three-flatland/api/three-flatland/src/interfaces/effectnodecontext/)

#### Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

# PassEffect

Defined in: [packages/three-flatland/src/pipeline/PassEffect.ts:84](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/PassEffect.ts#L84)

Base class for post-processing pass effects.

Mirrors the MaterialEffect pattern: class-based, schema-driven, with property
accessors. Uses TSL `uniform()` nodes for zero-cost runtime parameter updates —
changing a parameter updates the uniform value directly without rebuilding the
node graph.

## Examples

```typescript
class CRTEffect extends PassEffect {
  static readonly passName = 'crt'
  static readonly passSchema = { curvature: 0.1, scanlineIntensity: 0.2 } as const
  declare curvature: number
  declare scanlineIntensity: number

  static buildPass({ uniforms }: PassEffectContext): PassEffectFn {
    return (input, uv) => crtComplete(input, uv, {
      curvature: uniforms.curvature,
      scanlineIntensity: uniforms.scanlineIntensity,
    })
  }
}
```

```typescript
const VignetteEffect = createPassEffect({
  name: 'vignette',
  schema: { intensity: 0.5 },
  pass: ({ uniforms }) => (input, uv) => vignette(input, uv, uniforms.intensity),
})
```

## Constructors

### Constructor

> **new PassEffect**(): `PassEffect`

Defined in: [packages/three-flatland/src/pipeline/PassEffect.ts:197](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/PassEffect.ts#L197)

#### Returns

`PassEffect`

## Properties

### name

> `readonly` **name**: `string`

Defined in: [packages/three-flatland/src/pipeline/PassEffect.ts:171](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/PassEffect.ts#L171)

Pass name (from static).

***

### passName

> `readonly` `static` **passName**: `string`

Defined in: [packages/three-flatland/src/pipeline/PassEffect.ts:90](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/PassEffect.ts#L90)

Unique pass name. Must be overridden by subclass.

***

### passSchema

> `readonly` `static` **passSchema**: [`EffectSchema`](/three-flatland/api/three-flatland/src/type-aliases/effectschema/)

Defined in: [packages/three-flatland/src/pipeline/PassEffect.ts:92](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/PassEffect.ts#L92)

Per-pass data schema with default values. Must be overridden by subclass.

## Accessors

### enabled

#### Get Signature

> **get** **enabled**(): `boolean`

Defined in: [packages/three-flatland/src/pipeline/PassEffect.ts:262](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/PassEffect.ts#L262)

Whether this pass is enabled in the chain.

##### Returns

`boolean`

#### Set Signature

> **set** **enabled**(`value`): `void`

Defined in: [packages/three-flatland/src/pipeline/PassEffect.ts:267](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/PassEffect.ts#L267)

Toggle enabled state. This is a structural change — rebuilds the chain.

##### Parameters

###### value

`boolean`

##### Returns

`void`

## Methods

### buildPass()

> `static` **buildPass**(`_context`): [`PassEffectFn`](/three-flatland/api/three-flatland/src/type-aliases/passeffectfn/)

Defined in: [packages/three-flatland/src/pipeline/PassEffect.ts:108](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/PassEffect.ts#L108)

Build the pass function. Must be overridden by subclass (class-based path).
Called once when the pass is added to Flatland. The returned function closes
over uniform nodes for zero-cost parameter updates.

#### Parameters

##### \_context

[`PassEffectContext`](/three-flatland/api/three-flatland/src/interfaces/passeffectcontext/)

#### Returns

[`PassEffectFn`](/three-flatland/api/three-flatland/src/type-aliases/passeffectfn/)

# Sprite2D

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:80](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L80)

A 2D sprite for use with three-flatland's render pipeline.

Extends THREE.Mesh, so it works with standard Three.js scene graph
but designed for batched 2D rendering with explicit z-ordering.

**Two rendering modes:**
- **Standalone** (not enrolled): Setters write to snapshot + own geometry buffers immediately.
- **Batched** (enrolled in SpriteGroup): Setters write to ECS traits only.
  Systems sync traits to batch buffers in `updateMatrixWorld()`.

## Example

```typescript
const sprite = new Sprite2D({
  texture: myTexture,
  frame: spriteSheet.getFrame('player_idle'),
  anchor: [0.5, 1], // Bottom center
});
sprite.position.set(100, 200, 0);
sprite.layer = Layers.ENTITIES;
sprite.zIndex = sprite.position.y; // Y-sort
scene.add(sprite);
```

## Extends

- [`Mesh`](https://threejs.org/docs/#api/en/objects/Mesh)

## Extended by

- [`AnimatedSprite2D`](/three-flatland/api/three-flatland/src/classes/animatedsprite2d/)

## Constructors

### Constructor

> **new Sprite2D**(`options?`): `Sprite2D`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:394](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L394)

Create a new Sprite2D.
Can be called with no arguments for R3F compatibility - set texture via property.

#### Parameters

##### options?

[`Sprite2DOptions`](/three-flatland/api/three-flatland/src/interfaces/sprite2doptions/)

#### Returns

`Sprite2D`

#### Overrides

`Mesh.constructor`

## Properties

### \_idx

> **\_idx**: `number` = `0`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:287](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L287)

Index into the backing arrays (0 when standalone, eid when enrolled).

***

### animations

> **animations**: [`AnimationClip`](https://threejs.org/docs/)[]

Defined in: [three.js/core/Object3D:animations](https://threejs.org/docs/#api/en/core/Object3D.animations)

Array with object's animation clips.

#### Default Value

`[]`

#### Inherited from

`Mesh.animations`

***

### castShadow

> **castShadow**: `boolean`

Defined in: [three.js/core/Object3D:castShadow](https://threejs.org/docs/#api/en/core/Object3D.castShadow)

Whether the object gets rendered into shadow map.

#### Default Value

`false`

#### Inherited from

`Mesh.castShadow`

***

### children

> **children**: [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

Defined in: [three.js/core/Object3D:children](https://threejs.org/docs/#api/en/core/Object3D.children)

Array with object's children.

#### See

THREE.Object3DGroup \| Group for info on manually grouping objects.

#### Default Value

`[]`

#### Inherited from

`Mesh.children`

***

### count

> **count**: `number`

Defined in: [three.js/objects/Mesh:count](https://threejs.org/docs/#api/en/objects/Mesh.count)

The number of instances of this mesh.
Can only be used with WebGPURenderer.

#### Default

```ts
1
```

#### Inherited from

`Mesh.count`

***

### customDepthMaterial?

> `optional` **customDepthMaterial?**: [`Material`](https://threejs.org/docs/#api/en/materials/Material)

Defined in: [three.js/core/Object3D:customDepthMaterial](https://threejs.org/docs/#api/en/core/Object3D.customDepthMaterial)

Custom depth material to be used when rendering to the depth map.

#### Remarks

Can only be used in context of meshes.
When shadow-casting with a THREE.DirectionalLight \| DirectionalLight or THREE.SpotLight \| SpotLight,
if you are modifying vertex positions in the vertex shader you must specify a customDepthMaterial for proper shadows.

#### Default Value

`undefined`

#### Inherited from

`Mesh.customDepthMaterial`

***

### customDistanceMaterial?

> `optional` **customDistanceMaterial?**: [`Material`](https://threejs.org/docs/#api/en/materials/Material)

Defined in: [three.js/core/Object3D:customDistanceMaterial](https://threejs.org/docs/#api/en/core/Object3D.customDistanceMaterial)

Same as [customDepthMaterial](/three-flatland/api/three-flatland/src/classes/flatland/#customdepthmaterial), but used with THREE.Object3DPointLight \| PointLight.

#### Default Value

`undefined`

#### Inherited from

`Mesh.customDistanceMaterial`

***

### frustumCulled

> **frustumCulled**: `boolean`

Defined in: [three.js/core/Object3D:frustumCulled](https://threejs.org/docs/#api/en/core/Object3D.frustumCulled)

When this is set, it checks every frame if the object is in the frustum of the camera before rendering the object.
If set to `false` the object gets rendered every frame even if it is not in the frustum of the camera.

#### Default Value

`true`

#### Inherited from

`Mesh.frustumCulled`

***

### geometry

> **geometry**: [`PlaneGeometry`](https://threejs.org/docs/#api/en/geometries/PlaneGeometry)

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:81](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L81)

An instance of THREE.BufferGeometry \| BufferGeometry (or derived classes), defining the object's structure.

#### Default Value

THREE.BufferGeometry \| \`new THREE.BufferGeometry()\`.

#### Overrides

`Mesh.geometry`

***

### id

> `readonly` **id**: `number`

Defined in: [three.js/core/Object3D:id](https://threejs.org/docs/#api/en/core/Object3D.id)

Unique number for this [Object3D](https://threejs.org/docs/#api/en/core/Object3D) instance.

#### Remarks

Note that ids are assigned in chronological order: 1, 2, 3, ..., incrementing by one for each new object.
Expects a `Integer`

#### Inherited from

`Mesh.id`

***

### isMesh

> `readonly` **isMesh**: `true`

Defined in: [three.js/objects/Mesh:isMesh](https://threejs.org/docs/#api/en/objects/Mesh.isMesh)

Read-only flag to check if a given object is of type [Mesh](https://threejs.org/docs/#api/en/objects/Mesh).

#### Remarks

This is a _constant_ value

#### Default Value

`true`

#### Inherited from

`Mesh.isMesh`

***

### isObject3D

> `readonly` **isObject3D**: `true`

Defined in: [three.js/core/Object3D:isObject3D](https://threejs.org/docs/#api/en/core/Object3D.isObject3D)

Flag to check if a given object is of type [Object3D](https://threejs.org/docs/#api/en/core/Object3D).

#### Remarks

This is a _constant_ value

#### Default Value

`true`

#### Inherited from

`Mesh.isObject3D`

***

### layers

> **layers**: [`Layers`](https://threejs.org/docs/#api/en/core/Layers)

Defined in: [three.js/core/Object3D:layers](https://threejs.org/docs/#api/en/core/Object3D.layers)

The layer membership of the object.

#### Remarks

The object is only visible if it has at least one layer in common with the THREE.Object3DCamera \| Camera in use.
This property can also be used to filter out unwanted objects in ray-intersection tests when using THREE.Raycaster \| Raycaster.

#### Default Value

`new THREE.Layers()`

#### Inherited from

`Mesh.layers`

***

### material

> **material**: [`Sprite2DMaterial`](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/)

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:82](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L82)

An instance of material derived from the THREE.Material \| Material base class or an array of materials, defining the object's appearance.

#### Default Value

THREE.MeshBasicMaterial \| \`new THREE.MeshBasicMaterial()\`.

#### Overrides

`Mesh.material`

***

### matrix

> **matrix**: [`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Defined in: [three.js/core/Object3D:matrix](https://threejs.org/docs/#api/en/core/Object3D.matrix)

The local transform matrix.

#### Default Value

`new THREE.Matrix4()`

#### Inherited from

`Mesh.matrix`

***

### matrixAutoUpdate

> **matrixAutoUpdate**: `boolean`

Defined in: [three.js/core/Object3D:matrixAutoUpdate](https://threejs.org/docs/#api/en/core/Object3D.matrixAutoUpdate)

When this is set, it calculates the matrix of position, (rotation or quaternion) and
scale every frame and also recalculates the matrixWorld property.

#### Default Value

[DEFAULT\_MATRIX\_AUTO\_UPDATE](/three-flatland/api/three-flatland/src/classes/flatland/#default_matrix_auto_update) - that is `(true)`.

#### Inherited from

`Mesh.matrixAutoUpdate`

***

### matrixWorld

> **matrixWorld**: [`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Defined in: [three.js/core/Object3D:matrixWorld](https://threejs.org/docs/#api/en/core/Object3D.matrixWorld)

The global transform of the object.

#### Remarks

If the [Object3D](https://threejs.org/docs/#api/en/core/Object3D) has no parent, then it's identical to the local transform THREE.Object3D.matrix \| .matrix.

#### Default Value

`new THREE.Matrix4()`

#### Inherited from

`Mesh.matrixWorld`

***

### matrixWorldAutoUpdate

> **matrixWorldAutoUpdate**: `boolean`

Defined in: [three.js/core/Object3D:matrixWorldAutoUpdate](https://threejs.org/docs/#api/en/core/Object3D.matrixWorldAutoUpdate)

If set, then the renderer checks every frame if the object and its children need matrix updates.
When it isn't, then you have to maintain all matrices in the object and its children yourself.

#### Default Value

[DEFAULT\_MATRIX\_WORLD\_AUTO\_UPDATE](/three-flatland/api/three-flatland/src/classes/flatland/#default_matrix_world_auto_update) - that is `(true)`.

#### Inherited from

`Mesh.matrixWorldAutoUpdate`

***

### matrixWorldNeedsUpdate

> **matrixWorldNeedsUpdate**: `boolean`

Defined in: [three.js/core/Object3D:matrixWorldNeedsUpdate](https://threejs.org/docs/#api/en/core/Object3D.matrixWorldNeedsUpdate)

When this is set, it calculates the matrixWorld in that frame and resets this property to false.

#### Default Value

`false`

#### Inherited from

`Mesh.matrixWorldNeedsUpdate`

***

### modelViewMatrix

> `readonly` **modelViewMatrix**: [`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Defined in: [three.js/core/Object3D:modelViewMatrix](https://threejs.org/docs/#api/en/core/Object3D.modelViewMatrix)

#### Default Value

`new THREE.Matrix4()`

#### Inherited from

`Mesh.modelViewMatrix`

***

### morphTargetDictionary?

> `optional` **morphTargetDictionary?**: `object`

Defined in: [three.js/objects/Mesh:morphTargetDictionary](https://threejs.org/docs/#api/en/objects/Mesh.morphTargetDictionary)

A dictionary of morphTargets based on the `morphTarget.name` property.

#### Index Signature

\[`key`: `string`\]: `number`

#### Default Value

`undefined`, _but rebuilt by [.updateMorphTargets()](https://threejs.org/docs/)._

#### Inherited from

`Mesh.morphTargetDictionary`

***

### morphTargetInfluences?

> `optional` **morphTargetInfluences?**: `number`[]

Defined in: [three.js/objects/Mesh:morphTargetInfluences](https://threejs.org/docs/#api/en/objects/Mesh.morphTargetInfluences)

An array of weights typically from `0-1` that specify how much of the morph is applied.

#### Default Value

`undefined`, _but reset to a blank array by [.updateMorphTargets()](https://threejs.org/docs/)._

#### Inherited from

`Mesh.morphTargetInfluences`

***

### name

> **name**: `string`

Defined in: [three.js/core/Object3D:name](https://threejs.org/docs/#api/en/core/Object3D.name)

Optional name of the object

#### Remarks

_(doesn't need to be unique)_.

#### Default Value

`""`

#### Inherited from

`Mesh.name`

***

### normalMatrix

> `readonly` **normalMatrix**: [`Matrix3`](https://threejs.org/docs/#api/en/math/Matrix3)

Defined in: [three.js/core/Object3D:normalMatrix](https://threejs.org/docs/#api/en/core/Object3D.normalMatrix)

#### Default Value

`new THREE.Matrix3()`

#### Inherited from

`Mesh.normalMatrix`

***

### occlusionTest?

> `optional` **occlusionTest?**: `boolean`

Defined in: [three.js/renderers/common/Backend:occlusionTest](https://threejs.org/docs/#api/en/renderers/common/Backend.occlusionTest)

#### Inherited from

`Mesh.occlusionTest`

***

### parent

> **parent**: [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `null`

Defined in: [three.js/core/Object3D:parent](https://threejs.org/docs/#api/en/core/Object3D.parent)

Object's parent in the [scene graph](https://en.wikipedia.org/wiki/Scene_graph).

#### Remarks

An object can have at most one parent.

#### Default Value

`null`

#### Inherited from

`Mesh.parent`

***

### pivot

> **pivot**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3) \| `null`

Defined in: [three.js/core/Object3D:pivot](https://threejs.org/docs/#api/en/core/Object3D.pivot)

The pivot point for rotation and scale transformations.
When set, rotation and scale are applied around this point
instead of the object's origin.

#### Default

```ts
null
```

#### Inherited from

`Mesh.pivot`

***

### pixelPerfect

> **pixelPerfect**: `boolean` = `false`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:106](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L106)

Pixel-perfect mode

***

### position

> `readonly` **position**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:position](https://threejs.org/docs/#api/en/core/Object3D.position)

Object's local position.

#### Default Value

`new THREE.Vector3()` - that is `(0, 0, 0)`.

#### Inherited from

`Mesh.position`

***

### quaternion

> `readonly` **quaternion**: [`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

Defined in: [three.js/core/Object3D:quaternion](https://threejs.org/docs/#api/en/core/Object3D.quaternion)

Object's local rotation as a THREE.Quaternion \| Quaternion.

#### Default Value

`new THREE.Quaternion()` - that is `(0,  0, 0, 1)`.

#### Inherited from

`Mesh.quaternion`

***

### receiveShadow

> **receiveShadow**: `boolean`

Defined in: [three.js/core/Object3D:receiveShadow](https://threejs.org/docs/#api/en/core/Object3D.receiveShadow)

Whether the material receives shadows.

#### Default Value

`false`

#### Inherited from

`Mesh.receiveShadow`

***

### renderOrder

> **renderOrder**: `number`

Defined in: [three.js/core/Object3D:renderOrder](https://threejs.org/docs/#api/en/core/Object3D.renderOrder)

This value allows the default rendering order of [scene graph](https://en.wikipedia.org/wiki/Scene_graph)
objects to be overridden although opaque and transparent objects remain sorted independently.

#### Remarks

When this property is set for an instance of [Group](https://threejs.org/docs/#api/en/objects/Group), all descendants objects will be sorted and rendered together.
Sorting is from lowest to highest renderOrder.

#### Default Value

`0`

#### Inherited from

`Mesh.renderOrder`

***

### rotation

> `readonly` **rotation**: [`Euler`](https://threejs.org/docs/#api/en/math/Euler)

Defined in: [three.js/core/Object3D:rotation](https://threejs.org/docs/#api/en/core/Object3D.rotation)

Object's local rotation ([Euler angles](https://en.wikipedia.org/wiki/Euler_angles)), in radians.

#### Default Value

`new THREE.Euler()` - that is `(0, 0, 0, Euler.DEFAULT_ORDER)`.

#### Inherited from

`Mesh.rotation`

***

### scale

> `readonly` **scale**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:scale](https://threejs.org/docs/#api/en/core/Object3D.scale)

The object's local scale.

#### Default Value

`new THREE.Vector3( 1, 1, 1 )`

#### Inherited from

`Mesh.scale`

***

### static

> **static**: `boolean`

Defined in: [three.js/core/Object3D:static](https://threejs.org/docs/#api/en/core/Object3D.static)

Whether the 3D object is supposed to be static or not. If set to `true`, it means
the 3D object is not going to be changed after the initial renderer. This includes
geometry and material settings. A static 3D object can be processed by the renderer
slightly faster since certain state checks can be bypassed.

Only relevant in context of WebGPURenderer.

#### Default

```ts
false
```

#### Inherited from

`Mesh.static`

***

### type

> `readonly` **type**: `string`

Defined in: [three.js/objects/Mesh:type](https://threejs.org/docs/#api/en/objects/Mesh.type)

#### Default Value

`Mesh`

#### Inherited from

`Mesh.type`

***

### up

> **up**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:up](https://threejs.org/docs/#api/en/core/Object3D.up)

This is used by the [lookAt](https://threejs.org/docs/) method, for example, to determine the orientation of the result.

#### Default Value

[Object3D.DEFAULT\_UP](/three-flatland/api/three-flatland/src/classes/flatland/#default_up) - that is `(0, 1, 0)`.

#### Inherited from

`Mesh.up`

***

### userData

> **userData**: `Record`\<`string`, `any`\>

Defined in: [three.js/core/Object3D:userData](https://threejs.org/docs/#api/en/core/Object3D.userData)

An object that can be used to store custom data about the [Object3D](https://threejs.org/docs/#api/en/core/Object3D).

#### Remarks

It should not hold references to _functions_ as these **will not** be cloned.

#### Default

`{}`

#### Inherited from

`Mesh.userData`

***

### uuid

> **uuid**: `string`

Defined in: [three.js/core/Object3D:uuid](https://threejs.org/docs/#api/en/core/Object3D.uuid)

[UUID](http://en.wikipedia.org/wiki/Universally_unique_identifier) of this object instance.

#### Remarks

This gets automatically assigned and shouldn't be edited.

#### Inherited from

`Mesh.uuid`

***

### visible

> **visible**: `boolean`

Defined in: [three.js/core/Object3D:visible](https://threejs.org/docs/#api/en/core/Object3D.visible)

Object gets rendered if `true`.

#### Default Value

`true`

#### Inherited from

`Mesh.visible`

***

### DEFAULT\_MATRIX\_AUTO\_UPDATE

> `static` **DEFAULT\_MATRIX\_AUTO\_UPDATE**: `boolean`

Defined in: [three.js/core/Object3D:DEFAULT_MATRIX_AUTO_UPDATE](https://threejs.org/docs/#api/en/core/Object3D.DEFAULT_MATRIX_AUTO_UPDATE)

The default setting for [matrixAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixautoupdate) for newly created Object3Ds.

#### Default Value

`true`

#### Inherited from

`Mesh.DEFAULT_MATRIX_AUTO_UPDATE`

***

### DEFAULT\_MATRIX\_WORLD\_AUTO\_UPDATE

> `static` **DEFAULT\_MATRIX\_WORLD\_AUTO\_UPDATE**: `boolean`

Defined in: [three.js/core/Object3D:DEFAULT_MATRIX_WORLD_AUTO_UPDATE](https://threejs.org/docs/#api/en/core/Object3D.DEFAULT_MATRIX_WORLD_AUTO_UPDATE)

The default setting for [matrixWorldAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldautoupdate) for newly created Object3Ds.

#### Default Value

`true`

#### Inherited from

`Mesh.DEFAULT_MATRIX_WORLD_AUTO_UPDATE`

***

### DEFAULT\_UP

> `static` **DEFAULT\_UP**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:DEFAULT_UP](https://threejs.org/docs/#api/en/core/Object3D.DEFAULT_UP)

The default [up](/three-flatland/api/three-flatland/src/classes/flatland/#up) direction for objects, also used as the default position for THREE.DirectionalLight \| DirectionalLight,
THREE.HemisphereLight \| HemisphereLight and THREE.Spotlight \| Spotlight (which creates lights shining from the top down).

#### Default Value

`new THREE.Vector3( 0, 1, 0)`

#### Inherited from

`Mesh.DEFAULT_UP`

## Accessors

### alpha

#### Get Signature

> **get** **alpha**(): `number`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:793](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L793)

Get alpha/opacity.

##### Returns

`number`

#### Set Signature

> **set** **alpha**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:800](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L800)

Set alpha/opacity (0-1).

##### Parameters

###### value

`number`

##### Returns

`void`

***

### anchor

#### Get Signature

> **get** **anchor**(): [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:739](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L739)

Get the anchor point. Returns the stored Vector2 (like Object3D.position).

##### Returns

[`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

#### Set Signature

> **set** **anchor**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:746](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L746)

Set the anchor point. Accepts [x, y] array or Vector2.

##### Parameters

###### value

\[`number`, `number`\] \| [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

##### Returns

`void`

***

### castsShadow

#### Get Signature

> **get** **castsShadow**(): `boolean`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:219](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L219)

Whether this sprite contributes its silhouette to the shadow-caster
occlusion pre-pass. Stored as bit 2 of `_systemFlags`. Default: `false`
— most sprites don't cast; opt in by setting to `true`.

Consumed by the occlusion pre-pass shader, which masks the sprite's
alpha by this bit before the SDF seed. Flipping it takes effect on
the next frame with zero CPU rebuild (same model as `receiveShadows`).

##### Returns

`boolean`

#### Set Signature

> **set** **castsShadow**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:223](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L223)

##### Parameters

###### value

`boolean`

##### Returns

`void`

***

### flipX

#### Get Signature

> **get** **flipX**(): `boolean`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:819](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L819)

Get flipX state.

##### Returns

`boolean`

#### Set Signature

> **set** **flipX**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:826](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L826)

Set flipX state.

##### Parameters

###### value

`boolean`

##### Returns

`void`

***

### flipY

#### Get Signature

> **get** **flipY**(): `boolean`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:841](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L841)

Get flipY state.

##### Returns

`boolean`

#### Set Signature

> **set** **flipY**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:848](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L848)

Set flipY state.

##### Parameters

###### value

`boolean`

##### Returns

`void`

***

### frame

#### Get Signature

> **get** **frame**(): [`SpriteFrame`](/three-flatland/api/three-flatland/src/interfaces/spriteframe/) \| `null`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:691](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L691)

Get the current frame.

##### Returns

[`SpriteFrame`](/three-flatland/api/three-flatland/src/interfaces/spriteframe/) \| `null`

#### Set Signature

> **set** **frame**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:698](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L698)

Set the current frame (R3F prop compatibility).

##### Parameters

###### value

[`SpriteFrame`](/three-flatland/api/three-flatland/src/interfaces/spriteframe/) \| `null`

##### Returns

`void`

***

### height

#### Get Signature

> **get** **height**(): `number`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:940](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L940)

Get the height of the sprite in world units.

##### Returns

`number`

***

### layer

#### Get Signature

> **get** **layer**(): `number`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:880](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L880)

Get render layer (primary sort key).

##### Returns

`number`

#### Set Signature

> **set** **layer**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:887](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L887)

Set render layer (primary sort key).

##### Parameters

###### value

`number`

##### Returns

`void`

***

### lit

#### Get Signature

> **get** **lit**(): `boolean`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:114](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L114)

Whether this sprite receives lighting from Flatland's LightEffect.
Stored as bit 0 of `_systemFlags` so lit/unlit sprites with the same
texture share the same material and batch together.
Default: `true` — set `lit = false` to opt out.

##### Returns

`boolean`

#### Set Signature

> **set** **lit**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:118](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L118)

##### Parameters

###### value

`boolean`

##### Returns

`void`

***

### receiveShadows

#### Get Signature

> **get** **receiveShadows**(): `boolean`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:141](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L141)

Whether this sprite receives shadows from the SDF shadow pipeline.
Stored as bit 1 of `_systemFlags`.
Default: `true` — set `receiveShadows = false` to opt out.

##### Returns

`boolean`

#### Set Signature

> **set** **receiveShadows**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:145](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L145)

##### Parameters

###### value

`boolean`

##### Returns

`void`

***

### shadowRadius

#### Get Signature

> **get** **shadowRadius**(): `number` \| `undefined`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:193](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L193)

Per-sprite occluder radius (world units) consumed by shadow-casting
LightEffects — e.g. DefaultLightEffect's SDF sphere-tracer
uses it as the self-silhouette escape distance so a tracer launched
from inside the caster steps out cleanly.

Returns `undefined` while in auto-resolve mode (default), in which
case `transformSyncSystem` writes `max(|scale.x|, |scale.y|)` into
the per-instance attribute each frame — covering animation frames
and runtime scale changes without manual updates. Assign a number
to override (useful when the visible body is tighter than the
quad's bounds, or when an off-center anchor pushes the silhouette).
Assign `undefined` to return to auto-resolve.

##### Returns

`number` \| `undefined`

#### Set Signature

> **set** **shadowRadius**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:197](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L197)

##### Parameters

###### value

`number` \| `undefined`

##### Returns

`void`

***

### texture

#### Get Signature

> **get** **texture**(): [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:605](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L605)

Get the current texture.

##### Returns

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

#### Set Signature

> **set** **texture**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:612](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L612)

Set a new texture.

##### Parameters

###### value

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

##### Returns

`void`

***

### tint

#### Get Signature

> **get** **tint**(): [`Color`](https://threejs.org/docs/#api/en/math/Color)

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:772](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L772)

Get tint color. Returns a stored Color reference (like Material.color).
Mutating the returned Color triggers ECS sync via onChange callback.

##### Returns

[`Color`](https://threejs.org/docs/#api/en/math/Color)

#### Set Signature

> **set** **tint**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:779](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L779)

Set tint color. Accepts Color, hex string, hex number, or [r, g, b] array (0-1).

##### Parameters

###### value

`string` \| `number` \| \[`number`, `number`, `number`\] \| [`Color`](https://threejs.org/docs/#api/en/math/Color)

##### Returns

`void`

***

### width

#### Get Signature

> **get** **width**(): `number`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:933](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L933)

Get the width of the sprite in world units.

##### Returns

`number`

***

### zIndex

#### Get Signature

> **get** **zIndex**(): `number`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:897](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L897)

Get z-index within layer (secondary sort key).

##### Returns

`number`

#### Set Signature

> **set** **zIndex**(`value`): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:919](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L919)

Set z-index within layer (secondary sort key).

Hot path. Every moving sprite in a y-sorted scene calls this every
frame, so the cost has to stay near-zero per call.

The raw SoA write is unconditional — `transformSyncSystem` reads
`_zIndexArr` directly and bakes the value into the instance matrix
for the GPU depth test. That alone is enough for alphaTest+depthWrite
materials (GPU resolves order via the baked-in Z, no CPU sort needed).

For non-gated materials, we flip the batch's `_sortDirty` flag so
`batchSortSystem` knows to re-sort this batch on its next pass. This
replaced the prior `Changed(SpriteZIndex)` channel — Koota's change
tracker enumerated every flip every frame even when the gate trivially
skipped the sort, costing ~7ms/frame in a 12k-sprite demo. The
per-batch boolean costs one ref read + one write.

##### Parameters

###### value

`number`

##### Returns

`void`

## Methods

### \_setupInstanceAttributes()

> **\_setupInstanceAttributes**(): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:1003](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L1003)

Set up instance attributes on the geometry for single-sprite rendering.
Uses one interleaved buffer (mirroring SpriteBatch) so batched and
standalone paths share the same shader attribute shape. Also
allocates buffers for custom attributes from the material's schema
(pure effect data — `effectBuf0`, `effectBuf1`, ...).

#### Returns

`void`

***

### add()

> **add**(...`object`): `this`

Defined in: [three.js/core/Object3D:add](https://threejs.org/docs/#api/en/core/Object3D.add)

Adds another [Object3D](https://threejs.org/docs/#api/en/core/Object3D) as child of this [Object3D](https://threejs.org/docs/#api/en/core/Object3D).

#### Parameters

##### object

...[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

#### Returns

`this`

#### Remarks

An arbitrary number of objects may be added
Any current parent on an object passed in here will be removed, since an [Object3D](https://threejs.org/docs/#api/en/core/Object3D) can have at most one parent.

#### See

 - [attach](https://threejs.org/docs/)
 - THREE.Group \| Group for info on manually grouping objects.

#### Inherited from

`Mesh.add`

***

### addEffect()

> **addEffect**(`effect`): `this`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:1105](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L1105)

Add an effect instance to this sprite.
Auto-registers the effect type on the material if not already registered.
Sets the enable bit and writes effect data to packed buffers.

#### Parameters

##### effect

[`MaterialEffect`](/three-flatland/api/three-flatland/src/classes/materialeffect/)

#### Returns

`this`

#### Example

```typescript
const dissolve = new DissolveEffect()
dissolve.progress = 0.5
sprite.addEffect(dissolve)
```

***

### addEventListener()

> **addEventListener**\<`T`\>(`type`, `listener`): `void`

Defined in: [three.js/core/EventDispatcher:addEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.addEventListener)

Adds a listener to an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### type

`T`

The type of event to listen to.

##### listener

[`EventListener`](https://threejs.org/docs/)\<[`Object3DEventMap`](https://threejs.org/docs/)\[`T`\], `T`, `Sprite2D`\>

The function that gets called when the event is fired.

#### Returns

`void`

#### Inherited from

`Mesh.addEventListener`

***

### applyMatrix4()

> **applyMatrix4**(`matrix`): `void`

Defined in: [three.js/core/Object3D:applyMatrix4](https://threejs.org/docs/#api/en/core/Object3D.applyMatrix4)

Applies the matrix transform to the object and updates the object's position, rotation and scale.

#### Parameters

##### matrix

[`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

#### Returns

`void`

#### Inherited from

`Mesh.applyMatrix4`

***

### applyQuaternion()

> **applyQuaternion**(`quaternion`): `this`

Defined in: [three.js/core/Object3D:applyQuaternion](https://threejs.org/docs/#api/en/core/Object3D.applyQuaternion)

Applies the rotation represented by the quaternion to the object.

#### Parameters

##### quaternion

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

#### Returns

`this`

#### Inherited from

`Mesh.applyQuaternion`

***

### attach()

> **attach**(`object`): `this`

Defined in: [three.js/core/Object3D:attach](https://threejs.org/docs/#api/en/core/Object3D.attach)

Adds a [Object3D](https://threejs.org/docs/#api/en/core/Object3D) as a child of this, while maintaining the object's world transform.

#### Parameters

##### object

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)

#### Returns

`this`

#### Remarks

Note: This method does not support scene graphs having non-uniformly-scaled nodes(s).

#### See

[add](https://threejs.org/docs/)

#### Inherited from

`Mesh.attach`

***

### clear()

> **clear**(): `this`

Defined in: [three.js/core/Object3D:clear](https://threejs.org/docs/#api/en/core/Object3D.clear)

Removes all child objects.

#### Returns

`this`

#### Inherited from

`Mesh.clear`

***

### clone()

> **clone**(`recursive?`): `this`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:1669](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L1669)

Clone the sprite.

#### Parameters

##### recursive?

`boolean`

#### Returns

`this`

#### Overrides

`Mesh.clone`

***

### copy()

> **copy**(`object`, `recursive?`): `this`

Defined in: [three.js/core/Object3D:copy](https://threejs.org/docs/#api/en/core/Object3D.copy)

Copies the given object into this object.

#### Parameters

##### object

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)

##### recursive?

`boolean`

If set to `true`, descendants of the object are copied next to the existing ones. If set to
`false`, descendants are left unchanged. Default is `true`.

#### Returns

`this`

#### Remarks

Event listeners and user-defined callbacks (.onAfterRender and .onBeforeRender) are not copied.

#### Inherited from

`Mesh.copy`

***

### dispatchEvent()

> **dispatchEvent**\<`T`\>(`event`): `void`

Defined in: [three.js/core/EventDispatcher:dispatchEvent](https://threejs.org/docs/#api/en/core/EventDispatcher.dispatchEvent)

Fire an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### event

[`BaseEvent`](https://threejs.org/docs/)\<`T`\> & [`Object3DEventMap`](https://threejs.org/docs/)\[`T`\]

The event that gets fired.

#### Returns

`void`

#### Inherited from

`Mesh.dispatchEvent`

***

### dispose()

> **dispose**(): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:1648](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L1648)

Dispose of resources.

#### Returns

`void`

***

### flip()

> **flip**(`horizontal`, `vertical`): `this`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:863](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L863)

Flip the sprite.

#### Parameters

##### horizontal

`boolean`

##### vertical

`boolean`

#### Returns

`this`

***

### getObjectById()

> **getObjectById**(`id`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

Defined in: [three.js/core/Object3D:getObjectById](https://threejs.org/docs/#api/en/core/Object3D.getObjectById)

Searches through an object and its children, starting with the object itself, and returns the first with a matching id.

#### Parameters

##### id

`number`

Unique number of the object instance. Expects a `Integer`

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

#### Remarks

Note that ids are assigned in chronological order: 1, 2, 3, ..., incrementing by one for each new object.

#### See

id

#### Inherited from

`Mesh.getObjectById`

***

### getObjectByName()

> **getObjectByName**(`name`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

Defined in: [three.js/core/Object3D:getObjectByName](https://threejs.org/docs/#api/en/core/Object3D.getObjectByName)

Searches through an object and its children, starting with the object itself, and returns the first with a matching name.

#### Parameters

##### name

`string`

String to match to the children's Object3D.name property.

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

#### Remarks

Note that for most objects the name is an empty string by default
You will have to set it manually to make use of this method.

#### Inherited from

`Mesh.getObjectByName`

***

### getObjectByProperty()

> **getObjectByProperty**(`name`, `value`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

Defined in: [three.js/core/Object3D:getObjectByProperty](https://threejs.org/docs/#api/en/core/Object3D.getObjectByProperty)

Searches through an object and its children, starting with the object itself,
and returns the first with a property that matches the value given.

#### Parameters

##### name

`string`

the property name to search for.

##### value

`any`

value of the given property.

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

#### Inherited from

`Mesh.getObjectByProperty`

***

### getObjectsByProperty()

> **getObjectsByProperty**(`name`, `value`, `optionalTarget?`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

Defined in: [three.js/core/Object3D:getObjectsByProperty](https://threejs.org/docs/#api/en/core/Object3D.getObjectsByProperty)

Searches through an object and its children, starting with the object itself,
and returns the first with a property that matches the value given.

#### Parameters

##### name

`string`

The property name to search for.

##### value

`any`

Value of the given property.

##### optionalTarget?

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

target to set the result. Otherwise a new Array is instantiated. If set, you must clear
this array prior to each call (i.e., array.length = 0;).

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

#### Inherited from

`Mesh.getObjectsByProperty`

***

### getVertexPosition()

> **getVertexPosition**(`index`, `target`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/objects/Mesh:getVertexPosition](https://threejs.org/docs/#api/en/objects/Mesh.getVertexPosition)

Get the local-space position of the vertex at the given index,
taking into account the current animation state of both morph targets and skinning.

#### Parameters

##### index

`number`

Expects a `Integer`

##### target

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Mesh.getVertexPosition`

***

### getWorldDirection()

> **getWorldDirection**(`target`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:getWorldDirection](https://threejs.org/docs/#api/en/core/Object3D.getWorldDirection)

Returns a vector representing the direction of object's positive z-axis in world space.

#### Parameters

##### target

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

The result will be copied into this Vector3.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Mesh.getWorldDirection`

***

### getWorldPosition()

> **getWorldPosition**(`target`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:getWorldPosition](https://threejs.org/docs/#api/en/core/Object3D.getWorldPosition)

Returns a vector representing the position of the object in world space.

#### Parameters

##### target

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

The result will be copied into this Vector3.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Mesh.getWorldPosition`

***

### getWorldPosition2D()

> **getWorldPosition2D**(): [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:1083](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L1083)

Get world position (convenience method).

#### Returns

[`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

***

### getWorldQuaternion()

> **getWorldQuaternion**(`target`): [`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

Defined in: [three.js/core/Object3D:getWorldQuaternion](https://threejs.org/docs/#api/en/core/Object3D.getWorldQuaternion)

Returns a quaternion representing the rotation of the object in world space.

#### Parameters

##### target

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

The result will be copied into this Quaternion.

#### Returns

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

#### Inherited from

`Mesh.getWorldQuaternion`

***

### getWorldScale()

> **getWorldScale**(`target`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:getWorldScale](https://threejs.org/docs/#api/en/core/Object3D.getWorldScale)

Returns a vector of the scaling factors applied to the object for each axis in world space.

#### Parameters

##### target

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

The result will be copied into this Vector3.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Mesh.getWorldScale`

***

### hasEventListener()

> **hasEventListener**\<`T`\>(`type`, `listener`): `boolean`

Defined in: [three.js/core/EventDispatcher:hasEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.hasEventListener)

Checks if listener is added to an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### type

`T`

The type of event to listen to.

##### listener

[`EventListener`](https://threejs.org/docs/)\<[`Object3DEventMap`](https://threejs.org/docs/)\[`T`\], `T`, `Sprite2D`\>

The function that gets called when the event is fired.

#### Returns

`boolean`

#### Inherited from

`Mesh.hasEventListener`

***

### localToWorld()

> **localToWorld**(`vector`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:localToWorld](https://threejs.org/docs/#api/en/core/Object3D.localToWorld)

Converts the vector from this object's local space to world space.

#### Parameters

##### vector

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A vector representing a position in this object's local space.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Mesh.localToWorld`

***

### lookAt()

#### Call Signature

> **lookAt**(`vector`): `void`

Defined in: [three.js/core/Object3D:lookAt](https://threejs.org/docs/#api/en/core/Object3D.lookAt)

Rotates the object to face a point in world space.

##### Parameters

###### vector

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A vector representing a position in world space to look at.

##### Returns

`void`

##### Remarks

This method does not support objects having non-uniformly-scaled parent(s).

##### Inherited from

`Mesh.lookAt`

#### Call Signature

> **lookAt**(`x`, `y`, `z`): `void`

Defined in: [three.js/core/Object3D:lookAt](https://threejs.org/docs/#api/en/core/Object3D.lookAt)

Rotates the object to face a point in world space.

##### Parameters

###### x

`number`

Expects a `Float`

###### y

`number`

Expects a `Float`

###### z

`number`

Expects a `Float`

##### Returns

`void`

##### Remarks

This method does not support objects having non-uniformly-scaled parent(s).

##### Inherited from

`Mesh.lookAt`

***

### onAfterRender()

> **onAfterRender**(`renderer`, `scene`, `camera`, `geometry`, `material`, `group`): `void`

Defined in: [three.js/core/Object3D:onAfterRender](https://threejs.org/docs/#api/en/core/Object3D.onAfterRender)

An optional callback that is executed immediately after a 3D object is rendered.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### material

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, geometry, material, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

`Mesh.onAfterRender`

***

### onAfterShadow()

> **onAfterShadow**(`renderer`, `scene`, `camera`, `shadowCamera`, `geometry`, `depthMaterial`, `group`): `void`

Defined in: [three.js/core/Object3D:onAfterShadow](https://threejs.org/docs/#api/en/core/Object3D.onAfterShadow)

An optional callback that is executed immediately after a 3D object is rendered to a shadow map.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### shadowCamera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### depthMaterial

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, shadowCamera, geometry,
depthMaterial, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

`Mesh.onAfterShadow`

***

### onBeforeRender()

> **onBeforeRender**(`renderer`, `scene`, `camera`, `geometry`, `material`, `group`): `void`

Defined in: [three.js/core/Object3D:onBeforeRender](https://threejs.org/docs/#api/en/core/Object3D.onBeforeRender)

An optional callback that is executed immediately before a 3D object is rendered.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### material

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, geometry, material, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

`Mesh.onBeforeRender`

***

### onBeforeShadow()

> **onBeforeShadow**(`renderer`, `scene`, `camera`, `shadowCamera`, `geometry`, `depthMaterial`, `group`): `void`

Defined in: [three.js/core/Object3D:onBeforeShadow](https://threejs.org/docs/#api/en/core/Object3D.onBeforeShadow)

An optional callback that is executed immediately before a 3D object is rendered to a shadow map.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### shadowCamera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### depthMaterial

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, shadowCamera, geometry,
depthMaterial, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

`Mesh.onBeforeShadow`

***

### raycast()

> **raycast**(`raycaster`, `intersects`): `void`

Defined in: [three.js/core/Object3D:raycast](https://threejs.org/docs/#api/en/core/Object3D.raycast)

Abstract (empty) method to get intersections between a casted ray and this object

#### Parameters

##### raycaster

[`Raycaster`](https://threejs.org/docs/#api/en/core/Raycaster)

##### intersects

[`Intersection`](https://threejs.org/docs/)\<[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>\>[]

#### Returns

`void`

#### Remarks

Subclasses such as THREE.Mesh \| Mesh, THREE.Line \| Line, and THREE.Points \| Points implement this method in order to use raycasting.

#### See

THREE.Raycaster \| Raycaster

#### Default Value

`() => {}`

#### Inherited from

`Mesh.raycast`

***

### remove()

> **remove**(...`object`): `this`

Defined in: [three.js/core/Object3D:remove](https://threejs.org/docs/#api/en/core/Object3D.remove)

Removes a [Object3D](https://threejs.org/docs/#api/en/core/Object3D) as child of this [Object3D](https://threejs.org/docs/#api/en/core/Object3D).

#### Parameters

##### object

...[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

#### Returns

`this`

#### Remarks

An arbitrary number of objects may be removed.

#### See

THREE.Group \| Group for info on manually grouping objects.

#### Inherited from

`Mesh.remove`

***

### removeEffect()

> **removeEffect**(`effect`): `this`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:1214](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L1214)

Remove an effect instance from this sprite.
Clears the enable bit and resets effect data to defaults.
The effect type remains registered on the material (no shader change).

#### Parameters

##### effect

[`MaterialEffect`](/three-flatland/api/three-flatland/src/classes/materialeffect/)

#### Returns

`this`

***

### removeEventListener()

> **removeEventListener**\<`T`\>(`type`, `listener`): `void`

Defined in: [three.js/core/EventDispatcher:removeEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.removeEventListener)

Removes a listener from an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### type

`T`

The type of the listener that gets removed.

##### listener

[`EventListener`](https://threejs.org/docs/)\<[`Object3DEventMap`](https://threejs.org/docs/)\[`T`\], `T`, `Sprite2D`\>

The listener function that gets removed.

#### Returns

`void`

#### Inherited from

`Mesh.removeEventListener`

***

### removeFromParent()

> **removeFromParent**(): `this`

Defined in: [three.js/core/Object3D:removeFromParent](https://threejs.org/docs/#api/en/core/Object3D.removeFromParent)

Removes this object from its current parent.

#### Returns

`this`

#### Inherited from

`Mesh.removeFromParent`

***

### rotateOnAxis()

> **rotateOnAxis**(`axis`, `angle`): `this`

Defined in: [three.js/core/Object3D:rotateOnAxis](https://threejs.org/docs/#api/en/core/Object3D.rotateOnAxis)

Rotate an object along an axis in object space.

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in object space.

##### angle

`number`

The angle in radians. Expects a `Float`

#### Returns

`this`

#### Remarks

The axis is assumed to be normalized.

#### Inherited from

`Mesh.rotateOnAxis`

***

### rotateOnWorldAxis()

> **rotateOnWorldAxis**(`axis`, `angle`): `this`

Defined in: [three.js/core/Object3D:rotateOnWorldAxis](https://threejs.org/docs/#api/en/core/Object3D.rotateOnWorldAxis)

Rotate an object along an axis in world space.

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in world space.

##### angle

`number`

The angle in radians. Expects a `Float`

#### Returns

`this`

#### Remarks

The axis is assumed to be normalized
Method Assumes no rotated parent.

#### Inherited from

`Mesh.rotateOnWorldAxis`

***

### rotateX()

> **rotateX**(`angle`): `this`

Defined in: [three.js/core/Object3D:rotateX](https://threejs.org/docs/#api/en/core/Object3D.rotateX)

Rotates the object around _x_ axis in local space.

#### Parameters

##### angle

`number`

#### Returns

`this`

#### Inherited from

`Mesh.rotateX`

***

### rotateY()

> **rotateY**(`angle`): `this`

Defined in: [three.js/core/Object3D:rotateY](https://threejs.org/docs/#api/en/core/Object3D.rotateY)

Rotates the object around _y_ axis in local space.

#### Parameters

##### angle

`number`

#### Returns

`this`

#### Inherited from

`Mesh.rotateY`

***

### rotateZ()

> **rotateZ**(`angle`): `this`

Defined in: [three.js/core/Object3D:rotateZ](https://threejs.org/docs/#api/en/core/Object3D.rotateZ)

Rotates the object around _z_ axis in local space.

#### Parameters

##### angle

`number`

#### Returns

`this`

#### Inherited from

`Mesh.rotateZ`

***

### setAnchor()

> **setAnchor**(`x`, `y`): `this`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:763](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L763)

Set the anchor point (0-1).
(0, 0) = top-left, (0.5, 0.5) = center, (0.5, 1) = bottom-center

The anchor offset is baked into the matrix transform — no
geometry rebuild. Writing `_anchor.set(...)` triggers the
observable.vector2 callback which marks the matrix dirty; the next
`updateMatrix` picks up the new value.

#### Parameters

##### x

`number`

##### y

`number`

#### Returns

`this`

***

### setFrame()

> **setFrame**(`frame`): `this`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:708](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L708)

Set the current frame.
Note: Does not modify scale - call updateSize() manually if needed after first frame.

#### Parameters

##### frame

[`SpriteFrame`](/three-flatland/api/three-flatland/src/interfaces/spriteframe/)

#### Returns

`this`

***

### setRotationFromAxisAngle()

> **setRotationFromAxisAngle**(`axis`, `angle`): `void`

Defined in: [three.js/core/Object3D:setRotationFromAxisAngle](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromAxisAngle)

Calls THREE.Quaternion.setFromAxisAngle \| setFromAxisAngle(axis, angle) on the [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in object space.

##### angle

`number`

Angle in radians. Expects a `Float`

#### Returns

`void`

#### Inherited from

`Mesh.setRotationFromAxisAngle`

***

### setRotationFromEuler()

> **setRotationFromEuler**(`euler`): `void`

Defined in: [three.js/core/Object3D:setRotationFromEuler](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromEuler)

Calls THREE.Quaternion.setFromEuler \| setFromEuler(euler) on the [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### euler

[`Euler`](https://threejs.org/docs/#api/en/math/Euler)

Euler angle specifying rotation amount.

#### Returns

`void`

#### Inherited from

`Mesh.setRotationFromEuler`

***

### setRotationFromMatrix()

> **setRotationFromMatrix**(`m`): `void`

Defined in: [three.js/core/Object3D:setRotationFromMatrix](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromMatrix)

Calls THREE.Quaternion.setFromRotationMatrix \| setFromRotationMatrix(m) on the [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### m

[`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Rotate the quaternion by the rotation component of the matrix.

#### Returns

`void`

#### Remarks

Note that this assumes that the upper 3x3 of m is a pure rotation matrix (i.e, unscaled).

#### Inherited from

`Mesh.setRotationFromMatrix`

***

### setRotationFromQuaternion()

> **setRotationFromQuaternion**(`q`): `void`

Defined in: [three.js/core/Object3D:setRotationFromQuaternion](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromQuaternion)

Copy the given THREE.Quaternion \| Quaternion into [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### q

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

Normalized Quaternion.

#### Returns

`void`

#### Inherited from

`Mesh.setRotationFromQuaternion`

***

### toJSON()

> **toJSON**(`meta?`): [`MeshJSON`](https://threejs.org/docs/)

Defined in: [three.js/objects/Mesh:toJSON](https://threejs.org/docs/#api/en/objects/Mesh.toJSON)

Convert the object to three.js [JSON Object/Scene format](https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4).

#### Parameters

##### meta?

[`JSONMeta`](https://threejs.org/docs/)

Object containing metadata such as materials, textures or images for the object.

#### Returns

[`MeshJSON`](https://threejs.org/docs/)

#### Inherited from

`Mesh.toJSON`

***

### translateOnAxis()

> **translateOnAxis**(`axis`, `distance`): `this`

Defined in: [three.js/core/Object3D:translateOnAxis](https://threejs.org/docs/#api/en/core/Object3D.translateOnAxis)

Translate an object by distance along an axis in object space

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in object space.

##### distance

`number`

The distance to translate. Expects a `Float`

#### Returns

`this`

#### Remarks

The axis is assumed to be normalized.

#### Inherited from

`Mesh.translateOnAxis`

***

### translateX()

> **translateX**(`distance`): `this`

Defined in: [three.js/core/Object3D:translateX](https://threejs.org/docs/#api/en/core/Object3D.translateX)

Translates object along x axis in object space by distance units.

#### Parameters

##### distance

`number`

Expects a `Float`

#### Returns

`this`

#### Inherited from

`Mesh.translateX`

***

### translateY()

> **translateY**(`distance`): `this`

Defined in: [three.js/core/Object3D:translateY](https://threejs.org/docs/#api/en/core/Object3D.translateY)

Translates object along _y_ axis in object space by distance units.

#### Parameters

##### distance

`number`

Expects a `Float`

#### Returns

`this`

#### Inherited from

`Mesh.translateY`

***

### translateZ()

> **translateZ**(`distance`): `this`

Defined in: [three.js/core/Object3D:translateZ](https://threejs.org/docs/#api/en/core/Object3D.translateZ)

Translates object along _z_ axis in object space by distance units.

#### Parameters

##### distance

`number`

Expects a `Float`

#### Returns

`this`

#### Inherited from

`Mesh.translateZ`

***

### traverse()

> **traverse**(`callback`): `void`

Defined in: [three.js/core/Object3D:traverse](https://threejs.org/docs/#api/en/core/Object3D.traverse)

Executes the callback on this object and all descendants.

#### Parameters

##### callback

(`object`) => `any`

A function with as first argument an [Object3D](https://threejs.org/docs/#api/en/core/Object3D) object.

#### Returns

`void`

#### Remarks

Note: Modifying the scene graph inside the callback is discouraged.

#### Inherited from

`Mesh.traverse`

***

### traverseAncestors()

> **traverseAncestors**(`callback`): `void`

Defined in: [three.js/core/Object3D:traverseAncestors](https://threejs.org/docs/#api/en/core/Object3D.traverseAncestors)

Executes the callback on all ancestors.

#### Parameters

##### callback

(`object`) => `any`

A function with as first argument an [Object3D](https://threejs.org/docs/#api/en/core/Object3D) object.

#### Returns

`void`

#### Remarks

Note: Modifying the scene graph inside the callback is discouraged.

#### Inherited from

`Mesh.traverseAncestors`

***

### traverseVisible()

> **traverseVisible**(`callback`): `void`

Defined in: [three.js/core/Object3D:traverseVisible](https://threejs.org/docs/#api/en/core/Object3D.traverseVisible)

Like traverse, but the callback will only be executed for visible objects

#### Parameters

##### callback

(`object`) => `any`

A function with as first argument an [Object3D](https://threejs.org/docs/#api/en/core/Object3D) object.

#### Returns

`void`

#### Remarks

Descendants of invisible objects are not traversed.
Note: Modifying the scene graph inside the callback is discouraged.

#### Inherited from

`Mesh.traverseVisible`

***

### updateMatrix()

> **updateMatrix**(): `void`

Defined in: [packages/three-flatland/src/sprites/Sprite2D.ts:1421](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/Sprite2D.ts#L1421)

Fast 2D matrix update — bypasses Three.js quaternion-based compose().

Three.js Object3D.updateMatrix() calls matrix.compose(position, quaternion, scale)
which does full 3D quaternion→matrix math (~20 multiplies). For 2D sprites we only
need position, scale, and optional Z-axis rotation — written directly to the matrix
elements.

Also bakes in the layer/zIndex Z offset without save/restore of position.z.

#### Returns

`void`

#### Overrides

`Mesh.updateMatrix`

***

### updateMatrixWorld()

> **updateMatrixWorld**(`force?`): `void`

Defined in: [three.js/core/Object3D:updateMatrixWorld](https://threejs.org/docs/#api/en/core/Object3D.updateMatrixWorld)

Updates the global transform of the object.
And will update the object descendants if [.matrixWorldNeedsUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldneedsupdate) is set to true or if the force parameter is set to `true`.

#### Parameters

##### force?

`boolean`

A boolean that can be used to bypass [.matrixWorldAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldautoupdate), to recalculate the world matrix of the object and descendants on the current frame.
Useful if you cannot wait for the renderer to update it on the next frame, assuming [.matrixWorldAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldautoupdate) set to `true`.

#### Returns

`void`

#### Inherited from

`Mesh.updateMatrixWorld`

***

### updateMorphTargets()

> **updateMorphTargets**(): `void`

Defined in: [three.js/objects/Mesh:updateMorphTargets](https://threejs.org/docs/#api/en/objects/Mesh.updateMorphTargets)

Updates the morphTargets to have no influence on the object

#### Returns

`void`

#### Remarks

Resets the [morphTargetInfluences](/three-flatland/api/three-flatland/src/classes/animatedsprite2d/#morphtargetinfluences) and [morphTargetDictionary](https://threejs.org/docs/) properties.

#### Inherited from

`Mesh.updateMorphTargets`

***

### updateWorldMatrix()

> **updateWorldMatrix**(`updateParents`, `updateChildren`): `void`

Defined in: [three.js/core/Object3D:updateWorldMatrix](https://threejs.org/docs/#api/en/core/Object3D.updateWorldMatrix)

Updates the global transform of the object.

#### Parameters

##### updateParents

`boolean`

Recursively updates global transform of ancestors.

##### updateChildren

`boolean`

Recursively updates global transform of descendants.

#### Returns

`void`

#### Inherited from

`Mesh.updateWorldMatrix`

***

### worldToLocal()

> **worldToLocal**(`vector`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:worldToLocal](https://threejs.org/docs/#api/en/core/Object3D.worldToLocal)

Converts the vector from world space to this object's local space.

#### Parameters

##### vector

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A vector representing a position in world space.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Mesh.worldToLocal`

# Sprite2DMaterial

Defined in: [packages/three-flatland/src/materials/Sprite2DMaterial.ts:85](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/Sprite2DMaterial.ts#L85)

TSL-based material for 2D sprites.

UNIFIED API: This material reads from instance attributes, which works for:
- Single sprites (Sprite2D sets attributes on its geometry)
- Batched sprites (SpriteBatch sets instanced attributes)

Core instance attributes (always present):
- instanceUV (vec4): frame UV (x, y, width, height) in atlas
- instanceColor (vec4): tint color and alpha (r, g, b, a)
- instanceFlip (vec2): flip flags (x, y) where 1 = normal, -1 = flipped

Effects are composed via `registerEffect()`, which packs effect data into
fixed-size vec4 buffers with per-sprite enable flags.

## Extends

- [`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/)

## Constructors

### Constructor

> **new Sprite2DMaterial**(`options?`): `Sprite2DMaterial`

Defined in: [packages/three-flatland/src/materials/Sprite2DMaterial.ts:138](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/Sprite2DMaterial.ts#L138)

#### Parameters

##### options?

[`Sprite2DMaterialOptions`](/three-flatland/api/three-flatland/src/interfaces/sprite2dmaterialoptions/) = `{}`

#### Returns

`Sprite2DMaterial`

#### Overrides

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`constructor`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#constructor)

## Properties

### allowOverride

> **allowOverride**: `boolean`

Defined in: [three.js/materials/Material:allowOverride](https://threejs.org/docs/#api/en/materials/Material.allowOverride)

Whether it's possible to override the material with [Scene#overrideMaterial](https://threejs.org/docs/) or not.

#### Default

```ts
true
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`allowOverride`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#allowoverride)

***

### alphaHash

> **alphaHash**: `boolean`

Defined in: [three.js/materials/Material:alphaHash](https://threejs.org/docs/#api/en/materials/Material.alphaHash)

Enables alpha hashed transparency, an alternative to [Material#transparent](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#transparent) or
[Material#alphaTest](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#alphatest). The material will not be rendered if opacity is lower than
a random threshold. Randomization introduces some grain or noise, but approximates alpha
blending without the associated problems of sorting. Using TAA can reduce the resulting noise.

#### Default

```ts
false
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`alphaHash`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#alphahash)

***

### alphaMap

> **alphaMap**: [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

Defined in: [three.js/materials/MeshBasicMaterial:alphaMap](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.alphaMap)

The alpha map is a grayscale texture that controls the opacity across the
surface (black: fully transparent; white: fully opaque).

Only the color of the texture is used, ignoring the alpha channel if one
exists. For RGB and RGBA textures, the renderer will use the green channel
when sampling this texture due to the extra bit of precision provided for
green in DXT-compressed and uncompressed RGB 565 formats. Luminance-only and
luminance/alpha textures will also still work as expected.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`alphaMap`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#alphamap)

***

### alphaTestNode

> **alphaTestNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:alphaTestNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.alphaTestNode)

The alpha test of node materials is by default inferred from the `alphaTest`
property. This node property allows to overwrite the default and define the
alpha test with a node instead.

If you don't want to overwrite the alpha test but modify the existing
value instead, use materialAlphaTest.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`alphaTestNode`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#alphatestnode)

***

### alphaToCoverage

> **alphaToCoverage**: `boolean`

Defined in: [three.js/materials/Material:alphaToCoverage](https://threejs.org/docs/#api/en/materials/Material.alphaToCoverage)

Whether alpha to coverage should be enabled or not. Can only be used with MSAA-enabled contexts
(meaning when the renderer was created with *antialias* parameter set to `true`). Enabling this
will smooth aliasing on clip plane edges and alphaTest-clipped edges.

#### Default

```ts
false
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`alphaToCoverage`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#alphatocoverage)

***

### aoMap

> **aoMap**: [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

Defined in: [three.js/materials/MeshBasicMaterial:aoMap](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.aoMap)

The red channel of this texture is used as the ambient occlusion map.
Requires a second set of UVs.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`aoMap`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#aomap)

***

### aoMapIntensity

> **aoMapIntensity**: `number`

Defined in: [three.js/materials/MeshBasicMaterial:aoMapIntensity](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.aoMapIntensity)

Intensity of the ambient occlusion effect. Range is `[0,1]`, where `0`
disables ambient occlusion. Where intensity is `1` and the AO map's
red channel is also `1`, ambient light is fully occluded on a surface.

#### Default

```ts
1
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`aoMapIntensity`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#aomapintensity)

***

### aoNode

> **aoNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:aoNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.aoNode)

The lighting of node materials might be influenced by ambient occlusion.
The default AO is inferred from an ambient occlusion map assigned to `aoMap`
and the respective `aoMapIntensity`. This node property allows to overwrite
the default and define the ambient occlusion with a custom node instead.

If you don't want to overwrite the diffuse color but modify the existing
values instead, use materialAO.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`aoNode`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#aonode)

***

### backdropAlphaNode

> **backdropAlphaNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:backdropAlphaNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.backdropAlphaNode)

This node allows to modulate the influence of `backdropNode` to the outgoing light.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`backdropAlphaNode`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#backdropalphanode)

***

### backdropNode

> **backdropNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:backdropNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.backdropNode)

This node can be used to implement a variety of filter-like effects. The idea is
to store the current rendering into a texture e.g. via `viewportSharedTexture()`, use it
to create an arbitrary effect and then assign the node composition to this property.
Everything behind the object using this material will now be affected by a filter.

```js
const material = new NodeMaterial()
material.transparent = true;

// everything behind the object will be monochromatic
material.backdropNode = saturation( viewportSharedTexture().rgb, 0 );
```

Backdrop computations are part of the lighting so only lit materials can use this property.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`backdropNode`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#backdropnode)

***

### batchId

> `readonly` **batchId**: `number`

Defined in: [packages/three-flatland/src/materials/Sprite2DMaterial.ts:132](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/Sprite2DMaterial.ts#L132)

Unique batch ID for this material instance (used for batching).

***

### blendAlpha

> **blendAlpha**: `number`

Defined in: [three.js/materials/Material:blendAlpha](https://threejs.org/docs/#api/en/materials/Material.blendAlpha)

Represents the alpha value of the constant blend color.

This property has only an effect when using custom blending with `ConstantAlpha` or `OneMinusConstantAlpha`.

#### Default

```ts
0
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`blendAlpha`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#blendalpha)

***

### blendColor

> **blendColor**: [`Color`](https://threejs.org/docs/#api/en/math/Color)

Defined in: [three.js/materials/Material:blendColor](https://threejs.org/docs/#api/en/materials/Material.blendColor)

Represents the RGB values of the constant blend color.

This property has only an effect when using custom blending with `ConstantColor` or `OneMinusConstantColor`.

#### Default

```ts
(0,0,0)
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`blendColor`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#blendcolor)

***

### blendDst

> **blendDst**: [`BlendingDstFactor`](https://threejs.org/docs/)

Defined in: [three.js/materials/Material:blendDst](https://threejs.org/docs/#api/en/materials/Material.blendDst)

Defines the blending destination factor.

#### Default

```ts
OneMinusSrcAlphaFactor
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`blendDst`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#blenddst)

***

### blendDstAlpha

> **blendDstAlpha**: [`BlendingDstFactor`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/Material:blendDstAlpha](https://threejs.org/docs/#api/en/materials/Material.blendDstAlpha)

Defines the blending destination alpha factor.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`blendDstAlpha`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#blenddstalpha)

***

### blendEquation

> **blendEquation**: [`BlendingEquation`](https://threejs.org/docs/)

Defined in: [three.js/materials/Material:blendEquation](https://threejs.org/docs/#api/en/materials/Material.blendEquation)

Defines the blending equation.

#### Default

```ts
AddEquation
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`blendEquation`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#blendequation)

***

### blendEquationAlpha

> **blendEquationAlpha**: [`BlendingEquation`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/Material:blendEquationAlpha](https://threejs.org/docs/#api/en/materials/Material.blendEquationAlpha)

Defines the blending equation of the alpha channel.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`blendEquationAlpha`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#blendequationalpha)

***

### blending

> **blending**: [`Blending`](https://threejs.org/docs/)

Defined in: [three.js/materials/Material:blending](https://threejs.org/docs/#api/en/materials/Material.blending)

Defines the blending type of the material.

It must be set to `CustomBlending` if custom blending properties like
[Material#blendSrc](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#blendsrc), [Material#blendDst](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#blenddst) or [Material#blendEquation](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#blendequation)
should have any effect.

#### Default

```ts
NormalBlending
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`blending`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#blending)

***

### blendSrc

> **blendSrc**: [`BlendingSrcFactor`](https://threejs.org/docs/)

Defined in: [three.js/materials/Material:blendSrc](https://threejs.org/docs/#api/en/materials/Material.blendSrc)

Defines the blending source factor.

#### Default

```ts
SrcAlphaFactor
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`blendSrc`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#blendsrc)

***

### blendSrcAlpha

> **blendSrcAlpha**: [`BlendingSrcFactor`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/Material:blendSrcAlpha](https://threejs.org/docs/#api/en/materials/Material.blendSrcAlpha)

Defines the blending source alpha factor.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`blendSrcAlpha`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#blendsrcalpha)

***

### castShadowNode

> **castShadowNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:castShadowNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.castShadowNode)

This node can be used to influence how an object using this node material
casts shadows. To apply a color to shadows, you can simply do:

```js
material.castShadowNode = vec4( 1, 0, 0, 1 );
```

Which can be nice to fake colored shadows of semi-transparent objects. It
is also common to use the property with `Fn` function so checks are performed
per fragment.

```js
materialCustomShadow.castShadowNode = Fn( () => {
	hash( vertexIndex ).greaterThan( 0.5 ).discard();
	return materialColor;
} )();
 ```

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`castShadowNode`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#castshadownode)

***

### castShadowPositionNode

> **castShadowPositionNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:castShadowPositionNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.castShadowPositionNode)

Allows to overwrite the geometry position used for shadow map projection which
is by default positionLocal, the vertex position in local space.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`castShadowPositionNode`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#castshadowpositionnode)

***

### clipIntersection

> **clipIntersection**: `boolean`

Defined in: [three.js/materials/Material:clipIntersection](https://threejs.org/docs/#api/en/materials/Material.clipIntersection)

Changes the behavior of clipping planes so that only their intersection is
clipped, rather than their union.

#### Default

```ts
false
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`clipIntersection`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#clipintersection)

***

### clippingPlanes

> **clippingPlanes**: [`Plane`](https://threejs.org/docs/)[] \| `null`

Defined in: [three.js/materials/Material:clippingPlanes](https://threejs.org/docs/#api/en/materials/Material.clippingPlanes)

User-defined clipping planes specified as THREE.Plane objects in world
space. These planes apply to the objects this material is attached to.
Points in space whose signed distance to the plane is negative are clipped
(not rendered). This requires [WebGLRenderer#localClippingEnabled](https://threejs.org/docs/) to
be `true`.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`clippingPlanes`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#clippingplanes)

***

### clipShadows

> **clipShadows**: `boolean`

Defined in: [three.js/materials/Material:clipShadows](https://threejs.org/docs/#api/en/materials/Material.clipShadows)

Defines whether to clip shadows according to the clipping planes specified
on this material.

#### Default

```ts
false
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`clipShadows`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#clipshadows)

***

### color

> **color**: [`Color`](https://threejs.org/docs/#api/en/math/Color)

Defined in: [three.js/materials/MeshBasicMaterial:color](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.color)

Color of the material.

#### Default

```ts
(1,1,1)
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`color`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#color)

***

### colorNode

> **colorNode**: [`Node`](https://threejs.org/docs/)\<`"vec3"`\> \| [`Node`](https://threejs.org/docs/)\<`"float"`\> \| [`Node`](https://threejs.org/docs/)\<`"color"`\> \| [`Node`](https://threejs.org/docs/)\<`"vec2"`\> \| [`Node`](https://threejs.org/docs/)\<`"vec4"`\> \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:colorNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.colorNode)

The diffuse color of node materials is by default inferred from the
`color` and `map` properties. This node property allows to overwrite the default
and define the diffuse color with a node instead.

```js
material.colorNode = color( 0xff0000 ); // define red color
```

If you don't want to overwrite the diffuse color but modify the existing
values instead, use materialColor.

```js
material.colorNode = materialColor.mul( color( 0xff0000 ) ); // give diffuse colors a red tint
```

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`colorNode`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#colornode)

***

### colorWrite

> **colorWrite**: `boolean`

Defined in: [three.js/materials/Material:colorWrite](https://threejs.org/docs/#api/en/materials/Material.colorWrite)

Whether to render the material's color.

This can be used in conjunction with Object3D#renderOder to create invisible
objects that occlude other objects.

#### Default

```ts
true
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`colorWrite`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#colorwrite)

***

### combine

> **combine**: [`Combine`](https://threejs.org/docs/)

Defined in: [three.js/materials/MeshBasicMaterial:combine](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.combine)

How to combine the result of the surface's color with the environment map, if any.

When set to `MixOperation`, the [MeshBasicMaterial#reflectivity](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#reflectivity) is used to
blend between the two colors.

#### Default

```ts
MultiplyOperation
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`combine`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#combine)

***

### contextNode

> **contextNode**: [`ContextNode`](https://threejs.org/docs/)\<`unknown`\> \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:contextNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.contextNode)

This node can be used as a global context management component for this material.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`contextNode`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#contextnode)

***

### defines?

> `optional` **defines?**: `Record`\<`string`, `unknown`\>

Defined in: [three.js/materials/Material:defines](https://threejs.org/docs/#api/en/materials/Material.defines)

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`defines`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#defines)

***

### depthFunc

> **depthFunc**: [`DepthModes`](https://threejs.org/docs/)

Defined in: [three.js/materials/Material:depthFunc](https://threejs.org/docs/#api/en/materials/Material.depthFunc)

Defines the depth function.

#### Default

```ts
LessEqualDepth
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`depthFunc`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#depthfunc)

***

### depthNode

> **depthNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:depthNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.depthNode)

Allows to overwrite depth values in the fragment shader.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`depthNode`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#depthnode)

***

### depthTest

> **depthTest**: `boolean`

Defined in: [three.js/materials/Material:depthTest](https://threejs.org/docs/#api/en/materials/Material.depthTest)

Whether to have depth test enabled when rendering this material.
When the depth test is disabled, the depth write will also be implicitly disabled.

#### Default

```ts
true
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`depthTest`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#depthtest)

***

### depthWrite

> **depthWrite**: `boolean`

Defined in: [three.js/materials/Material:depthWrite](https://threejs.org/docs/#api/en/materials/Material.depthWrite)

Whether rendering this material has any effect on the depth buffer.

When drawing 2D overlays it can be useful to disable the depth writing in
order to layer several things together without creating z-index artifacts.

#### Default

```ts
true
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`depthWrite`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#depthwrite)

***

### dithering

> **dithering**: `boolean`

Defined in: [three.js/materials/Material:dithering](https://threejs.org/docs/#api/en/materials/Material.dithering)

Whether to apply dithering to the color to remove the appearance of banding.

#### Default

```ts
false
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`dithering`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#dithering)

***

### envMap

> **envMap**: [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

Defined in: [three.js/materials/MeshBasicMaterial:envMap](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.envMap)

The environment map.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`envMap`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#envmap)

***

### envMapRotation

> **envMapRotation**: [`Euler`](https://threejs.org/docs/#api/en/math/Euler)

Defined in: [three.js/materials/MeshBasicMaterial:envMapRotation](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.envMapRotation)

The rotation of the environment map in radians.

#### Default

```ts
(0,0,0)
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`envMapRotation`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#envmaprotation)

***

### envNode

> **envNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:envNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.envNode)

The environment of node materials can be defined by an environment
map assigned to the `envMap` property or by `Scene.environment`
if the node material is a PBR material. This node property allows to overwrite
the default behavior and define the environment with a custom node.

```js
material.envNode = pmremTexture( renderTarget.texture );
```

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`envNode`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#envnode)

***

### fog

> **fog**: `boolean`

Defined in: [three.js/materials/nodes/NodeMaterial:fog](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.fog)

Whether this material is affected by fog or not.

#### Default

```ts
true
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`fog`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#fog)

***

### forceSinglePass

> **forceSinglePass**: `boolean`

Defined in: [three.js/materials/Material:forceSinglePass](https://threejs.org/docs/#api/en/materials/Material.forceSinglePass)

Whether double-sided, transparent objects should be rendered with a single pass or not.

The engine renders double-sided, transparent objects with two draw calls (back faces first,
then front faces) to mitigate transparency artifacts. There are scenarios however where this
approach produces no quality gains but still doubles draw calls e.g. when rendering flat
vegetation like grass sprites. In these cases, set the `forceSinglePass` flag to `true` to
disable the two pass rendering to avoid performance issues.

#### Default

```ts
false
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`forceSinglePass`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#forcesinglepass)

***

### fragmentNode

> **fragmentNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:fragmentNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.fragmentNode)

This node property can be used if you need complete freedom in implementing
the fragment shader. Assigning a node will replace the built-in material
logic used in the fragment stage.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`fragmentNode`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#fragmentnode)

***

### geometryNode

> **geometryNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:geometryNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.geometryNode)

This node property is intended for logic which modifies geometry data once or per animation step.
Apps usually place such logic randomly in initialization routines or in the animation loop.
`geometryNode` is intended as a dedicated API so there is an intended spot where geometry modifications
can be implemented.

The idea is to assign a `Fn` definition that holds the geometry modification logic. A typical example
would be a GPU based particle system that provides a node material for usage on app level. The particle
simulation would be implemented as compute shaders and managed inside a `Fn` function. This function is
eventually assigned to `geometryNode`.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`geometryNode`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#geometrynode)

***

### hardwareClipping

> **hardwareClipping**: `boolean`

Defined in: [three.js/materials/nodes/NodeMaterial:hardwareClipping](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.hardwareClipping)

Whether this material uses hardware clipping or not.
This property is managed by the engine and should not be
modified by apps.

#### Default

```ts
false
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`hardwareClipping`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#hardwareclipping)

***

### isMaterial

> `readonly` **isMaterial**: `boolean`

Defined in: [three.js/materials/Material:isMaterial](https://threejs.org/docs/#api/en/materials/Material.isMaterial)

This flag can be used for type testing.

#### Default

```ts
true
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`isMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#ismaterial)

***

### isMeshBasicNodeMaterial

> `readonly` **isMeshBasicNodeMaterial**: `boolean`

Defined in: [three.js/materials/nodes/MeshBasicNodeMaterial:isMeshBasicNodeMaterial](https://threejs.org/docs/#api/en/materials/nodes/MeshBasicNodeMaterial.isMeshBasicNodeMaterial)

This flag can be used for type testing.

#### Default

```ts
true
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`isMeshBasicNodeMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#ismeshbasicnodematerial)

***

### isNodeMaterial

> `readonly` **isNodeMaterial**: `boolean`

Defined in: [three.js/materials/nodes/NodeMaterial:isNodeMaterial](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.isNodeMaterial)

This flag can be used for type testing.

#### Default

```ts
true
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`isNodeMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#isnodematerial)

***

### lightMap

> **lightMap**: [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

Defined in: [three.js/materials/MeshBasicMaterial:lightMap](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.lightMap)

The light map. Requires a second set of UVs.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`lightMap`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#lightmap)

***

### lightMapIntensity

> **lightMapIntensity**: `number`

Defined in: [three.js/materials/MeshBasicMaterial:lightMapIntensity](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.lightMapIntensity)

Intensity of the baked light.

#### Default

```ts
1
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`lightMapIntensity`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#lightmapintensity)

***

### lights

> **lights**: `boolean`

Defined in: [three.js/materials/nodes/NodeMaterial:lights](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.lights)

Whether this material is affected by lights or not.

#### Default

```ts
false
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`lights`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#lights)

***

### lightsNode

> **lightsNode**: [`LightsNode`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:lightsNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.lightsNode)

Node materials which set their `lights` property to `true`
are affected by all lights of the scene. Sometimes selective
lighting is wanted which means only _some_ lights in the scene
affect a material. This can be achieved by creating an instance
of [LightsNode](https://threejs.org/docs/) with a list of selective
lights and assign the node to this property.

```js
const customLightsNode = lights( [ light1, light2 ] );
material.lightsNode = customLightsNode;
```

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`lightsNode`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#lightsnode)

***

### map

> **map**: [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

Defined in: [three.js/materials/MeshBasicMaterial:map](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.map)

The color map. May optionally include an alpha channel, typically combined
with [Material#transparent](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#transparent) or [Material#alphaTest](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#alphatest). The texture map
color is modulated by the diffuse `color`.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`map`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#map)

***

### maskNode

> **maskNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:maskNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.maskNode)

Discards the fragment if the mask value is `false`.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`maskNode`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#masknode)

***

### maskShadowNode

> **maskShadowNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:maskShadowNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.maskShadowNode)

This node can be used to implement a shadow mask for the material.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`maskShadowNode`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#maskshadownode)

***

### mrtNode

> **mrtNode**: [`MRTNode`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:mrtNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.mrtNode)

MRT configuration is done on renderer or pass level. This node allows to
overwrite what values are written into MRT targets on material level. This
can be useful for implementing selective FX features that should only affect
specific objects.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`mrtNode`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#mrtnode)

***

### name

> **name**: `string`

Defined in: [three.js/materials/Material:name](https://threejs.org/docs/#api/en/materials/Material.name)

The name of the material.

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`name`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#name)

***

### normalNode

> **normalNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:normalNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.normalNode)

The normals of node materials are by default inferred from the `normalMap`/`normalScale`
or `bumpMap`/`bumpScale` properties. This node property allows to overwrite the default
and define the normals with a node instead.

If you don't want to overwrite the normals but modify the existing values instead,
use materialNormal.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`normalNode`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#normalnode)

***

### opacity

> **opacity**: `number`

Defined in: [three.js/materials/Material:opacity](https://threejs.org/docs/#api/en/materials/Material.opacity)

Defines how transparent the material is.
A value of `0.0` indicates fully transparent, `1.0` is fully opaque.

If the [Material#transparent](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#transparent) is not set to `true`,
the material will remain fully opaque and this value will only affect its color.

#### Default

```ts
1
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`opacity`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#opacity)

***

### opacityNode

> **opacityNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:opacityNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.opacityNode)

The opacity of node materials is by default inferred from the `opacity`
and `alphaMap` properties. This node property allows to overwrite the default
and define the opacity with a node instead.

If you don't want to overwrite the opacity but modify the existing
value instead, use materialOpacity.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`opacityNode`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#opacitynode)

***

### outputNode

> **outputNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:outputNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.outputNode)

This node can be used to define the final output of the material.

TODO: Explain the differences to `fragmentNode`.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`outputNode`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#outputnode)

***

### polygonOffset

> **polygonOffset**: `boolean`

Defined in: [three.js/materials/Material:polygonOffset](https://threejs.org/docs/#api/en/materials/Material.polygonOffset)

Whether to use polygon offset or not. When enabled, each fragment's depth value will
be offset after it is interpolated from the depth values of the appropriate vertices.
The offset is added before the depth test is performed and before the value is written
into the depth buffer.

Can be useful for rendering hidden-line images, for applying decals to surfaces, and for
rendering solids with highlighted edges.

#### Default

```ts
false
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`polygonOffset`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#polygonoffset)

***

### polygonOffsetFactor

> **polygonOffsetFactor**: `number`

Defined in: [three.js/materials/Material:polygonOffsetFactor](https://threejs.org/docs/#api/en/materials/Material.polygonOffsetFactor)

Specifies a scale factor that is used to create a variable depth offset for each polygon.

#### Default

```ts
0
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`polygonOffsetFactor`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#polygonoffsetfactor)

***

### polygonOffsetUnits

> **polygonOffsetUnits**: `number`

Defined in: [three.js/materials/Material:polygonOffsetUnits](https://threejs.org/docs/#api/en/materials/Material.polygonOffsetUnits)

Is multiplied by an implementation-specific value to create a constant depth offset.

#### Default

```ts
0
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`polygonOffsetUnits`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#polygonoffsetunits)

***

### positionNode

> **positionNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:positionNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.positionNode)

The local vertex positions are computed based on multiple factors like the
attribute data, morphing or skinning. This node property allows to overwrite
the default and define local vertex positions with nodes instead.

If you don't want to overwrite the vertex positions but modify the existing
values instead, use positionLocal.

```js
material.positionNode = positionLocal.add( displace );
```

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`positionNode`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#positionnode)

***

### precision

> **precision**: `"highp"` \| `"mediump"` \| `"lowp"` \| `null`

Defined in: [three.js/materials/Material:precision](https://threejs.org/docs/#api/en/materials/Material.precision)

Override the renderer's default precision for this material.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`precision`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#precision)

***

### premultipliedAlpha

> **premultipliedAlpha**: `boolean`

Defined in: [three.js/materials/Material:premultipliedAlpha](https://threejs.org/docs/#api/en/materials/Material.premultipliedAlpha)

Whether to premultiply the alpha (transparency) value.

#### Default

```ts
false
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`premultipliedAlpha`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#premultipliedalpha)

***

### receivedShadowNode

> **receivedShadowNode**: (() => [`Node`](https://threejs.org/docs/)) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:receivedShadowNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.receivedShadowNode)

This node can be used to influence how an object using this node material
receive shadows.

```js
const totalShadows = float( 1 ).toVar();
material.receivedShadowNode = Fn( ( [ shadow ] ) => {
	totalShadows.mulAssign( shadow );
	//return float( 1 ); // bypass received shadows
	return shadow.mix( color( 0xff0000 ), 1 ); // modify shadow color
} );

@default null

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`receivedShadowNode`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#receivedshadownode)

***

### receivedShadowPositionNode

> **receivedShadowPositionNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:receivedShadowPositionNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.receivedShadowPositionNode)

Allows to overwrite the position used for shadow map rendering which
is by default positionWorld, the vertex position
in world space.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`receivedShadowPositionNode`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#receivedshadowpositionnode)

***

### reflectivity

> **reflectivity**: `number`

Defined in: [three.js/materials/MeshBasicMaterial:reflectivity](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.reflectivity)

How much the environment map affects the surface.
The valid range is between `0` (no reflections) and `1` (full reflections).

#### Default

```ts
1
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`reflectivity`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#reflectivity)

***

### refractionRatio

> **refractionRatio**: `number`

Defined in: [three.js/materials/MeshBasicMaterial:refractionRatio](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.refractionRatio)

The index of refraction (IOR) of air (approximately 1) divided by the
index of refraction of the material. It is used with environment mapping
modes CubeRefractionMapping and EquirectangularRefractionMapping.
The refraction ratio should not exceed `1`.

#### Default

```ts
0.98
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`refractionRatio`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#refractionratio)

***

### shadowSide

> **shadowSide**: [`Side`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/Material:shadowSide](https://threejs.org/docs/#api/en/materials/Material.shadowSide)

Defines which side of faces cast shadows. If `null`, the side casting shadows
is determined as follows:

- When [Material#side](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#side) is set to `FrontSide`, the back side cast shadows.
- When [Material#side](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#side) is set to `BackSide`, the front side cast shadows.
- When [Material#side](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#side) is set to `DoubleSide`, both sides cast shadows.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`shadowSide`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#shadowside)

***

### side

> **side**: [`Side`](https://threejs.org/docs/)

Defined in: [three.js/materials/Material:side](https://threejs.org/docs/#api/en/materials/Material.side)

Defines which side of faces will be rendered - front, back or both.

#### Default

```ts
FrontSide
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`side`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#side)

***

### specularMap

> **specularMap**: [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

Defined in: [three.js/materials/MeshBasicMaterial:specularMap](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.specularMap)

Specular map used by the material.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`specularMap`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#specularmap)

***

### stencilFail

> **stencilFail**: [`StencilOp`](https://threejs.org/docs/)

Defined in: [three.js/materials/Material:stencilFail](https://threejs.org/docs/#api/en/materials/Material.stencilFail)

Which stencil operation to perform when the comparison function returns `false`.

#### Default

```ts
KeepStencilOp
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`stencilFail`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#stencilfail)

***

### stencilFunc

> **stencilFunc**: [`StencilFunc`](https://threejs.org/docs/)

Defined in: [three.js/materials/Material:stencilFunc](https://threejs.org/docs/#api/en/materials/Material.stencilFunc)

The stencil comparison function to use.

#### Default

```ts
AlwaysStencilFunc
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`stencilFunc`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#stencilfunc)

***

### stencilFuncMask

> **stencilFuncMask**: `number`

Defined in: [three.js/materials/Material:stencilFuncMask](https://threejs.org/docs/#api/en/materials/Material.stencilFuncMask)

The bit mask to use when comparing against the stencil buffer.

#### Default

```ts
0xff
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`stencilFuncMask`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#stencilfuncmask)

***

### stencilRef

> **stencilRef**: `number`

Defined in: [three.js/materials/Material:stencilRef](https://threejs.org/docs/#api/en/materials/Material.stencilRef)

The value to use when performing stencil comparisons or stencil operations.

#### Default

```ts
0
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`stencilRef`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#stencilref)

***

### stencilWrite

> **stencilWrite**: `boolean`

Defined in: [three.js/materials/Material:stencilWrite](https://threejs.org/docs/#api/en/materials/Material.stencilWrite)

Whether stencil operations are performed against the stencil buffer. In
order to perform writes or comparisons against the stencil buffer this
value must be `true`.

#### Default

```ts
false
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`stencilWrite`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#stencilwrite)

***

### stencilWriteMask

> **stencilWriteMask**: `number`

Defined in: [three.js/materials/Material:stencilWriteMask](https://threejs.org/docs/#api/en/materials/Material.stencilWriteMask)

The bit mask to use when writing to the stencil buffer.

#### Default

```ts
0xff
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`stencilWriteMask`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#stencilwritemask)

***

### stencilZFail

> **stencilZFail**: [`StencilOp`](https://threejs.org/docs/)

Defined in: [three.js/materials/Material:stencilZFail](https://threejs.org/docs/#api/en/materials/Material.stencilZFail)

Which stencil operation to perform when the comparison function returns
`true` but the depth test fails.

#### Default

```ts
KeepStencilOp
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`stencilZFail`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#stencilzfail)

***

### stencilZPass

> **stencilZPass**: [`StencilOp`](https://threejs.org/docs/)

Defined in: [three.js/materials/Material:stencilZPass](https://threejs.org/docs/#api/en/materials/Material.stencilZPass)

Which stencil operation to perform when the comparison function returns
`true` and the depth test passes.

#### Default

```ts
KeepStencilOp
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`stencilZPass`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#stencilzpass)

***

### toneMapped

> **toneMapped**: `boolean`

Defined in: [three.js/materials/Material:toneMapped](https://threejs.org/docs/#api/en/materials/Material.toneMapped)

Defines whether this material is tone mapped according to the renderer's tone mapping setting.

It is ignored when rendering to a render target or using post processing or when using
`WebGPURenderer`. In all these cases, all materials are honored by tone mapping.

#### Default

```ts
true
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`toneMapped`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#tonemapped)

***

### transparent

> **transparent**: `boolean`

Defined in: [three.js/materials/Material:transparent](https://threejs.org/docs/#api/en/materials/Material.transparent)

Defines whether this material is transparent. This has an effect on
rendering as transparent objects need special treatment and are rendered
after non-transparent objects.

When set to true, the extent to which the material is transparent is
controlled by [Material#opacity](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#opacity).

#### Default

```ts
false
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`transparent`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#transparent)

***

### type

> **type**: `string` = `'Sprite2DMaterial'`

Defined in: [packages/three-flatland/src/materials/Sprite2DMaterial.ts:93](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/Sprite2DMaterial.ts#L93)

Canonical three.js class identifier — every built-in material
overrides this (MeshBasicMaterial's `type` is `'MeshBasicMaterial'`,
etc.). Devtools / inspectors that walk the scene graph read `.type`
to categorise materials without `instanceof` checks. Subclasses
(e.g. future `TileMapMaterial`) should override again.

#### Overrides

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`type`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#type)

***

### userData

> **userData**: `Record`\<`string`, `any`\>

Defined in: [three.js/materials/Material:userData](https://threejs.org/docs/#api/en/materials/Material.userData)

An object that can be used to store custom data about the Material. It
should not hold references to functions as these will not be cloned.

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`userData`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#userdata)

***

### uuid

> `readonly` **uuid**: `string`

Defined in: [three.js/materials/Material:uuid](https://threejs.org/docs/#api/en/materials/Material.uuid)

The UUID of the material.

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`uuid`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#uuid)

***

### version

> `readonly` **version**: `number`

Defined in: [three.js/materials/Material:version](https://threejs.org/docs/#api/en/materials/Material.version)

This starts at `0` and counts how many times [Material#needsUpdate](https://threejs.org/docs/) is set to `true`.

#### Default

```ts
0
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`version`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#version)

***

### vertexColors

> **vertexColors**: `boolean`

Defined in: [three.js/materials/Material:vertexColors](https://threejs.org/docs/#api/en/materials/Material.vertexColors)

If set to `true`, vertex colors should be used.

The engine supports RGB and RGBA vertex colors depending on whether a three (RGB) or
four (RGBA) component color buffer attribute is used.

#### Default

```ts
false
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`vertexColors`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#vertexcolors)

***

### vertexNode

> **vertexNode**: [`Node`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/NodeMaterial:vertexNode](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.vertexNode)

This node property can be used if you need complete freedom in implementing
the vertex shader. Assigning a node will replace the built-in material logic
used in the vertex stage.

#### Default

```ts
null
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`vertexNode`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#vertexnode)

***

### visible

> **visible**: `boolean`

Defined in: [three.js/materials/Material:visible](https://threejs.org/docs/#api/en/materials/Material.visible)

Defines whether 3D objects using this material are visible.

#### Default

```ts
true
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`visible`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#visible)

***

### wireframe

> **wireframe**: `boolean`

Defined in: [three.js/materials/MeshBasicMaterial:wireframe](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.wireframe)

Renders the geometry as a wireframe.

#### Default

```ts
false
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`wireframe`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#wireframe)

***

### wireframeLinecap

> **wireframeLinecap**: `"round"` \| `"bevel"` \| `"miter"`

Defined in: [three.js/materials/MeshBasicMaterial:wireframeLinecap](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.wireframeLinecap)

Defines appearance of wireframe ends.

Can only be used with SVGRenderer.

#### Default

```ts
'round'
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`wireframeLinecap`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#wireframelinecap)

***

### wireframeLinejoin

> **wireframeLinejoin**: `"round"` \| `"bevel"` \| `"miter"`

Defined in: [three.js/materials/MeshBasicMaterial:wireframeLinejoin](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.wireframeLinejoin)

Defines appearance of wireframe joints.

Can only be used with SVGRenderer.

#### Default

```ts
'round'
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`wireframeLinejoin`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#wireframelinejoin)

***

### wireframeLinewidth

> **wireframeLinewidth**: `number`

Defined in: [three.js/materials/MeshBasicMaterial:wireframeLinewidth](https://threejs.org/docs/#api/en/materials/MeshBasicMaterial.wireframeLinewidth)

Controls the thickness of the wireframe.

Can only be used with SVGRenderer.

#### Default

```ts
1
```

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`wireframeLinewidth`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#wireframelinewidth)

***

### MAX\_EFFECT\_FLOATS

> `readonly` `static` **MAX\_EFFECT\_FLOATS**: `12` = `12`

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:144](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L144)

Maximum total effect-data floats allowed across all registered
effects on this material. WebGPU allows 8 vertex-buffer bindings
per pipeline; SpriteBatch uses 5 fixed bindings (3 geometry +
instanceMatrix + interleaved core), leaving 3 for `effectBuf0/1/2`
× 4 floats = 12 floats. Exceeding this would force a 4th effectBuf
binding which WebGPU rejects at pipeline creation with a cryptic
"vertex buffer count exceeds maximum" error. `registerEffect`
throws clearly when the cap would be exceeded.

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`MAX_EFFECT_FLOATS`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#max_effect_floats)

## Accessors

### alphaTest

#### Get Signature

> **get** **alphaTest**(): `number`

Defined in: [three.js/materials/Material:alphaTest](https://threejs.org/docs/#api/en/materials/Material.alphaTest)

Sets the alpha value to be used when running an alpha test. The material
will not be rendered if the opacity is lower than this value.

##### Default

```ts
0
```

##### Returns

`number`

#### Set Signature

> **set** **alphaTest**(`value`): `void`

Defined in: [three.js/materials/Material:alphaTest](https://threejs.org/docs/#api/en/materials/Material.alphaTest)

##### Parameters

###### value

`number`

##### Returns

`void`

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`alphaTest`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#alphatest)

***

### colorTransform

#### Get Signature

> **get** **colorTransform**(): [`ColorTransformFn`](/three-flatland/api/three-flatland/src/type-aliases/colortransformfn/) \| `null`

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:223](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L223)

Get the color transform function.

##### Returns

[`ColorTransformFn`](/three-flatland/api/three-flatland/src/type-aliases/colortransformfn/) \| `null`

#### Set Signature

> **set** **colorTransform**(`value`): `void`

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:231](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L231)

Set the color transform function.
Triggers shader rebuild.

##### Parameters

###### value

[`ColorTransformFn`](/three-flatland/api/three-flatland/src/type-aliases/colortransformfn/) \| `null`

##### Returns

`void`

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`colorTransform`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#colortransform)

***

### globalUniforms

#### Get Signature

> **get** **globalUniforms**(): [`GlobalUniforms`](/three-flatland/api/three-flatland/src/classes/globaluniforms/) \| `null`

Defined in: [packages/three-flatland/src/materials/Sprite2DMaterial.ts:178](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/Sprite2DMaterial.ts#L178)

Get the global uniforms reference.

##### Returns

[`GlobalUniforms`](/three-flatland/api/three-flatland/src/classes/globaluniforms/) \| `null`

#### Set Signature

> **set** **globalUniforms**(`value`): `void`

Defined in: [packages/three-flatland/src/materials/Sprite2DMaterial.ts:186](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/Sprite2DMaterial.ts#L186)

Set the global uniforms reference.
Triggers shader rebuild to include global tint.

##### Parameters

###### value

[`GlobalUniforms`](/three-flatland/api/three-flatland/src/classes/globaluniforms/) \| `null`

##### Returns

`void`

***

### needsUpdate

#### Set Signature

> **set** **needsUpdate**(`value`): `void`

Defined in: [three.js/materials/Material:needsUpdate](https://threejs.org/docs/#api/en/materials/Material.needsUpdate)

Setting this property to `true` indicates the engine the material
needs to be recompiled.

##### Default

```ts
false
```

##### Parameters

###### value

`boolean`

##### Returns

`void`

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`needsUpdate`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#needsupdate)

***

### requiredChannels

#### Get Signature

> **get** **requiredChannels**(): `ReadonlySet`\<`string`\>

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:243](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L243)

Get the required channels set.

##### Returns

`ReadonlySet`\<`string`\>

#### Set Signature

> **set** **requiredChannels**(`value`): `void`

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:251](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L251)

Set the required channels.
Triggers shader rebuild when channels change.

##### Parameters

###### value

`ReadonlySet`\<`string`\>

##### Returns

`void`

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`requiredChannels`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#requiredchannels)

***

### type

#### Get Signature

> **get** `static` **type**(): `string`

Defined in: [three.js/materials/nodes/NodeMaterial:type](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.type)

##### Returns

`string`

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`type`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#type-1)

## Methods

### addEventListener()

> **addEventListener**\<`T`\>(`type`, `listener`): `void`

Defined in: [three.js/core/EventDispatcher:addEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.addEventListener)

Adds a listener to an event type.

#### Type Parameters

##### T

`T` *extends* `"dispose"`

#### Parameters

##### type

`T`

The type of event to listen to.

##### listener

[`EventListener`](https://threejs.org/docs/)\<`object`\[`T`\], `T`, `Sprite2DMaterial`\>

The function that gets called when the event is fired.

#### Returns

`void`

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`addEventListener`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#addeventlistener)

***

### build()

> **build**(`builder`): `void`

Defined in: [three.js/materials/nodes/NodeMaterial:build](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.build)

Builds this material with the given node builder.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

`void`

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`build`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#build)

***

### clone()

> **clone**(): `this`

Defined in: [packages/three-flatland/src/materials/Sprite2DMaterial.ts:306](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/Sprite2DMaterial.ts#L306)

Clone this material.

#### Returns

`this`

#### Overrides

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`clone`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#clone)

***

### copy()

> **copy**(`source`): `this`

Defined in: [three.js/materials/nodes/NodeMaterial:copy](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.copy)

Copies the properties of the given node material to this instance.

#### Parameters

##### source

[`NodeMaterial`](https://threejs.org/docs/)

The material to copy.

#### Returns

`this`

A reference to this node material.

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`copy`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#copy)

***

### customProgramCacheKey()

> **customProgramCacheKey**(): `string`

Defined in: [three.js/materials/Material:customProgramCacheKey](https://threejs.org/docs/#api/en/materials/Material.customProgramCacheKey)

In case [Material#onBeforeCompile](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#onbeforecompile) is used, this callback can be used to identify
values of settings used in `onBeforeCompile()`, so three.js can reuse a cached
shader or recompile the shader for this material as needed.

This method can only be used when rendering with [WebGLRenderer](https://threejs.org/docs/#api/en/renderers/WebGLRenderer).

#### Returns

`string`

The custom program cache key.

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`customProgramCacheKey`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#customprogramcachekey)

***

### dispatchEvent()

> **dispatchEvent**\<`T`\>(`event`): `void`

Defined in: [three.js/core/EventDispatcher:dispatchEvent](https://threejs.org/docs/#api/en/core/EventDispatcher.dispatchEvent)

Fire an event type.

#### Type Parameters

##### T

`T` *extends* `"dispose"`

#### Parameters

##### event

[`BaseEvent`](https://threejs.org/docs/)\<`T`\> & `object`\[`T`\]

The event that gets fired.

#### Returns

`void`

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`dispatchEvent`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#dispatchevent)

***

### dispose()

> **dispose**(): `void`

Defined in: [packages/three-flatland/src/materials/Sprite2DMaterial.ts:328](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/Sprite2DMaterial.ts#L328)

Frees the GPU-related resources allocated by this instance. Call this
method whenever this instance is no longer used in your app.

#### Returns

`void`

#### Fires

Material#dispose

#### Overrides

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`dispose`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#dispose)

***

### getEffectFieldLocation()

> **getEffectFieldLocation**(`effectName`, `fieldName`): \{ `bufferName`: `string`; `componentIndex`: `number`; `size`: `number`; \} \| `undefined`

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:640](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L640)

Locate an effect's schema field within the packed instance buffers.
Returns the `effectBufN` attribute that contains this field, the
float offset within a single instance's 4-float slice of that
buffer (0-3), and the field's float width. Returns `undefined`
if no registered effect declares the given field.

Used by instance-writing code (e.g. TileLayer, SpriteBatch) that
needs to poke per-instance effect values directly without going
through a MaterialEffect instance's property setter.

#### Parameters

##### effectName

`string`

##### fieldName

`string`

#### Returns

\{ `bufferName`: `string`; `componentIndex`: `number`; `size`: `number`; \} \| `undefined`

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`getEffectFieldLocation`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#geteffectfieldlocation)

***

### getEffects()

> **getEffects**(): readonly *typeof* [`MaterialEffect`](/three-flatland/api/three-flatland/src/classes/materialeffect/)[]

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:366](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L366)

Get the list of registered effect classes.

#### Returns

readonly *typeof* [`MaterialEffect`](/three-flatland/api/three-flatland/src/classes/materialeffect/)[]

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`getEffects`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#geteffects)

***

### getTexture()

> **getTexture**(): [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

Defined in: [packages/three-flatland/src/materials/Sprite2DMaterial.ts:288](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/Sprite2DMaterial.ts#L288)

Get the sprite texture.

#### Returns

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

***

### getUsedEffectFloats()

> **getUsedEffectFloats**(): `number`

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:193](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L193)

Current per-instance effect-float usage (sum across all registered
effects). Complements [getMaxEffectFloats](/three-flatland/api/three-flatland/src/classes/effectmaterial/#getmaxeffectfloats).

#### Returns

`number`

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`getUsedEffectFloats`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#getusedeffectfloats)

***

### hasEffect()

> **hasEffect**(`effectClass`): `boolean`

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:359](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L359)

Check if an effect class is registered on this material.

#### Parameters

##### effectClass

*typeof* [`MaterialEffect`](/three-flatland/api/three-flatland/src/classes/materialeffect/)

#### Returns

`boolean`

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`hasEffect`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#haseffect)

***

### hasEventListener()

> **hasEventListener**\<`T`\>(`type`, `listener`): `boolean`

Defined in: [three.js/core/EventDispatcher:hasEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.hasEventListener)

Checks if listener is added to an event type.

#### Type Parameters

##### T

`T` *extends* `"dispose"`

#### Parameters

##### type

`T`

The type of event to listen to.

##### listener

[`EventListener`](https://threejs.org/docs/)\<`object`\[`T`\], `T`, `Sprite2DMaterial`\>

The function that gets called when the event is fired.

#### Returns

`boolean`

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`hasEventListener`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#haseventlistener)

***

### onBeforeCompile()

> **onBeforeCompile**(`parameters`, `renderer`): `void`

Defined in: [three.js/materials/Material:onBeforeCompile](https://threejs.org/docs/#api/en/materials/Material.onBeforeCompile)

An optional callback that is executed immediately before the shader
program is compiled. This function is called with the shader source code
as a parameter. Useful for the modification of built-in materials.

This method can only be used when rendering with [WebGLRenderer](https://threejs.org/docs/#api/en/renderers/WebGLRenderer). The
recommended approach when customizing materials is to use `WebGPURenderer` with the new
Node Material system and [TSL](https://github.com/mrdoob/three.js/wiki/Three.js-Shading-Language).

#### Parameters

##### parameters

[`WebGLProgramParametersWithUniforms`](https://threejs.org/docs/)

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

A reference to the renderer.

#### Returns

`void`

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`onBeforeCompile`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#onbeforecompile)

***

### onBeforeRender()

> **onBeforeRender**(`renderer`, `scene`, `camera`, `geometry`, `object`, `group`): `void`

Defined in: [three.js/materials/Material:onBeforeRender](https://threejs.org/docs/#api/en/materials/Material.onBeforeRender)

An optional callback that is executed immediately before the material is used to render a 3D object.

This method can only be used when rendering with [WebGLRenderer](https://threejs.org/docs/#api/en/renderers/WebGLRenderer).

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

The renderer.

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

The scene.

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

The camera that is used to render the scene.

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

The 3D object's geometry.

##### object

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)

The 3D object.

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

The geometry group data.

#### Returns

`void`

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`onBeforeRender`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#onbeforerender)

***

### registerEffect()

> **registerEffect**(`effectClass`, `constants?`): `boolean`

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:273](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L273)

Register an effect class on this material.
Assigns a bit index and packed buffer slots, then rebuilds the shader.
If the effect is already registered, this is a no-op.

#### Parameters

##### effectClass

*typeof* [`MaterialEffect`](/three-flatland/api/three-flatland/src/classes/materialeffect/)

The MaterialEffect subclass to register

##### constants?

`Record`\<`string`, `unknown`\>

Optional constants from the effect instance (for provider effects)

#### Returns

`boolean`

Whether the buffer tier changed (requiring batch rebuild).

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`registerEffect`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#registereffect)

***

### removeEventListener()

> **removeEventListener**\<`T`\>(`type`, `listener`): `void`

Defined in: [three.js/core/EventDispatcher:removeEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.removeEventListener)

Removes a listener from an event type.

#### Type Parameters

##### T

`T` *extends* `"dispose"`

#### Parameters

##### type

`T`

The type of the listener that gets removed.

##### listener

[`EventListener`](https://threejs.org/docs/)\<`object`\[`T`\], `T`, `Sprite2DMaterial`\>

The listener function that gets removed.

#### Returns

`void`

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`removeEventListener`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#removeeventlistener)

***

### setDefaultValues()

> **setDefaultValues**(`material`): `void`

Defined in: [three.js/materials/nodes/NodeMaterial:setDefaultValues](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setDefaultValues)

Most classic material types have a node pendant e.g. for `MeshBasicMaterial`
there is `MeshBasicNodeMaterial`. This utility method is intended for
defining all material properties of the classic type in the node type.

#### Parameters

##### material

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

The material to copy properties with their values to this node material.

#### Returns

`void`

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`setDefaultValues`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#setdefaultvalues)

***

### setTexture()

> **setTexture**(`value`): `void`

Defined in: [packages/three-flatland/src/materials/Sprite2DMaterial.ts:295](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/Sprite2DMaterial.ts#L295)

Set the sprite texture.

#### Parameters

##### value

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

#### Returns

`void`

***

### setup()

> **setup**(`builder`): `void`

Defined in: [three.js/materials/nodes/NodeMaterial:setup](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setup)

Setups the vertex and fragment stage of this node material.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

`void`

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`setup`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#setup)

***

### setupClipping()

> **setupClipping**(`builder`): [`ClippingNode`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupClipping](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupClipping)

Setups the clipping node.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

[`ClippingNode`](https://threejs.org/docs/)

The clipping node.

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`setupClipping`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#setupclipping)

***

### setupDepth()

> **setupDepth**(`builder`): `void`

Defined in: [three.js/materials/nodes/NodeMaterial:setupDepth](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupDepth)

Setups the depth of this material.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

`void`

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`setupDepth`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#setupdepth)

***

### setupDiffuseColor()

> **setupDiffuseColor**(`builder`): `void`

Defined in: [three.js/materials/nodes/NodeMaterial:setupDiffuseColor](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupDiffuseColor)

Setups the computation of the material's diffuse color.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

`void`

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`setupDiffuseColor`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#setupdiffusecolor)

***

### setupEnvironment()

> **setupEnvironment**(`builder`): [`BasicEnvironmentNode`](https://threejs.org/docs/) \| `null`

Defined in: [three.js/materials/nodes/MeshBasicNodeMaterial:setupEnvironment](https://threejs.org/docs/#api/en/materials/nodes/MeshBasicNodeMaterial.setupEnvironment)

Overwritten since this type of material uses [BasicEnvironmentNode](https://threejs.org/docs/)
to implement the default environment mapping.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

[`BasicEnvironmentNode`](https://threejs.org/docs/) \| `null`

The environment node.

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`setupEnvironment`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#setupenvironment)

***

### setupFog()

> **setupFog**(`builder`, `outputNode`): [`Node`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupFog](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupFog)

Setup the fog.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

##### outputNode

[`Node`](https://threejs.org/docs/)

The existing output node.

#### Returns

[`Node`](https://threejs.org/docs/)

The output node.

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`setupFog`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#setupfog)

***

### setupHardwareClipping()

> **setupHardwareClipping**(`builder`): `void`

Defined in: [three.js/materials/nodes/NodeMaterial:setupHardwareClipping](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupHardwareClipping)

Setups the hardware clipping if available on the current device.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

`void`

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`setupHardwareClipping`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#setuphardwareclipping)

***

### setupLighting()

> **setupLighting**(`builder`): [`Node`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupLighting](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupLighting)

Setups the outgoing light node.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

[`Node`](https://threejs.org/docs/)

The outgoing light node.

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`setupLighting`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#setuplighting)

***

### setupLightingModel()

> **setupLightingModel**(): [`BasicLightingModel`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/MeshBasicNodeMaterial:setupLightingModel](https://threejs.org/docs/#api/en/materials/nodes/MeshBasicNodeMaterial.setupLightingModel)

Setups the lighting model.

#### Returns

[`BasicLightingModel`](https://threejs.org/docs/)

The lighting model.

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`setupLightingModel`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#setuplightingmodel)

***

### setupLightMap()

> **setupLightMap**(`builder`): [`Node`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupLightMap](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupLightMap)

Setups the light map node from the material.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

[`Node`](https://threejs.org/docs/)

The light map node.

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`setupLightMap`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#setuplightmap)

***

### setupLights()

> **setupLights**(`builder`): [`LightsNode`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupLights](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupLights)

Setups the lights node based on the scene, environment and material.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

[`LightsNode`](https://threejs.org/docs/)

The lights node.

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`setupLights`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#setuplights)

***

### setupModelViewProjection()

> **setupModelViewProjection**(): [`Node`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupModelViewProjection](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupModelViewProjection)

Setups the position in clip space.

#### Returns

[`Node`](https://threejs.org/docs/)

The position in view space.

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`setupModelViewProjection`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#setupmodelviewprojection)

***

### setupNormal()

> **setupNormal**(): [`Node`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupNormal](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupNormal)

Setups the normal node from the material.

#### Returns

[`Node`](https://threejs.org/docs/)

The normal node.

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`setupNormal`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#setupnormal)

***

### setupObserver()

> **setupObserver**(`builder`): [`NodeMaterialObserver`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupObserver](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupObserver)

Setups a node material observer with the given builder.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

[`NodeMaterialObserver`](https://threejs.org/docs/)

The node material observer.

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`setupObserver`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#setupobserver)

***

### setupOutgoingLight()

> **setupOutgoingLight**(): [`Node`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupOutgoingLight](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupOutgoingLight)

Setups the outgoing light node variable

#### Returns

[`Node`](https://threejs.org/docs/)

The outgoing light node.

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`setupOutgoingLight`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#setupoutgoinglight)

***

### setupOutput()

> **setupOutput**(`builder`, `outputNode`): [`Node`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupOutput](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupOutput)

Setups the output node.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

##### outputNode

[`Node`](https://threejs.org/docs/)

The existing output node.

#### Returns

[`Node`](https://threejs.org/docs/)

The output node.

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`setupOutput`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#setupoutput)

***

### setupPosition()

> **setupPosition**(`builder`): [`Node`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupPosition](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupPosition)

Setups the computation of the position in local space.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

[`Node`](https://threejs.org/docs/)

The position in local space.

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`setupPosition`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#setupposition)

***

### setupPositionView()

> **setupPositionView**(`builder`): [`Node`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupPositionView](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupPositionView)

Setups the position node in view space. This method exists
so derived node materials can modify the implementation e.g. sprite materials.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

[`Node`](https://threejs.org/docs/)

The position in view space.

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`setupPositionView`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#setuppositionview)

***

### setupPremultipliedAlpha()

> **setupPremultipliedAlpha**(`builder`, `outputNode`): [`Node`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupPremultipliedAlpha](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupPremultipliedAlpha)

Setups premultiplied alpha.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

##### outputNode

[`Node`](https://threejs.org/docs/)

The existing output node.

#### Returns

[`Node`](https://threejs.org/docs/)

The output node.

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`setupPremultipliedAlpha`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#setuppremultipliedalpha)

***

### setupVariants()

> `abstract` **setupVariants**(`builder`): `void`

Defined in: [three.js/materials/nodes/NodeMaterial:setupVariants](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupVariants)

Abstract interface method that can be implemented by derived materials
to setup material-specific node variables.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

`void`

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`setupVariants`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#setupvariants)

***

### setupVertex()

> **setupVertex**(`builder`): [`Node`](https://threejs.org/docs/)

Defined in: [three.js/materials/nodes/NodeMaterial:setupVertex](https://threejs.org/docs/#api/en/materials/nodes/NodeMaterial.setupVertex)

Setups the logic for the vertex stage.

#### Parameters

##### builder

[`NodeBuilder`](https://threejs.org/docs/)

The current node builder.

#### Returns

[`Node`](https://threejs.org/docs/)

The position in clip space.

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`setupVertex`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#setupvertex)

***

### setValues()

> **setValues**(`values?`): `void`

Defined in: [three.js/materials/nodes/MeshBasicNodeMaterial:setValues](https://threejs.org/docs/#api/en/materials/nodes/MeshBasicNodeMaterial.setValues)

#### Parameters

##### values?

[`MeshBasicNodeMaterialParameters`](https://threejs.org/docs/)

#### Returns

`void`

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`setValues`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#setvalues)

***

### toJSON()

> **toJSON**(`meta?`): [`MaterialJSON`](https://threejs.org/docs/)

Defined in: [three.js/materials/Material:toJSON](https://threejs.org/docs/#api/en/materials/Material.toJSON)

Serializes the material into JSON.

#### Parameters

##### meta?

[`JSONMeta`](https://threejs.org/docs/)

An optional value holding meta information about the serialization.

#### Returns

[`MaterialJSON`](https://threejs.org/docs/)

A JSON object representing the serialized material.

#### See

ObjectLoader#parse

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`toJSON`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#tojson)

***

### getMaxEffectFloats()

> `static` **getMaxEffectFloats**(): `number`

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:185](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L185)

Return the maximum number of per-instance effect floats this
material type supports. See [MAX\_EFFECT\_FLOATS](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/#max_effect_floats).

#### Returns

`number`

#### Inherited from

[`EffectMaterial`](/three-flatland/api/three-flatland/src/classes/effectmaterial/).[`getMaxEffectFloats`](/three-flatland/api/three-flatland/src/classes/effectmaterial/#getmaxeffectfloats)

***

### getShared()

> `static` **getShared**(`options?`): `Sprite2DMaterial`

Defined in: [packages/three-flatland/src/materials/Sprite2DMaterial.ts:107](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/Sprite2DMaterial.ts#L107)

Get a shared material instance for the given options.
Materials with identical configuration (texture, transparent, lit, colorTransform)
return the same instance, enabling automatic batching.

#### Parameters

##### options?

[`Sprite2DMaterialOptions`](/three-flatland/api/three-flatland/src/interfaces/sprite2dmaterialoptions/) = `{}`

#### Returns

`Sprite2DMaterial`

# SpriteGroup

Defined in: [packages/three-flatland/src/pipeline/SpriteGroup.ts:69](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/SpriteGroup.ts#L69)

2D render pipeline with automatic batching and sorting.

Add SpriteGroup to your scene and add sprites to it.
Sprites are automatically batched by material and sorted by layer/zIndex.

ECS systems run automatically in `updateMatrixWorld()`, which Three.js
calls during `renderer.render(scene, camera)`. No explicit `update()` needed.

Batching is fully ECS-driven:
- Sprite entities get InBatch relations linking them to batch entities
- Systems handle all data flow: assignment, reassignment, buffer sync, removal
- No imperative BatchManager — batch entities, runs, and slot management are pure ECS

## Example

```typescript
const spriteGroup = new SpriteGroup()
scene.add(spriteGroup)

const sprite = new Sprite2D({ texture })
sprite.layer = Layers.ENTITIES
spriteGroup.add(sprite)

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

## Extends

- [`Group`](https://threejs.org/docs/#api/en/objects/Group)

## Implements

- `WorldProvider`

## Constructors

### Constructor

> **new SpriteGroup**(`options?`): `SpriteGroup`

Defined in: [packages/three-flatland/src/pipeline/SpriteGroup.ts:146](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/SpriteGroup.ts#L146)

#### Parameters

##### options?

[`SpriteGroupOptions`](/three-flatland/api/three-flatland/src/interfaces/spritegroupoptions/) = `{}`

#### Returns

`SpriteGroup`

#### Overrides

`Group.constructor`

## Properties

### animations

> **animations**: [`AnimationClip`](https://threejs.org/docs/)[]

Defined in: [three.js/core/Object3D:animations](https://threejs.org/docs/#api/en/core/Object3D.animations)

Array with object's animation clips.

#### Default Value

`[]`

#### Inherited from

`Group.animations`

***

### autoInvalidateTransforms

> **autoInvalidateTransforms**: `boolean`

Defined in: [packages/three-flatland/src/pipeline/SpriteGroup.ts:116](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/SpriteGroup.ts#L116)

Whether to automatically invalidate transforms every frame.
Enable for games where sprites move frequently.
Disable for static UIs and call invalidateTransforms() manually.

***

### autoSort

> **autoSort**: `boolean`

Defined in: [packages/three-flatland/src/pipeline/SpriteGroup.ts:109](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/SpriteGroup.ts#L109)

Whether auto-sorting is enabled.

***

### castShadow

> **castShadow**: `boolean`

Defined in: [three.js/core/Object3D:castShadow](https://threejs.org/docs/#api/en/core/Object3D.castShadow)

Whether the object gets rendered into shadow map.

#### Default Value

`false`

#### Inherited from

`Group.castShadow`

***

### children

> **children**: [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

Defined in: [three.js/core/Object3D:children](https://threejs.org/docs/#api/en/core/Object3D.children)

Array with object's children.

#### See

THREE.Object3DGroup \| Group for info on manually grouping objects.

#### Default Value

`[]`

#### Inherited from

`Group.children`

***

### count?

> `optional` **count?**: `number`

Defined in: [three.js/renderers/common/Backend:count](https://threejs.org/docs/#api/en/renderers/common/Backend.count)

#### Inherited from

`Group.count`

***

### customDepthMaterial?

> `optional` **customDepthMaterial?**: [`Material`](https://threejs.org/docs/#api/en/materials/Material)

Defined in: [three.js/core/Object3D:customDepthMaterial](https://threejs.org/docs/#api/en/core/Object3D.customDepthMaterial)

Custom depth material to be used when rendering to the depth map.

#### Remarks

Can only be used in context of meshes.
When shadow-casting with a THREE.DirectionalLight \| DirectionalLight or THREE.SpotLight \| SpotLight,
if you are modifying vertex positions in the vertex shader you must specify a customDepthMaterial for proper shadows.

#### Default Value

`undefined`

#### Inherited from

`Group.customDepthMaterial`

***

### customDistanceMaterial?

> `optional` **customDistanceMaterial?**: [`Material`](https://threejs.org/docs/#api/en/materials/Material)

Defined in: [three.js/core/Object3D:customDistanceMaterial](https://threejs.org/docs/#api/en/core/Object3D.customDistanceMaterial)

Same as [customDepthMaterial](/three-flatland/api/three-flatland/src/classes/flatland/#customdepthmaterial), but used with THREE.Object3DPointLight \| PointLight.

#### Default Value

`undefined`

#### Inherited from

`Group.customDistanceMaterial`

***

### frustumCulled

> **frustumCulled**: `boolean`

Defined in: [three.js/core/Object3D:frustumCulled](https://threejs.org/docs/#api/en/core/Object3D.frustumCulled)

When this is set, it checks every frame if the object is in the frustum of the camera before rendering the object.
If set to `false` the object gets rendered every frame even if it is not in the frustum of the camera.

#### Default Value

`true`

#### Inherited from

`Group.frustumCulled`

***

### frustumCulling

> **frustumCulling**: `boolean`

Defined in: [packages/three-flatland/src/pipeline/SpriteGroup.ts:104](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/SpriteGroup.ts#L104)

Whether frustum culling is enabled.

***

### id

> `readonly` **id**: `number`

Defined in: [three.js/core/Object3D:id](https://threejs.org/docs/#api/en/core/Object3D.id)

Unique number for this [Object3D](https://threejs.org/docs/#api/en/core/Object3D) instance.

#### Remarks

Note that ids are assigned in chronological order: 1, 2, 3, ..., incrementing by one for each new object.
Expects a `Integer`

#### Inherited from

`Group.id`

***

### isGroup

> `readonly` **isGroup**: `true`

Defined in: [three.js/objects/Group:isGroup](https://threejs.org/docs/#api/en/objects/Group.isGroup)

Read-only flag to check if a given object is of type [Group](https://threejs.org/docs/#api/en/objects/Group).

#### Remarks

This is a _constant_ value

#### Default Value

`true`

#### Inherited from

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/).[`isGroup`](/three-flatland/api/three-flatland/src/classes/flatland/#isgroup)

***

### isObject3D

> `readonly` **isObject3D**: `true`

Defined in: [three.js/core/Object3D:isObject3D](https://threejs.org/docs/#api/en/core/Object3D.isObject3D)

Flag to check if a given object is of type [Object3D](https://threejs.org/docs/#api/en/core/Object3D).

#### Remarks

This is a _constant_ value

#### Default Value

`true`

#### Inherited from

`Group.isObject3D`

***

### layers

> **layers**: [`Layers`](https://threejs.org/docs/#api/en/core/Layers)

Defined in: [three.js/core/Object3D:layers](https://threejs.org/docs/#api/en/core/Object3D.layers)

The layer membership of the object.

#### Remarks

The object is only visible if it has at least one layer in common with the THREE.Object3DCamera \| Camera in use.
This property can also be used to filter out unwanted objects in ray-intersection tests when using THREE.Raycaster \| Raycaster.

#### Default Value

`new THREE.Layers()`

#### Inherited from

`Group.layers`

***

### matrix

> **matrix**: [`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Defined in: [three.js/core/Object3D:matrix](https://threejs.org/docs/#api/en/core/Object3D.matrix)

The local transform matrix.

#### Default Value

`new THREE.Matrix4()`

#### Inherited from

`Group.matrix`

***

### matrixAutoUpdate

> **matrixAutoUpdate**: `boolean`

Defined in: [three.js/core/Object3D:matrixAutoUpdate](https://threejs.org/docs/#api/en/core/Object3D.matrixAutoUpdate)

When this is set, it calculates the matrix of position, (rotation or quaternion) and
scale every frame and also recalculates the matrixWorld property.

#### Default Value

[DEFAULT\_MATRIX\_AUTO\_UPDATE](/three-flatland/api/three-flatland/src/classes/flatland/#default_matrix_auto_update) - that is `(true)`.

#### Inherited from

`Group.matrixAutoUpdate`

***

### matrixWorld

> **matrixWorld**: [`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Defined in: [three.js/core/Object3D:matrixWorld](https://threejs.org/docs/#api/en/core/Object3D.matrixWorld)

The global transform of the object.

#### Remarks

If the [Object3D](https://threejs.org/docs/#api/en/core/Object3D) has no parent, then it's identical to the local transform THREE.Object3D.matrix \| .matrix.

#### Default Value

`new THREE.Matrix4()`

#### Inherited from

`Group.matrixWorld`

***

### matrixWorldAutoUpdate

> **matrixWorldAutoUpdate**: `boolean`

Defined in: [three.js/core/Object3D:matrixWorldAutoUpdate](https://threejs.org/docs/#api/en/core/Object3D.matrixWorldAutoUpdate)

If set, then the renderer checks every frame if the object and its children need matrix updates.
When it isn't, then you have to maintain all matrices in the object and its children yourself.

#### Default Value

[DEFAULT\_MATRIX\_WORLD\_AUTO\_UPDATE](/three-flatland/api/three-flatland/src/classes/flatland/#default_matrix_world_auto_update) - that is `(true)`.

#### Inherited from

`Group.matrixWorldAutoUpdate`

***

### matrixWorldNeedsUpdate

> **matrixWorldNeedsUpdate**: `boolean`

Defined in: [three.js/core/Object3D:matrixWorldNeedsUpdate](https://threejs.org/docs/#api/en/core/Object3D.matrixWorldNeedsUpdate)

When this is set, it calculates the matrixWorld in that frame and resets this property to false.

#### Default Value

`false`

#### Inherited from

`Group.matrixWorldNeedsUpdate`

***

### modelViewMatrix

> `readonly` **modelViewMatrix**: [`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Defined in: [three.js/core/Object3D:modelViewMatrix](https://threejs.org/docs/#api/en/core/Object3D.modelViewMatrix)

#### Default Value

`new THREE.Matrix4()`

#### Inherited from

`Group.modelViewMatrix`

***

### name

> **name**: `string`

Defined in: [three.js/core/Object3D:name](https://threejs.org/docs/#api/en/core/Object3D.name)

Optional name of the object

#### Remarks

_(doesn't need to be unique)_.

#### Default Value

`""`

#### Inherited from

`Group.name`

***

### normalMatrix

> `readonly` **normalMatrix**: [`Matrix3`](https://threejs.org/docs/#api/en/math/Matrix3)

Defined in: [three.js/core/Object3D:normalMatrix](https://threejs.org/docs/#api/en/core/Object3D.normalMatrix)

#### Default Value

`new THREE.Matrix3()`

#### Inherited from

`Group.normalMatrix`

***

### occlusionTest?

> `optional` **occlusionTest?**: `boolean`

Defined in: [three.js/renderers/common/Backend:occlusionTest](https://threejs.org/docs/#api/en/renderers/common/Backend.occlusionTest)

#### Inherited from

`Group.occlusionTest`

***

### parent

> **parent**: [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `null`

Defined in: [three.js/core/Object3D:parent](https://threejs.org/docs/#api/en/core/Object3D.parent)

Object's parent in the [scene graph](https://en.wikipedia.org/wiki/Scene_graph).

#### Remarks

An object can have at most one parent.

#### Default Value

`null`

#### Inherited from

`Group.parent`

***

### pivot

> **pivot**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3) \| `null`

Defined in: [three.js/core/Object3D:pivot](https://threejs.org/docs/#api/en/core/Object3D.pivot)

The pivot point for rotation and scale transformations.
When set, rotation and scale are applied around this point
instead of the object's origin.

#### Default

```ts
null
```

#### Inherited from

`Group.pivot`

***

### position

> `readonly` **position**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:position](https://threejs.org/docs/#api/en/core/Object3D.position)

Object's local position.

#### Default Value

`new THREE.Vector3()` - that is `(0, 0, 0)`.

#### Inherited from

`Group.position`

***

### quaternion

> `readonly` **quaternion**: [`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

Defined in: [three.js/core/Object3D:quaternion](https://threejs.org/docs/#api/en/core/Object3D.quaternion)

Object's local rotation as a THREE.Quaternion \| Quaternion.

#### Default Value

`new THREE.Quaternion()` - that is `(0,  0, 0, 1)`.

#### Inherited from

`Group.quaternion`

***

### receiveShadow

> **receiveShadow**: `boolean`

Defined in: [three.js/core/Object3D:receiveShadow](https://threejs.org/docs/#api/en/core/Object3D.receiveShadow)

Whether the material receives shadows.

#### Default Value

`false`

#### Inherited from

`Group.receiveShadow`

***

### renderOrder

> **renderOrder**: `number`

Defined in: [three.js/core/Object3D:renderOrder](https://threejs.org/docs/#api/en/core/Object3D.renderOrder)

This value allows the default rendering order of [scene graph](https://en.wikipedia.org/wiki/Scene_graph)
objects to be overridden although opaque and transparent objects remain sorted independently.

#### Remarks

When this property is set for an instance of [Group](https://threejs.org/docs/#api/en/objects/Group), all descendants objects will be sorted and rendered together.
Sorting is from lowest to highest renderOrder.

#### Default Value

`0`

#### Inherited from

`Group.renderOrder`

***

### rotation

> `readonly` **rotation**: [`Euler`](https://threejs.org/docs/#api/en/math/Euler)

Defined in: [three.js/core/Object3D:rotation](https://threejs.org/docs/#api/en/core/Object3D.rotation)

Object's local rotation ([Euler angles](https://en.wikipedia.org/wiki/Euler_angles)), in radians.

#### Default Value

`new THREE.Euler()` - that is `(0, 0, 0, Euler.DEFAULT_ORDER)`.

#### Inherited from

`Group.rotation`

***

### scale

> `readonly` **scale**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:scale](https://threejs.org/docs/#api/en/core/Object3D.scale)

The object's local scale.

#### Default Value

`new THREE.Vector3( 1, 1, 1 )`

#### Inherited from

`Group.scale`

***

### static

> **static**: `boolean`

Defined in: [three.js/core/Object3D:static](https://threejs.org/docs/#api/en/core/Object3D.static)

Whether the 3D object is supposed to be static or not. If set to `true`, it means
the 3D object is not going to be changed after the initial renderer. This includes
geometry and material settings. A static 3D object can be processed by the renderer
slightly faster since certain state checks can be bypassed.

Only relevant in context of WebGPURenderer.

#### Default

```ts
false
```

#### Inherited from

`Group.static`

***

### type

> `readonly` **type**: `string`

Defined in: [three.js/core/Object3D:type](https://threejs.org/docs/#api/en/core/Object3D.type)

A Read-only _string_ to check `this` object type.

#### Remarks

This can be used to find a specific type of Object3D in a scene.
Sub-classes will update this value.

#### Default Value

`Object3D`

#### Inherited from

`Group.type`

***

### up

> **up**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:up](https://threejs.org/docs/#api/en/core/Object3D.up)

This is used by the [lookAt](https://threejs.org/docs/) method, for example, to determine the orientation of the result.

#### Default Value

[Object3D.DEFAULT\_UP](/three-flatland/api/three-flatland/src/classes/flatland/#default_up) - that is `(0, 1, 0)`.

#### Inherited from

`Group.up`

***

### userData

> **userData**: `Record`\<`string`, `any`\>

Defined in: [three.js/core/Object3D:userData](https://threejs.org/docs/#api/en/core/Object3D.userData)

An object that can be used to store custom data about the [Object3D](https://threejs.org/docs/#api/en/core/Object3D).

#### Remarks

It should not hold references to _functions_ as these **will not** be cloned.

#### Default

`{}`

#### Inherited from

`Group.userData`

***

### uuid

> **uuid**: `string`

Defined in: [three.js/core/Object3D:uuid](https://threejs.org/docs/#api/en/core/Object3D.uuid)

[UUID](http://en.wikipedia.org/wiki/Universally_unique_identifier) of this object instance.

#### Remarks

This gets automatically assigned and shouldn't be edited.

#### Inherited from

`Group.uuid`

***

### visible

> **visible**: `boolean`

Defined in: [three.js/core/Object3D:visible](https://threejs.org/docs/#api/en/core/Object3D.visible)

Object gets rendered if `true`.

#### Default Value

`true`

#### Inherited from

`Group.visible`

***

### DEFAULT\_MATRIX\_AUTO\_UPDATE

> `static` **DEFAULT\_MATRIX\_AUTO\_UPDATE**: `boolean`

Defined in: [three.js/core/Object3D:DEFAULT_MATRIX_AUTO_UPDATE](https://threejs.org/docs/#api/en/core/Object3D.DEFAULT_MATRIX_AUTO_UPDATE)

The default setting for [matrixAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixautoupdate) for newly created Object3Ds.

#### Default Value

`true`

#### Inherited from

`Group.DEFAULT_MATRIX_AUTO_UPDATE`

***

### DEFAULT\_MATRIX\_WORLD\_AUTO\_UPDATE

> `static` **DEFAULT\_MATRIX\_WORLD\_AUTO\_UPDATE**: `boolean`

Defined in: [three.js/core/Object3D:DEFAULT_MATRIX_WORLD_AUTO_UPDATE](https://threejs.org/docs/#api/en/core/Object3D.DEFAULT_MATRIX_WORLD_AUTO_UPDATE)

The default setting for [matrixWorldAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldautoupdate) for newly created Object3Ds.

#### Default Value

`true`

#### Inherited from

`Group.DEFAULT_MATRIX_WORLD_AUTO_UPDATE`

***

### DEFAULT\_UP

> `static` **DEFAULT\_UP**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:DEFAULT_UP](https://threejs.org/docs/#api/en/core/Object3D.DEFAULT_UP)

The default [up](/three-flatland/api/three-flatland/src/classes/flatland/#up) direction for objects, also used as the default position for THREE.DirectionalLight \| DirectionalLight,
THREE.HemisphereLight \| HemisphereLight and THREE.Spotlight \| Spotlight (which creates lights shining from the top down).

#### Default Value

`new THREE.Vector3( 0, 1, 0)`

#### Inherited from

`Group.DEFAULT_UP`

## Accessors

### batchCount

#### Get Signature

> **get** **batchCount**(): `number`

Defined in: [packages/three-flatland/src/pipeline/SpriteGroup.ts:598](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/SpriteGroup.ts#L598)

Get the number of batches.

##### Returns

`number`

***

### isEmpty

#### Get Signature

> **get** **isEmpty**(): `boolean`

Defined in: [packages/three-flatland/src/pipeline/SpriteGroup.ts:606](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/SpriteGroup.ts#L606)

Check if the renderer has any sprites.

##### Returns

`boolean`

***

### spriteCount

#### Get Signature

> **get** **spriteCount**(): `number`

Defined in: [packages/three-flatland/src/pipeline/SpriteGroup.ts:591](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/SpriteGroup.ts#L591)

Get the number of sprites.

##### Returns

`number`

***

### stats

#### Get Signature

> **get** **stats**(): [`RenderStats`](/three-flatland/api/three-flatland/src/interfaces/renderstats/)

Defined in: [packages/three-flatland/src/pipeline/SpriteGroup.ts:569](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/SpriteGroup.ts#L569)

Get render statistics.

Note: `drawCalls` is NOT computed here — it must come from
`renderer.info.render.calls` after the actual Three.js render pass.
See Flatland.stats for the real value, or capture the delta yourself:
```ts
const before = renderer.info.render.calls
renderer.render(scene, camera)
const drawCalls = renderer.info.render.calls - before
```

##### Returns

[`RenderStats`](/three-flatland/api/three-flatland/src/interfaces/renderstats/)

***

### world

#### Get Signature

> **get** **world**(): `World`

Defined in: [packages/three-flatland/src/pipeline/SpriteGroup.ts:163](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/SpriteGroup.ts#L163)

The ECS world managed by this renderer.
Sprites added to this renderer are enrolled in this world.

##### Returns

`World`

#### Implementation of

`WorldProvider.world`

## Methods

### add()

#### Call Signature

> **add**(...`objects`): `this`

Defined in: [packages/three-flatland/src/pipeline/SpriteGroup.ts:278](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/SpriteGroup.ts#L278)

Add a sprite to the renderer.

##### Parameters

###### objects

...[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

##### Returns

`this`

##### Overrides

`Group.add`

#### Call Signature

> **add**(`sprite`): `this`

Defined in: [packages/three-flatland/src/pipeline/SpriteGroup.ts:279](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/SpriteGroup.ts#L279)

Add a sprite to the renderer.

##### Parameters

###### sprite

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/)

##### Returns

`this`

##### Overrides

`Group.add`

***

### addEventListener()

> **addEventListener**\<`T`\>(`type`, `listener`): `void`

Defined in: [three.js/core/EventDispatcher:addEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.addEventListener)

Adds a listener to an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### type

`T`

The type of event to listen to.

##### listener

[`EventListener`](https://threejs.org/docs/)\<[`Object3DEventMap`](https://threejs.org/docs/)\[`T`\], `T`, `SpriteGroup`\>

The function that gets called when the event is fired.

#### Returns

`void`

#### Inherited from

`Group.addEventListener`

***

### addSprites()

> **addSprites**(...`sprites`): `this`

Defined in: [packages/three-flatland/src/pipeline/SpriteGroup.ts:303](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/SpriteGroup.ts#L303)

Add multiple sprites to the renderer.

#### Parameters

##### sprites

...[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/)[]

#### Returns

`this`

***

### applyMatrix4()

> **applyMatrix4**(`matrix`): `void`

Defined in: [three.js/core/Object3D:applyMatrix4](https://threejs.org/docs/#api/en/core/Object3D.applyMatrix4)

Applies the matrix transform to the object and updates the object's position, rotation and scale.

#### Parameters

##### matrix

[`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

#### Returns

`void`

#### Inherited from

`Group.applyMatrix4`

***

### applyQuaternion()

> **applyQuaternion**(`quaternion`): `this`

Defined in: [three.js/core/Object3D:applyQuaternion](https://threejs.org/docs/#api/en/core/Object3D.applyQuaternion)

Applies the rotation represented by the quaternion to the object.

#### Parameters

##### quaternion

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

#### Returns

`this`

#### Inherited from

`Group.applyQuaternion`

***

### attach()

> **attach**(`object`): `this`

Defined in: [three.js/core/Object3D:attach](https://threejs.org/docs/#api/en/core/Object3D.attach)

Adds a [Object3D](https://threejs.org/docs/#api/en/core/Object3D) as a child of this, while maintaining the object's world transform.

#### Parameters

##### object

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)

#### Returns

`this`

#### Remarks

Note: This method does not support scene graphs having non-uniformly-scaled nodes(s).

#### See

[add](https://threejs.org/docs/)

#### Inherited from

`Group.attach`

***

### clear()

> **clear**(): `this`

Defined in: [packages/three-flatland/src/pipeline/SpriteGroup.ts:613](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/SpriteGroup.ts#L613)

Clear all sprites.

#### Returns

`this`

#### Overrides

`Group.clear`

***

### clone()

> **clone**(`recursive?`): `this`

Defined in: [packages/three-flatland/src/pipeline/SpriteGroup.ts:675](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/SpriteGroup.ts#L675)

Clone for devtools/serialization compatibility.
SpriteGroup manages an ECS world that cannot be meaningfully cloned.
Returns a Group containing cloned child meshes (the SpriteBatch instances).

#### Parameters

##### recursive?

`boolean`

#### Returns

`this`

#### Overrides

`Group.clone`

***

### copy()

> **copy**(`object`, `recursive?`): `this`

Defined in: [three.js/core/Object3D:copy](https://threejs.org/docs/#api/en/core/Object3D.copy)

Copies the given object into this object.

#### Parameters

##### object

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)

##### recursive?

`boolean`

If set to `true`, descendants of the object are copied next to the existing ones. If set to
`false`, descendants are left unchanged. Default is `true`.

#### Returns

`this`

#### Remarks

Event listeners and user-defined callbacks (.onAfterRender and .onBeforeRender) are not copied.

#### Inherited from

`Group.copy`

***

### dispatchEvent()

> **dispatchEvent**\<`T`\>(`event`): `void`

Defined in: [three.js/core/EventDispatcher:dispatchEvent](https://threejs.org/docs/#api/en/core/EventDispatcher.dispatchEvent)

Fire an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### event

[`BaseEvent`](https://threejs.org/docs/)\<`T`\> & [`Object3DEventMap`](https://threejs.org/docs/)\[`T`\]

The event that gets fired.

#### Returns

`void`

#### Inherited from

`Group.dispatchEvent`

***

### dispose()

> **dispose**(): `void`

Defined in: [packages/three-flatland/src/pipeline/SpriteGroup.ts:694](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/SpriteGroup.ts#L694)

Dispose of all resources.

#### Returns

`void`

***

### getObjectById()

> **getObjectById**(`id`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

Defined in: [three.js/core/Object3D:getObjectById](https://threejs.org/docs/#api/en/core/Object3D.getObjectById)

Searches through an object and its children, starting with the object itself, and returns the first with a matching id.

#### Parameters

##### id

`number`

Unique number of the object instance. Expects a `Integer`

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

#### Remarks

Note that ids are assigned in chronological order: 1, 2, 3, ..., incrementing by one for each new object.

#### See

id

#### Inherited from

`Group.getObjectById`

***

### getObjectByName()

> **getObjectByName**(`name`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

Defined in: [three.js/core/Object3D:getObjectByName](https://threejs.org/docs/#api/en/core/Object3D.getObjectByName)

Searches through an object and its children, starting with the object itself, and returns the first with a matching name.

#### Parameters

##### name

`string`

String to match to the children's Object3D.name property.

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

#### Remarks

Note that for most objects the name is an empty string by default
You will have to set it manually to make use of this method.

#### Inherited from

`Group.getObjectByName`

***

### getObjectByProperty()

> **getObjectByProperty**(`name`, `value`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

Defined in: [three.js/core/Object3D:getObjectByProperty](https://threejs.org/docs/#api/en/core/Object3D.getObjectByProperty)

Searches through an object and its children, starting with the object itself,
and returns the first with a property that matches the value given.

#### Parameters

##### name

`string`

the property name to search for.

##### value

`any`

value of the given property.

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

#### Inherited from

`Group.getObjectByProperty`

***

### getObjectsByProperty()

> **getObjectsByProperty**(`name`, `value`, `optionalTarget?`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

Defined in: [three.js/core/Object3D:getObjectsByProperty](https://threejs.org/docs/#api/en/core/Object3D.getObjectsByProperty)

Searches through an object and its children, starting with the object itself,
and returns the first with a property that matches the value given.

#### Parameters

##### name

`string`

The property name to search for.

##### value

`any`

Value of the given property.

##### optionalTarget?

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

target to set the result. Otherwise a new Array is instantiated. If set, you must clear
this array prior to each call (i.e., array.length = 0;).

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

#### Inherited from

`Group.getObjectsByProperty`

***

### getWorldDirection()

> **getWorldDirection**(`target`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:getWorldDirection](https://threejs.org/docs/#api/en/core/Object3D.getWorldDirection)

Returns a vector representing the direction of object's positive z-axis in world space.

#### Parameters

##### target

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

The result will be copied into this Vector3.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Group.getWorldDirection`

***

### getWorldPosition()

> **getWorldPosition**(`target`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:getWorldPosition](https://threejs.org/docs/#api/en/core/Object3D.getWorldPosition)

Returns a vector representing the position of the object in world space.

#### Parameters

##### target

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

The result will be copied into this Vector3.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Group.getWorldPosition`

***

### getWorldQuaternion()

> **getWorldQuaternion**(`target`): [`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

Defined in: [three.js/core/Object3D:getWorldQuaternion](https://threejs.org/docs/#api/en/core/Object3D.getWorldQuaternion)

Returns a quaternion representing the rotation of the object in world space.

#### Parameters

##### target

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

The result will be copied into this Quaternion.

#### Returns

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

#### Inherited from

`Group.getWorldQuaternion`

***

### getWorldScale()

> **getWorldScale**(`target`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:getWorldScale](https://threejs.org/docs/#api/en/core/Object3D.getWorldScale)

Returns a vector of the scaling factors applied to the object for each axis in world space.

#### Parameters

##### target

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

The result will be copied into this Vector3.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Group.getWorldScale`

***

### hasEventListener()

> **hasEventListener**\<`T`\>(`type`, `listener`): `boolean`

Defined in: [three.js/core/EventDispatcher:hasEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.hasEventListener)

Checks if listener is added to an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### type

`T`

The type of event to listen to.

##### listener

[`EventListener`](https://threejs.org/docs/)\<[`Object3DEventMap`](https://threejs.org/docs/)\[`T`\], `T`, `SpriteGroup`\>

The function that gets called when the event is fired.

#### Returns

`boolean`

#### Inherited from

`Group.hasEventListener`

***

### invalidate()

> **invalidate**(`_sprite`): `void`

Defined in: [packages/three-flatland/src/pipeline/SpriteGroup.ts:350](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/SpriteGroup.ts#L350)

Mark a sprite as needing sort recalculation.
Call when sprite's layer or zIndex changes.
Note: With pure ECS batching, Changed() queries detect this automatically.
This method is kept for explicit invalidation if needed.

#### Parameters

##### \_sprite

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/)

#### Returns

`void`

***

### invalidateAll()

> **invalidateAll**(): `void`

Defined in: [packages/three-flatland/src/pipeline/SpriteGroup.ts:358](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/SpriteGroup.ts#L358)

Mark all sprites as needing update.
Note: With pure ECS batching, this is largely a no-op since systems detect changes.

#### Returns

`void`

***

### invalidateTransforms()

> **invalidateTransforms**(): `void`

Defined in: [packages/three-flatland/src/pipeline/SpriteGroup.ts:366](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/SpriteGroup.ts#L366)

Mark transforms as needing update.
Note: With autoInvalidateTransforms=true (default), this happens every frame.

#### Returns

`void`

***

### localToWorld()

> **localToWorld**(`vector`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:localToWorld](https://threejs.org/docs/#api/en/core/Object3D.localToWorld)

Converts the vector from this object's local space to world space.

#### Parameters

##### vector

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A vector representing a position in this object's local space.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Group.localToWorld`

***

### lookAt()

#### Call Signature

> **lookAt**(`vector`): `void`

Defined in: [three.js/core/Object3D:lookAt](https://threejs.org/docs/#api/en/core/Object3D.lookAt)

Rotates the object to face a point in world space.

##### Parameters

###### vector

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A vector representing a position in world space to look at.

##### Returns

`void`

##### Remarks

This method does not support objects having non-uniformly-scaled parent(s).

##### Inherited from

`Group.lookAt`

#### Call Signature

> **lookAt**(`x`, `y`, `z`): `void`

Defined in: [three.js/core/Object3D:lookAt](https://threejs.org/docs/#api/en/core/Object3D.lookAt)

Rotates the object to face a point in world space.

##### Parameters

###### x

`number`

Expects a `Float`

###### y

`number`

Expects a `Float`

###### z

`number`

Expects a `Float`

##### Returns

`void`

##### Remarks

This method does not support objects having non-uniformly-scaled parent(s).

##### Inherited from

`Group.lookAt`

***

### onAfterRender()

> **onAfterRender**(`renderer`, `scene`, `camera`, `geometry`, `material`, `group`): `void`

Defined in: [three.js/core/Object3D:onAfterRender](https://threejs.org/docs/#api/en/core/Object3D.onAfterRender)

An optional callback that is executed immediately after a 3D object is rendered.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### material

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, geometry, material, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

`Group.onAfterRender`

***

### onAfterShadow()

> **onAfterShadow**(`renderer`, `scene`, `camera`, `shadowCamera`, `geometry`, `depthMaterial`, `group`): `void`

Defined in: [three.js/core/Object3D:onAfterShadow](https://threejs.org/docs/#api/en/core/Object3D.onAfterShadow)

An optional callback that is executed immediately after a 3D object is rendered to a shadow map.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### shadowCamera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### depthMaterial

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, shadowCamera, geometry,
depthMaterial, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

`Group.onAfterShadow`

***

### onBeforeRender()

> **onBeforeRender**(`renderer`, `scene`, `camera`, `geometry`, `material`, `group`): `void`

Defined in: [three.js/core/Object3D:onBeforeRender](https://threejs.org/docs/#api/en/core/Object3D.onBeforeRender)

An optional callback that is executed immediately before a 3D object is rendered.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### material

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, geometry, material, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

`Group.onBeforeRender`

***

### onBeforeShadow()

> **onBeforeShadow**(`renderer`, `scene`, `camera`, `shadowCamera`, `geometry`, `depthMaterial`, `group`): `void`

Defined in: [three.js/core/Object3D:onBeforeShadow](https://threejs.org/docs/#api/en/core/Object3D.onBeforeShadow)

An optional callback that is executed immediately before a 3D object is rendered to a shadow map.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### shadowCamera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### depthMaterial

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, shadowCamera, geometry,
depthMaterial, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

`Group.onBeforeShadow`

***

### raycast()

> **raycast**(`raycaster`, `intersects`): `void`

Defined in: [three.js/core/Object3D:raycast](https://threejs.org/docs/#api/en/core/Object3D.raycast)

Abstract (empty) method to get intersections between a casted ray and this object

#### Parameters

##### raycaster

[`Raycaster`](https://threejs.org/docs/#api/en/core/Raycaster)

##### intersects

[`Intersection`](https://threejs.org/docs/)\<[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>\>[]

#### Returns

`void`

#### Remarks

Subclasses such as THREE.Mesh \| Mesh, THREE.Line \| Line, and THREE.Points \| Points implement this method in order to use raycasting.

#### See

THREE.Raycaster \| Raycaster

#### Default Value

`() => {}`

#### Inherited from

`Group.raycast`

***

### remove()

#### Call Signature

> **remove**(...`objects`): `this`

Defined in: [packages/three-flatland/src/pipeline/SpriteGroup.ts:316](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/SpriteGroup.ts#L316)

Remove a sprite from the renderer.

##### Parameters

###### objects

...[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

##### Returns

`this`

##### Overrides

`Group.remove`

#### Call Signature

> **remove**(`sprite`): `this`

Defined in: [packages/three-flatland/src/pipeline/SpriteGroup.ts:317](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/SpriteGroup.ts#L317)

Remove a sprite from the renderer.

##### Parameters

###### sprite

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/)

##### Returns

`this`

##### Overrides

`Group.remove`

***

### removeEventListener()

> **removeEventListener**\<`T`\>(`type`, `listener`): `void`

Defined in: [three.js/core/EventDispatcher:removeEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.removeEventListener)

Removes a listener from an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### type

`T`

The type of the listener that gets removed.

##### listener

[`EventListener`](https://threejs.org/docs/)\<[`Object3DEventMap`](https://threejs.org/docs/)\[`T`\], `T`, `SpriteGroup`\>

The listener function that gets removed.

#### Returns

`void`

#### Inherited from

`Group.removeEventListener`

***

### removeFromParent()

> **removeFromParent**(): `this`

Defined in: [three.js/core/Object3D:removeFromParent](https://threejs.org/docs/#api/en/core/Object3D.removeFromParent)

Removes this object from its current parent.

#### Returns

`this`

#### Inherited from

`Group.removeFromParent`

***

### removeSprites()

> **removeSprites**(...`sprites`): `this`

Defined in: [packages/three-flatland/src/pipeline/SpriteGroup.ts:336](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/SpriteGroup.ts#L336)

Remove multiple sprites from the renderer.

#### Parameters

##### sprites

...[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/)[]

#### Returns

`this`

***

### rotateOnAxis()

> **rotateOnAxis**(`axis`, `angle`): `this`

Defined in: [three.js/core/Object3D:rotateOnAxis](https://threejs.org/docs/#api/en/core/Object3D.rotateOnAxis)

Rotate an object along an axis in object space.

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in object space.

##### angle

`number`

The angle in radians. Expects a `Float`

#### Returns

`this`

#### Remarks

The axis is assumed to be normalized.

#### Inherited from

`Group.rotateOnAxis`

***

### rotateOnWorldAxis()

> **rotateOnWorldAxis**(`axis`, `angle`): `this`

Defined in: [three.js/core/Object3D:rotateOnWorldAxis](https://threejs.org/docs/#api/en/core/Object3D.rotateOnWorldAxis)

Rotate an object along an axis in world space.

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in world space.

##### angle

`number`

The angle in radians. Expects a `Float`

#### Returns

`this`

#### Remarks

The axis is assumed to be normalized
Method Assumes no rotated parent.

#### Inherited from

`Group.rotateOnWorldAxis`

***

### rotateX()

> **rotateX**(`angle`): `this`

Defined in: [three.js/core/Object3D:rotateX](https://threejs.org/docs/#api/en/core/Object3D.rotateX)

Rotates the object around _x_ axis in local space.

#### Parameters

##### angle

`number`

#### Returns

`this`

#### Inherited from

`Group.rotateX`

***

### rotateY()

> **rotateY**(`angle`): `this`

Defined in: [three.js/core/Object3D:rotateY](https://threejs.org/docs/#api/en/core/Object3D.rotateY)

Rotates the object around _y_ axis in local space.

#### Parameters

##### angle

`number`

#### Returns

`this`

#### Inherited from

`Group.rotateY`

***

### rotateZ()

> **rotateZ**(`angle`): `this`

Defined in: [three.js/core/Object3D:rotateZ](https://threejs.org/docs/#api/en/core/Object3D.rotateZ)

Rotates the object around _z_ axis in local space.

#### Parameters

##### angle

`number`

#### Returns

`this`

#### Inherited from

`Group.rotateZ`

***

### setRotationFromAxisAngle()

> **setRotationFromAxisAngle**(`axis`, `angle`): `void`

Defined in: [three.js/core/Object3D:setRotationFromAxisAngle](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromAxisAngle)

Calls THREE.Quaternion.setFromAxisAngle \| setFromAxisAngle(axis, angle) on the [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in object space.

##### angle

`number`

Angle in radians. Expects a `Float`

#### Returns

`void`

#### Inherited from

`Group.setRotationFromAxisAngle`

***

### setRotationFromEuler()

> **setRotationFromEuler**(`euler`): `void`

Defined in: [three.js/core/Object3D:setRotationFromEuler](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromEuler)

Calls THREE.Quaternion.setFromEuler \| setFromEuler(euler) on the [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### euler

[`Euler`](https://threejs.org/docs/#api/en/math/Euler)

Euler angle specifying rotation amount.

#### Returns

`void`

#### Inherited from

`Group.setRotationFromEuler`

***

### setRotationFromMatrix()

> **setRotationFromMatrix**(`m`): `void`

Defined in: [three.js/core/Object3D:setRotationFromMatrix](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromMatrix)

Calls THREE.Quaternion.setFromRotationMatrix \| setFromRotationMatrix(m) on the [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### m

[`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Rotate the quaternion by the rotation component of the matrix.

#### Returns

`void`

#### Remarks

Note that this assumes that the upper 3x3 of m is a pure rotation matrix (i.e, unscaled).

#### Inherited from

`Group.setRotationFromMatrix`

***

### setRotationFromQuaternion()

> **setRotationFromQuaternion**(`q`): `void`

Defined in: [three.js/core/Object3D:setRotationFromQuaternion](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromQuaternion)

Copy the given THREE.Quaternion \| Quaternion into [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### q

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

Normalized Quaternion.

#### Returns

`void`

#### Inherited from

`Group.setRotationFromQuaternion`

***

### toJSON()

> **toJSON**(`meta?`): [`Object3DJSON`](https://threejs.org/docs/)

Defined in: [three.js/core/Object3D:toJSON](https://threejs.org/docs/#api/en/core/Object3D.toJSON)

Convert the object to three.js [JSON Object/Scene format](https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4).

#### Parameters

##### meta?

[`JSONMeta`](https://threejs.org/docs/)

Object containing metadata such as materials, textures or images for the object.

#### Returns

[`Object3DJSON`](https://threejs.org/docs/)

#### Inherited from

`Group.toJSON`

***

### translateOnAxis()

> **translateOnAxis**(`axis`, `distance`): `this`

Defined in: [three.js/core/Object3D:translateOnAxis](https://threejs.org/docs/#api/en/core/Object3D.translateOnAxis)

Translate an object by distance along an axis in object space

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in object space.

##### distance

`number`

The distance to translate. Expects a `Float`

#### Returns

`this`

#### Remarks

The axis is assumed to be normalized.

#### Inherited from

`Group.translateOnAxis`

***

### translateX()

> **translateX**(`distance`): `this`

Defined in: [three.js/core/Object3D:translateX](https://threejs.org/docs/#api/en/core/Object3D.translateX)

Translates object along x axis in object space by distance units.

#### Parameters

##### distance

`number`

Expects a `Float`

#### Returns

`this`

#### Inherited from

`Group.translateX`

***

### translateY()

> **translateY**(`distance`): `this`

Defined in: [three.js/core/Object3D:translateY](https://threejs.org/docs/#api/en/core/Object3D.translateY)

Translates object along _y_ axis in object space by distance units.

#### Parameters

##### distance

`number`

Expects a `Float`

#### Returns

`this`

#### Inherited from

`Group.translateY`

***

### translateZ()

> **translateZ**(`distance`): `this`

Defined in: [three.js/core/Object3D:translateZ](https://threejs.org/docs/#api/en/core/Object3D.translateZ)

Translates object along _z_ axis in object space by distance units.

#### Parameters

##### distance

`number`

Expects a `Float`

#### Returns

`this`

#### Inherited from

`Group.translateZ`

***

### traverse()

> **traverse**(`callback`): `void`

Defined in: [three.js/core/Object3D:traverse](https://threejs.org/docs/#api/en/core/Object3D.traverse)

Executes the callback on this object and all descendants.

#### Parameters

##### callback

(`object`) => `any`

A function with as first argument an [Object3D](https://threejs.org/docs/#api/en/core/Object3D) object.

#### Returns

`void`

#### Remarks

Note: Modifying the scene graph inside the callback is discouraged.

#### Inherited from

`Group.traverse`

***

### traverseAncestors()

> **traverseAncestors**(`callback`): `void`

Defined in: [three.js/core/Object3D:traverseAncestors](https://threejs.org/docs/#api/en/core/Object3D.traverseAncestors)

Executes the callback on all ancestors.

#### Parameters

##### callback

(`object`) => `any`

A function with as first argument an [Object3D](https://threejs.org/docs/#api/en/core/Object3D) object.

#### Returns

`void`

#### Remarks

Note: Modifying the scene graph inside the callback is discouraged.

#### Inherited from

`Group.traverseAncestors`

***

### traverseVisible()

> **traverseVisible**(`callback`): `void`

Defined in: [three.js/core/Object3D:traverseVisible](https://threejs.org/docs/#api/en/core/Object3D.traverseVisible)

Like traverse, but the callback will only be executed for visible objects

#### Parameters

##### callback

(`object`) => `any`

A function with as first argument an [Object3D](https://threejs.org/docs/#api/en/core/Object3D) object.

#### Returns

`void`

#### Remarks

Descendants of invisible objects are not traversed.
Note: Modifying the scene graph inside the callback is discouraged.

#### Inherited from

`Group.traverseVisible`

***

### ~~update()~~

> **update**(): `void`

Defined in: [packages/three-flatland/src/pipeline/SpriteGroup.ts:428](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/SpriteGroup.ts#L428)

Explicitly run all ECS systems for a new frame.

:::caution[Deprecated]
Use Three.js `renderer.render()` instead — systems run
automatically in `updateMatrixWorld()`. Kept for backwards compatibility.
:::

#### Returns

`void`

***

### updateMatrix()

> **updateMatrix**(): `void`

Defined in: [three.js/core/Object3D:updateMatrix](https://threejs.org/docs/#api/en/core/Object3D.updateMatrix)

Updates local transform.

#### Returns

`void`

#### Inherited from

`Group.updateMatrix`

***

### updateMatrixWorld()

> **updateMatrixWorld**(`force?`): `void`

Defined in: [packages/three-flatland/src/pipeline/SpriteGroup.ts:388](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/SpriteGroup.ts#L388)

Updates the global transform of the object.
And will update the object descendants if [.matrixWorldNeedsUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldneedsupdate) is set to true or if the force parameter is set to `true`.

#### Parameters

##### force?

`boolean`

A boolean that can be used to bypass [.matrixWorldAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldautoupdate), to recalculate the world matrix of the object and descendants on the current frame.
Useful if you cannot wait for the renderer to update it on the next frame, assuming [.matrixWorldAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldautoupdate) set to `true`.

#### Returns

`void`

#### Overrides

`Group.updateMatrixWorld`

***

### updateWorldMatrix()

> **updateWorldMatrix**(`updateParents`, `updateChildren`): `void`

Defined in: [three.js/core/Object3D:updateWorldMatrix](https://threejs.org/docs/#api/en/core/Object3D.updateWorldMatrix)

Updates the global transform of the object.

#### Parameters

##### updateParents

`boolean`

Recursively updates global transform of ancestors.

##### updateChildren

`boolean`

Recursively updates global transform of descendants.

#### Returns

`void`

#### Inherited from

`Group.updateWorldMatrix`

***

### worldToLocal()

> **worldToLocal**(`vector`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:worldToLocal](https://threejs.org/docs/#api/en/core/Object3D.worldToLocal)

Converts the vector from world space to this object's local space.

#### Parameters

##### vector

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A vector representing a position in world space.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Group.worldToLocal`

# SpriteSheetLoader

Defined in: [packages/three-flatland/src/loaders/SpriteSheetLoader.ts:67](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/SpriteSheetLoader.ts#L67)

Loader for spritesheet JSON files.

Extends Three.js's Loader class for compatibility with R3F's useLoader.
Supports:
- JSON Hash format (TexturePacker default)
- JSON Array format

## Example

```typescript
// Three.js usage - static API
const sheet = await SpriteSheetLoader.load('/sprites/player.json');

// R3F usage - works with useLoader
import { SpriteSheetLoader } from 'three-flatland/react';
const sheet = useLoader(SpriteSheetLoader, '/sprites/player.json');

// Override preset via extension
const sheet = useLoader(SpriteSheetLoader, '/sprites/ui.json', (loader) => {
  loader.preset = 'smooth';
});

// Set loader-level default
SpriteSheetLoader.options = 'smooth';
```

## Extends

- [`Loader`](https://threejs.org/docs/#api/en/loaders/Loader)\<[`SpriteSheet`](/three-flatland/api/three-flatland/src/interfaces/spritesheet/)\>

## Constructors

### Constructor

> **new SpriteSheetLoader**(`manager?`): `SpriteSheetLoader`

Defined in: [three.js/loaders/Loader:SpriteSheetLoader](https://threejs.org/docs/#api/en/loaders/Loader.SpriteSheetLoader)

#### Parameters

##### manager?

[`LoadingManager`](https://threejs.org/docs/)

#### Returns

`SpriteSheetLoader`

#### Inherited from

`Loader<SpriteSheet>.constructor`

## Properties

### crossOrigin

> **crossOrigin**: `string`

Defined in: [three.js/loaders/Loader:crossOrigin](https://threejs.org/docs/#api/en/loaders/Loader.crossOrigin)

#### Default

```ts
'anonymous'
```

#### Inherited from

`Loader.crossOrigin`

***

### forceRuntime

> **forceRuntime**: `boolean` = `false`

Defined in: [packages/three-flatland/src/loaders/SpriteSheetLoader.ts:101](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/SpriteSheetLoader.ts#L101)

Generate this sheet's normal map in the browser on every load
instead of loading a pre-baked sidecar. The in-memory bake runs on
every load; the sidecar probe and "no baked sibling" warn are
skipped. Not a dev-iteration knob.
See [BakedAssetLoaderOptions.forceRuntime](/three-flatland/api/three-flatland/src/interfaces/spritesheetloaderoptions/#forceruntime).

***

### manager

> **manager**: [`LoadingManager`](https://threejs.org/docs/)

Defined in: [three.js/loaders/Loader:manager](https://threejs.org/docs/#api/en/loaders/Loader.manager)

#### Inherited from

`Loader.manager`

***

### normals

> **normals**: `SpriteSheetNormalsOption` = `false`

Defined in: [packages/three-flatland/src/loaders/SpriteSheetLoader.ts:92](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/SpriteSheetLoader.ts#L92)

Normal-map generation. See [SpriteSheetLoaderOptions.normals](/three-flatland/api/three-flatland/src/interfaces/spritesheetloaderoptions/#normals).

***

### path

> **path**: `string`

Defined in: [three.js/loaders/Loader:path](https://threejs.org/docs/#api/en/loaders/Loader.path)

#### Default

```ts
''
```

#### Inherited from

`Loader.path`

***

### preset

> **preset**: [`TexturePreset`](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/) \| [`TextureOptions`](/three-flatland/api/three-flatland/src/interfaces/textureoptions/) \| `undefined` = `undefined`

Defined in: [packages/three-flatland/src/loaders/SpriteSheetLoader.ts:87](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/SpriteSheetLoader.ts#L87)

Instance-level preset override.
Set via R3F's useLoader extension callback.

#### Example

```tsx
const sheet = useLoader(SpriteSheetLoader, '/sprites/ui.json', (loader) => {
  loader.preset = 'smooth';
});
```

***

### requestHeader

> **requestHeader**: `object`

Defined in: [three.js/loaders/Loader:requestHeader](https://threejs.org/docs/#api/en/loaders/Loader.requestHeader)

#### Index Signature

\[`header`: `string`\]: `string`

#### Default

```ts
{}
```

#### Inherited from

`Loader.requestHeader`

***

### resourcePath

> **resourcePath**: `string`

Defined in: [three.js/loaders/Loader:resourcePath](https://threejs.org/docs/#api/en/loaders/Loader.resourcePath)

#### Default

```ts
''
```

#### Inherited from

`Loader.resourcePath`

***

### withCredentials

> **withCredentials**: `boolean`

Defined in: [three.js/loaders/Loader:withCredentials](https://threejs.org/docs/#api/en/loaders/Loader.withCredentials)

#### Default

```ts
false
```

#### Inherited from

`Loader.withCredentials`

***

### DEFAULT\_MATERIAL\_NAME

> `static` **DEFAULT\_MATERIAL\_NAME**: `string`

Defined in: [three.js/loaders/Loader:DEFAULT_MATERIAL_NAME](https://threejs.org/docs/#api/en/loaders/Loader.DEFAULT_MATERIAL_NAME)

#### Inherited from

`Loader.DEFAULT_MATERIAL_NAME`

***

### options

> `static` **options**: [`TexturePreset`](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/) \| [`TextureOptions`](/three-flatland/api/three-flatland/src/interfaces/textureoptions/) \| `undefined` = `undefined`

Defined in: [packages/three-flatland/src/loaders/SpriteSheetLoader.ts:74](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/SpriteSheetLoader.ts#L74)

Texture options for this loader class.
When undefined, falls through to TextureConfig.options.

## Methods

### abort()

> **abort**(): `this`

Defined in: [three.js/loaders/Loader:abort](https://threejs.org/docs/#api/en/loaders/Loader.abort)

#### Returns

`this`

#### Inherited from

`Loader.abort`

***

### load()

> **load**(`url`, `onLoad`, `onProgress?`, `onError?`): `void`

Defined in: [three.js/loaders/Loader:load](https://threejs.org/docs/#api/en/loaders/Loader.load)

#### Parameters

##### url

`string`

##### onLoad

(`data`) => `void`

##### onProgress?

(`event`) => `void`

##### onError?

(`err`) => `void`

#### Returns

`void`

#### Inherited from

`Loader.load`

***

### loadAsync()

> **loadAsync**(`url`): `Promise`\<[`SpriteSheet`](/three-flatland/api/three-flatland/src/interfaces/spritesheet/)\>

Defined in: [packages/three-flatland/src/loaders/SpriteSheetLoader.ts:107](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/SpriteSheetLoader.ts#L107)

Load a spritesheet asynchronously (for R3F useLoader compatibility).
Presets are automatically applied.

#### Parameters

##### url

`string`

#### Returns

`Promise`\<[`SpriteSheet`](/three-flatland/api/three-flatland/src/interfaces/spritesheet/)\>

#### Overrides

`Loader.loadAsync`

***

### setCrossOrigin()

> **setCrossOrigin**(`crossOrigin`): `this`

Defined in: [three.js/loaders/Loader:setCrossOrigin](https://threejs.org/docs/#api/en/loaders/Loader.setCrossOrigin)

#### Parameters

##### crossOrigin

`string`

#### Returns

`this`

#### Inherited from

`Loader.setCrossOrigin`

***

### setPath()

> **setPath**(`path`): `this`

Defined in: [three.js/loaders/Loader:setPath](https://threejs.org/docs/#api/en/loaders/Loader.setPath)

#### Parameters

##### path

`string`

#### Returns

`this`

#### Inherited from

`Loader.setPath`

***

### setRequestHeader()

> **setRequestHeader**(`requestHeader`): `this`

Defined in: [three.js/loaders/Loader:setRequestHeader](https://threejs.org/docs/#api/en/loaders/Loader.setRequestHeader)

#### Parameters

##### requestHeader

#### Returns

`this`

#### Inherited from

`Loader.setRequestHeader`

***

### setResourcePath()

> **setResourcePath**(`resourcePath`): `this`

Defined in: [three.js/loaders/Loader:setResourcePath](https://threejs.org/docs/#api/en/loaders/Loader.setResourcePath)

#### Parameters

##### resourcePath

`string`

#### Returns

`this`

#### Inherited from

`Loader.setResourcePath`

***

### setWithCredentials()

> **setWithCredentials**(`value`): `this`

Defined in: [three.js/loaders/Loader:setWithCredentials](https://threejs.org/docs/#api/en/loaders/Loader.setWithCredentials)

#### Parameters

##### value

`boolean`

#### Returns

`this`

#### Inherited from

`Loader.setWithCredentials`

***

### clearCache()

> `static` **clearCache**(): `void`

Defined in: [packages/three-flatland/src/loaders/SpriteSheetLoader.ts:358](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/SpriteSheetLoader.ts#L358)

Clear the cache.

#### Returns

`void`

***

### load()

> `static` **load**(`url`, `options?`): `Promise`\<[`SpriteSheet`](/three-flatland/api/three-flatland/src/interfaces/spritesheet/)\>

Defined in: [packages/three-flatland/src/loaders/SpriteSheetLoader.ts:124](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/SpriteSheetLoader.ts#L124)

Load a spritesheet from a JSON file (static method for Three.js usage).
Results are cached by URL and resolved options.

#### Parameters

##### url

`string`

##### options?

[`SpriteSheetLoaderOptions`](/three-flatland/api/three-flatland/src/interfaces/spritesheetloaderoptions/)

#### Returns

`Promise`\<[`SpriteSheet`](/three-flatland/api/three-flatland/src/interfaces/spritesheet/)\>

***

### preload()

> `static` **preload**(`urls`, `options?`): `Promise`\<[`SpriteSheet`](/three-flatland/api/three-flatland/src/interfaces/spritesheet/)[]\>

Defined in: [packages/three-flatland/src/loaders/SpriteSheetLoader.ts:365](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/SpriteSheetLoader.ts#L365)

Preload multiple spritesheets.

#### Parameters

##### urls

`string`[]

##### options?

[`SpriteSheetLoaderOptions`](/three-flatland/api/three-flatland/src/interfaces/spritesheetloaderoptions/)

#### Returns

`Promise`\<[`SpriteSheet`](/three-flatland/api/three-flatland/src/interfaces/spritesheet/)[]\>

# TextureConfig

Defined in: [packages/three-flatland/src/loaders/texturePresets.ts:59](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/texturePresets.ts#L59)

Global texture configuration.

Sets system-wide defaults for texture loading. Individual loaders
can override via their static `options` property, and per-load
overrides are supported via options parameters.

## Example

```typescript
import { TextureConfig } from 'three-flatland'

// Use smooth filtering globally
TextureConfig.options = 'smooth'

// Or use custom options
TextureConfig.options = {
  minFilter: NearestFilter,
  magFilter: LinearFilter,
}
```

## Constructors

### Constructor

> **new TextureConfig**(): `TextureConfig`

#### Returns

`TextureConfig`

## Accessors

### options

#### Get Signature

> **get** `static` **options**(): [`TexturePreset`](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/) \| [`TextureOptions`](/three-flatland/api/three-flatland/src/interfaces/textureoptions/)

Defined in: [packages/three-flatland/src/loaders/texturePresets.ts:63](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/texturePresets.ts#L63)

Get the global texture options

##### Returns

[`TexturePreset`](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/) \| [`TextureOptions`](/three-flatland/api/three-flatland/src/interfaces/textureoptions/)

#### Set Signature

> **set** `static` **options**(`value`): `void`

Defined in: [packages/three-flatland/src/loaders/texturePresets.ts:68](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/texturePresets.ts#L68)

Set the global texture options

##### Parameters

###### value

[`TexturePreset`](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/) \| [`TextureOptions`](/three-flatland/api/three-flatland/src/interfaces/textureoptions/)

##### Returns

`void`

## Methods

### reset()

> `static` **reset**(): `void`

Defined in: [packages/three-flatland/src/loaders/texturePresets.ts:73](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/texturePresets.ts#L73)

Reset to system default ('pixel-art')

#### Returns

`void`

# TextureLoader

Defined in: [packages/three-flatland/src/loaders/TextureLoader.ts:43](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/TextureLoader.ts#L43)

Texture loader with hierarchical preset support.

Extends Three.js's Loader class for compatibility with R3F's useLoader.
Automatically applies texture presets based on the hierarchy:
1. TextureLoader.options (static loader default)
2. TextureConfig.options (global default)
3. 'pixel-art' (system default)

## Example

```typescript
// Three.js usage - static API
const texture = await TextureLoader.load('/sprites/player.png')

// R3F usage - works with useLoader
import { TextureLoader } from 'three-flatland/react'
const texture = useLoader(TextureLoader, '/sprite.png')
// Presets are automatically applied!

// Override presets for specific textures
const smoothTexture = await TextureLoader.load('/ui.png', { texture: 'smooth' })

// Set loader-level default
TextureLoader.options = 'smooth'
```

## Extends

- [`Loader`](https://threejs.org/docs/#api/en/loaders/Loader)\<[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\>

## Constructors

### Constructor

> **new TextureLoader**(`manager?`): `TextureLoader`

Defined in: [three.js/loaders/Loader:TextureLoader](https://threejs.org/docs/#api/en/loaders/Loader.TextureLoader)

#### Parameters

##### manager?

[`LoadingManager`](https://threejs.org/docs/)

#### Returns

`TextureLoader`

#### Inherited from

`Loader<Texture>.constructor`

## Properties

### crossOrigin

> **crossOrigin**: `string`

Defined in: [three.js/loaders/Loader:crossOrigin](https://threejs.org/docs/#api/en/loaders/Loader.crossOrigin)

#### Default

```ts
'anonymous'
```

#### Inherited from

`Loader.crossOrigin`

***

### manager

> **manager**: [`LoadingManager`](https://threejs.org/docs/)

Defined in: [three.js/loaders/Loader:manager](https://threejs.org/docs/#api/en/loaders/Loader.manager)

#### Inherited from

`Loader.manager`

***

### path

> **path**: `string`

Defined in: [three.js/loaders/Loader:path](https://threejs.org/docs/#api/en/loaders/Loader.path)

#### Default

```ts
''
```

#### Inherited from

`Loader.path`

***

### preset

> **preset**: [`TexturePreset`](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/) \| [`TextureOptions`](/three-flatland/api/three-flatland/src/interfaces/textureoptions/) \| `undefined` = `undefined`

Defined in: [packages/three-flatland/src/loaders/TextureLoader.ts:65](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/TextureLoader.ts#L65)

Instance-level preset override.
Set via R3F's useLoader extension callback.

#### Example

```tsx
// Override preset for specific textures via extension
const texture = useLoader(TextureLoader, '/ui.png', (loader) => {
  loader.preset = 'smooth'
})
```

***

### requestHeader

> **requestHeader**: `object`

Defined in: [three.js/loaders/Loader:requestHeader](https://threejs.org/docs/#api/en/loaders/Loader.requestHeader)

#### Index Signature

\[`header`: `string`\]: `string`

#### Default

```ts
{}
```

#### Inherited from

`Loader.requestHeader`

***

### resourcePath

> **resourcePath**: `string`

Defined in: [three.js/loaders/Loader:resourcePath](https://threejs.org/docs/#api/en/loaders/Loader.resourcePath)

#### Default

```ts
''
```

#### Inherited from

`Loader.resourcePath`

***

### withCredentials

> **withCredentials**: `boolean`

Defined in: [three.js/loaders/Loader:withCredentials](https://threejs.org/docs/#api/en/loaders/Loader.withCredentials)

#### Default

```ts
false
```

#### Inherited from

`Loader.withCredentials`

***

### DEFAULT\_MATERIAL\_NAME

> `static` **DEFAULT\_MATERIAL\_NAME**: `string`

Defined in: [three.js/loaders/Loader:DEFAULT_MATERIAL_NAME](https://threejs.org/docs/#api/en/loaders/Loader.DEFAULT_MATERIAL_NAME)

#### Inherited from

`Loader.DEFAULT_MATERIAL_NAME`

***

### options

> `static` **options**: [`TexturePreset`](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/) \| [`TextureOptions`](/three-flatland/api/three-flatland/src/interfaces/textureoptions/) \| `undefined` = `undefined`

Defined in: [packages/three-flatland/src/loaders/TextureLoader.ts:51](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/TextureLoader.ts#L51)

Texture options for this loader class.
When undefined, falls through to TextureConfig.options.

## Methods

### abort()

> **abort**(): `this`

Defined in: [three.js/loaders/Loader:abort](https://threejs.org/docs/#api/en/loaders/Loader.abort)

#### Returns

`this`

#### Inherited from

`Loader.abort`

***

### load()

> **load**(`url`, `onLoad?`, `onProgress?`, `onError?`): [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Defined in: [packages/three-flatland/src/loaders/TextureLoader.ts:71](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/TextureLoader.ts#L71)

Load a texture (callback style for R3F useLoader compatibility).
Presets are automatically applied.

#### Parameters

##### url

`string`

##### onLoad?

(`texture`) => `void`

##### onProgress?

(`event`) => `void`

##### onError?

(`err`) => `void`

#### Returns

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

#### Overrides

`Loader.load`

***

### loadAsync()

> **loadAsync**(`url`, `onProgress?`): `Promise`\<[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\>\>

Defined in: [packages/three-flatland/src/loaders/TextureLoader.ts:95](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/TextureLoader.ts#L95)

Load a texture asynchronously.
Presets are automatically applied.

#### Parameters

##### url

`string`

##### onProgress?

(`event`) => `void`

#### Returns

`Promise`\<[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\>\>

#### Overrides

`Loader.loadAsync`

***

### setCrossOrigin()

> **setCrossOrigin**(`crossOrigin`): `this`

Defined in: [three.js/loaders/Loader:setCrossOrigin](https://threejs.org/docs/#api/en/loaders/Loader.setCrossOrigin)

#### Parameters

##### crossOrigin

`string`

#### Returns

`this`

#### Inherited from

`Loader.setCrossOrigin`

***

### setPath()

> **setPath**(`path`): `this`

Defined in: [three.js/loaders/Loader:setPath](https://threejs.org/docs/#api/en/loaders/Loader.setPath)

#### Parameters

##### path

`string`

#### Returns

`this`

#### Inherited from

`Loader.setPath`

***

### setRequestHeader()

> **setRequestHeader**(`requestHeader`): `this`

Defined in: [three.js/loaders/Loader:setRequestHeader](https://threejs.org/docs/#api/en/loaders/Loader.setRequestHeader)

#### Parameters

##### requestHeader

#### Returns

`this`

#### Inherited from

`Loader.setRequestHeader`

***

### setResourcePath()

> **setResourcePath**(`resourcePath`): `this`

Defined in: [three.js/loaders/Loader:setResourcePath](https://threejs.org/docs/#api/en/loaders/Loader.setResourcePath)

#### Parameters

##### resourcePath

`string`

#### Returns

`this`

#### Inherited from

`Loader.setResourcePath`

***

### setWithCredentials()

> **setWithCredentials**(`value`): `this`

Defined in: [three.js/loaders/Loader:setWithCredentials](https://threejs.org/docs/#api/en/loaders/Loader.setWithCredentials)

#### Parameters

##### value

`boolean`

#### Returns

`this`

#### Inherited from

`Loader.setWithCredentials`

***

### clearCache()

> `static` **clearCache**(): `void`

Defined in: [packages/three-flatland/src/loaders/TextureLoader.ts:159](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/TextureLoader.ts#L159)

Clear the cache.

#### Returns

`void`

***

### load()

> `static` **load**(`url`, `options?`): `Promise`\<[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\>\>

Defined in: [packages/three-flatland/src/loaders/TextureLoader.ts:109](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/TextureLoader.ts#L109)

Load a texture from a URL (static method for Three.js usage).
Results are cached by URL and resolved options.

#### Parameters

##### url

`string`

##### options?

[`TextureLoaderOptions`](/three-flatland/api/three-flatland/src/interfaces/textureloaderoptions/)

#### Returns

`Promise`\<[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\>\>

***

### preload()

> `static` **preload**(`urls`, `options?`): `Promise`\<[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\>[]\>

Defined in: [packages/three-flatland/src/loaders/TextureLoader.ts:152](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/TextureLoader.ts#L152)

Preload multiple textures.

#### Parameters

##### urls

`string`[]

##### options?

[`TextureLoaderOptions`](/three-flatland/api/three-flatland/src/interfaces/textureloaderoptions/)

#### Returns

`Promise`\<[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\>[]\>

# TiledLoader

Defined in: [packages/three-flatland/src/loaders/TiledLoader.ts:169](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/TiledLoader.ts#L169)

Loader for Tiled JSON format (.tmj/.json).

Extends Three.js's Loader class for compatibility with R3F's useLoader.
Supports:
- Standard JSON map format
- Embedded and external tilesets
- Tile layers with data arrays
- Infinite maps with chunks
- Object layers
- Tile animations
- Tile collision data

## Example

```typescript
// Three.js usage - static API
const mapData = await TiledLoader.load('/maps/level1.json')

// Override for this load
const mapData = await TiledLoader.load('/maps/hd-level.json', { texture: 'smooth' })

// R3F usage - works with useLoader
import { TiledLoader } from 'three-flatland/react';
const mapData = useLoader(TiledLoader, '/maps/level1.json');

// Override preset via extension
const mapData = useLoader(TiledLoader, '/maps/hd-level.json', (loader) => {
  loader.preset = 'smooth';
});

// Set loader-level default
TiledLoader.options = 'pixel-art'
```

## Extends

- [`Loader`](https://threejs.org/docs/#api/en/loaders/Loader)\<[`TileMapData`](/three-flatland/api/three-flatland/src/interfaces/tilemapdata/)\>

## Constructors

### Constructor

> **new TiledLoader**(`manager?`): `TiledLoader`

Defined in: [three.js/loaders/Loader:TiledLoader](https://threejs.org/docs/#api/en/loaders/Loader.TiledLoader)

#### Parameters

##### manager?

[`LoadingManager`](https://threejs.org/docs/)

#### Returns

`TiledLoader`

#### Inherited from

`Loader<TileMapData>.constructor`

## Properties

### crossOrigin

> **crossOrigin**: `string`

Defined in: [three.js/loaders/Loader:crossOrigin](https://threejs.org/docs/#api/en/loaders/Loader.crossOrigin)

#### Default

```ts
'anonymous'
```

#### Inherited from

`Loader.crossOrigin`

***

### forceRuntime

> **forceRuntime**: `boolean` = `false`

Defined in: [packages/three-flatland/src/loaders/TiledLoader.ts:203](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/TiledLoader.ts#L203)

Generate this tilemap's tileset normal maps in the browser on
every load instead of loading pre-baked sidecars. The in-memory
bake runs on every load; sidecar probes and "no baked sibling"
warns are skipped. Not a dev-iteration knob.
See [BakedAssetLoaderOptions.forceRuntime](/three-flatland/api/three-flatland/src/interfaces/spritesheetloaderoptions/#forceruntime).

***

### manager

> **manager**: [`LoadingManager`](https://threejs.org/docs/)

Defined in: [three.js/loaders/Loader:manager](https://threejs.org/docs/#api/en/loaders/Loader.manager)

#### Inherited from

`Loader.manager`

***

### normals

> **normals**: `TiledNormalsOption` = `false`

Defined in: [packages/three-flatland/src/loaders/TiledLoader.ts:194](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/TiledLoader.ts#L194)

Normal-map generation. See [TiledLoaderOptions.normals](/three-flatland/api/three-flatland/src/interfaces/tiledloaderoptions/#normals).

***

### path

> **path**: `string`

Defined in: [three.js/loaders/Loader:path](https://threejs.org/docs/#api/en/loaders/Loader.path)

#### Default

```ts
''
```

#### Inherited from

`Loader.path`

***

### preset

> **preset**: [`TexturePreset`](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/) \| [`TextureOptions`](/three-flatland/api/three-flatland/src/interfaces/textureoptions/) \| `undefined` = `undefined`

Defined in: [packages/three-flatland/src/loaders/TiledLoader.ts:189](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/TiledLoader.ts#L189)

Instance-level preset override.
Set via R3F's useLoader extension callback.

#### Example

```tsx
const mapData = useLoader(TiledLoader, '/maps/level.json', (loader) => {
  loader.preset = 'smooth';
});
```

***

### requestHeader

> **requestHeader**: `object`

Defined in: [three.js/loaders/Loader:requestHeader](https://threejs.org/docs/#api/en/loaders/Loader.requestHeader)

#### Index Signature

\[`header`: `string`\]: `string`

#### Default

```ts
{}
```

#### Inherited from

`Loader.requestHeader`

***

### resourcePath

> **resourcePath**: `string`

Defined in: [three.js/loaders/Loader:resourcePath](https://threejs.org/docs/#api/en/loaders/Loader.resourcePath)

#### Default

```ts
''
```

#### Inherited from

`Loader.resourcePath`

***

### withCredentials

> **withCredentials**: `boolean`

Defined in: [three.js/loaders/Loader:withCredentials](https://threejs.org/docs/#api/en/loaders/Loader.withCredentials)

#### Default

```ts
false
```

#### Inherited from

`Loader.withCredentials`

***

### DEFAULT\_MATERIAL\_NAME

> `static` **DEFAULT\_MATERIAL\_NAME**: `string`

Defined in: [three.js/loaders/Loader:DEFAULT_MATERIAL_NAME](https://threejs.org/docs/#api/en/loaders/Loader.DEFAULT_MATERIAL_NAME)

#### Inherited from

`Loader.DEFAULT_MATERIAL_NAME`

***

### options

> `static` **options**: [`TexturePreset`](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/) \| [`TextureOptions`](/three-flatland/api/three-flatland/src/interfaces/textureoptions/) \| `undefined` = `undefined`

Defined in: [packages/three-flatland/src/loaders/TiledLoader.ts:176](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/TiledLoader.ts#L176)

Texture options for this loader class.
When undefined, falls through to TextureConfig.options.

## Methods

### abort()

> **abort**(): `this`

Defined in: [three.js/loaders/Loader:abort](https://threejs.org/docs/#api/en/loaders/Loader.abort)

#### Returns

`this`

#### Inherited from

`Loader.abort`

***

### load()

> **load**(`url`, `onLoad`, `onProgress?`, `onError?`): `void`

Defined in: [three.js/loaders/Loader:load](https://threejs.org/docs/#api/en/loaders/Loader.load)

#### Parameters

##### url

`string`

##### onLoad

(`data`) => `void`

##### onProgress?

(`event`) => `void`

##### onError?

(`err`) => `void`

#### Returns

`void`

#### Inherited from

`Loader.load`

***

### loadAsync()

> **loadAsync**(`url`): `Promise`\<[`TileMapData`](/three-flatland/api/three-flatland/src/interfaces/tilemapdata/)\>

Defined in: [packages/three-flatland/src/loaders/TiledLoader.ts:209](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/TiledLoader.ts#L209)

Load a Tiled map asynchronously (for R3F useLoader compatibility).
Presets are automatically applied.

#### Parameters

##### url

`string`

#### Returns

`Promise`\<[`TileMapData`](/three-flatland/api/three-flatland/src/interfaces/tilemapdata/)\>

#### Overrides

`Loader.loadAsync`

***

### setCrossOrigin()

> **setCrossOrigin**(`crossOrigin`): `this`

Defined in: [three.js/loaders/Loader:setCrossOrigin](https://threejs.org/docs/#api/en/loaders/Loader.setCrossOrigin)

#### Parameters

##### crossOrigin

`string`

#### Returns

`this`

#### Inherited from

`Loader.setCrossOrigin`

***

### setPath()

> **setPath**(`path`): `this`

Defined in: [three.js/loaders/Loader:setPath](https://threejs.org/docs/#api/en/loaders/Loader.setPath)

#### Parameters

##### path

`string`

#### Returns

`this`

#### Inherited from

`Loader.setPath`

***

### setRequestHeader()

> **setRequestHeader**(`requestHeader`): `this`

Defined in: [three.js/loaders/Loader:setRequestHeader](https://threejs.org/docs/#api/en/loaders/Loader.setRequestHeader)

#### Parameters

##### requestHeader

#### Returns

`this`

#### Inherited from

`Loader.setRequestHeader`

***

### setResourcePath()

> **setResourcePath**(`resourcePath`): `this`

Defined in: [three.js/loaders/Loader:setResourcePath](https://threejs.org/docs/#api/en/loaders/Loader.setResourcePath)

#### Parameters

##### resourcePath

`string`

#### Returns

`this`

#### Inherited from

`Loader.setResourcePath`

***

### setWithCredentials()

> **setWithCredentials**(`value`): `this`

Defined in: [three.js/loaders/Loader:setWithCredentials](https://threejs.org/docs/#api/en/loaders/Loader.setWithCredentials)

#### Parameters

##### value

`boolean`

#### Returns

`this`

#### Inherited from

`Loader.setWithCredentials`

***

### clearCache()

> `static` **clearCache**(): `void`

Defined in: [packages/three-flatland/src/loaders/TiledLoader.ts:649](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/TiledLoader.ts#L649)

Clear the cache.

#### Returns

`void`

***

### load()

> `static` **load**(`url`, `options?`): `Promise`\<[`TileMapData`](/three-flatland/api/three-flatland/src/interfaces/tilemapdata/)\>

Defined in: [packages/three-flatland/src/loaders/TiledLoader.ts:226](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/TiledLoader.ts#L226)

Load a Tiled JSON map (static method for Three.js usage).
Results are cached by URL and resolved options.

#### Parameters

##### url

`string`

##### options?

[`TiledLoaderOptions`](/three-flatland/api/three-flatland/src/interfaces/tiledloaderoptions/)

#### Returns

`Promise`\<[`TileMapData`](/three-flatland/api/three-flatland/src/interfaces/tilemapdata/)\>

***

### preload()

> `static` **preload**(`urls`, `options?`): `Promise`\<[`TileMapData`](/three-flatland/api/three-flatland/src/interfaces/tilemapdata/)[]\>

Defined in: [packages/three-flatland/src/loaders/TiledLoader.ts:656](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/TiledLoader.ts#L656)

Preload multiple maps.

#### Parameters

##### urls

`string`[]

##### options?

[`TiledLoaderOptions`](/three-flatland/api/three-flatland/src/interfaces/tiledloaderoptions/)

#### Returns

`Promise`\<[`TileMapData`](/three-flatland/api/three-flatland/src/interfaces/tilemapdata/)[]\>

# TileLayer

Defined in: [packages/three-flatland/src/tilemap/TileLayer.ts:65](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileLayer.ts#L65)

A layer of tiles in a tilemap.

Splits tiles into regional chunks for frustum culling, each rendered as a
single InstancedMesh with Sprite2DMaterial. Maps up to chunkSize×chunkSize
tiles naturally collapse into one chunk (one draw call).

## Example

```typescript
const layer = new TileLayer(
  layerData,
  tileset,
  16, // tileWidth
  16, // tileHeight
)

scene.add(layer)

// In update loop
layer.update(deltaMs)

// Access material for effects
layer.material.colorNode = myCustomEffect
```

## Extends

- [`Group`](https://threejs.org/docs/#api/en/objects/Group)

## Constructors

### Constructor

> **new TileLayer**(`data`, `tileset`, `tileWidth`, `tileHeight`, `chunkSize?`): `TileLayer`

Defined in: [packages/three-flatland/src/tilemap/TileLayer.ts:237](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileLayer.ts#L237)

#### Parameters

##### data

[`TileLayerData`](/three-flatland/api/three-flatland/src/interfaces/tilelayerdata/)

##### tileset

[`Tileset`](/three-flatland/api/three-flatland/src/classes/tileset/)

##### tileWidth

`number`

##### tileHeight

`number`

##### chunkSize?

`number` = `256`

#### Returns

`TileLayer`

#### Overrides

`Group.constructor`

## Properties

### animations

> **animations**: [`AnimationClip`](https://threejs.org/docs/)[]

Defined in: [three.js/core/Object3D:animations](https://threejs.org/docs/#api/en/core/Object3D.animations)

Array with object's animation clips.

#### Default Value

`[]`

#### Inherited from

`Group.animations`

***

### castShadow

> **castShadow**: `boolean`

Defined in: [three.js/core/Object3D:castShadow](https://threejs.org/docs/#api/en/core/Object3D.castShadow)

Whether the object gets rendered into shadow map.

#### Default Value

`false`

#### Inherited from

`Group.castShadow`

***

### children

> **children**: [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

Defined in: [three.js/core/Object3D:children](https://threejs.org/docs/#api/en/core/Object3D.children)

Array with object's children.

#### See

THREE.Object3DGroup \| Group for info on manually grouping objects.

#### Default Value

`[]`

#### Inherited from

`Group.children`

***

### chunkSize

> `readonly` **chunkSize**: `number`

Defined in: [packages/three-flatland/src/tilemap/TileLayer.ts:74](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileLayer.ts#L74)

Chunk size in tiles (e.g., 256 means 256×256 tiles per chunk)

***

### count?

> `optional` **count?**: `number`

Defined in: [three.js/renderers/common/Backend:count](https://threejs.org/docs/#api/en/renderers/common/Backend.count)

#### Inherited from

`Group.count`

***

### customDepthMaterial?

> `optional` **customDepthMaterial?**: [`Material`](https://threejs.org/docs/#api/en/materials/Material)

Defined in: [three.js/core/Object3D:customDepthMaterial](https://threejs.org/docs/#api/en/core/Object3D.customDepthMaterial)

Custom depth material to be used when rendering to the depth map.

#### Remarks

Can only be used in context of meshes.
When shadow-casting with a THREE.DirectionalLight \| DirectionalLight or THREE.SpotLight \| SpotLight,
if you are modifying vertex positions in the vertex shader you must specify a customDepthMaterial for proper shadows.

#### Default Value

`undefined`

#### Inherited from

`Group.customDepthMaterial`

***

### customDistanceMaterial?

> `optional` **customDistanceMaterial?**: [`Material`](https://threejs.org/docs/#api/en/materials/Material)

Defined in: [three.js/core/Object3D:customDistanceMaterial](https://threejs.org/docs/#api/en/core/Object3D.customDistanceMaterial)

Same as [customDepthMaterial](/three-flatland/api/three-flatland/src/classes/flatland/#customdepthmaterial), but used with THREE.Object3DPointLight \| PointLight.

#### Default Value

`undefined`

#### Inherited from

`Group.customDistanceMaterial`

***

### data

> `readonly` **data**: [`TileLayerData`](/three-flatland/api/three-flatland/src/interfaces/tilelayerdata/)

Defined in: [packages/three-flatland/src/tilemap/TileLayer.ts:67](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileLayer.ts#L67)

Layer data

***

### frustumCulled

> **frustumCulled**: `boolean`

Defined in: [three.js/core/Object3D:frustumCulled](https://threejs.org/docs/#api/en/core/Object3D.frustumCulled)

When this is set, it checks every frame if the object is in the frustum of the camera before rendering the object.
If set to `false` the object gets rendered every frame even if it is not in the frustum of the camera.

#### Default Value

`true`

#### Inherited from

`Group.frustumCulled`

***

### id

> `readonly` **id**: `number`

Defined in: [three.js/core/Object3D:id](https://threejs.org/docs/#api/en/core/Object3D.id)

Unique number for this [Object3D](https://threejs.org/docs/#api/en/core/Object3D) instance.

#### Remarks

Note that ids are assigned in chronological order: 1, 2, 3, ..., incrementing by one for each new object.
Expects a `Integer`

#### Inherited from

`Group.id`

***

### isGroup

> `readonly` **isGroup**: `true`

Defined in: [three.js/objects/Group:isGroup](https://threejs.org/docs/#api/en/objects/Group.isGroup)

Read-only flag to check if a given object is of type [Group](https://threejs.org/docs/#api/en/objects/Group).

#### Remarks

This is a _constant_ value

#### Default Value

`true`

#### Inherited from

`Group.isGroup`

***

### isObject3D

> `readonly` **isObject3D**: `true`

Defined in: [three.js/core/Object3D:isObject3D](https://threejs.org/docs/#api/en/core/Object3D.isObject3D)

Flag to check if a given object is of type [Object3D](https://threejs.org/docs/#api/en/core/Object3D).

#### Remarks

This is a _constant_ value

#### Default Value

`true`

#### Inherited from

`Group.isObject3D`

***

### layers

> **layers**: [`Layers`](https://threejs.org/docs/#api/en/core/Layers)

Defined in: [three.js/core/Object3D:layers](https://threejs.org/docs/#api/en/core/Object3D.layers)

The layer membership of the object.

#### Remarks

The object is only visible if it has at least one layer in common with the THREE.Object3DCamera \| Camera in use.
This property can also be used to filter out unwanted objects in ray-intersection tests when using THREE.Raycaster \| Raycaster.

#### Default Value

`new THREE.Layers()`

#### Inherited from

`Group.layers`

***

### material

> `readonly` **material**: [`Sprite2DMaterial`](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/)

Defined in: [packages/three-flatland/src/tilemap/TileLayer.ts:77](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileLayer.ts#L77)

The Sprite2DMaterial used for rendering (apply effects here)

***

### matrix

> **matrix**: [`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Defined in: [three.js/core/Object3D:matrix](https://threejs.org/docs/#api/en/core/Object3D.matrix)

The local transform matrix.

#### Default Value

`new THREE.Matrix4()`

#### Inherited from

`Group.matrix`

***

### matrixAutoUpdate

> **matrixAutoUpdate**: `boolean`

Defined in: [three.js/core/Object3D:matrixAutoUpdate](https://threejs.org/docs/#api/en/core/Object3D.matrixAutoUpdate)

When this is set, it calculates the matrix of position, (rotation or quaternion) and
scale every frame and also recalculates the matrixWorld property.

#### Default Value

[DEFAULT\_MATRIX\_AUTO\_UPDATE](/three-flatland/api/three-flatland/src/classes/flatland/#default_matrix_auto_update) - that is `(true)`.

#### Inherited from

`Group.matrixAutoUpdate`

***

### matrixWorld

> **matrixWorld**: [`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Defined in: [three.js/core/Object3D:matrixWorld](https://threejs.org/docs/#api/en/core/Object3D.matrixWorld)

The global transform of the object.

#### Remarks

If the [Object3D](https://threejs.org/docs/#api/en/core/Object3D) has no parent, then it's identical to the local transform THREE.Object3D.matrix \| .matrix.

#### Default Value

`new THREE.Matrix4()`

#### Inherited from

`Group.matrixWorld`

***

### matrixWorldAutoUpdate

> **matrixWorldAutoUpdate**: `boolean`

Defined in: [three.js/core/Object3D:matrixWorldAutoUpdate](https://threejs.org/docs/#api/en/core/Object3D.matrixWorldAutoUpdate)

If set, then the renderer checks every frame if the object and its children need matrix updates.
When it isn't, then you have to maintain all matrices in the object and its children yourself.

#### Default Value

[DEFAULT\_MATRIX\_WORLD\_AUTO\_UPDATE](/three-flatland/api/three-flatland/src/classes/flatland/#default_matrix_world_auto_update) - that is `(true)`.

#### Inherited from

`Group.matrixWorldAutoUpdate`

***

### matrixWorldNeedsUpdate

> **matrixWorldNeedsUpdate**: `boolean`

Defined in: [three.js/core/Object3D:matrixWorldNeedsUpdate](https://threejs.org/docs/#api/en/core/Object3D.matrixWorldNeedsUpdate)

When this is set, it calculates the matrixWorld in that frame and resets this property to false.

#### Default Value

`false`

#### Inherited from

`Group.matrixWorldNeedsUpdate`

***

### modelViewMatrix

> `readonly` **modelViewMatrix**: [`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Defined in: [three.js/core/Object3D:modelViewMatrix](https://threejs.org/docs/#api/en/core/Object3D.modelViewMatrix)

#### Default Value

`new THREE.Matrix4()`

#### Inherited from

`Group.modelViewMatrix`

***

### name

> **name**: `string`

Defined in: [three.js/core/Object3D:name](https://threejs.org/docs/#api/en/core/Object3D.name)

Optional name of the object

#### Remarks

_(doesn't need to be unique)_.

#### Default Value

`""`

#### Inherited from

`Group.name`

***

### normalMatrix

> `readonly` **normalMatrix**: [`Matrix3`](https://threejs.org/docs/#api/en/math/Matrix3)

Defined in: [three.js/core/Object3D:normalMatrix](https://threejs.org/docs/#api/en/core/Object3D.normalMatrix)

#### Default Value

`new THREE.Matrix3()`

#### Inherited from

`Group.normalMatrix`

***

### occlusionTest?

> `optional` **occlusionTest?**: `boolean`

Defined in: [three.js/renderers/common/Backend:occlusionTest](https://threejs.org/docs/#api/en/renderers/common/Backend.occlusionTest)

#### Inherited from

`Group.occlusionTest`

***

### parent

> **parent**: [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `null`

Defined in: [three.js/core/Object3D:parent](https://threejs.org/docs/#api/en/core/Object3D.parent)

Object's parent in the [scene graph](https://en.wikipedia.org/wiki/Scene_graph).

#### Remarks

An object can have at most one parent.

#### Default Value

`null`

#### Inherited from

`Group.parent`

***

### pivot

> **pivot**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3) \| `null`

Defined in: [three.js/core/Object3D:pivot](https://threejs.org/docs/#api/en/core/Object3D.pivot)

The pivot point for rotation and scale transformations.
When set, rotation and scale are applied around this point
instead of the object's origin.

#### Default

```ts
null
```

#### Inherited from

`Group.pivot`

***

### position

> `readonly` **position**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:position](https://threejs.org/docs/#api/en/core/Object3D.position)

Object's local position.

#### Default Value

`new THREE.Vector3()` - that is `(0, 0, 0)`.

#### Inherited from

`Group.position`

***

### quaternion

> `readonly` **quaternion**: [`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

Defined in: [three.js/core/Object3D:quaternion](https://threejs.org/docs/#api/en/core/Object3D.quaternion)

Object's local rotation as a THREE.Quaternion \| Quaternion.

#### Default Value

`new THREE.Quaternion()` - that is `(0,  0, 0, 1)`.

#### Inherited from

`Group.quaternion`

***

### receiveShadow

> **receiveShadow**: `boolean`

Defined in: [three.js/core/Object3D:receiveShadow](https://threejs.org/docs/#api/en/core/Object3D.receiveShadow)

Whether the material receives shadows.

#### Default Value

`false`

#### Inherited from

`Group.receiveShadow`

***

### renderOrder

> **renderOrder**: `number`

Defined in: [three.js/core/Object3D:renderOrder](https://threejs.org/docs/#api/en/core/Object3D.renderOrder)

This value allows the default rendering order of [scene graph](https://en.wikipedia.org/wiki/Scene_graph)
objects to be overridden although opaque and transparent objects remain sorted independently.

#### Remarks

When this property is set for an instance of [Group](https://threejs.org/docs/#api/en/objects/Group), all descendants objects will be sorted and rendered together.
Sorting is from lowest to highest renderOrder.

#### Default Value

`0`

#### Inherited from

`Group.renderOrder`

***

### rotation

> `readonly` **rotation**: [`Euler`](https://threejs.org/docs/#api/en/math/Euler)

Defined in: [three.js/core/Object3D:rotation](https://threejs.org/docs/#api/en/core/Object3D.rotation)

Object's local rotation ([Euler angles](https://en.wikipedia.org/wiki/Euler_angles)), in radians.

#### Default Value

`new THREE.Euler()` - that is `(0, 0, 0, Euler.DEFAULT_ORDER)`.

#### Inherited from

`Group.rotation`

***

### scale

> `readonly` **scale**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:scale](https://threejs.org/docs/#api/en/core/Object3D.scale)

The object's local scale.

#### Default Value

`new THREE.Vector3( 1, 1, 1 )`

#### Inherited from

`Group.scale`

***

### static

> **static**: `boolean`

Defined in: [three.js/core/Object3D:static](https://threejs.org/docs/#api/en/core/Object3D.static)

Whether the 3D object is supposed to be static or not. If set to `true`, it means
the 3D object is not going to be changed after the initial renderer. This includes
geometry and material settings. A static 3D object can be processed by the renderer
slightly faster since certain state checks can be bypassed.

Only relevant in context of WebGPURenderer.

#### Default

```ts
false
```

#### Inherited from

`Group.static`

***

### tileHeight

> `readonly` **tileHeight**: `number`

Defined in: [packages/three-flatland/src/tilemap/TileLayer.ts:71](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileLayer.ts#L71)

***

### tileWidth

> `readonly` **tileWidth**: `number`

Defined in: [packages/three-flatland/src/tilemap/TileLayer.ts:70](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileLayer.ts#L70)

Tile dimensions

***

### type

> `readonly` **type**: `string`

Defined in: [three.js/core/Object3D:type](https://threejs.org/docs/#api/en/core/Object3D.type)

A Read-only _string_ to check `this` object type.

#### Remarks

This can be used to find a specific type of Object3D in a scene.
Sub-classes will update this value.

#### Default Value

`Object3D`

#### Inherited from

`Group.type`

***

### up

> **up**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:up](https://threejs.org/docs/#api/en/core/Object3D.up)

This is used by the [lookAt](https://threejs.org/docs/) method, for example, to determine the orientation of the result.

#### Default Value

[Object3D.DEFAULT\_UP](/three-flatland/api/three-flatland/src/classes/flatland/#default_up) - that is `(0, 1, 0)`.

#### Inherited from

`Group.up`

***

### userData

> **userData**: `Record`\<`string`, `any`\>

Defined in: [three.js/core/Object3D:userData](https://threejs.org/docs/#api/en/core/Object3D.userData)

An object that can be used to store custom data about the [Object3D](https://threejs.org/docs/#api/en/core/Object3D).

#### Remarks

It should not hold references to _functions_ as these **will not** be cloned.

#### Default

`{}`

#### Inherited from

`Group.userData`

***

### uuid

> **uuid**: `string`

Defined in: [three.js/core/Object3D:uuid](https://threejs.org/docs/#api/en/core/Object3D.uuid)

[UUID](http://en.wikipedia.org/wiki/Universally_unique_identifier) of this object instance.

#### Remarks

This gets automatically assigned and shouldn't be edited.

#### Inherited from

`Group.uuid`

***

### visible

> **visible**: `boolean`

Defined in: [three.js/core/Object3D:visible](https://threejs.org/docs/#api/en/core/Object3D.visible)

Object gets rendered if `true`.

#### Default Value

`true`

#### Inherited from

`Group.visible`

***

### DEFAULT\_MATRIX\_AUTO\_UPDATE

> `static` **DEFAULT\_MATRIX\_AUTO\_UPDATE**: `boolean`

Defined in: [three.js/core/Object3D:DEFAULT_MATRIX_AUTO_UPDATE](https://threejs.org/docs/#api/en/core/Object3D.DEFAULT_MATRIX_AUTO_UPDATE)

The default setting for [matrixAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixautoupdate) for newly created Object3Ds.

#### Default Value

`true`

#### Inherited from

`Group.DEFAULT_MATRIX_AUTO_UPDATE`

***

### DEFAULT\_MATRIX\_WORLD\_AUTO\_UPDATE

> `static` **DEFAULT\_MATRIX\_WORLD\_AUTO\_UPDATE**: `boolean`

Defined in: [three.js/core/Object3D:DEFAULT_MATRIX_WORLD_AUTO_UPDATE](https://threejs.org/docs/#api/en/core/Object3D.DEFAULT_MATRIX_WORLD_AUTO_UPDATE)

The default setting for [matrixWorldAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldautoupdate) for newly created Object3Ds.

#### Default Value

`true`

#### Inherited from

`Group.DEFAULT_MATRIX_WORLD_AUTO_UPDATE`

***

### DEFAULT\_UP

> `static` **DEFAULT\_UP**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:DEFAULT_UP](https://threejs.org/docs/#api/en/core/Object3D.DEFAULT_UP)

The default [up](/three-flatland/api/three-flatland/src/classes/flatland/#up) direction for objects, also used as the default position for THREE.DirectionalLight \| DirectionalLight,
THREE.HemisphereLight \| HemisphereLight and THREE.Spotlight \| Spotlight (which creates lights shining from the top down).

#### Default Value

`new THREE.Vector3( 0, 1, 0)`

#### Inherited from

`Group.DEFAULT_UP`

## Accessors

### chunkCount

#### Get Signature

> **get** **chunkCount**(): `number`

Defined in: [packages/three-flatland/src/tilemap/TileLayer.ts:693](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileLayer.ts#L693)

Get the number of chunks in this layer.

##### Returns

`number`

***

### lit

#### Get Signature

> **get** **lit**(): `boolean`

Defined in: [packages/three-flatland/src/tilemap/TileLayer.ts:129](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileLayer.ts#L129)

##### Returns

`boolean`

#### Set Signature

> **set** **lit**(`value`): `void`

Defined in: [packages/three-flatland/src/tilemap/TileLayer.ts:133](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileLayer.ts#L133)

##### Parameters

###### value

`boolean`

##### Returns

`void`

***

### receiveShadows

#### Get Signature

> **get** **receiveShadows**(): `boolean`

Defined in: [packages/three-flatland/src/tilemap/TileLayer.ts:144](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileLayer.ts#L144)

##### Returns

`boolean`

#### Set Signature

> **set** **receiveShadows**(`value`): `void`

Defined in: [packages/three-flatland/src/tilemap/TileLayer.ts:148](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileLayer.ts#L148)

##### Parameters

###### value

`boolean`

##### Returns

`void`

***

### tileCount

#### Get Signature

> **get** **tileCount**(): `number`

Defined in: [packages/three-flatland/src/tilemap/TileLayer.ts:700](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileLayer.ts#L700)

Get total tile count across all chunks.

##### Returns

`number`

## Methods

### add()

> **add**(...`object`): `this`

Defined in: [three.js/core/Object3D:add](https://threejs.org/docs/#api/en/core/Object3D.add)

Adds another [Object3D](https://threejs.org/docs/#api/en/core/Object3D) as child of this [Object3D](https://threejs.org/docs/#api/en/core/Object3D).

#### Parameters

##### object

...[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

#### Returns

`this`

#### Remarks

An arbitrary number of objects may be added
Any current parent on an object passed in here will be removed, since an [Object3D](https://threejs.org/docs/#api/en/core/Object3D) can have at most one parent.

#### See

 - [attach](https://threejs.org/docs/)
 - THREE.Group \| Group for info on manually grouping objects.

#### Inherited from

`Group.add`

***

### addEventListener()

> **addEventListener**\<`T`\>(`type`, `listener`): `void`

Defined in: [three.js/core/EventDispatcher:addEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.addEventListener)

Adds a listener to an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### type

`T`

The type of event to listen to.

##### listener

[`EventListener`](https://threejs.org/docs/)\<[`Object3DEventMap`](https://threejs.org/docs/)\[`T`\], `T`, `TileLayer`\>

The function that gets called when the event is fired.

#### Returns

`void`

#### Inherited from

`Group.addEventListener`

***

### applyMatrix4()

> **applyMatrix4**(`matrix`): `void`

Defined in: [three.js/core/Object3D:applyMatrix4](https://threejs.org/docs/#api/en/core/Object3D.applyMatrix4)

Applies the matrix transform to the object and updates the object's position, rotation and scale.

#### Parameters

##### matrix

[`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

#### Returns

`void`

#### Inherited from

`Group.applyMatrix4`

***

### applyQuaternion()

> **applyQuaternion**(`quaternion`): `this`

Defined in: [three.js/core/Object3D:applyQuaternion](https://threejs.org/docs/#api/en/core/Object3D.applyQuaternion)

Applies the rotation represented by the quaternion to the object.

#### Parameters

##### quaternion

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

#### Returns

`this`

#### Inherited from

`Group.applyQuaternion`

***

### attach()

> **attach**(`object`): `this`

Defined in: [three.js/core/Object3D:attach](https://threejs.org/docs/#api/en/core/Object3D.attach)

Adds a [Object3D](https://threejs.org/docs/#api/en/core/Object3D) as a child of this, while maintaining the object's world transform.

#### Parameters

##### object

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)

#### Returns

`this`

#### Remarks

Note: This method does not support scene graphs having non-uniformly-scaled nodes(s).

#### See

[add](https://threejs.org/docs/)

#### Inherited from

`Group.attach`

***

### clear()

> **clear**(): `this`

Defined in: [three.js/core/Object3D:clear](https://threejs.org/docs/#api/en/core/Object3D.clear)

Removes all child objects.

#### Returns

`this`

#### Inherited from

`Group.clear`

***

### clone()

> **clone**(`recursive?`): `this`

Defined in: [packages/three-flatland/src/tilemap/TileLayer.ts:710](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileLayer.ts#L710)

Clone for devtools/serialization compatibility.
TileLayer requires data/tileset in its constructor, so the default
Object3D.clone() (`new this.constructor()`) would crash.
Returns a Group containing cloned child meshes.

#### Parameters

##### recursive?

`boolean`

#### Returns

`this`

#### Overrides

`Group.clone`

***

### copy()

> **copy**(`object`, `recursive?`): `this`

Defined in: [three.js/core/Object3D:copy](https://threejs.org/docs/#api/en/core/Object3D.copy)

Copies the given object into this object.

#### Parameters

##### object

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)

##### recursive?

`boolean`

If set to `true`, descendants of the object are copied next to the existing ones. If set to
`false`, descendants are left unchanged. Default is `true`.

#### Returns

`this`

#### Remarks

Event listeners and user-defined callbacks (.onAfterRender and .onBeforeRender) are not copied.

#### Inherited from

`Group.copy`

***

### dispatchEvent()

> **dispatchEvent**\<`T`\>(`event`): `void`

Defined in: [three.js/core/EventDispatcher:dispatchEvent](https://threejs.org/docs/#api/en/core/EventDispatcher.dispatchEvent)

Fire an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### event

[`BaseEvent`](https://threejs.org/docs/)\<`T`\> & [`Object3DEventMap`](https://threejs.org/docs/)\[`T`\]

The event that gets fired.

#### Returns

`void`

#### Inherited from

`Group.dispatchEvent`

***

### dispose()

> **dispose**(): `void`

Defined in: [packages/three-flatland/src/tilemap/TileLayer.ts:728](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileLayer.ts#L728)

Dispose of all resources.

#### Returns

`void`

***

### getObjectById()

> **getObjectById**(`id`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

Defined in: [three.js/core/Object3D:getObjectById](https://threejs.org/docs/#api/en/core/Object3D.getObjectById)

Searches through an object and its children, starting with the object itself, and returns the first with a matching id.

#### Parameters

##### id

`number`

Unique number of the object instance. Expects a `Integer`

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

#### Remarks

Note that ids are assigned in chronological order: 1, 2, 3, ..., incrementing by one for each new object.

#### See

id

#### Inherited from

`Group.getObjectById`

***

### getObjectByName()

> **getObjectByName**(`name`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

Defined in: [three.js/core/Object3D:getObjectByName](https://threejs.org/docs/#api/en/core/Object3D.getObjectByName)

Searches through an object and its children, starting with the object itself, and returns the first with a matching name.

#### Parameters

##### name

`string`

String to match to the children's Object3D.name property.

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

#### Remarks

Note that for most objects the name is an empty string by default
You will have to set it manually to make use of this method.

#### Inherited from

`Group.getObjectByName`

***

### getObjectByProperty()

> **getObjectByProperty**(`name`, `value`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

Defined in: [three.js/core/Object3D:getObjectByProperty](https://threejs.org/docs/#api/en/core/Object3D.getObjectByProperty)

Searches through an object and its children, starting with the object itself,
and returns the first with a property that matches the value given.

#### Parameters

##### name

`string`

the property name to search for.

##### value

`any`

value of the given property.

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

#### Inherited from

`Group.getObjectByProperty`

***

### getObjectsByProperty()

> **getObjectsByProperty**(`name`, `value`, `optionalTarget?`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

Defined in: [three.js/core/Object3D:getObjectsByProperty](https://threejs.org/docs/#api/en/core/Object3D.getObjectsByProperty)

Searches through an object and its children, starting with the object itself,
and returns the first with a property that matches the value given.

#### Parameters

##### name

`string`

The property name to search for.

##### value

`any`

Value of the given property.

##### optionalTarget?

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

target to set the result. Otherwise a new Array is instantiated. If set, you must clear
this array prior to each call (i.e., array.length = 0;).

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

#### Inherited from

`Group.getObjectsByProperty`

***

### getTileAt()

> **getTileAt**(`tileX`, `tileY`): `number`

Defined in: [packages/three-flatland/src/tilemap/TileLayer.ts:638](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileLayer.ts#L638)

Get tile GID at position (in tiles, using original Tiled coordinates).

#### Parameters

##### tileX

`number`

##### tileY

`number`

#### Returns

`number`

***

### getWorldDirection()

> **getWorldDirection**(`target`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:getWorldDirection](https://threejs.org/docs/#api/en/core/Object3D.getWorldDirection)

Returns a vector representing the direction of object's positive z-axis in world space.

#### Parameters

##### target

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

The result will be copied into this Vector3.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Group.getWorldDirection`

***

### getWorldPosition()

> **getWorldPosition**(`target`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:getWorldPosition](https://threejs.org/docs/#api/en/core/Object3D.getWorldPosition)

Returns a vector representing the position of the object in world space.

#### Parameters

##### target

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

The result will be copied into this Vector3.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Group.getWorldPosition`

***

### getWorldQuaternion()

> **getWorldQuaternion**(`target`): [`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

Defined in: [three.js/core/Object3D:getWorldQuaternion](https://threejs.org/docs/#api/en/core/Object3D.getWorldQuaternion)

Returns a quaternion representing the rotation of the object in world space.

#### Parameters

##### target

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

The result will be copied into this Quaternion.

#### Returns

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

#### Inherited from

`Group.getWorldQuaternion`

***

### getWorldScale()

> **getWorldScale**(`target`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:getWorldScale](https://threejs.org/docs/#api/en/core/Object3D.getWorldScale)

Returns a vector of the scaling factors applied to the object for each axis in world space.

#### Parameters

##### target

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

The result will be copied into this Vector3.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Group.getWorldScale`

***

### hasEventListener()

> **hasEventListener**\<`T`\>(`type`, `listener`): `boolean`

Defined in: [three.js/core/EventDispatcher:hasEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.hasEventListener)

Checks if listener is added to an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### type

`T`

The type of event to listen to.

##### listener

[`EventListener`](https://threejs.org/docs/)\<[`Object3DEventMap`](https://threejs.org/docs/)\[`T`\], `T`, `TileLayer`\>

The function that gets called when the event is fired.

#### Returns

`boolean`

#### Inherited from

`Group.hasEventListener`

***

### localToWorld()

> **localToWorld**(`vector`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:localToWorld](https://threejs.org/docs/#api/en/core/Object3D.localToWorld)

Converts the vector from this object's local space to world space.

#### Parameters

##### vector

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A vector representing a position in this object's local space.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Group.localToWorld`

***

### lookAt()

#### Call Signature

> **lookAt**(`vector`): `void`

Defined in: [three.js/core/Object3D:lookAt](https://threejs.org/docs/#api/en/core/Object3D.lookAt)

Rotates the object to face a point in world space.

##### Parameters

###### vector

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A vector representing a position in world space to look at.

##### Returns

`void`

##### Remarks

This method does not support objects having non-uniformly-scaled parent(s).

##### Inherited from

`Group.lookAt`

#### Call Signature

> **lookAt**(`x`, `y`, `z`): `void`

Defined in: [three.js/core/Object3D:lookAt](https://threejs.org/docs/#api/en/core/Object3D.lookAt)

Rotates the object to face a point in world space.

##### Parameters

###### x

`number`

Expects a `Float`

###### y

`number`

Expects a `Float`

###### z

`number`

Expects a `Float`

##### Returns

`void`

##### Remarks

This method does not support objects having non-uniformly-scaled parent(s).

##### Inherited from

`Group.lookAt`

***

### onAfterRender()

> **onAfterRender**(`renderer`, `scene`, `camera`, `geometry`, `material`, `group`): `void`

Defined in: [three.js/core/Object3D:onAfterRender](https://threejs.org/docs/#api/en/core/Object3D.onAfterRender)

An optional callback that is executed immediately after a 3D object is rendered.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### material

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, geometry, material, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

`Group.onAfterRender`

***

### onAfterShadow()

> **onAfterShadow**(`renderer`, `scene`, `camera`, `shadowCamera`, `geometry`, `depthMaterial`, `group`): `void`

Defined in: [three.js/core/Object3D:onAfterShadow](https://threejs.org/docs/#api/en/core/Object3D.onAfterShadow)

An optional callback that is executed immediately after a 3D object is rendered to a shadow map.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### shadowCamera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### depthMaterial

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, shadowCamera, geometry,
depthMaterial, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

`Group.onAfterShadow`

***

### onBeforeRender()

> **onBeforeRender**(`renderer`, `scene`, `camera`, `geometry`, `material`, `group`): `void`

Defined in: [three.js/core/Object3D:onBeforeRender](https://threejs.org/docs/#api/en/core/Object3D.onBeforeRender)

An optional callback that is executed immediately before a 3D object is rendered.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### material

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, geometry, material, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

`Group.onBeforeRender`

***

### onBeforeShadow()

> **onBeforeShadow**(`renderer`, `scene`, `camera`, `shadowCamera`, `geometry`, `depthMaterial`, `group`): `void`

Defined in: [three.js/core/Object3D:onBeforeShadow](https://threejs.org/docs/#api/en/core/Object3D.onBeforeShadow)

An optional callback that is executed immediately before a 3D object is rendered to a shadow map.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### shadowCamera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### depthMaterial

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, shadowCamera, geometry,
depthMaterial, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

`Group.onBeforeShadow`

***

### raycast()

> **raycast**(`raycaster`, `intersects`): `void`

Defined in: [three.js/core/Object3D:raycast](https://threejs.org/docs/#api/en/core/Object3D.raycast)

Abstract (empty) method to get intersections between a casted ray and this object

#### Parameters

##### raycaster

[`Raycaster`](https://threejs.org/docs/#api/en/core/Raycaster)

##### intersects

[`Intersection`](https://threejs.org/docs/)\<[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>\>[]

#### Returns

`void`

#### Remarks

Subclasses such as THREE.Mesh \| Mesh, THREE.Line \| Line, and THREE.Points \| Points implement this method in order to use raycasting.

#### See

THREE.Raycaster \| Raycaster

#### Default Value

`() => {}`

#### Inherited from

`Group.raycast`

***

### remove()

> **remove**(...`object`): `this`

Defined in: [three.js/core/Object3D:remove](https://threejs.org/docs/#api/en/core/Object3D.remove)

Removes a [Object3D](https://threejs.org/docs/#api/en/core/Object3D) as child of this [Object3D](https://threejs.org/docs/#api/en/core/Object3D).

#### Parameters

##### object

...[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

#### Returns

`this`

#### Remarks

An arbitrary number of objects may be removed.

#### See

THREE.Group \| Group for info on manually grouping objects.

#### Inherited from

`Group.remove`

***

### removeEventListener()

> **removeEventListener**\<`T`\>(`type`, `listener`): `void`

Defined in: [three.js/core/EventDispatcher:removeEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.removeEventListener)

Removes a listener from an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### type

`T`

The type of the listener that gets removed.

##### listener

[`EventListener`](https://threejs.org/docs/)\<[`Object3DEventMap`](https://threejs.org/docs/)\[`T`\], `T`, `TileLayer`\>

The listener function that gets removed.

#### Returns

`void`

#### Inherited from

`Group.removeEventListener`

***

### removeFromParent()

> **removeFromParent**(): `this`

Defined in: [three.js/core/Object3D:removeFromParent](https://threejs.org/docs/#api/en/core/Object3D.removeFromParent)

Removes this object from its current parent.

#### Returns

`this`

#### Inherited from

`Group.removeFromParent`

***

### rotateOnAxis()

> **rotateOnAxis**(`axis`, `angle`): `this`

Defined in: [three.js/core/Object3D:rotateOnAxis](https://threejs.org/docs/#api/en/core/Object3D.rotateOnAxis)

Rotate an object along an axis in object space.

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in object space.

##### angle

`number`

The angle in radians. Expects a `Float`

#### Returns

`this`

#### Remarks

The axis is assumed to be normalized.

#### Inherited from

`Group.rotateOnAxis`

***

### rotateOnWorldAxis()

> **rotateOnWorldAxis**(`axis`, `angle`): `this`

Defined in: [three.js/core/Object3D:rotateOnWorldAxis](https://threejs.org/docs/#api/en/core/Object3D.rotateOnWorldAxis)

Rotate an object along an axis in world space.

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in world space.

##### angle

`number`

The angle in radians. Expects a `Float`

#### Returns

`this`

#### Remarks

The axis is assumed to be normalized
Method Assumes no rotated parent.

#### Inherited from

`Group.rotateOnWorldAxis`

***

### rotateX()

> **rotateX**(`angle`): `this`

Defined in: [three.js/core/Object3D:rotateX](https://threejs.org/docs/#api/en/core/Object3D.rotateX)

Rotates the object around _x_ axis in local space.

#### Parameters

##### angle

`number`

#### Returns

`this`

#### Inherited from

`Group.rotateX`

***

### rotateY()

> **rotateY**(`angle`): `this`

Defined in: [three.js/core/Object3D:rotateY](https://threejs.org/docs/#api/en/core/Object3D.rotateY)

Rotates the object around _y_ axis in local space.

#### Parameters

##### angle

`number`

#### Returns

`this`

#### Inherited from

`Group.rotateY`

***

### rotateZ()

> **rotateZ**(`angle`): `this`

Defined in: [three.js/core/Object3D:rotateZ](https://threejs.org/docs/#api/en/core/Object3D.rotateZ)

Rotates the object around _z_ axis in local space.

#### Parameters

##### angle

`number`

#### Returns

`this`

#### Inherited from

`Group.rotateZ`

***

### setCastsShadowAt()

> **setCastsShadowAt**(`tileX`, `tileY`, `value`): `void`

Defined in: [packages/three-flatland/src/tilemap/TileLayer.ts:163](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileLayer.ts#L163)

Set castsShadow on a specific tile by its data-array index.
Use with IntGrid data to mark wall tiles as shadow casters.

#### Parameters

##### tileX

`number`

##### tileY

`number`

##### value

`boolean`

#### Returns

`void`

***

### setRotationFromAxisAngle()

> **setRotationFromAxisAngle**(`axis`, `angle`): `void`

Defined in: [three.js/core/Object3D:setRotationFromAxisAngle](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromAxisAngle)

Calls THREE.Quaternion.setFromAxisAngle \| setFromAxisAngle(axis, angle) on the [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in object space.

##### angle

`number`

Angle in radians. Expects a `Float`

#### Returns

`void`

#### Inherited from

`Group.setRotationFromAxisAngle`

***

### setRotationFromEuler()

> **setRotationFromEuler**(`euler`): `void`

Defined in: [three.js/core/Object3D:setRotationFromEuler](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromEuler)

Calls THREE.Quaternion.setFromEuler \| setFromEuler(euler) on the [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### euler

[`Euler`](https://threejs.org/docs/#api/en/math/Euler)

Euler angle specifying rotation amount.

#### Returns

`void`

#### Inherited from

`Group.setRotationFromEuler`

***

### setRotationFromMatrix()

> **setRotationFromMatrix**(`m`): `void`

Defined in: [three.js/core/Object3D:setRotationFromMatrix](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromMatrix)

Calls THREE.Quaternion.setFromRotationMatrix \| setFromRotationMatrix(m) on the [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### m

[`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Rotate the quaternion by the rotation component of the matrix.

#### Returns

`void`

#### Remarks

Note that this assumes that the upper 3x3 of m is a pure rotation matrix (i.e, unscaled).

#### Inherited from

`Group.setRotationFromMatrix`

***

### setRotationFromQuaternion()

> **setRotationFromQuaternion**(`q`): `void`

Defined in: [three.js/core/Object3D:setRotationFromQuaternion](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromQuaternion)

Copy the given THREE.Quaternion \| Quaternion into [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### q

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

Normalized Quaternion.

#### Returns

`void`

#### Inherited from

`Group.setRotationFromQuaternion`

***

### setTileAt()

> **setTileAt**(`tileX`, `tileY`, `gid`): `void`

Defined in: [packages/three-flatland/src/tilemap/TileLayer.ts:652](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileLayer.ts#L652)

Set tile GID at position (in tiles).
For changes between non-zero values, updates in-place.
For add/remove (0 <-> non-zero), rebuilds the entire layer.

#### Parameters

##### tileX

`number`

##### tileY

`number`

##### gid

`number`

#### Returns

`void`

***

### toJSON()

> **toJSON**(`meta?`): [`Object3DJSON`](https://threejs.org/docs/)

Defined in: [three.js/core/Object3D:toJSON](https://threejs.org/docs/#api/en/core/Object3D.toJSON)

Convert the object to three.js [JSON Object/Scene format](https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4).

#### Parameters

##### meta?

[`JSONMeta`](https://threejs.org/docs/)

Object containing metadata such as materials, textures or images for the object.

#### Returns

[`Object3DJSON`](https://threejs.org/docs/)

#### Inherited from

`Group.toJSON`

***

### translateOnAxis()

> **translateOnAxis**(`axis`, `distance`): `this`

Defined in: [three.js/core/Object3D:translateOnAxis](https://threejs.org/docs/#api/en/core/Object3D.translateOnAxis)

Translate an object by distance along an axis in object space

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in object space.

##### distance

`number`

The distance to translate. Expects a `Float`

#### Returns

`this`

#### Remarks

The axis is assumed to be normalized.

#### Inherited from

`Group.translateOnAxis`

***

### translateX()

> **translateX**(`distance`): `this`

Defined in: [three.js/core/Object3D:translateX](https://threejs.org/docs/#api/en/core/Object3D.translateX)

Translates object along x axis in object space by distance units.

#### Parameters

##### distance

`number`

Expects a `Float`

#### Returns

`this`

#### Inherited from

`Group.translateX`

***

### translateY()

> **translateY**(`distance`): `this`

Defined in: [three.js/core/Object3D:translateY](https://threejs.org/docs/#api/en/core/Object3D.translateY)

Translates object along _y_ axis in object space by distance units.

#### Parameters

##### distance

`number`

Expects a `Float`

#### Returns

`this`

#### Inherited from

`Group.translateY`

***

### translateZ()

> **translateZ**(`distance`): `this`

Defined in: [three.js/core/Object3D:translateZ](https://threejs.org/docs/#api/en/core/Object3D.translateZ)

Translates object along _z_ axis in object space by distance units.

#### Parameters

##### distance

`number`

Expects a `Float`

#### Returns

`this`

#### Inherited from

`Group.translateZ`

***

### traverse()

> **traverse**(`callback`): `void`

Defined in: [three.js/core/Object3D:traverse](https://threejs.org/docs/#api/en/core/Object3D.traverse)

Executes the callback on this object and all descendants.

#### Parameters

##### callback

(`object`) => `any`

A function with as first argument an [Object3D](https://threejs.org/docs/#api/en/core/Object3D) object.

#### Returns

`void`

#### Remarks

Note: Modifying the scene graph inside the callback is discouraged.

#### Inherited from

`Group.traverse`

***

### traverseAncestors()

> **traverseAncestors**(`callback`): `void`

Defined in: [three.js/core/Object3D:traverseAncestors](https://threejs.org/docs/#api/en/core/Object3D.traverseAncestors)

Executes the callback on all ancestors.

#### Parameters

##### callback

(`object`) => `any`

A function with as first argument an [Object3D](https://threejs.org/docs/#api/en/core/Object3D) object.

#### Returns

`void`

#### Remarks

Note: Modifying the scene graph inside the callback is discouraged.

#### Inherited from

`Group.traverseAncestors`

***

### traverseVisible()

> **traverseVisible**(`callback`): `void`

Defined in: [three.js/core/Object3D:traverseVisible](https://threejs.org/docs/#api/en/core/Object3D.traverseVisible)

Like traverse, but the callback will only be executed for visible objects

#### Parameters

##### callback

(`object`) => `any`

A function with as first argument an [Object3D](https://threejs.org/docs/#api/en/core/Object3D) object.

#### Returns

`void`

#### Remarks

Descendants of invisible objects are not traversed.
Note: Modifying the scene graph inside the callback is discouraged.

#### Inherited from

`Group.traverseVisible`

***

### update()

> **update**(`deltaMs`): `void`

Defined in: [packages/three-flatland/src/tilemap/TileLayer.ts:578](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileLayer.ts#L578)

Update animated tiles.

#### Parameters

##### deltaMs

`number`

#### Returns

`void`

***

### updateMatrix()

> **updateMatrix**(): `void`

Defined in: [three.js/core/Object3D:updateMatrix](https://threejs.org/docs/#api/en/core/Object3D.updateMatrix)

Updates local transform.

#### Returns

`void`

#### Inherited from

`Group.updateMatrix`

***

### updateMatrixWorld()

> **updateMatrixWorld**(`force?`): `void`

Defined in: [three.js/core/Object3D:updateMatrixWorld](https://threejs.org/docs/#api/en/core/Object3D.updateMatrixWorld)

Updates the global transform of the object.
And will update the object descendants if [.matrixWorldNeedsUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldneedsupdate) is set to true or if the force parameter is set to `true`.

#### Parameters

##### force?

`boolean`

A boolean that can be used to bypass [.matrixWorldAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldautoupdate), to recalculate the world matrix of the object and descendants on the current frame.
Useful if you cannot wait for the renderer to update it on the next frame, assuming [.matrixWorldAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldautoupdate) set to `true`.

#### Returns

`void`

#### Inherited from

`Group.updateMatrixWorld`

***

### updateWorldMatrix()

> **updateWorldMatrix**(`updateParents`, `updateChildren`): `void`

Defined in: [three.js/core/Object3D:updateWorldMatrix](https://threejs.org/docs/#api/en/core/Object3D.updateWorldMatrix)

Updates the global transform of the object.

#### Parameters

##### updateParents

`boolean`

Recursively updates global transform of ancestors.

##### updateChildren

`boolean`

Recursively updates global transform of descendants.

#### Returns

`void`

#### Inherited from

`Group.updateWorldMatrix`

***

### worldToLocal()

> **worldToLocal**(`vector`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:worldToLocal](https://threejs.org/docs/#api/en/core/Object3D.worldToLocal)

Converts the vector from world space to this object's local space.

#### Parameters

##### vector

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A vector representing a position in world space.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Group.worldToLocal`

# TileMap2D

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:49](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L49)

Main tilemap class for rendering 2D tile-based maps.

Supports:
- Multiple tile layers
- Animated tiles
- Chunked rendering for large maps
- Collision data extraction
- Object layer access (spawn points, triggers, etc.)

Follows R3F-compatible constructor pattern with optional parameters.

## Examples

```typescript
// Three.js
const mapData = await TiledLoader.load('/maps/level1.json')
const tilemap = new TileMap2D({ data: mapData })
scene.add(tilemap)

// In update loop
tilemap.update(deltaMs)
```

```tsx
// React Three Fiber (after extending)
extend({ TileMap2D })

function Level() {
  const mapData = use(TiledLoader.load('/maps/level1.json'))
  return <tileMap2D data={mapData} />
}
```

## Extends

- [`Group`](https://threejs.org/docs/#api/en/objects/Group)

## Constructors

### Constructor

> **new TileMap2D**(`options?`): `TileMap2D`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:92](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L92)

Create a new TileMap2D.

#### Parameters

##### options?

[`TileMap2DOptions`](/three-flatland/api/three-flatland/src/interfaces/tilemap2doptions/)

Optional configuration. If not provided (R3F path),
                 the tilemap will be initialized when `data` is set.

#### Returns

`TileMap2D`

#### Overrides

`Group.constructor`

## Properties

### animations

> **animations**: [`AnimationClip`](https://threejs.org/docs/)[]

Defined in: [three.js/core/Object3D:animations](https://threejs.org/docs/#api/en/core/Object3D.animations)

Array with object's animation clips.

#### Default Value

`[]`

#### Inherited from

`Group.animations`

***

### castShadow

> **castShadow**: `boolean`

Defined in: [three.js/core/Object3D:castShadow](https://threejs.org/docs/#api/en/core/Object3D.castShadow)

Whether the object gets rendered into shadow map.

#### Default Value

`false`

#### Inherited from

`Group.castShadow`

***

### children

> **children**: [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

Defined in: [three.js/core/Object3D:children](https://threejs.org/docs/#api/en/core/Object3D.children)

Array with object's children.

#### See

THREE.Object3DGroup \| Group for info on manually grouping objects.

#### Default Value

`[]`

#### Inherited from

`Group.children`

***

### count?

> `optional` **count?**: `number`

Defined in: [three.js/renderers/common/Backend:count](https://threejs.org/docs/#api/en/renderers/common/Backend.count)

#### Inherited from

`Group.count`

***

### customDepthMaterial?

> `optional` **customDepthMaterial?**: [`Material`](https://threejs.org/docs/#api/en/materials/Material)

Defined in: [three.js/core/Object3D:customDepthMaterial](https://threejs.org/docs/#api/en/core/Object3D.customDepthMaterial)

Custom depth material to be used when rendering to the depth map.

#### Remarks

Can only be used in context of meshes.
When shadow-casting with a THREE.DirectionalLight \| DirectionalLight or THREE.SpotLight \| SpotLight,
if you are modifying vertex positions in the vertex shader you must specify a customDepthMaterial for proper shadows.

#### Default Value

`undefined`

#### Inherited from

`Group.customDepthMaterial`

***

### customDistanceMaterial?

> `optional` **customDistanceMaterial?**: [`Material`](https://threejs.org/docs/#api/en/materials/Material)

Defined in: [three.js/core/Object3D:customDistanceMaterial](https://threejs.org/docs/#api/en/core/Object3D.customDistanceMaterial)

Same as [customDepthMaterial](/three-flatland/api/three-flatland/src/classes/flatland/#customdepthmaterial), but used with THREE.Object3DPointLight \| PointLight.

#### Default Value

`undefined`

#### Inherited from

`Group.customDistanceMaterial`

***

### frustumCulled

> **frustumCulled**: `boolean`

Defined in: [three.js/core/Object3D:frustumCulled](https://threejs.org/docs/#api/en/core/Object3D.frustumCulled)

When this is set, it checks every frame if the object is in the frustum of the camera before rendering the object.
If set to `false` the object gets rendered every frame even if it is not in the frustum of the camera.

#### Default Value

`true`

#### Inherited from

`Group.frustumCulled`

***

### id

> `readonly` **id**: `number`

Defined in: [three.js/core/Object3D:id](https://threejs.org/docs/#api/en/core/Object3D.id)

Unique number for this [Object3D](https://threejs.org/docs/#api/en/core/Object3D) instance.

#### Remarks

Note that ids are assigned in chronological order: 1, 2, 3, ..., incrementing by one for each new object.
Expects a `Integer`

#### Inherited from

`Group.id`

***

### isGroup

> `readonly` **isGroup**: `true`

Defined in: [three.js/objects/Group:isGroup](https://threejs.org/docs/#api/en/objects/Group.isGroup)

Read-only flag to check if a given object is of type [Group](https://threejs.org/docs/#api/en/objects/Group).

#### Remarks

This is a _constant_ value

#### Default Value

`true`

#### Inherited from

`Group.isGroup`

***

### isObject3D

> `readonly` **isObject3D**: `true`

Defined in: [three.js/core/Object3D:isObject3D](https://threejs.org/docs/#api/en/core/Object3D.isObject3D)

Flag to check if a given object is of type [Object3D](https://threejs.org/docs/#api/en/core/Object3D).

#### Remarks

This is a _constant_ value

#### Default Value

`true`

#### Inherited from

`Group.isObject3D`

***

### layers

> **layers**: [`Layers`](https://threejs.org/docs/#api/en/core/Layers)

Defined in: [three.js/core/Object3D:layers](https://threejs.org/docs/#api/en/core/Object3D.layers)

The layer membership of the object.

#### Remarks

The object is only visible if it has at least one layer in common with the THREE.Object3DCamera \| Camera in use.
This property can also be used to filter out unwanted objects in ray-intersection tests when using THREE.Raycaster \| Raycaster.

#### Default Value

`new THREE.Layers()`

#### Inherited from

`Group.layers`

***

### matrix

> **matrix**: [`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Defined in: [three.js/core/Object3D:matrix](https://threejs.org/docs/#api/en/core/Object3D.matrix)

The local transform matrix.

#### Default Value

`new THREE.Matrix4()`

#### Inherited from

`Group.matrix`

***

### matrixAutoUpdate

> **matrixAutoUpdate**: `boolean`

Defined in: [three.js/core/Object3D:matrixAutoUpdate](https://threejs.org/docs/#api/en/core/Object3D.matrixAutoUpdate)

When this is set, it calculates the matrix of position, (rotation or quaternion) and
scale every frame and also recalculates the matrixWorld property.

#### Default Value

[DEFAULT\_MATRIX\_AUTO\_UPDATE](/three-flatland/api/three-flatland/src/classes/flatland/#default_matrix_auto_update) - that is `(true)`.

#### Inherited from

`Group.matrixAutoUpdate`

***

### matrixWorld

> **matrixWorld**: [`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Defined in: [three.js/core/Object3D:matrixWorld](https://threejs.org/docs/#api/en/core/Object3D.matrixWorld)

The global transform of the object.

#### Remarks

If the [Object3D](https://threejs.org/docs/#api/en/core/Object3D) has no parent, then it's identical to the local transform THREE.Object3D.matrix \| .matrix.

#### Default Value

`new THREE.Matrix4()`

#### Inherited from

`Group.matrixWorld`

***

### matrixWorldAutoUpdate

> **matrixWorldAutoUpdate**: `boolean`

Defined in: [three.js/core/Object3D:matrixWorldAutoUpdate](https://threejs.org/docs/#api/en/core/Object3D.matrixWorldAutoUpdate)

If set, then the renderer checks every frame if the object and its children need matrix updates.
When it isn't, then you have to maintain all matrices in the object and its children yourself.

#### Default Value

[DEFAULT\_MATRIX\_WORLD\_AUTO\_UPDATE](/three-flatland/api/three-flatland/src/classes/flatland/#default_matrix_world_auto_update) - that is `(true)`.

#### Inherited from

`Group.matrixWorldAutoUpdate`

***

### matrixWorldNeedsUpdate

> **matrixWorldNeedsUpdate**: `boolean`

Defined in: [three.js/core/Object3D:matrixWorldNeedsUpdate](https://threejs.org/docs/#api/en/core/Object3D.matrixWorldNeedsUpdate)

When this is set, it calculates the matrixWorld in that frame and resets this property to false.

#### Default Value

`false`

#### Inherited from

`Group.matrixWorldNeedsUpdate`

***

### modelViewMatrix

> `readonly` **modelViewMatrix**: [`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Defined in: [three.js/core/Object3D:modelViewMatrix](https://threejs.org/docs/#api/en/core/Object3D.modelViewMatrix)

#### Default Value

`new THREE.Matrix4()`

#### Inherited from

`Group.modelViewMatrix`

***

### name

> **name**: `string`

Defined in: [three.js/core/Object3D:name](https://threejs.org/docs/#api/en/core/Object3D.name)

Optional name of the object

#### Remarks

_(doesn't need to be unique)_.

#### Default Value

`""`

#### Inherited from

`Group.name`

***

### normalMatrix

> `readonly` **normalMatrix**: [`Matrix3`](https://threejs.org/docs/#api/en/math/Matrix3)

Defined in: [three.js/core/Object3D:normalMatrix](https://threejs.org/docs/#api/en/core/Object3D.normalMatrix)

#### Default Value

`new THREE.Matrix3()`

#### Inherited from

`Group.normalMatrix`

***

### occlusionTest?

> `optional` **occlusionTest?**: `boolean`

Defined in: [three.js/renderers/common/Backend:occlusionTest](https://threejs.org/docs/#api/en/renderers/common/Backend.occlusionTest)

#### Inherited from

`Group.occlusionTest`

***

### parent

> **parent**: [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `null`

Defined in: [three.js/core/Object3D:parent](https://threejs.org/docs/#api/en/core/Object3D.parent)

Object's parent in the [scene graph](https://en.wikipedia.org/wiki/Scene_graph).

#### Remarks

An object can have at most one parent.

#### Default Value

`null`

#### Inherited from

`Group.parent`

***

### pivot

> **pivot**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3) \| `null`

Defined in: [three.js/core/Object3D:pivot](https://threejs.org/docs/#api/en/core/Object3D.pivot)

The pivot point for rotation and scale transformations.
When set, rotation and scale are applied around this point
instead of the object's origin.

#### Default

```ts
null
```

#### Inherited from

`Group.pivot`

***

### position

> `readonly` **position**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:position](https://threejs.org/docs/#api/en/core/Object3D.position)

Object's local position.

#### Default Value

`new THREE.Vector3()` - that is `(0, 0, 0)`.

#### Inherited from

`Group.position`

***

### quaternion

> `readonly` **quaternion**: [`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

Defined in: [three.js/core/Object3D:quaternion](https://threejs.org/docs/#api/en/core/Object3D.quaternion)

Object's local rotation as a THREE.Quaternion \| Quaternion.

#### Default Value

`new THREE.Quaternion()` - that is `(0,  0, 0, 1)`.

#### Inherited from

`Group.quaternion`

***

### receiveShadow

> **receiveShadow**: `boolean`

Defined in: [three.js/core/Object3D:receiveShadow](https://threejs.org/docs/#api/en/core/Object3D.receiveShadow)

Whether the material receives shadows.

#### Default Value

`false`

#### Inherited from

`Group.receiveShadow`

***

### renderOrder

> **renderOrder**: `number`

Defined in: [three.js/core/Object3D:renderOrder](https://threejs.org/docs/#api/en/core/Object3D.renderOrder)

This value allows the default rendering order of [scene graph](https://en.wikipedia.org/wiki/Scene_graph)
objects to be overridden although opaque and transparent objects remain sorted independently.

#### Remarks

When this property is set for an instance of [Group](https://threejs.org/docs/#api/en/objects/Group), all descendants objects will be sorted and rendered together.
Sorting is from lowest to highest renderOrder.

#### Default Value

`0`

#### Inherited from

`Group.renderOrder`

***

### rotation

> `readonly` **rotation**: [`Euler`](https://threejs.org/docs/#api/en/math/Euler)

Defined in: [three.js/core/Object3D:rotation](https://threejs.org/docs/#api/en/core/Object3D.rotation)

Object's local rotation ([Euler angles](https://en.wikipedia.org/wiki/Euler_angles)), in radians.

#### Default Value

`new THREE.Euler()` - that is `(0, 0, 0, Euler.DEFAULT_ORDER)`.

#### Inherited from

`Group.rotation`

***

### scale

> `readonly` **scale**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:scale](https://threejs.org/docs/#api/en/core/Object3D.scale)

The object's local scale.

#### Default Value

`new THREE.Vector3( 1, 1, 1 )`

#### Inherited from

`Group.scale`

***

### static

> **static**: `boolean`

Defined in: [three.js/core/Object3D:static](https://threejs.org/docs/#api/en/core/Object3D.static)

Whether the 3D object is supposed to be static or not. If set to `true`, it means
the 3D object is not going to be changed after the initial renderer. This includes
geometry and material settings. A static 3D object can be processed by the renderer
slightly faster since certain state checks can be bypassed.

Only relevant in context of WebGPURenderer.

#### Default

```ts
false
```

#### Inherited from

`Group.static`

***

### type

> `readonly` **type**: `string`

Defined in: [three.js/core/Object3D:type](https://threejs.org/docs/#api/en/core/Object3D.type)

A Read-only _string_ to check `this` object type.

#### Remarks

This can be used to find a specific type of Object3D in a scene.
Sub-classes will update this value.

#### Default Value

`Object3D`

#### Inherited from

`Group.type`

***

### up

> **up**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:up](https://threejs.org/docs/#api/en/core/Object3D.up)

This is used by the [lookAt](https://threejs.org/docs/) method, for example, to determine the orientation of the result.

#### Default Value

[Object3D.DEFAULT\_UP](/three-flatland/api/three-flatland/src/classes/flatland/#default_up) - that is `(0, 1, 0)`.

#### Inherited from

`Group.up`

***

### userData

> **userData**: `Record`\<`string`, `any`\>

Defined in: [three.js/core/Object3D:userData](https://threejs.org/docs/#api/en/core/Object3D.userData)

An object that can be used to store custom data about the [Object3D](https://threejs.org/docs/#api/en/core/Object3D).

#### Remarks

It should not hold references to _functions_ as these **will not** be cloned.

#### Default

`{}`

#### Inherited from

`Group.userData`

***

### uuid

> **uuid**: `string`

Defined in: [three.js/core/Object3D:uuid](https://threejs.org/docs/#api/en/core/Object3D.uuid)

[UUID](http://en.wikipedia.org/wiki/Universally_unique_identifier) of this object instance.

#### Remarks

This gets automatically assigned and shouldn't be edited.

#### Inherited from

`Group.uuid`

***

### visible

> **visible**: `boolean`

Defined in: [three.js/core/Object3D:visible](https://threejs.org/docs/#api/en/core/Object3D.visible)

Object gets rendered if `true`.

#### Default Value

`true`

#### Inherited from

`Group.visible`

***

### DEFAULT\_MATRIX\_AUTO\_UPDATE

> `static` **DEFAULT\_MATRIX\_AUTO\_UPDATE**: `boolean`

Defined in: [three.js/core/Object3D:DEFAULT_MATRIX_AUTO_UPDATE](https://threejs.org/docs/#api/en/core/Object3D.DEFAULT_MATRIX_AUTO_UPDATE)

The default setting for [matrixAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixautoupdate) for newly created Object3Ds.

#### Default Value

`true`

#### Inherited from

`Group.DEFAULT_MATRIX_AUTO_UPDATE`

***

### DEFAULT\_MATRIX\_WORLD\_AUTO\_UPDATE

> `static` **DEFAULT\_MATRIX\_WORLD\_AUTO\_UPDATE**: `boolean`

Defined in: [three.js/core/Object3D:DEFAULT_MATRIX_WORLD_AUTO_UPDATE](https://threejs.org/docs/#api/en/core/Object3D.DEFAULT_MATRIX_WORLD_AUTO_UPDATE)

The default setting for [matrixWorldAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldautoupdate) for newly created Object3Ds.

#### Default Value

`true`

#### Inherited from

`Group.DEFAULT_MATRIX_WORLD_AUTO_UPDATE`

***

### DEFAULT\_UP

> `static` **DEFAULT\_UP**: [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:DEFAULT_UP](https://threejs.org/docs/#api/en/core/Object3D.DEFAULT_UP)

The default [up](/three-flatland/api/three-flatland/src/classes/flatland/#up) direction for objects, also used as the default position for THREE.DirectionalLight \| DirectionalLight,
THREE.HemisphereLight \| HemisphereLight and THREE.Spotlight \| Spotlight (which creates lights shining from the top down).

#### Default Value

`new THREE.Vector3( 0, 1, 0)`

#### Inherited from

`Group.DEFAULT_UP`

## Accessors

### bounds

#### Get Signature

> **get** **bounds**(): [`Box3`](https://threejs.org/docs/#api/en/math/Box3)

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:574](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L574)

Get map bounds.

##### Returns

[`Box3`](https://threejs.org/docs/#api/en/math/Box3)

***

### chunkSize

#### Get Signature

> **get** **chunkSize**(): `number`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:133](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L133)

Get/set chunk size in tiles (default: 512).
Each layer is split into chunks of chunkSize×chunkSize tiles for frustum culling.
Maps smaller than chunkSize naturally use a single chunk per layer.

##### Returns

`number`

#### Set Signature

> **set** **chunkSize**(`value`): `void`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:137](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L137)

##### Parameters

###### value

`number`

##### Returns

`void`

***

### data

#### Get Signature

> **get** **data**(): [`TileMapData`](/three-flatland/api/three-flatland/src/interfaces/tilemapdata/) \| `null`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:108](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L108)

Get the tilemap data.

##### Returns

[`TileMapData`](/three-flatland/api/three-flatland/src/interfaces/tilemapdata/) \| `null`

#### Set Signature

> **set** **data**(`value`): `void`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:115](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L115)

Set the tilemap data and rebuild the map.

##### Parameters

###### value

[`TileMapData`](/three-flatland/api/three-flatland/src/interfaces/tilemapdata/) \| `null`

##### Returns

`void`

***

### enableCollision

#### Get Signature

> **get** **enableCollision**(): `boolean`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:150](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L150)

Get/set collision extraction flag.

##### Returns

`boolean`

#### Set Signature

> **set** **enableCollision**(`value`): `void`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:154](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L154)

##### Parameters

###### value

`boolean`

##### Returns

`void`

***

### heightInPixels

#### Get Signature

> **get** **heightInPixels**(): `number`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:180](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L180)

##### Returns

`number`

***

### heightInTiles

#### Get Signature

> **get** **heightInTiles**(): `number`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:168](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L168)

##### Returns

`number`

***

### layerCount

#### Get Signature

> **get** **layerCount**(): `number`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:508](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L508)

Get layer count.

##### Returns

`number`

***

### lit

#### Get Signature

> **get** **lit**(): `boolean`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:406](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L406)

##### Returns

`boolean`

#### Set Signature

> **set** **lit**(`value`): `void`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:410](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L410)

##### Parameters

###### value

`boolean`

##### Returns

`void`

***

### receiveShadows

#### Get Signature

> **get** **receiveShadows**(): `boolean`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:416](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L416)

##### Returns

`boolean`

#### Set Signature

> **set** **receiveShadows**(`value`): `void`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:420](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L420)

##### Parameters

###### value

`boolean`

##### Returns

`void`

***

### tileHeight

#### Get Signature

> **get** **tileHeight**(): `number`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:174](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L174)

##### Returns

`number`

***

### tileWidth

#### Get Signature

> **get** **tileWidth**(): `number`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:171](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L171)

##### Returns

`number`

***

### totalChunkCount

#### Get Signature

> **get** **totalChunkCount**(): `number`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:595](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L595)

Get total chunk count across all layers (equals total draw calls for tiles).

##### Returns

`number`

***

### totalTileCount

#### Get Signature

> **get** **totalTileCount**(): `number`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:602](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L602)

Get total tile count across all layers.

##### Returns

`number`

***

### widthInPixels

#### Get Signature

> **get** **widthInPixels**(): `number`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:177](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L177)

##### Returns

`number`

***

### widthInTiles

#### Get Signature

> **get** **widthInTiles**(): `number`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:165](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L165)

##### Returns

`number`

## Methods

### add()

> **add**(...`object`): `this`

Defined in: [three.js/core/Object3D:add](https://threejs.org/docs/#api/en/core/Object3D.add)

Adds another [Object3D](https://threejs.org/docs/#api/en/core/Object3D) as child of this [Object3D](https://threejs.org/docs/#api/en/core/Object3D).

#### Parameters

##### object

...[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

#### Returns

`this`

#### Remarks

An arbitrary number of objects may be added
Any current parent on an object passed in here will be removed, since an [Object3D](https://threejs.org/docs/#api/en/core/Object3D) can have at most one parent.

#### See

 - [attach](https://threejs.org/docs/)
 - THREE.Group \| Group for info on manually grouping objects.

#### Inherited from

`Group.add`

***

### addEffect()

> **addEffect**(`effect`): `this`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:438](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L438)

Register a MaterialEffect on all tile layer materials.
Use this to add channel providers (e.g. NormalMapProvider) so
tilemaps participate in the lighting pipeline's channel system.

#### Parameters

##### effect

[`MaterialEffect`](/three-flatland/api/three-flatland/src/classes/materialeffect/)

#### Returns

`this`

#### Example

```tsx
<tileMap2D data={mapData}>
  <normalMapProvider attach={attachEffect} />
</tileMap2D>
```

***

### addEventListener()

> **addEventListener**\<`T`\>(`type`, `listener`): `void`

Defined in: [three.js/core/EventDispatcher:addEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.addEventListener)

Adds a listener to an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### type

`T`

The type of event to listen to.

##### listener

[`EventListener`](https://threejs.org/docs/)\<[`Object3DEventMap`](https://threejs.org/docs/)\[`T`\], `T`, `TileMap2D`\>

The function that gets called when the event is fired.

#### Returns

`void`

#### Inherited from

`Group.addEventListener`

***

### applyMatrix4()

> **applyMatrix4**(`matrix`): `void`

Defined in: [three.js/core/Object3D:applyMatrix4](https://threejs.org/docs/#api/en/core/Object3D.applyMatrix4)

Applies the matrix transform to the object and updates the object's position, rotation and scale.

#### Parameters

##### matrix

[`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

#### Returns

`void`

#### Inherited from

`Group.applyMatrix4`

***

### applyQuaternion()

> **applyQuaternion**(`quaternion`): `this`

Defined in: [three.js/core/Object3D:applyQuaternion](https://threejs.org/docs/#api/en/core/Object3D.applyQuaternion)

Applies the rotation represented by the quaternion to the object.

#### Parameters

##### quaternion

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

#### Returns

`this`

#### Inherited from

`Group.applyQuaternion`

***

### attach()

> **attach**(`object`): `this`

Defined in: [three.js/core/Object3D:attach](https://threejs.org/docs/#api/en/core/Object3D.attach)

Adds a [Object3D](https://threejs.org/docs/#api/en/core/Object3D) as a child of this, while maintaining the object's world transform.

#### Parameters

##### object

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)

#### Returns

`this`

#### Remarks

Note: This method does not support scene graphs having non-uniformly-scaled nodes(s).

#### See

[add](https://threejs.org/docs/)

#### Inherited from

`Group.attach`

***

### clear()

> **clear**(): `this`

Defined in: [three.js/core/Object3D:clear](https://threejs.org/docs/#api/en/core/Object3D.clear)

Removes all child objects.

#### Returns

`this`

#### Inherited from

`Group.clear`

***

### clone()

> **clone**(`recursive?`): `this`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:626](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L626)

Clone for devtools/serialization compatibility.
Returns a Group containing cloned child layers for visual inspection.

#### Parameters

##### recursive?

`boolean`

#### Returns

`this`

#### Overrides

`Group.clone`

***

### copy()

> **copy**(`object`, `recursive?`): `this`

Defined in: [three.js/core/Object3D:copy](https://threejs.org/docs/#api/en/core/Object3D.copy)

Copies the given object into this object.

#### Parameters

##### object

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)

##### recursive?

`boolean`

If set to `true`, descendants of the object are copied next to the existing ones. If set to
`false`, descendants are left unchanged. Default is `true`.

#### Returns

`this`

#### Remarks

Event listeners and user-defined callbacks (.onAfterRender and .onBeforeRender) are not copied.

#### Inherited from

`Group.copy`

***

### dispatchEvent()

> **dispatchEvent**\<`T`\>(`event`): `void`

Defined in: [three.js/core/EventDispatcher:dispatchEvent](https://threejs.org/docs/#api/en/core/EventDispatcher.dispatchEvent)

Fire an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### event

[`BaseEvent`](https://threejs.org/docs/)\<`T`\> & [`Object3DEventMap`](https://threejs.org/docs/)\[`T`\]

The event that gets fired.

#### Returns

`void`

#### Inherited from

`Group.dispatchEvent`

***

### dispose()

> **dispose**(): `void`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:661](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L661)

Dispose of all resources.

#### Returns

`void`

***

### getCollisionShapes()

> **getCollisionShapes**(): readonly [`CollisionShape`](/three-flatland/api/three-flatland/src/type-aliases/collisionshape/)[]

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:567](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L567)

Get collision shapes.

#### Returns

readonly [`CollisionShape`](/three-flatland/api/three-flatland/src/type-aliases/collisionshape/)[]

***

### getLayer()

> **getLayer**(`name`): [`TileLayer`](/three-flatland/api/three-flatland/src/classes/tilelayer/) \| `undefined`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:487](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L487)

Get tile layer by name.

#### Parameters

##### name

`string`

#### Returns

[`TileLayer`](/three-flatland/api/three-flatland/src/classes/tilelayer/) \| `undefined`

***

### getLayerAt()

> **getLayerAt**(`index`): [`TileLayer`](/three-flatland/api/three-flatland/src/classes/tilelayer/) \| `undefined`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:494](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L494)

Get tile layer by index.

#### Parameters

##### index

`number`

#### Returns

[`TileLayer`](/three-flatland/api/three-flatland/src/classes/tilelayer/) \| `undefined`

***

### getLayerMaterial()

> **getLayerMaterial**(`name`): [`Sprite2DMaterial`](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/) \| `undefined`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:610](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L610)

Get the Sprite2DMaterial for a tile layer by name.
Use this to apply TSL effects or lighting to specific layers.

#### Parameters

##### name

`string`

#### Returns

[`Sprite2DMaterial`](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/) \| `undefined`

***

### getLayerMaterialAt()

> **getLayerMaterialAt**(`index`): [`Sprite2DMaterial`](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/) \| `undefined`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:618](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L618)

Get the Sprite2DMaterial for a tile layer by index.
Use this to apply TSL effects or lighting to specific layers.

#### Parameters

##### index

`number`

#### Returns

[`Sprite2DMaterial`](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/) \| `undefined`

***

### getLayers()

> **getLayers**(): readonly [`TileLayer`](/three-flatland/api/three-flatland/src/classes/tilelayer/)[]

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:501](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L501)

Get all tile layers.

#### Returns

readonly [`TileLayer`](/three-flatland/api/three-flatland/src/classes/tilelayer/)[]

***

### getObjectById()

> **getObjectById**(`id`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

Defined in: [three.js/core/Object3D:getObjectById](https://threejs.org/docs/#api/en/core/Object3D.getObjectById)

Searches through an object and its children, starting with the object itself, and returns the first with a matching id.

#### Parameters

##### id

`number`

Unique number of the object instance. Expects a `Integer`

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

#### Remarks

Note that ids are assigned in chronological order: 1, 2, 3, ..., incrementing by one for each new object.

#### See

id

#### Inherited from

`Group.getObjectById`

***

### getObjectByName()

> **getObjectByName**(`name`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

Defined in: [three.js/core/Object3D:getObjectByName](https://threejs.org/docs/#api/en/core/Object3D.getObjectByName)

Searches through an object and its children, starting with the object itself, and returns the first with a matching name.

#### Parameters

##### name

`string`

String to match to the children's Object3D.name property.

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

#### Remarks

Note that for most objects the name is an empty string by default
You will have to set it manually to make use of this method.

#### Inherited from

`Group.getObjectByName`

***

### getObjectByProperty()

> **getObjectByProperty**(`name`, `value`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

Defined in: [three.js/core/Object3D:getObjectByProperty](https://threejs.org/docs/#api/en/core/Object3D.getObjectByProperty)

Searches through an object and its children, starting with the object itself,
and returns the first with a property that matches the value given.

#### Parameters

##### name

`string`

the property name to search for.

##### value

`any`

value of the given property.

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\> \| `undefined`

#### Inherited from

`Group.getObjectByProperty`

***

### getObjectLayer()

> **getObjectLayer**(`name`): [`ObjectLayerData`](/three-flatland/api/three-flatland/src/interfaces/objectlayerdata/) \| `undefined`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:515](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L515)

Get object layer by name.

#### Parameters

##### name

`string`

#### Returns

[`ObjectLayerData`](/three-flatland/api/three-flatland/src/interfaces/objectlayerdata/) \| `undefined`

***

### getObjectsByProperty()

> **getObjectsByProperty**(`name`, `value`, `optionalTarget?`): [`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

Defined in: [three.js/core/Object3D:getObjectsByProperty](https://threejs.org/docs/#api/en/core/Object3D.getObjectsByProperty)

Searches through an object and its children, starting with the object itself,
and returns the first with a property that matches the value given.

#### Parameters

##### name

`string`

The property name to search for.

##### value

`any`

Value of the given property.

##### optionalTarget?

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

target to set the result. Otherwise a new Array is instantiated. If set, you must clear
this array prior to each call (i.e., array.length = 0;).

#### Returns

[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

#### Inherited from

`Group.getObjectsByProperty`

***

### getObjectsByType()

> **getObjectsByType**(`type`): [`TileMapObject`](/three-flatland/api/three-flatland/src/interfaces/tilemapobject/)[]

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:522](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L522)

Get all objects of a specific type.

#### Parameters

##### type

`string`

#### Returns

[`TileMapObject`](/three-flatland/api/three-flatland/src/interfaces/tilemapobject/)[]

***

### getProperty()

> **getProperty**\<`T`\>(`name`): `T` \| `undefined`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:588](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L588)

Get custom property from map data.

#### Type Parameters

##### T

`T`

#### Parameters

##### name

`string`

#### Returns

`T` \| `undefined`

***

### getTileAtWorld()

> **getTileAtWorld**(`worldX`, `worldY`, `layerIndex?`): `number`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:537](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L537)

Get tile GID at world position.

#### Parameters

##### worldX

`number`

##### worldY

`number`

##### layerIndex?

`number` = `0`

#### Returns

`number`

***

### getTileset()

> **getTileset**(`name`): [`Tileset`](/three-flatland/api/three-flatland/src/classes/tileset/) \| `undefined`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:581](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L581)

Get tileset by name.

#### Parameters

##### name

`string`

#### Returns

[`Tileset`](/three-flatland/api/three-flatland/src/classes/tileset/) \| `undefined`

***

### getWorldDirection()

> **getWorldDirection**(`target`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:getWorldDirection](https://threejs.org/docs/#api/en/core/Object3D.getWorldDirection)

Returns a vector representing the direction of object's positive z-axis in world space.

#### Parameters

##### target

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

The result will be copied into this Vector3.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Group.getWorldDirection`

***

### getWorldPosition()

> **getWorldPosition**(`target`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:getWorldPosition](https://threejs.org/docs/#api/en/core/Object3D.getWorldPosition)

Returns a vector representing the position of the object in world space.

#### Parameters

##### target

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

The result will be copied into this Vector3.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Group.getWorldPosition`

***

### getWorldQuaternion()

> **getWorldQuaternion**(`target`): [`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

Defined in: [three.js/core/Object3D:getWorldQuaternion](https://threejs.org/docs/#api/en/core/Object3D.getWorldQuaternion)

Returns a quaternion representing the rotation of the object in world space.

#### Parameters

##### target

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

The result will be copied into this Quaternion.

#### Returns

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

#### Inherited from

`Group.getWorldQuaternion`

***

### getWorldScale()

> **getWorldScale**(`target`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:getWorldScale](https://threejs.org/docs/#api/en/core/Object3D.getWorldScale)

Returns a vector of the scaling factors applied to the object for each axis in world space.

#### Parameters

##### target

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

The result will be copied into this Vector3.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Group.getWorldScale`

***

### hasEventListener()

> **hasEventListener**\<`T`\>(`type`, `listener`): `boolean`

Defined in: [three.js/core/EventDispatcher:hasEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.hasEventListener)

Checks if listener is added to an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### type

`T`

The type of event to listen to.

##### listener

[`EventListener`](https://threejs.org/docs/)\<[`Object3DEventMap`](https://threejs.org/docs/)\[`T`\], `T`, `TileMap2D`\>

The function that gets called when the event is fired.

#### Returns

`boolean`

#### Inherited from

`Group.hasEventListener`

***

### localToWorld()

> **localToWorld**(`vector`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:localToWorld](https://threejs.org/docs/#api/en/core/Object3D.localToWorld)

Converts the vector from this object's local space to world space.

#### Parameters

##### vector

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A vector representing a position in this object's local space.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Group.localToWorld`

***

### lookAt()

#### Call Signature

> **lookAt**(`vector`): `void`

Defined in: [three.js/core/Object3D:lookAt](https://threejs.org/docs/#api/en/core/Object3D.lookAt)

Rotates the object to face a point in world space.

##### Parameters

###### vector

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A vector representing a position in world space to look at.

##### Returns

`void`

##### Remarks

This method does not support objects having non-uniformly-scaled parent(s).

##### Inherited from

`Group.lookAt`

#### Call Signature

> **lookAt**(`x`, `y`, `z`): `void`

Defined in: [three.js/core/Object3D:lookAt](https://threejs.org/docs/#api/en/core/Object3D.lookAt)

Rotates the object to face a point in world space.

##### Parameters

###### x

`number`

Expects a `Float`

###### y

`number`

Expects a `Float`

###### z

`number`

Expects a `Float`

##### Returns

`void`

##### Remarks

This method does not support objects having non-uniformly-scaled parent(s).

##### Inherited from

`Group.lookAt`

***

### markOccluders()

> **markOccluders**(`types`, `layerIndex?`): `void`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:460](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L460)

Mark tiles as shadow casters based on object layer data.
Typically called with IntGrid-derived collision objects.

#### Parameters

##### types

`string`[]

Object types to treat as occluders (e.g. ['collision', 'torch_switch'])

##### layerIndex?

`number` = `0`

Which tile layer to mark (default: 0)

#### Returns

`void`

***

### onAfterRender()

> **onAfterRender**(`renderer`, `scene`, `camera`, `geometry`, `material`, `group`): `void`

Defined in: [three.js/core/Object3D:onAfterRender](https://threejs.org/docs/#api/en/core/Object3D.onAfterRender)

An optional callback that is executed immediately after a 3D object is rendered.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### material

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, geometry, material, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

`Group.onAfterRender`

***

### onAfterShadow()

> **onAfterShadow**(`renderer`, `scene`, `camera`, `shadowCamera`, `geometry`, `depthMaterial`, `group`): `void`

Defined in: [three.js/core/Object3D:onAfterShadow](https://threejs.org/docs/#api/en/core/Object3D.onAfterShadow)

An optional callback that is executed immediately after a 3D object is rendered to a shadow map.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### shadowCamera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### depthMaterial

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, shadowCamera, geometry,
depthMaterial, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

`Group.onAfterShadow`

***

### onBeforeRender()

> **onBeforeRender**(`renderer`, `scene`, `camera`, `geometry`, `material`, `group`): `void`

Defined in: [three.js/core/Object3D:onBeforeRender](https://threejs.org/docs/#api/en/core/Object3D.onBeforeRender)

An optional callback that is executed immediately before a 3D object is rendered.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### material

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, geometry, material, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

`Group.onBeforeRender`

***

### onBeforeShadow()

> **onBeforeShadow**(`renderer`, `scene`, `camera`, `shadowCamera`, `geometry`, `depthMaterial`, `group`): `void`

Defined in: [three.js/core/Object3D:onBeforeShadow](https://threejs.org/docs/#api/en/core/Object3D.onBeforeShadow)

An optional callback that is executed immediately before a 3D object is rendered to a shadow map.

#### Parameters

##### renderer

[`WebGLRenderer`](https://threejs.org/docs/#api/en/renderers/WebGLRenderer)

##### scene

[`Scene`](https://threejs.org/docs/#api/en/scenes/Scene)

##### camera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### shadowCamera

[`Camera`](https://threejs.org/docs/#api/en/cameras/Camera)

##### geometry

[`BufferGeometry`](https://threejs.org/docs/#api/en/core/BufferGeometry)

##### depthMaterial

[`Material`](https://threejs.org/docs/#api/en/materials/Material)

##### group

[`Group`](https://threejs.org/docs/#api/en/objects/Group)

#### Returns

`void`

#### Remarks

This function is called with the following parameters: renderer, scene, camera, shadowCamera, geometry,
depthMaterial, group.
Please notice that this callback is only executed for `renderable` 3D objects. Meaning 3D objects which
define their visual appearance with geometries and materials like instances of Mesh, Line,
Points or Sprite. Instances of [Object3D](https://threejs.org/docs/#api/en/core/Object3D), [Group](https://threejs.org/docs/#api/en/objects/Group) or Bone are not renderable
and thus this callback is not executed for such objects.

#### Inherited from

`Group.onBeforeShadow`

***

### raycast()

> **raycast**(`raycaster`, `intersects`): `void`

Defined in: [three.js/core/Object3D:raycast](https://threejs.org/docs/#api/en/core/Object3D.raycast)

Abstract (empty) method to get intersections between a casted ray and this object

#### Parameters

##### raycaster

[`Raycaster`](https://threejs.org/docs/#api/en/core/Raycaster)

##### intersects

[`Intersection`](https://threejs.org/docs/)\<[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>\>[]

#### Returns

`void`

#### Remarks

Subclasses such as THREE.Mesh \| Mesh, THREE.Line \| Line, and THREE.Points \| Points implement this method in order to use raycasting.

#### See

THREE.Raycaster \| Raycaster

#### Default Value

`() => {}`

#### Inherited from

`Group.raycast`

***

### remove()

> **remove**(...`object`): `this`

Defined in: [three.js/core/Object3D:remove](https://threejs.org/docs/#api/en/core/Object3D.remove)

Removes a [Object3D](https://threejs.org/docs/#api/en/core/Object3D) as child of this [Object3D](https://threejs.org/docs/#api/en/core/Object3D).

#### Parameters

##### object

...[`Object3D`](https://threejs.org/docs/#api/en/core/Object3D)\<[`Object3DEventMap`](https://threejs.org/docs/)\>[]

#### Returns

`this`

#### Remarks

An arbitrary number of objects may be removed.

#### See

THREE.Group \| Group for info on manually grouping objects.

#### Inherited from

`Group.remove`

***

### removeEffect()

> **removeEffect**(`_effect`): `this`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:449](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L449)

#### Parameters

##### \_effect

[`MaterialEffect`](/three-flatland/api/three-flatland/src/classes/materialeffect/)

#### Returns

`this`

***

### removeEventListener()

> **removeEventListener**\<`T`\>(`type`, `listener`): `void`

Defined in: [three.js/core/EventDispatcher:removeEventListener](https://threejs.org/docs/#api/en/core/EventDispatcher.removeEventListener)

Removes a listener from an event type.

#### Type Parameters

##### T

`T` *extends* keyof [`Object3DEventMap`](https://threejs.org/docs/)

#### Parameters

##### type

`T`

The type of the listener that gets removed.

##### listener

[`EventListener`](https://threejs.org/docs/)\<[`Object3DEventMap`](https://threejs.org/docs/)\[`T`\], `T`, `TileMap2D`\>

The listener function that gets removed.

#### Returns

`void`

#### Inherited from

`Group.removeEventListener`

***

### removeFromParent()

> **removeFromParent**(): `this`

Defined in: [three.js/core/Object3D:removeFromParent](https://threejs.org/docs/#api/en/core/Object3D.removeFromParent)

Removes this object from its current parent.

#### Returns

`this`

#### Inherited from

`Group.removeFromParent`

***

### rotateOnAxis()

> **rotateOnAxis**(`axis`, `angle`): `this`

Defined in: [three.js/core/Object3D:rotateOnAxis](https://threejs.org/docs/#api/en/core/Object3D.rotateOnAxis)

Rotate an object along an axis in object space.

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in object space.

##### angle

`number`

The angle in radians. Expects a `Float`

#### Returns

`this`

#### Remarks

The axis is assumed to be normalized.

#### Inherited from

`Group.rotateOnAxis`

***

### rotateOnWorldAxis()

> **rotateOnWorldAxis**(`axis`, `angle`): `this`

Defined in: [three.js/core/Object3D:rotateOnWorldAxis](https://threejs.org/docs/#api/en/core/Object3D.rotateOnWorldAxis)

Rotate an object along an axis in world space.

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in world space.

##### angle

`number`

The angle in radians. Expects a `Float`

#### Returns

`this`

#### Remarks

The axis is assumed to be normalized
Method Assumes no rotated parent.

#### Inherited from

`Group.rotateOnWorldAxis`

***

### rotateX()

> **rotateX**(`angle`): `this`

Defined in: [three.js/core/Object3D:rotateX](https://threejs.org/docs/#api/en/core/Object3D.rotateX)

Rotates the object around _x_ axis in local space.

#### Parameters

##### angle

`number`

#### Returns

`this`

#### Inherited from

`Group.rotateX`

***

### rotateY()

> **rotateY**(`angle`): `this`

Defined in: [three.js/core/Object3D:rotateY](https://threejs.org/docs/#api/en/core/Object3D.rotateY)

Rotates the object around _y_ axis in local space.

#### Parameters

##### angle

`number`

#### Returns

`this`

#### Inherited from

`Group.rotateY`

***

### rotateZ()

> **rotateZ**(`angle`): `this`

Defined in: [three.js/core/Object3D:rotateZ](https://threejs.org/docs/#api/en/core/Object3D.rotateZ)

Rotates the object around _z_ axis in local space.

#### Parameters

##### angle

`number`

#### Returns

`this`

#### Inherited from

`Group.rotateZ`

***

### setRotationFromAxisAngle()

> **setRotationFromAxisAngle**(`axis`, `angle`): `void`

Defined in: [three.js/core/Object3D:setRotationFromAxisAngle](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromAxisAngle)

Calls THREE.Quaternion.setFromAxisAngle \| setFromAxisAngle(axis, angle) on the [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in object space.

##### angle

`number`

Angle in radians. Expects a `Float`

#### Returns

`void`

#### Inherited from

`Group.setRotationFromAxisAngle`

***

### setRotationFromEuler()

> **setRotationFromEuler**(`euler`): `void`

Defined in: [three.js/core/Object3D:setRotationFromEuler](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromEuler)

Calls THREE.Quaternion.setFromEuler \| setFromEuler(euler) on the [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### euler

[`Euler`](https://threejs.org/docs/#api/en/math/Euler)

Euler angle specifying rotation amount.

#### Returns

`void`

#### Inherited from

`Group.setRotationFromEuler`

***

### setRotationFromMatrix()

> **setRotationFromMatrix**(`m`): `void`

Defined in: [three.js/core/Object3D:setRotationFromMatrix](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromMatrix)

Calls THREE.Quaternion.setFromRotationMatrix \| setFromRotationMatrix(m) on the [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### m

[`Matrix4`](https://threejs.org/docs/#api/en/math/Matrix4)

Rotate the quaternion by the rotation component of the matrix.

#### Returns

`void`

#### Remarks

Note that this assumes that the upper 3x3 of m is a pure rotation matrix (i.e, unscaled).

#### Inherited from

`Group.setRotationFromMatrix`

***

### setRotationFromQuaternion()

> **setRotationFromQuaternion**(`q`): `void`

Defined in: [three.js/core/Object3D:setRotationFromQuaternion](https://threejs.org/docs/#api/en/core/Object3D.setRotationFromQuaternion)

Copy the given THREE.Quaternion \| Quaternion into [.quaternion](/three-flatland/api/three-flatland/src/classes/flatland/#quaternion).

#### Parameters

##### q

[`Quaternion`](https://threejs.org/docs/#api/en/math/Quaternion)

Normalized Quaternion.

#### Returns

`void`

#### Inherited from

`Group.setRotationFromQuaternion`

***

### tileToWorld()

> **tileToWorld**(`tileX`, `tileY`): `object`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:557](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L557)

Convert tile coordinates to world position (center of tile).

#### Parameters

##### tileX

`number`

##### tileY

`number`

#### Returns

`object`

##### x

> **x**: `number`

##### y

> **y**: `number`

***

### toJSON()

> **toJSON**(`meta?`): [`Object3DJSON`](https://threejs.org/docs/)

Defined in: [three.js/core/Object3D:toJSON](https://threejs.org/docs/#api/en/core/Object3D.toJSON)

Convert the object to three.js [JSON Object/Scene format](https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4).

#### Parameters

##### meta?

[`JSONMeta`](https://threejs.org/docs/)

Object containing metadata such as materials, textures or images for the object.

#### Returns

[`Object3DJSON`](https://threejs.org/docs/)

#### Inherited from

`Group.toJSON`

***

### translateOnAxis()

> **translateOnAxis**(`axis`, `distance`): `this`

Defined in: [three.js/core/Object3D:translateOnAxis](https://threejs.org/docs/#api/en/core/Object3D.translateOnAxis)

Translate an object by distance along an axis in object space

#### Parameters

##### axis

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A normalized vector in object space.

##### distance

`number`

The distance to translate. Expects a `Float`

#### Returns

`this`

#### Remarks

The axis is assumed to be normalized.

#### Inherited from

`Group.translateOnAxis`

***

### translateX()

> **translateX**(`distance`): `this`

Defined in: [three.js/core/Object3D:translateX](https://threejs.org/docs/#api/en/core/Object3D.translateX)

Translates object along x axis in object space by distance units.

#### Parameters

##### distance

`number`

Expects a `Float`

#### Returns

`this`

#### Inherited from

`Group.translateX`

***

### translateY()

> **translateY**(`distance`): `this`

Defined in: [three.js/core/Object3D:translateY](https://threejs.org/docs/#api/en/core/Object3D.translateY)

Translates object along _y_ axis in object space by distance units.

#### Parameters

##### distance

`number`

Expects a `Float`

#### Returns

`this`

#### Inherited from

`Group.translateY`

***

### translateZ()

> **translateZ**(`distance`): `this`

Defined in: [three.js/core/Object3D:translateZ](https://threejs.org/docs/#api/en/core/Object3D.translateZ)

Translates object along _z_ axis in object space by distance units.

#### Parameters

##### distance

`number`

Expects a `Float`

#### Returns

`this`

#### Inherited from

`Group.translateZ`

***

### traverse()

> **traverse**(`callback`): `void`

Defined in: [three.js/core/Object3D:traverse](https://threejs.org/docs/#api/en/core/Object3D.traverse)

Executes the callback on this object and all descendants.

#### Parameters

##### callback

(`object`) => `any`

A function with as first argument an [Object3D](https://threejs.org/docs/#api/en/core/Object3D) object.

#### Returns

`void`

#### Remarks

Note: Modifying the scene graph inside the callback is discouraged.

#### Inherited from

`Group.traverse`

***

### traverseAncestors()

> **traverseAncestors**(`callback`): `void`

Defined in: [three.js/core/Object3D:traverseAncestors](https://threejs.org/docs/#api/en/core/Object3D.traverseAncestors)

Executes the callback on all ancestors.

#### Parameters

##### callback

(`object`) => `any`

A function with as first argument an [Object3D](https://threejs.org/docs/#api/en/core/Object3D) object.

#### Returns

`void`

#### Remarks

Note: Modifying the scene graph inside the callback is discouraged.

#### Inherited from

`Group.traverseAncestors`

***

### traverseVisible()

> **traverseVisible**(`callback`): `void`

Defined in: [three.js/core/Object3D:traverseVisible](https://threejs.org/docs/#api/en/core/Object3D.traverseVisible)

Like traverse, but the callback will only be executed for visible objects

#### Parameters

##### callback

(`object`) => `any`

A function with as first argument an [Object3D](https://threejs.org/docs/#api/en/core/Object3D) object.

#### Returns

`void`

#### Remarks

Descendants of invisible objects are not traversed.
Note: Modifying the scene graph inside the callback is discouraged.

#### Inherited from

`Group.traverseVisible`

***

### update()

> **update**(`deltaMs`): `void`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:478](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L478)

Update animated tiles.
Call this in your animation loop with delta time in milliseconds.

#### Parameters

##### deltaMs

`number`

#### Returns

`void`

***

### updateMatrix()

> **updateMatrix**(): `void`

Defined in: [three.js/core/Object3D:updateMatrix](https://threejs.org/docs/#api/en/core/Object3D.updateMatrix)

Updates local transform.

#### Returns

`void`

#### Inherited from

`Group.updateMatrix`

***

### updateMatrixWorld()

> **updateMatrixWorld**(`force?`): `void`

Defined in: [three.js/core/Object3D:updateMatrixWorld](https://threejs.org/docs/#api/en/core/Object3D.updateMatrixWorld)

Updates the global transform of the object.
And will update the object descendants if [.matrixWorldNeedsUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldneedsupdate) is set to true or if the force parameter is set to `true`.

#### Parameters

##### force?

`boolean`

A boolean that can be used to bypass [.matrixWorldAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldautoupdate), to recalculate the world matrix of the object and descendants on the current frame.
Useful if you cannot wait for the renderer to update it on the next frame, assuming [.matrixWorldAutoUpdate](/three-flatland/api/three-flatland/src/classes/flatland/#matrixworldautoupdate) set to `true`.

#### Returns

`void`

#### Inherited from

`Group.updateMatrixWorld`

***

### updateWorldMatrix()

> **updateWorldMatrix**(`updateParents`, `updateChildren`): `void`

Defined in: [three.js/core/Object3D:updateWorldMatrix](https://threejs.org/docs/#api/en/core/Object3D.updateWorldMatrix)

Updates the global transform of the object.

#### Parameters

##### updateParents

`boolean`

Recursively updates global transform of ancestors.

##### updateChildren

`boolean`

Recursively updates global transform of descendants.

#### Returns

`void`

#### Inherited from

`Group.updateWorldMatrix`

***

### worldToLocal()

> **worldToLocal**(`vector`): [`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

Defined in: [three.js/core/Object3D:worldToLocal](https://threejs.org/docs/#api/en/core/Object3D.worldToLocal)

Converts the vector from world space to this object's local space.

#### Parameters

##### vector

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

A vector representing a position in world space.

#### Returns

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

#### Inherited from

`Group.worldToLocal`

***

### worldToTile()

> **worldToTile**(`worldX`, `worldY`): `object`

Defined in: [packages/three-flatland/src/tilemap/TileMap2D.ts:547](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/TileMap2D.ts#L547)

Convert world position to tile coordinates (in Tiled's Y-down system).

#### Parameters

##### worldX

`number`

##### worldY

`number`

#### Returns

`object`

##### x

> **x**: `number`

##### y

> **y**: `number`

# Tileset

Defined in: [packages/three-flatland/src/tilemap/Tileset.ts:33](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/Tileset.ts#L33)

Represents a tileset with tile definitions and texture atlas.

Handles UV coordinate calculation and animated tile management.

## Example

```typescript
const tileset = new Tileset({
  name: 'dungeon',
  firstGid: 1,
  tileWidth: 16,
  tileHeight: 16,
  imageWidth: 256,
  imageHeight: 256,
  columns: 16,
  tileCount: 256,
  tiles: new Map(),
  texture: myTexture,
})

const uv = tileset.getUV(5) // Get UV for tile GID 5
```

## Constructors

### Constructor

> **new Tileset**(`data`): `Tileset`

Defined in: [packages/three-flatland/src/tilemap/Tileset.ts:66](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/Tileset.ts#L66)

#### Parameters

##### data

[`TilesetData`](/three-flatland/api/three-flatland/src/interfaces/tilesetdata/)

#### Returns

`Tileset`

## Properties

### columns

> `readonly` **columns**: `number`

Defined in: [packages/three-flatland/src/tilemap/Tileset.ts:49](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/Tileset.ts#L49)

Grid info

***

### firstGid

> `readonly` **firstGid**: `number`

Defined in: [packages/three-flatland/src/tilemap/Tileset.ts:38](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/Tileset.ts#L38)

First GID

***

### imageHeight

> `readonly` **imageHeight**: `number`

Defined in: [packages/three-flatland/src/tilemap/Tileset.ts:46](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/Tileset.ts#L46)

***

### imageWidth

> `readonly` **imageWidth**: `number`

Defined in: [packages/three-flatland/src/tilemap/Tileset.ts:45](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/Tileset.ts#L45)

Atlas dimensions

***

### margin

> `readonly` **margin**: `number`

Defined in: [packages/three-flatland/src/tilemap/Tileset.ts:52](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/Tileset.ts#L52)

***

### name

> `readonly` **name**: `string`

Defined in: [packages/three-flatland/src/tilemap/Tileset.ts:35](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/Tileset.ts#L35)

Tileset name

***

### spacing

> `readonly` **spacing**: `number`

Defined in: [packages/three-flatland/src/tilemap/Tileset.ts:51](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/Tileset.ts#L51)

***

### tileCount

> `readonly` **tileCount**: `number`

Defined in: [packages/three-flatland/src/tilemap/Tileset.ts:50](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/Tileset.ts#L50)

***

### tileHeight

> `readonly` **tileHeight**: `number`

Defined in: [packages/three-flatland/src/tilemap/Tileset.ts:42](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/Tileset.ts#L42)

***

### tileWidth

> `readonly` **tileWidth**: `number`

Defined in: [packages/three-flatland/src/tilemap/Tileset.ts:41](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/Tileset.ts#L41)

Tile dimensions

## Accessors

### texture

#### Get Signature

> **get** **texture**(): [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

Defined in: [packages/three-flatland/src/tilemap/Tileset.ts:94](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/Tileset.ts#L94)

Get the texture atlas.

##### Returns

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

#### Set Signature

> **set** **texture**(`value`): `void`

Defined in: [packages/three-flatland/src/tilemap/Tileset.ts:102](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/Tileset.ts#L102)

Set the texture atlas.
Applies texture options from textureOptions property or TextureConfig.options.

##### Parameters

###### value

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

##### Returns

`void`

***

### textureOptions

#### Get Signature

> **get** **textureOptions**(): [`TexturePreset`](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/) \| [`TextureOptions`](/three-flatland/api/three-flatland/src/interfaces/textureoptions/) \| `undefined`

Defined in: [packages/three-flatland/src/tilemap/Tileset.ts:113](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/Tileset.ts#L113)

Get the texture options for this tileset.

##### Returns

[`TexturePreset`](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/) \| [`TextureOptions`](/three-flatland/api/three-flatland/src/interfaces/textureoptions/) \| `undefined`

#### Set Signature

> **set** **textureOptions**(`value`): `void`

Defined in: [packages/three-flatland/src/tilemap/Tileset.ts:121](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/Tileset.ts#L121)

Set the texture options for this tileset.
If a texture is already set, it will be updated with the new options.

##### Parameters

###### value

[`TexturePreset`](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/) \| [`TextureOptions`](/three-flatland/api/three-flatland/src/interfaces/textureoptions/) \| `undefined`

##### Returns

`void`

## Methods

### containsGid()

> **containsGid**(`gid`): `boolean`

Defined in: [packages/three-flatland/src/tilemap/Tileset.ts:132](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/Tileset.ts#L132)

Check if a GID belongs to this tileset.

#### Parameters

##### gid

`number`

#### Returns

`boolean`

***

### dispose()

> **dispose**(): `void`

Defined in: [packages/three-flatland/src/tilemap/Tileset.ts:207](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/Tileset.ts#L207)

Dispose of resources.

#### Returns

`void`

***

### getAnimatedTileIds()

> **getAnimatedTileIds**(): `number`[]

Defined in: [packages/three-flatland/src/tilemap/Tileset.ts:200](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/Tileset.ts#L200)

Get all animated tile IDs (as GIDs).

#### Returns

`number`[]

***

### getAnimation()

> **getAnimation**(`gid`): [`TileAnimationFrame`](/three-flatland/api/three-flatland/src/interfaces/tileanimationframe/)[] \| `undefined`

Defined in: [packages/three-flatland/src/tilemap/Tileset.ts:192](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/Tileset.ts#L192)

Get animation frames for a tile.

#### Parameters

##### gid

`number`

#### Returns

[`TileAnimationFrame`](/three-flatland/api/three-flatland/src/interfaces/tileanimationframe/)[] \| `undefined`

***

### getLocalId()

> **getLocalId**(`gid`): `number`

Defined in: [packages/three-flatland/src/tilemap/Tileset.ts:140](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/Tileset.ts#L140)

Get local ID from GID.

#### Parameters

##### gid

`number`

#### Returns

`number`

***

### getTile()

> **getTile**(`gid`): [`TileDefinition`](/three-flatland/api/three-flatland/src/interfaces/tiledefinition/) \| `undefined`

Defined in: [packages/three-flatland/src/tilemap/Tileset.ts:176](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/Tileset.ts#L176)

Get tile definition.

#### Parameters

##### gid

`number`

#### Returns

[`TileDefinition`](/three-flatland/api/three-flatland/src/interfaces/tiledefinition/) \| `undefined`

***

### getUV()

> **getUV**(`gid`): `object`

Defined in: [packages/three-flatland/src/tilemap/Tileset.ts:149](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/Tileset.ts#L149)

Get UV coordinates for a tile.
Returns normalized UV coordinates (0-1) for the tile in the atlas.
Note: Y is NOT flipped here - the material handles coordinate space conversion.

#### Parameters

##### gid

`number`

#### Returns

`object`

##### height

> **height**: `number`

##### width

> **width**: `number`

##### x

> **x**: `number`

##### y

> **y**: `number`

***

### isAnimated()

> **isAnimated**(`gid`): `boolean`

Defined in: [packages/three-flatland/src/tilemap/Tileset.ts:184](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/Tileset.ts#L184)

Check if a tile is animated.

#### Parameters

##### gid

`number`

#### Returns

`boolean`

# applyHierarchicalPresets

> **applyHierarchicalPresets**(`texture`, `instanceOptions?`, `loaderOptions?`): `void`

Defined in: [packages/three-flatland/src/loaders/TextureLoader.ts:183](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/TextureLoader.ts#L183)

Apply hierarchical texture presets to a texture.

Useful when you need to override presets after loading, or when
using Three's TextureLoader directly.

Hierarchy (highest to lowest priority):
1. instanceOptions (per-call override)
2. loaderOptions (loader-level default)
3. TextureConfig.options (global default)
4. 'pixel-art' (system default)

## Parameters

### texture

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

### instanceOptions?

[`TexturePreset`](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/) \| [`TextureOptions`](/three-flatland/api/three-flatland/src/interfaces/textureoptions/)

### loaderOptions?

[`TexturePreset`](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/) \| [`TextureOptions`](/three-flatland/api/three-flatland/src/interfaces/textureoptions/)

## Returns

`void`

## Example

```typescript
// Override presets on an already-loaded texture
const texture = await TextureLoader.load('/sprite.png')
applyHierarchicalPresets(texture, 'smooth') // Override to smooth filtering
```

# applyTextureOptions

> **applyTextureOptions**(`texture`, `preset`): `void`

Defined in: [packages/three-flatland/src/loaders/texturePresets.ts:81](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/texturePresets.ts#L81)

Apply texture preset or custom options to a texture.

## Parameters

### texture

[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

### preset

[`TexturePreset`](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/) \| [`TextureOptions`](/three-flatland/api/three-flatland/src/interfaces/textureoptions/)

## Returns

`void`

# computeTier

> **computeTier**(`neededFloats`): `number`

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:37](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L37)

Compute the buffer tier for a given float count.
Tiers: 0, 4, 8, 16, and multiples of 4 beyond 16.

## Parameters

### neededFloats

`number`

## Returns

`number`

# concatAnimations

> **concatAnimations**(`name`, `animations`, `options?`): [`Animation`](/three-flatland/api/three-flatland/src/interfaces/animation/)

Defined in: [packages/three-flatland/src/animation/utils.ts:132](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/utils.ts#L132)

Concatenate multiple animations into one.

## Parameters

### name

`string`

### animations

[`Animation`](/three-flatland/api/three-flatland/src/interfaces/animation/)[]

### options?

#### fps?

`number`

#### loop?

`boolean`

## Returns

[`Animation`](/three-flatland/api/three-flatland/src/interfaces/animation/)

# createAnimation

> **createAnimation**(`spriteSheet`, `name`, `frameNames`, `options?`): [`Animation`](/three-flatland/api/three-flatland/src/interfaces/animation/)

Defined in: [packages/three-flatland/src/animation/utils.ts:95](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/utils.ts#L95)

Create a simple animation from an array of frame names.

## Parameters

### spriteSheet

[`SpriteSheet`](/three-flatland/api/three-flatland/src/interfaces/spritesheet/)

### name

`string`

### frameNames

`string`[]

### options?

#### fps?

`number`

#### loop?

`boolean`

#### pingPong?

`boolean`

## Returns

[`Animation`](/three-flatland/api/three-flatland/src/interfaces/animation/)

# createAnimationFromPattern

> **createAnimationFromPattern**(`spriteSheet`, `name`, `prefix`, `count`, `options?`): [`Animation`](/three-flatland/api/three-flatland/src/interfaces/animation/)

Defined in: [packages/three-flatland/src/animation/utils.ts:13](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/utils.ts#L13)

Create an animation from a frame name pattern.

## Parameters

### spriteSheet

[`SpriteSheet`](/three-flatland/api/three-flatland/src/interfaces/spritesheet/)

### name

`string`

### prefix

`string`

### count

`number`

### options?

#### fps?

`number`

#### loop?

`boolean`

#### pingPong?

`boolean`

#### startIndex?

`number`

#### suffix?

`string`

## Returns

[`Animation`](/three-flatland/api/three-flatland/src/interfaces/animation/)

## Example

```typescript
// Creates animation from 'player_walk_0', 'player_walk_1', etc.
const walkAnim = createAnimationFromPattern(sheet, 'walk', 'player_walk_', 4);
```

# createAnimationsFromNaming

> **createAnimationsFromNaming**(`spriteSheet`, `prefix`, `options?`): [`Animation`](/three-flatland/api/three-flatland/src/interfaces/animation/)[]

Defined in: [packages/three-flatland/src/animation/utils.ts:61](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/utils.ts#L61)

Create animations from a naming convention.
Assumes frames are named: `{prefix}_{animationName}_{frameIndex}`

## Parameters

### spriteSheet

[`SpriteSheet`](/three-flatland/api/three-flatland/src/interfaces/spritesheet/)

### prefix

`string`

### options?

#### fps?

`number`

#### loop?

`boolean`

## Returns

[`Animation`](/three-flatland/api/three-flatland/src/interfaces/animation/)[]

## Example

```typescript
// Auto-detect animations from frames like 'player_idle_0', 'player_walk_0', etc.
const animations = createAnimationsFromNaming(sheet, 'player');
```

# createDevtoolsProvider

> **createDevtoolsProvider**(`options?`): [`DevtoolsProviderHandle`](/three-flatland/api/three-flatland/src/interfaces/devtoolsproviderhandle/)

Defined in: [packages/three-flatland/src/debug/createDevtoolsProvider.ts:58](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/debug/createDevtoolsProvider.ts#L58)

Construct a devtools provider when bundled + active; otherwise a
no-op stub. Safe to call unconditionally from app code.

## Parameters

### options?

`DevtoolsProviderOptions` = `{}`

## Returns

[`DevtoolsProviderHandle`](/three-flatland/api/three-flatland/src/interfaces/devtoolsproviderhandle/)

# createLightEffect

> **createLightEffect**\<`S`, `C`\>(`config`): [`LightEffectClass`](/three-flatland/api/three-flatland/src/type-aliases/lighteffectclass/)\<`S`\>

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:653](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L653)

Create a LightEffect class from a configuration object.

Supports lifecycle hooks (init/update/resize/dispose) for effects that
manage GPU resources. Use factory function fields in the schema for
per-instance constants (e.g., ForwardPlusLighting).

## Type Parameters

### S

`S` *extends* [`EffectSchema`](/three-flatland/api/three-flatland/src/type-aliases/effectschema/)

### C

`C` *extends* readonly keyof [`ChannelNodeMap`](/three-flatland/api/three-flatland/src/interfaces/channelnodemap/)[] = readonly \[\]

## Parameters

### config

`LightEffectConfig`\<`S`, `C`\>

## Returns

[`LightEffectClass`](/three-flatland/api/three-flatland/src/type-aliases/lighteffectclass/)\<`S`\>

## Example

```typescript
const DefaultLightEffect = createLightEffect({
  name: 'defaultLight',
  schema: { ambientIntensity: 0.2 },
  light: ({ uniforms, lightStore }) => {
    // build light loop using lightStore.readLightData()
  },
})

const lighting = new DefaultLightEffect()
flatland.setLighting(lighting)
lighting.ambientIntensity = 0.4  // zero-cost uniform update
```

# createMaterialEffect

> **createMaterialEffect**\<`S`, `C`\>(`config`): [`MaterialEffectClass`](/three-flatland/api/three-flatland/src/type-aliases/materialeffectclass/)\<`S`\>

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:509](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L509)

Create a MaterialEffect class from a configuration object.

This is the simple factory path — for quick effect definitions without
writing a full class. Returns a class that extends MaterialEffect with
typed properties.

## Type Parameters

### S

`S` *extends* [`EffectSchema`](/three-flatland/api/three-flatland/src/type-aliases/effectschema/)

### C

`C` *extends* readonly keyof [`ChannelNodeMap`](/three-flatland/api/three-flatland/src/interfaces/channelnodemap/)[] = readonly \[\]

## Parameters

### config

`MaterialEffectConfig`\<`S`, `C`\>

## Returns

[`MaterialEffectClass`](/three-flatland/api/three-flatland/src/type-aliases/materialeffectclass/)\<`S`\>

## Example

```typescript
const DissolveEffect = createMaterialEffect({
  name: 'dissolve',
  schema: { progress: 0 },
  node({ inputColor, attrs }) {
    return mix(inputColor, vec4(0, 0, 0, 0), attrs.progress)
  },
})

const dissolve = new DissolveEffect()
dissolve.progress = 0.5
sprite.addEffect(dissolve)
```

# createPassEffect

> **createPassEffect**\<`S`\>(`config`): [`PassEffectClass`](/three-flatland/api/three-flatland/src/type-aliases/passeffectclass/)\<`S`\>

Defined in: [packages/three-flatland/src/pipeline/PassEffect.ts:429](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/PassEffect.ts#L429)

Create a PassEffect class from a configuration object.

## Type Parameters

### S

`S` *extends* [`EffectSchema`](/three-flatland/api/three-flatland/src/type-aliases/effectschema/)

## Parameters

### config

`PassEffectConfig`\<`S`\>

## Returns

[`PassEffectClass`](/three-flatland/api/three-flatland/src/type-aliases/passeffectclass/)\<`S`\>

## Example

```typescript
const VignetteEffect = createPassEffect({
  name: 'vignette',
  schema: { intensity: 0.5 },
  pass: ({ uniforms }) => (input, uv) => vignette(input, uv, uniforms.intensity),
})

const v = new VignetteEffect()
flatland.addPass(v)
v.intensity = 0.8  // zero-cost uniform update
```

# decodeSortKey

> **decodeSortKey**(`sortKey`): `object`

Defined in: [packages/three-flatland/src/pipeline/layers.ts:72](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/layers.ts#L72)

Decode a sort key back to its components.

## Parameters

### sortKey

`number`

Encoded sort key

## Returns

`object`

Object with layer, batchId, and zIndex

### batchId

> **batchId**: `number`

### layer

> **layer**: `number`

### zIndex

> **zIndex**: `number`

# encodeSortKey

> **encodeSortKey**(`layer`, `batchId`, `zIndex`): `number`

Defined in: [packages/three-flatland/src/pipeline/layers.ts:60](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/layers.ts#L60)

Encode a sort key from layer, material ID, and zIndex.

Format: (layer & 0xFF) << 24 | (batchId & 0xFFF) << 12 | (zIndex & 0xFFF)

This allows efficient sorting with a single numeric comparison.

## Parameters

### layer

`number`

Layer value (0-255)

### batchId

`number`

Material ID (0-4095)

### zIndex

`number`

Z-index within layer (0-4095, or negative values mapped to positive range)

## Returns

`number`

Encoded sort key

# framesToRegions

> **framesToRegions**(`frames`): [`NormalRegion`](/three-flatland/api/three-flatland/src/interfaces/normalregion/)[]

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:122](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L122)

Build one flat region per frame rect. Each region inherits
descriptor defaults — most sprite sheets don't need per-frame
direction, but individual frames can be overridden by the caller
merging custom regions in.

Region-local alpha clamping (applied by the baker) is what keeps
adjacent frames from bleeding gradients into each other.

## Parameters

### frames

[`SpriteFrameRect`](/three-flatland/api/three-flatland/src/interfaces/spriteframerect/)[]

## Returns

[`NormalRegion`](/three-flatland/api/three-flatland/src/interfaces/normalregion/)[]

# getPackedComponent

> **getPackedComponent**(`bufNodes`, `absoluteOffset`): [`Node`](https://threejs.org/docs/)\<`"float"`\>

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:49](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L49)

Get a TSL component accessor from a packed vec4 buffer array.
Maps an absolute float offset to the correct bufNode[n].xyzw component.

## Parameters

### bufNodes

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>[]

### absoluteOffset

`number`

## Returns

[`Node`](https://threejs.org/docs/)\<`"float"`\>

# isDevtoolsActive

> **isDevtoolsActive**(): `boolean`

Defined in: [packages/three-flatland/src/debug-protocol.ts:229](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/debug-protocol.ts#L229)

**Layer 1 (build-time): the devtools build gate.** Every devtools call
site is guarded by one consistent, hard-coded expression written
directly at the gate — never a named const, never an import:

```ts
if (process.env.NODE_ENV !== 'production' || process.env.FL_DEVTOOLS === 'true') {
  // devtools-only work
}
```

Two switches:
- `process.env.NODE_ENV !== 'production'` — every bundler (webpack, Vite,
  esbuild, Rollup) and Node statically replaces `NODE_ENV`, so a production
  build folds this to `false`.
- `process.env.FL_DEVTOOLS === 'true'` — the repo's own escape hatch: a
  production-mode build that `define`s `process.env.FL_DEVTOOLS = 'true'`
  (the examples do) keeps devtools; everything else folds it away.

The expression is **inlined per gate site — never hoisted into a named
const, never imported from a shared exported const.** A local or
cross-module const is NOT inlined by every bundler (esbuild in particular
keeps it as a live binding), which defeats the dead-strip and ships the
whole devtools subsystem. Writing the literal `process.env.*` reads at each
gate lets every bundler replace-then-dead-strip locally. The negated form
(for early-return guards) is the De Morgan inverse:
`process.env.NODE_ENV === 'production' && process.env.FL_DEVTOOLS !== 'true'`.

**Layer 2 (runtime): `isDevtoolsActive()`.** Only reachable when the gate is
true. Reads `window.__FLATLAND_DEVTOOLS__` as an opt-out (false disables an
otherwise-bundled build). Cannot enable what isn't bundled — rogue clients
can't "hack devtools on" in prod.

| Build state | `window.__FLATLAND_DEVTOOLS__` | Enabled? |
|---|---|---|
| dev (`NODE_ENV !== 'production'`) or `FL_DEVTOOLS='true'` | undefined | yes (default on) |
| dev or `FL_DEVTOOLS='true'` | false     | no (user disabled) |
| dev or `FL_DEVTOOLS='true'` | true      | yes (explicit) |
| production, no opt-in       | anything  | no (code not in bundle) |

## Returns

`boolean`

# isLight2D

> **isLight2D**(`object`): `object is Light2D`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:362](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L362)

Type guard for Light2D.

## Parameters

### object

`unknown`

## Returns

`object is Light2D`

# readCastShadowFlag

> **readCastShadowFlag**(): [`Node`](https://threejs.org/docs/)\<`"bool"`\>

Defined in: [packages/three-flatland/src/materials/instanceAttributes.ts:105](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/instanceAttributes.ts#L105)

Read the per-instance castsShadow flag (bit 2 of `instanceSystem.z`).
Consumed by the occlusion-pass fragment shader to mask a sprite's
alpha contribution to the SDF seed — casters emit their silhouette,
non-casters emit alpha = 0.

## Returns

[`Node`](https://threejs.org/docs/)\<`"bool"`\>

# readEnableBits

> **readEnableBits**(): [`Node`](https://threejs.org/docs/)\<`"int"`\>

Defined in: [packages/three-flatland/src/materials/instanceAttributes.ts:61](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/instanceAttributes.ts#L61)

Read the MaterialEffect enable-bits bitmask from `instanceSystem.w`.
Bit N is set while the Nth registered effect is active on this
instance. 24 slots (bits 0..23) — matches `EFFECT_BIT_OFFSET`.

## Returns

[`Node`](https://threejs.org/docs/)\<`"int"`\>

# readFlip

> **readFlip**(): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/three-flatland/src/materials/instanceAttributes.ts:40](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/instanceAttributes.ts#L40)

Read the per-instance flip vector from `instanceSystem.xy`. Each
component is +1 for unflipped, -1 for flipped. Consumers typically
destructure into `.x` and `.y` to drive axis-specific flip math.

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

# readLitFlag

> **readLitFlag**(): [`Node`](https://threejs.org/docs/)\<`"bool"`\>

Defined in: [packages/three-flatland/src/materials/instanceAttributes.ts:86](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/instanceAttributes.ts#L86)

Read the per-instance lit flag (bit 0 of `instanceSystem.z`).
Used by `wrapWithLightFlags` to gate the light pipeline; custom
ColorTransforms can also call this directly.

## Returns

[`Node`](https://threejs.org/docs/)\<`"bool"`\>

# readReceiveShadowsFlag

> **readReceiveShadowsFlag**(): [`Node`](https://threejs.org/docs/)\<`"bool"`\>

Defined in: [packages/three-flatland/src/materials/instanceAttributes.ts:95](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/instanceAttributes.ts#L95)

Read the per-instance receiveShadows flag (bit 1 of
`instanceSystem.z`). Preset LightEffects call this in their shadow
calculation to skip shadow for sprites that have opted out.

## Returns

[`Node`](https://threejs.org/docs/)\<`"bool"`\>

# readShadowRadius

> **readShadowRadius**(): [`Node`](https://threejs.org/docs/)\<`"float"`\>

Defined in: [packages/three-flatland/src/materials/instanceAttributes.ts:75](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/instanceAttributes.ts#L75)

Read the per-instance shadow-occluder radius from `instanceExtras.x`.
World units. Auto-resolved each frame to `max(|scale.x|, |scale.y|)`
by `transformSyncSystem`, overridable via `Sprite2D.shadowRadius`.

Shadow-casting LightEffects consume this value for algorithm-
specific purposes — SDF sphere-tracers use it as the self-silhouette
escape distance; future shadow maps would use it for depth bias;
AO passes could use it for sample radius.

## Returns

[`Node`](https://threejs.org/docs/)\<`"float"`\>

# readSystemFlags

> **readSystemFlags**(): [`Node`](https://threejs.org/docs/)\<`"int"`\>

Defined in: [packages/three-flatland/src/materials/instanceAttributes.ts:52](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/instanceAttributes.ts#L52)

Read the raw system-flags bitfield from `instanceSystem.z`. Bit 0 =
lit, bit 1 = receiveShadows, bit 2 = castsShadow, bits 3..23 reserved.
Prefer the typed helpers ([readLitFlag](/three-flatland/api/three-flatland/src/functions/readlitflag/), etc.) for individual
bits — this is the lower-level access used when you need to mask or
compare against multiple bits at once.

## Returns

[`Node`](https://threejs.org/docs/)\<`"int"`\>

# registerDebugArray

> **registerDebugArray**(`name`, `ref`, `kind`, `opts?`): `void`

Defined in: [packages/three-flatland/src/debug/debug-sink.ts:103](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/debug/debug-sink.ts#L103)

Publish (or re-publish) a named CPU array to the devtools pane.
Holds a *reference*; the host keeps mutating its own buffer. Call
`touchDebugArray(name)` when you mutate in place so the provider
knows to re-send on the next batch. Replacing the buffer (new
`ref`) calls `touchDebugArray` implicitly.

Safe to call any time — no-op when devtools isn't bundled.

## Parameters

### name

`string`

### ref

`Int32Array`\<`ArrayBufferLike`\> \| `Float32Array`\<`ArrayBufferLike`\> \| `Uint32Array`\<`ArrayBufferLike`\>

### kind

`RegistryEntryKind`

### opts?

#### label?

`string`

#### length?

`number`

## Returns

`void`

# registerDebugTexture

> **registerDebugTexture**(`name`, `source`, `pixelType?`, `opts?`): `void`

Defined in: [packages/three-flatland/src/debug/debug-sink.ts:139](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/debug/debug-sink.ts#L139)

Publish a debug texture (DataTexture or RenderTarget) to the
devtools pane. Readback is only performed when a consumer has
selected this name for preview — safe to leave registered.

`source` may be a `DataTexture` (CPU-backed, cheap) or any object
shaped like a `WebGLRenderTarget` / `WebGPURenderTarget` with
`width`, `height`, `texture`. No-op when devtools isn't bundled.

## Parameters

### name

`string`

### source

[`DataTexture`](https://threejs.org/docs/#api/en/textures/DataTexture) \| \{ `height`: `number`; `texture`: [`Texture`](https://threejs.org/docs/#api/en/textures/Texture); `width`: `number`; \}

### pixelType?

`TexturePixelType` = `'rgba8'`

### opts?

#### display?

`BufferDisplayMode`

#### label?

`string`

## Returns

`void`

# resolveTextureOptions

> **resolveTextureOptions**(`instanceOptions?`, `loaderOptions?`): [`TexturePreset`](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/) \| [`TextureOptions`](/three-flatland/api/three-flatland/src/interfaces/textureoptions/)

Defined in: [packages/three-flatland/src/loaders/texturePresets.ts:98](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/texturePresets.ts#L98)

Resolve options from hierarchy: instance > loader > global > 'pixel-art'

## Parameters

### instanceOptions?

[`TexturePreset`](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/) \| [`TextureOptions`](/three-flatland/api/three-flatland/src/interfaces/textureoptions/)

### loaderOptions?

[`TexturePreset`](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/) \| [`TextureOptions`](/three-flatland/api/three-flatland/src/interfaces/textureoptions/)

## Returns

[`TexturePreset`](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/) \| [`TextureOptions`](/three-flatland/api/three-flatland/src/interfaces/textureoptions/)

# reverseAnimation

> **reverseAnimation**(`animation`, `newName?`): [`Animation`](/three-flatland/api/three-flatland/src/interfaces/animation/)

Defined in: [packages/three-flatland/src/animation/utils.ts:121](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/utils.ts#L121)

Reverse an animation's frame order.

## Parameters

### animation

[`Animation`](/three-flatland/api/three-flatland/src/interfaces/animation/)

### newName?

`string`

## Returns

[`Animation`](/three-flatland/api/three-flatland/src/interfaces/animation/)

# shallowEqual

> **shallowEqual**(`a`, `b`): `boolean`

Defined in: [packages/three-flatland/src/observable/index.ts:72](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/observable/index.ts#L72)

Shallow-compare two snapshots. Used by the registry to bail out
of redundant action fires when an observed value's fields didn't
actually change.

## Parameters

### a

[`Snapshot`](/three-flatland/api/three-flatland/src/type-aliases/snapshot/)

### b

[`Snapshot`](/three-flatland/api/three-flatland/src/type-aliases/snapshot/)

## Returns

`boolean`

# tilesetToRegions

> **tilesetToRegions**(`cells`): [`NormalRegion`](/three-flatland/api/three-flatland/src/interfaces/normalregion/)[]

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:154](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L154)

Build regions for a whole tileset. Each cell becomes one or more
regions depending on its custom data — untagged cells emit a single
flat region; cells with `tileDirection` + cap fields emit cap strips
plus a face region.

## Parameters

### cells

[`TilesetCell`](/three-flatland/api/three-flatland/src/interfaces/tilesetcell/)[]

## Returns

[`NormalRegion`](/three-flatland/api/three-flatland/src/interfaces/normalregion/)[]

# tileToRegions

> **tileToRegions**(`cell`, `meta`): [`NormalRegion`](/three-flatland/api/three-flatland/src/interfaces/normalregion/)[]

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:187](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L187)

Synthesize regions for a single tile cell given its custom data.

Cap geometry:
  - Each of `tileCap{Top,Bottom,Left,Right}` carves a cap strip off
    that edge (full width/height).
  - Each of `tileCap{TopLeft,TopRight,BottomLeft,BottomRight}` carves
    an N×N cap square at that corner — use when the tile art has a
    small flat patch in one corner and the wall face wraps around
    it in an L-shape (outer walls facing outward).
  - `tileCap` shorthand: `tileCapTop` when no per-edge field is set.
    The explicit per-edge / per-corner fields always win.
  - Cap rects compose by UNION — the cap region is everything any
    cap covers, and the face is the complement. Overlapping caps are
    harmless (duplicate rects get deduplicated by the baker's
    per-texel write).

The face area — whatever the cell's interior minus all cap rects —
is decomposed into one or more non-overlapping rectangles, each
tilted toward `tileDir` with `tilePitch`.

When `tileDir` is absent (or equals `'flat'`), the entire cell emits
as a single flat region and cap fields are ignored — a flat tile has
no face to distinguish from its cap.

## Parameters

### cell

#### h

`number`

#### w

`number`

#### x

`number`

#### y

`number`

### meta

[`TileNormalCustomData`](/three-flatland/api/three-flatland/src/interfaces/tilenormalcustomdata/) \| `undefined`

## Returns

[`NormalRegion`](/three-flatland/api/three-flatland/src/interfaces/normalregion/)[]

# touchDebugArray

> **touchDebugArray**(`name`, `length?`): `void`

Defined in: [packages/three-flatland/src/debug/debug-sink.ts:119](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/debug/debug-sink.ts#L119)

Signal that a previously-registered array has been mutated in place
and should be re-sampled on the next batch flush.

## Parameters

### name

`string`

### length?

`number`

## Returns

`void`

# touchDebugTexture

> **touchDebugTexture**(`name`): `void`

Defined in: [packages/three-flatland/src/debug/debug-sink.ts:152](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/debug/debug-sink.ts#L152)

Signal that a registered texture's content has changed.

## Parameters

### name

`string`

## Returns

`void`

# unregisterDebugArray

> **unregisterDebugArray**(`name`): `void`

Defined in: [packages/three-flatland/src/debug/debug-sink.ts:125](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/debug/debug-sink.ts#L125)

Remove a named array. Consumers will see it disappear on the next batch.

## Parameters

### name

`string`

## Returns

`void`

# unregisterDebugTexture

> **unregisterDebugTexture**(`name`): `void`

Defined in: [packages/three-flatland/src/debug/debug-sink.ts:158](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/debug/debug-sink.ts#L158)

Remove a named texture.

## Parameters

### name

`string`

## Returns

`void`

# uvToWorld

> **uvToWorld**(`uvPos`, `occSize`, `occOffset`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/three-flatland/src/lights/coordUtils.ts:20](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/coordUtils.ts#L20)

Convert UV [0,1] space to world position.
uv.mul(size).add(offset)

## Parameters

### uvPos

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

### occSize

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

### occOffset

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

# wholeTextureRegion

> **wholeTextureRegion**(`width`, `height`): [`NormalRegion`](/three-flatland/api/three-flatland/src/interfaces/normalregion/)[]

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:129](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L129)

Single region covering the whole texture. Used by `TextureLoader`.

## Parameters

### width

`number`

### height

`number`

## Returns

[`NormalRegion`](/three-flatland/api/three-flatland/src/interfaces/normalregion/)[]

# worldToUV

> **worldToUV**(`worldPos`, `occSize`, `occOffset`): [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/three-flatland/src/lights/coordUtils.ts:8](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/coordUtils.ts#L8)

Convert world position to UV [0,1] space.
worldPos.sub(offset).div(size)

## Parameters

### worldPos

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

### occSize

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

### occOffset

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

# wrapWithLightFlags

> **wrapWithLightFlags**(`lightFn`): [`ColorTransformFn`](/three-flatland/api/three-flatland/src/type-aliases/colortransformfn/)

Defined in: [packages/three-flatland/src/lights/wrapWithLightFlags.ts:21](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/wrapWithLightFlags.ts#L21)

Wrap a light `ColorTransformFn` with a per-instance lit-bit gate.

Uses [readLitFlag](/three-flatland/api/three-flatland/src/functions/readlitflag/) + `select()` to bypass lighting for sprites
whose `lit` flag is not set. Only needed for batched sprites —
standalone usage can assign the raw `lightFn` directly.

This is the only light-specific helper in the per-instance-accessor
family; the raw accessors ([readFlip](/three-flatland/api/three-flatland/src/functions/readflip/), [readShadowRadius](/three-flatland/api/three-flatland/src/functions/readshadowradius/),
etc.) live in `materials/instanceAttributes.ts` alongside the
flag-mask constants that define the bit layout. They're re-exported
from this module's barrel for convenience and backward compatibility.

## Parameters

### lightFn

[`ColorTransformFn`](/three-flatland/api/three-flatland/src/type-aliases/colortransformfn/)

The lighting ColorTransformFn to wrap

## Returns

[`ColorTransformFn`](/three-flatland/api/three-flatland/src/type-aliases/colortransformfn/)

A new ColorTransformFn that gates lighting per instance

# AnimatedSprite2DOptions

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:12](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L12)

Options for creating an AnimatedSprite2D.

## Properties

### alpha?

> `optional` **alpha?**: `number`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:30](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L30)

Opacity 0-1, default 1

***

### anchor?

> `optional` **anchor?**: \[`number`, `number`\] \| [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:26](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L26)

Anchor/pivot point (0-1), default [0.5, 0.5] (center)

***

### animation?

> `optional` **animation?**: `string`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:22](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L22)

Initial animation to play

***

### animations?

> `optional` **animations?**: [`Animation`](/three-flatland/api/three-flatland/src/interfaces/animation/)[]

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:18](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L18)

Animation definitions

***

### animationSet?

> `optional` **animationSet?**: [`AnimationSetDefinition`](/three-flatland/api/three-flatland/src/interfaces/animationsetdefinition/)

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:20](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L20)

Animation set definition (alternative to animations array)

***

### autoPlay?

> `optional` **autoPlay?**: `boolean`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:24](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L24)

Auto-play on creation (default: true)

***

### flipX?

> `optional` **flipX?**: `boolean`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:32](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L32)

Flip horizontally

***

### flipY?

> `optional` **flipY?**: `boolean`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:34](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L34)

Flip vertically

***

### layer?

> `optional` **layer?**: `number`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:36](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L36)

Render layer (for SpriteGroup)

***

### material?

> `optional` **material?**: [`Sprite2DMaterial`](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/)

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:16](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L16)

Custom material (sprites with same material instance batch together)

***

### pixelPerfect?

> `optional` **pixelPerfect?**: `boolean`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:40](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L40)

Pixel-perfect rendering (snap to pixels)

***

### spriteSheet

> **spriteSheet**: [`SpriteSheet`](/three-flatland/api/three-flatland/src/interfaces/spritesheet/)

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:14](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L14)

SpriteSheet containing animation frames

***

### tint?

> `optional` **tint?**: `string` \| `number` \| [`Color`](https://threejs.org/docs/#api/en/math/Color)

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:28](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L28)

Tint color, default white

***

### zIndex?

> `optional` **zIndex?**: `number`

Defined in: [packages/three-flatland/src/sprites/AnimatedSprite2D.ts:38](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/AnimatedSprite2D.ts#L38)

Z-index within layer

# Animation

Defined in: [packages/three-flatland/src/animation/types.ts:20](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L20)

Animation definition.

## Properties

### fps?

> `optional` **fps?**: `number`

Defined in: [packages/three-flatland/src/animation/types.ts:26](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L26)

Frames per second (default: 12)

***

### frames

> **frames**: [`AnimationFrame`](/three-flatland/api/three-flatland/src/interfaces/animationframe/)[]

Defined in: [packages/three-flatland/src/animation/types.ts:24](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L24)

Sequence of frames

***

### loop?

> `optional` **loop?**: `boolean`

Defined in: [packages/three-flatland/src/animation/types.ts:28](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L28)

Whether to loop (default: true)

***

### loopCount?

> `optional` **loopCount?**: `number`

Defined in: [packages/three-flatland/src/animation/types.ts:32](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L32)

Number of times to loop (-1 for infinite, default)

***

### name

> **name**: `string`

Defined in: [packages/three-flatland/src/animation/types.ts:22](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L22)

Animation name

***

### pingPong?

> `optional` **pingPong?**: `boolean`

Defined in: [packages/three-flatland/src/animation/types.ts:30](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L30)

Ping-pong animation (play forward then backward)

# AnimationFrame

Defined in: [packages/three-flatland/src/animation/types.ts:6](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L6)

A single frame in an animation sequence.

## Properties

### data?

> `optional` **data?**: `Record`\<`string`, `unknown`\>

Defined in: [packages/three-flatland/src/animation/types.ts:14](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L14)

Custom data attached to this frame

***

### duration?

> `optional` **duration?**: `number`

Defined in: [packages/three-flatland/src/animation/types.ts:10](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L10)

Duration of this frame in milliseconds (overrides animation fps)

***

### event?

> `optional` **event?**: `string`

Defined in: [packages/three-flatland/src/animation/types.ts:12](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L12)

Event to fire when this frame is reached

***

### frame

> **frame**: [`SpriteFrame`](/three-flatland/api/three-flatland/src/interfaces/spriteframe/)

Defined in: [packages/three-flatland/src/animation/types.ts:8](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L8)

Reference to the sprite frame

# AnimationSetDefinition

Defined in: [packages/three-flatland/src/animation/types.ts:78](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L78)

Animation set definition (for loading from JSON).

## Properties

### animations

> **animations**: `object`

Defined in: [packages/three-flatland/src/animation/types.ts:82](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L82)

Animation definitions

#### Index Signature

\[`name`: `string`\]: `object`

***

### fps?

> `optional` **fps?**: `number`

Defined in: [packages/three-flatland/src/animation/types.ts:80](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L80)

Default FPS for all animations

# AnimationState

Defined in: [packages/three-flatland/src/animation/types.ts:58](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L58)

Animation controller state.

## Properties

### animation

> **animation**: `string` \| `null`

Defined in: [packages/three-flatland/src/animation/types.ts:60](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L60)

Current animation name

***

### elapsed

> **elapsed**: `number`

Defined in: [packages/three-flatland/src/animation/types.ts:64](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L64)

Time elapsed in current frame (ms)

***

### frameIndex

> **frameIndex**: `number`

Defined in: [packages/three-flatland/src/animation/types.ts:62](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L62)

Current frame index

***

### loopCount

> **loopCount**: `number`

Defined in: [packages/three-flatland/src/animation/types.ts:70](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L70)

Current loop count

***

### paused

> **paused**: `boolean`

Defined in: [packages/three-flatland/src/animation/types.ts:68](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L68)

Is animation paused

***

### playing

> **playing**: `boolean`

Defined in: [packages/three-flatland/src/animation/types.ts:66](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L66)

Is animation playing

***

### speed

> **speed**: `number`

Defined in: [packages/three-flatland/src/animation/types.ts:72](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L72)

Speed multiplier

# BatchKey

Defined in: [packages/three-flatland/src/pipeline/types.ts:91](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/types.ts#L91)

Batch key for grouping sprites by material.

## Properties

### batchId

> **batchId**: `number`

Defined in: [packages/three-flatland/src/pipeline/types.ts:95](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/types.ts#L95)

Material batch ID for fast comparison

***

### material

> **material**: [`Sprite2DMaterial`](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/)

Defined in: [packages/three-flatland/src/pipeline/types.ts:93](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/types.ts#L93)

Material instance

# ChannelNodeContext

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:100](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L100)

Context passed to a provider effect's channel node builder.

## Type Parameters

### S

`S` *extends* [`EffectSchema`](/three-flatland/api/three-flatland/src/type-aliases/effectschema/) = [`EffectSchema`](/three-flatland/api/three-flatland/src/type-aliases/effectschema/)

## Properties

### atlasUV

> **atlasUV**: [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:102](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L102)

Atlas UV coordinates (vec2 node).

***

### attrs

> **attrs**: \{ \[K in string \| number \| symbol\]: SchemaToNodeType\<S\[K\]\> \}

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:106](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L106)

TSL attribute nodes for each uniform schema field, keyed by unprefixed name.

***

### baseTexture

> **baseTexture**: [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:108](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L108)

Base sprite texture (for auto-normal generation, etc.). Null if unavailable.

***

### constants

> **constants**: [`EffectConstants`](/three-flatland/api/three-flatland/src/type-aliases/effectconstants/)\<`S`\>

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:104](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L104)

Read-only constants from factory function fields.

# ChannelNodeMap

Defined in: [packages/three-flatland/src/materials/channels.ts:24](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/channels.ts#L24)

Maps well-known channel names to their TSL node types.
Users extend via module augmentation for custom channels:

## Example

```typescript
declare module 'three-flatland' {
  interface ChannelNodeMap {
    roughness: Node<'float'>
    emissive: Node<'vec3'>
  }
}
```

## Properties

### elevation

> **elevation**: [`Node`](https://threejs.org/docs/)\<`"float"`\>

Defined in: [packages/three-flatland/src/materials/channels.ts:34](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/channels.ts#L34)

World-space elevation of the fragment in [0, 1]. 0 = ground plane
(floor), 1 = top-of-wall (cap). Consumed by `DefaultLightEffect`
to compute `L.z = lightHeight − elevation` per fragment per light,
so torches below wall caps stop lighting them. Baked into the
normal atlas's B channel; reconstructed-nz is derived at runtime
from the RG channels (nz = sqrt(1 − nx² − ny²)).

***

### normal

> **normal**: [`Node`](https://threejs.org/docs/)\<`"vec3"`\>

Defined in: [packages/three-flatland/src/materials/channels.ts:25](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/channels.ts#L25)

# ChunkCoord

Defined in: [packages/three-flatland/src/tilemap/types.ts:202](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L202)

Chunk coordinates.

## Properties

### x

> **x**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:203](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L203)

***

### y

> **y**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:204](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L204)

# ColorTransformContext

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:18](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L18)

Context passed to colorTransform callbacks.

## Properties

### atlasUV

> **atlasUV**: [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:22](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L22)

UV after flip + atlas remap

***

### color

> **color**: [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:20](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L20)

Base sampled + tinted color (vec4)

***

### worldPosition

> **worldPosition**: [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:24](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L24)

World position XY (works with instancing via positionWorld)

# DevtoolsProviderHandle

Defined in: [packages/three-flatland/src/debug/createDevtoolsProvider.ts:46](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/debug/createDevtoolsProvider.ts#L46)

Minimal interface — what host code calls per frame. The real
`DevtoolsProvider` and the no-op stub both implement it.

## Properties

### disposed

> `readonly` **disposed**: `boolean`

Defined in: [packages/three-flatland/src/debug/createDevtoolsProvider.ts:51](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/debug/createDevtoolsProvider.ts#L51)

`true` once `dispose()` has been called.

## Methods

### beginFrame()

> **beginFrame**(`now`, `renderer`): `void`

Defined in: [packages/three-flatland/src/debug/createDevtoolsProvider.ts:47](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/debug/createDevtoolsProvider.ts#L47)

#### Parameters

##### now

`number`

##### renderer

[`WebGPURenderer`](https://threejs.org/docs/)

#### Returns

`void`

***

### dispose()

> **dispose**(): `void`

Defined in: [packages/three-flatland/src/debug/createDevtoolsProvider.ts:49](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/debug/createDevtoolsProvider.ts#L49)

#### Returns

`void`

***

### endFrame()

> **endFrame**(`renderer`): `void`

Defined in: [packages/three-flatland/src/debug/createDevtoolsProvider.ts:48](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/debug/createDevtoolsProvider.ts#L48)

#### Parameters

##### renderer

[`WebGPURenderer`](https://threejs.org/docs/)

#### Returns

`void`

# EffectField

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:65](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L65)

Computed field metadata from schema.

## Properties

### default

> **default**: `number`[]

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:71](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L71)

Default values as flat array.

***

### name

> **name**: `string`

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:67](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L67)

Field name (unprefixed).

***

### size

> **size**: `number`

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:69](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L69)

Number of float components (1=float, 2=vec2, 3=vec3, 4=vec4).

# EffectMaterialOptions

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:61](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L61)

Options for EffectMaterial constructor.

## Properties

### effectTier?

> `optional` **effectTier?**: `number`

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:68](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L68)

Effect buffer tier size in floats.
Buffers are allocated in tiers: 0, 4, 8, 16.
Default is 8 (2 vec4 buffers), covering most effect combinations.
Set to 0 for fully effect-free materials (no effect buffer overhead).

# EffectNodeContext

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:88](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L88)

Context passed to an effect's TSL node builder.

## Type Parameters

### S

`S` *extends* [`EffectSchema`](/three-flatland/api/three-flatland/src/type-aliases/effectschema/) = [`EffectSchema`](/three-flatland/api/three-flatland/src/type-aliases/effectschema/)

## Properties

### attrs

> **attrs**: \{ \[K in string \| number \| symbol\]: SchemaToNodeType\<S\[K\]\> \}

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:94](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L94)

TSL attribute nodes for each uniform schema field, keyed by unprefixed name.

***

### constants

> **constants**: [`EffectConstants`](/three-flatland/api/three-flatland/src/type-aliases/effectconstants/)\<`S`\>

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:96](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L96)

Read-only constants from factory function fields.

***

### inputColor

> **inputColor**: [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:90](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L90)

The previous color in the effect chain (vec4 node).

***

### inputUV

> **inputUV**: [`Node`](https://threejs.org/docs/)\<`"vec2"`\>

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:92](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L92)

Atlas UV coordinates (vec2 node).

# FlatlandOptions

Defined in: [packages/three-flatland/src/Flatland.ts:75](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L75)

Options for creating a Flatland instance.

## Properties

### aspect?

> `optional` **aspect?**: `number`

Defined in: [packages/three-flatland/src/Flatland.ts:98](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L98)

Initial aspect ratio (default: 1, use resize() to update)

***

### autoClear?

> `optional` **autoClear?**: `boolean`

Defined in: [packages/three-flatland/src/Flatland.ts:90](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L90)

Clear before render (default: true)

***

### camera?

> `optional` **camera?**: [`OrthographicCamera`](https://threejs.org/docs/#api/en/cameras/OrthographicCamera) \| `null`

Defined in: [packages/three-flatland/src/Flatland.ts:86](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L86)

Camera to use (null = use internal orthographic camera)

***

### clearAlpha?

> `optional` **clearAlpha?**: `number`

Defined in: [packages/three-flatland/src/Flatland.ts:94](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L94)

Background alpha (default: 1)

***

### clearColor?

> `optional` **clearColor?**: [`ColorRepresentation`](https://threejs.org/docs/)

Defined in: [packages/three-flatland/src/Flatland.ts:92](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L92)

Background color

***

### name?

> `optional` **name?**: `string`

Defined in: [packages/three-flatland/src/Flatland.ts:82](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L82)

Human-readable name shown in the devtools consumer UI. Useful to
distinguish multiple Flatland instances (e.g. `name: 'main-game'`
vs `name: 'minimap'`) or a custom engine's provider from the
default. Default: `'flatland'`.

***

### postProcessing?

> `optional` **postProcessing?**: `boolean`

Defined in: [packages/three-flatland/src/Flatland.ts:96](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L96)

Enable post-processing pipeline (default: false)

***

### renderTarget?

> `optional` **renderTarget?**: [`RenderTarget`](https://threejs.org/docs/)\<[`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\>\> \| `null`

Defined in: [packages/three-flatland/src/Flatland.ts:84](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L84)

Render target (null = render to viewport)

***

### viewSize?

> `optional` **viewSize?**: `number`

Defined in: [packages/three-flatland/src/Flatland.ts:88](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/Flatland.ts#L88)

Orthographic view size in pixels (default: 400)

# InstanceAttributeConfig

Defined in: [packages/three-flatland/src/pipeline/types.ts:21](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/types.ts#L21)

Configuration for a custom instance attribute.

## Properties

### defaultValue

> **defaultValue**: `number` \| \[`number`, `number`, `number`, `number`\] \| \[`number`, `number`, `number`\] \| \[`number`, `number`\]

Defined in: [packages/three-flatland/src/pipeline/types.ts:27](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/types.ts#L27)

Default value

***

### name

> **name**: `string`

Defined in: [packages/three-flatland/src/pipeline/types.ts:23](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/types.ts#L23)

Attribute name (used in TSL as instanceFloat('name'))

***

### type

> **type**: [`InstanceAttributeType`](/three-flatland/api/three-flatland/src/type-aliases/instanceattributetype/)

Defined in: [packages/three-flatland/src/pipeline/types.ts:25](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/types.ts#L25)

Data type

# LayerConfig

Defined in: [packages/three-flatland/src/pipeline/types.ts:33](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/types.ts#L33)

Layer configuration.

## Properties

### blendMode?

> `optional` **blendMode?**: [`BlendMode`](/three-flatland/api/three-flatland/src/type-aliases/blendmode/)

Defined in: [packages/three-flatland/src/pipeline/types.ts:39](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/types.ts#L39)

Blend mode for this layer

***

### name

> **name**: `string`

Defined in: [packages/three-flatland/src/pipeline/types.ts:35](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/types.ts#L35)

Layer name

***

### sortMode?

> `optional` **sortMode?**: [`SortMode`](/three-flatland/api/three-flatland/src/type-aliases/sortmode/)

Defined in: [packages/three-flatland/src/pipeline/types.ts:41](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/types.ts#L41)

Sort mode for sprites in this layer

***

### value

> **value**: `number`

Defined in: [packages/three-flatland/src/pipeline/types.ts:37](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/types.ts#L37)

Layer value/index

***

### visible?

> `optional` **visible?**: `boolean`

Defined in: [packages/three-flatland/src/pipeline/types.ts:43](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/types.ts#L43)

Whether this layer is visible

# LDtkLoaderOptions

Defined in: [packages/three-flatland/src/loaders/LDtkLoader.ts:155](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/LDtkLoader.ts#L155)

Options for loading an LDtk project.

## Extends

- `BakedAssetLoaderOptions`

## Properties

### forceRuntime?

> `optional` **forceRuntime?**: `boolean`

Defined in: [packages/bake/src/types.ts:90](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/bake/src/types.ts#L90)

Generate this asset's derived data in the browser on every load
instead of loading a pre-baked sidecar. The runtime generator
becomes the canonical source — no sidecar probe, no devtime "no
baked sibling" warning, just a fresh generate on every load.

If you ask for the data (e.g. `normals: true`), you always get it.
`forceRuntime` chooses *where* the generation happens — browser vs
CI — it does not choose whether you get the data. The default path
still produces the data on every miss; this flag just commits to
"the browser is always where it's produced for this asset."

Use when runtime really is the right home for the generation:
procedurally varied content, throwaway prototypes, asset bundles
where shipping the sidecar isn't worth the bytes. Not a dev-
iteration knob — the default path (probe → generate on miss + warn
pointing at `flatland-bake`) already handles iteration.

Default `false`. Mirrors `SlugFontLoader.forceRuntime` — one flag
across every baked-asset loader in the codebase.

#### Inherited from

`BakedAssetLoaderOptions.forceRuntime`

***

### normals?

> `optional` **normals?**: `LDtkNormalsOption`

Defined in: [packages/three-flatland/src/loaders/LDtkLoader.ts:167](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/LDtkLoader.ts#L167)

Normal-map generation. When truthy, the loader synthesizes a
descriptor from each tileset's tile custom data (`tileDir`,
`tileCap*`, etc.), probes for a baked `.normal.png` sibling with
a matching descriptor hash, and falls back to an in-memory bake.

The resulting texture is attached to `TilesetData.normalMap`,
1:1 co-registered with the tileset image.

***

### texture?

> `optional` **texture?**: [`TexturePreset`](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/) \| [`TextureOptions`](/three-flatland/api/three-flatland/src/interfaces/textureoptions/)

Defined in: [packages/three-flatland/src/loaders/LDtkLoader.ts:157](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/LDtkLoader.ts#L157)

Texture preset or custom options. Overrides loader and global defaults.

# Light2DOptions

Defined in: [packages/three-flatland/src/lights/Light2D.ts:12](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L12)

Options for creating a Light2D.

## Properties

### angle?

> `optional` **angle?**: `number`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:26](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L26)

Cone angle for spot lights (radians, default: Math.PI/4)

***

### castsShadow?

> `optional` **castsShadow?**: `boolean`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:32](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L32)

Whether this light casts shadows (default: true)

***

### category?

> `optional` **category?**: `string`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:58](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L58)

Group tag used by Forward+ to bucket `castsShadow: false` fill
lights into independent per-tile quotas with per-bucket luminance
compensation. Lights sharing a category compete for that
category's 2-slot quota; different categories never evict each
other. Up to 4 distinct buckets (hashed from the string — 5th+
categories collide into earlier buckets, degrading gracefully).

Typical usage: `"slime"`, `"water"`, `"fire"` for cosmetic fills
with visually distinct identities. Hero lights (`castsShadow:
true`) ignore this field entirely. When omitted, the light
shares bucket 0 with every other un-tagged fill.

***

### color?

> `optional` **color?**: [`ColorRepresentation`](https://threejs.org/docs/)

Defined in: [packages/three-flatland/src/lights/Light2D.ts:16](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L16)

Light color

***

### decay?

> `optional` **decay?**: `number`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:30](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L30)

Decay exponent controlling attenuation curve shape (default: 2 for quadratic)

***

### direction?

> `optional` **direction?**: \[`number`, `number`\] \| [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

Defined in: [packages/three-flatland/src/lights/Light2D.ts:22](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L22)

Direction for directional/spot lights (normalized automatically)

***

### distance?

> `optional` **distance?**: `number`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:24](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L24)

Maximum light distance for point/spot lights (0 = no cutoff, default: 0)

***

### importance?

> `optional` **importance?**: `number`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:44](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L44)

Multiplicative bias applied to this light's tile-ranking score
during Forward+ tile assignment. Default `1.0` (neutral). Higher
values bias this light toward winning slot allocation when tiles
saturate. Typical use: set hero lights (torches, key lights) to
`10` so they resist eviction by dense cosmetic clusters.

Score ordering only — never appears in the fragment shader's
illuminance math, so it doesn't change how the light looks once
it's in a tile slot, only which lights claim the slots.

***

### intensity?

> `optional` **intensity?**: `number`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:18](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L18)

Light intensity (default: 1)

***

### penumbra?

> `optional` **penumbra?**: `number`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:28](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L28)

Penumbra for spot lights (0-1, default: 0)

***

### position?

> `optional` **position?**: \[`number`, `number`\] \| [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

Defined in: [packages/three-flatland/src/lights/Light2D.ts:20](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L20)

Position for point/spot lights

***

### type?

> `optional` **type?**: [`Light2DType`](/three-flatland/api/three-flatland/src/type-aliases/light2dtype/)

Defined in: [packages/three-flatland/src/lights/Light2D.ts:14](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L14)

Light type

# Light2DUniforms

Defined in: [packages/three-flatland/src/lights/Light2D.ts:64](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L64)

Uniform data structure for passing to shaders.

## Properties

### angle

> **angle**: `number`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:71](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L71)

***

### castsShadow

> **castsShadow**: `boolean`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:74](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L74)

***

### category

> **category**: `string` \| `undefined`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:76](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L76)

***

### color

> **color**: [`Color`](https://threejs.org/docs/#api/en/math/Color)

Defined in: [packages/three-flatland/src/lights/Light2D.ts:68](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L68)

***

### decay

> **decay**: `number`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:73](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L73)

***

### direction

> **direction**: [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

Defined in: [packages/three-flatland/src/lights/Light2D.ts:67](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L67)

***

### distance

> **distance**: `number`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:70](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L70)

***

### importance

> **importance**: `number`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:75](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L75)

***

### intensity

> **intensity**: `number`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:69](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L69)

***

### penumbra

> **penumbra**: `number`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:72](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L72)

***

### position

> **position**: [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

Defined in: [packages/three-flatland/src/lights/Light2D.ts:66](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L66)

***

### type

> **type**: [`Light2DType`](/three-flatland/api/three-flatland/src/type-aliases/light2dtype/)

Defined in: [packages/three-flatland/src/lights/Light2D.ts:65](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L65)

# LightEffectBuildContext

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:41](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L41)

Compile-time context — passed to buildLightFn (called once on attach).

## Type Parameters

### S

`S` *extends* [`EffectSchema`](/three-flatland/api/three-flatland/src/type-aliases/effectschema/) = [`EffectSchema`](/three-flatland/api/three-flatland/src/type-aliases/effectschema/)

## Properties

### constants

> **constants**: [`EffectConstants`](/three-flatland/api/three-flatland/src/type-aliases/effectconstants/)\<`S`\>

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:45](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L45)

Read-only constants from factory function fields.

***

### lightStore

> **lightStore**: `LightStore`

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:47](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L47)

The LightStore providing light data textures and count.

***

### sdfTexture

> **sdfTexture**: [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\> \| `null`

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:61](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L61)

Stable reference to the scene's SDF texture. Non-null only when the
effect's class declared `needsShadows = true` — in that case Flatland
eagerly allocates the SDFGenerator before calling buildLightFn so the
reference is bindable in TSL `texture()` calls. The texture's RTs are
1×1 placeholders at build time; the shadow pipeline system resizes
them on first frame and refreshes contents each subsequent frame,
without ever changing the reference.

Null when the active effect doesn't declare `needsShadows` — shaders
should compile out the shadow path in that case (JS-level `if`, not
a GPU branch).

***

### uniforms

> **uniforms**: \{ \[K in string \| number \| symbol\]: SchemaToNodeType\<S\[K\]\> \}

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:43](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L43)

TSL uniform nodes for each uniform schema field, keyed by field name.

***

### worldOffsetNode

> **worldOffsetNode**: [`UniformNode`](https://threejs.org/docs/)\<`"vec2"`, [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)\>

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:72](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L72)

Camera frustum bottom-left offset uniform node, updated each frame.

***

### worldSizeNode

> **worldSizeNode**: [`UniformNode`](https://threejs.org/docs/)\<`"vec2"`, [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)\>

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:68](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L68)

Camera frustum width/height uniform node, updated each frame from the
camera bounds. Effects that map between world and UV space
(shadow sampling, radiance cascades, any other screen-projected
sampler) consume this instead of rolling their own uniform.

# LightEffectRuntimeContext

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:76](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L76)

Runtime context — passed to init/update each frame.

## Properties

### camera

> **camera**: [`OrthographicCamera`](https://threejs.org/docs/#api/en/cameras/OrthographicCamera)

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:78](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L78)

***

### lights

> **lights**: readonly [`Light2D`](/three-flatland/api/three-flatland/src/classes/light2d/)[]

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:81](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L81)

***

### lightStore

> **lightStore**: `LightStore`

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:79](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L79)

***

### renderer

> **renderer**: [`WebGPURenderer`](https://threejs.org/docs/)

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:77](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L77)

***

### sdfGenerator

> **sdfGenerator**: `SDFGenerator` \| `null`

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:80](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L80)

***

### worldOffset

> **worldOffset**: [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:83](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L83)

***

### worldSize

> **worldSize**: [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:82](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L82)

# NormalRegion

Defined in: [packages/normals/src/descriptor.ts:125](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/normals/src/descriptor.ts#L125)

## Properties

### bump?

> `optional` **bump?**: [`NormalBump`](/three-flatland/api/three-flatland/src/type-aliases/normalbump/)

Defined in: [packages/normals/src/descriptor.ts:131](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/normals/src/descriptor.ts#L131)

Per-texel bump source. Default inherits from descriptor (`'alpha'`).

***

### direction?

> `optional` **direction?**: [`NormalDirection`](/three-flatland/api/three-flatland/src/type-aliases/normaldirection/)

Defined in: [packages/normals/src/descriptor.ts:133](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/normals/src/descriptor.ts#L133)

Base tilt direction. Default inherits from descriptor (`'flat'`).

***

### elevation?

> `optional` **elevation?**: `number`

Defined in: [packages/normals/src/descriptor.ts:150](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/normals/src/descriptor.ts#L150)

World-space elevation of the region in [0, 1], where 0 = ground
plane (floor) and 1 = top-of-wall (cap). Baked into the normal
atlas's B channel and consumed by the light pass to compute
per-fragment light direction (`L.z = lightHeight − elevation`).

Default inherits from the descriptor, which defaults to 0. Cap
regions typically set 1; tilted face regions typically set 0.5.

***

### h

> **h**: `number`

Defined in: [packages/normals/src/descriptor.ts:129](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/normals/src/descriptor.ts#L129)

***

### pitch?

> `optional` **pitch?**: `number`

Defined in: [packages/normals/src/descriptor.ts:138](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/normals/src/descriptor.ts#L138)

Tilt angle in radians from flat. Ignored when `direction === 'flat'`.
Default inherits from descriptor, which defaults to `Math.PI / 4`.

***

### strength?

> `optional` **strength?**: `number`

Defined in: [packages/normals/src/descriptor.ts:140](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/normals/src/descriptor.ts#L140)

Gradient strength multiplier for this region. Default 1.

***

### w

> **w**: `number`

Defined in: [packages/normals/src/descriptor.ts:128](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/normals/src/descriptor.ts#L128)

***

### x

> **x**: `number`

Defined in: [packages/normals/src/descriptor.ts:126](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/normals/src/descriptor.ts#L126)

***

### y

> **y**: `number`

Defined in: [packages/normals/src/descriptor.ts:127](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/normals/src/descriptor.ts#L127)

# NormalSourceDescriptor

Defined in: [packages/normals/src/descriptor.ts:153](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/normals/src/descriptor.ts#L153)

## Properties

### bump?

> `optional` **bump?**: [`NormalBump`](/three-flatland/api/three-flatland/src/type-aliases/normalbump/)

Defined in: [packages/normals/src/descriptor.ts:157](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/normals/src/descriptor.ts#L157)

Default bump source for regions that don't specify one. Default `'alpha'`.

***

### direction?

> `optional` **direction?**: [`NormalDirection`](/three-flatland/api/three-flatland/src/type-aliases/normaldirection/)

Defined in: [packages/normals/src/descriptor.ts:159](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/normals/src/descriptor.ts#L159)

Default tilt for regions that don't specify one. Default `'flat'`.

***

### elevation?

> `optional` **elevation?**: `number`

Defined in: [packages/normals/src/descriptor.ts:165](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/normals/src/descriptor.ts#L165)

Default elevation for regions that don't specify one. Default 0 (ground).

***

### pitch?

> `optional` **pitch?**: `number`

Defined in: [packages/normals/src/descriptor.ts:161](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/normals/src/descriptor.ts#L161)

Default tilt pitch in radians. Default `Math.PI / 4`.

***

### regions?

> `optional` **regions?**: [`NormalRegion`](/three-flatland/api/three-flatland/src/interfaces/normalregion/)[]

Defined in: [packages/normals/src/descriptor.ts:170](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/normals/src/descriptor.ts#L170)

Regions of the source texture. When omitted, the whole texture is
treated as a single region inheriting all descriptor defaults.

***

### strength?

> `optional` **strength?**: `number`

Defined in: [packages/normals/src/descriptor.ts:163](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/normals/src/descriptor.ts#L163)

Default gradient strength. Default `1`.

***

### version?

> `optional` **version?**: `1`

Defined in: [packages/normals/src/descriptor.ts:155](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/normals/src/descriptor.ts#L155)

Reserved for future schema evolution. Currently always `1`.

# ObjectLayerData

Defined in: [packages/three-flatland/src/tilemap/types.ts:106](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L106)

Object layer data (for entities, spawn points, etc.).

## Properties

### id

> **id**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:110](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L110)

Layer ID

***

### name

> **name**: `string`

Defined in: [packages/three-flatland/src/tilemap/types.ts:108](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L108)

Layer name

***

### objects

> **objects**: [`TileMapObject`](/three-flatland/api/three-flatland/src/interfaces/tilemapobject/)[]

Defined in: [packages/three-flatland/src/tilemap/types.ts:112](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L112)

Objects in this layer

***

### offset?

> `optional` **offset?**: `object`

Defined in: [packages/three-flatland/src/tilemap/types.ts:114](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L114)

Layer offset in pixels

#### x

> **x**: `number`

#### y

> **y**: `number`

***

### properties?

> `optional` **properties?**: `Record`\<`string`, `unknown`\>

Defined in: [packages/three-flatland/src/tilemap/types.ts:118](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L118)

Custom properties

***

### visible?

> `optional` **visible?**: `boolean`

Defined in: [packages/three-flatland/src/tilemap/types.ts:116](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L116)

Layer visibility

# OcclusionPassOptions

Defined in: [packages/three-flatland/src/lights/OcclusionPass.ts:30](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/OcclusionPass.ts#L30)

Optional construction knobs for OcclusionPass.

## Properties

### clearAlpha?

> `optional` **clearAlpha?**: `number`

Defined in: [packages/three-flatland/src/lights/OcclusionPass.ts:46](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/OcclusionPass.ts#L46)

Clear alpha. Default: 0.

***

### clearColor?

> `optional` **clearColor?**: [`ColorRepresentation`](https://threejs.org/docs/)

Defined in: [packages/three-flatland/src/lights/OcclusionPass.ts:44](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/OcclusionPass.ts#L44)

Clear color for the RT. Default: transparent black.

***

### linearFilter?

> `optional` **linearFilter?**: `boolean`

Defined in: [packages/three-flatland/src/lights/OcclusionPass.ts:56](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/OcclusionPass.ts#L56)

Use LinearFilter on the RT texture instead of the NearestFilter default.
Linear sampling smears alpha across silhouette edges (a texel just
outside the sprite interpolates to a fractional alpha), which inflates
the SDF seed by ~½ pixel in every direction and produces a faint halo
around every caster. NearestFilter keeps the alpha binary and pixel-
perfect. Flip to `true` only if a custom consumer explicitly wants the
anti-aliased silhouette.

***

### resolutionScale?

> `optional` **resolutionScale?**: `number`

Defined in: [packages/three-flatland/src/lights/OcclusionPass.ts:42](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/OcclusionPass.ts#L42)

Resolution multiplier relative to the main viewport (0 < x <= 1).
The SDF is derived from this RT, so lower values trade shadow fidelity
for shadow cost. Default: 0.5 (half resolution) — quarters fill cost
across every RT-sized pass while staying visually indistinguishable
from full-res on typical viewports (the separable blur masks the
coarser seed; NearestFilter keeps edges crisp). Set `1` for very
small / pixel-art viewports where the half-pixel silhouette
quantization reads as blocky, or drop to `0.25` on low-end mobile
where the shadow cost dominates and a blockier silhouette is acceptable.

# PassEffectContext

Defined in: [packages/three-flatland/src/pipeline/PassEffect.ts:27](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/PassEffect.ts#L27)

Context passed to a PassEffect's static buildPass method.

## Type Parameters

### S

`S` *extends* [`EffectSchema`](/three-flatland/api/three-flatland/src/type-aliases/effectschema/) = [`EffectSchema`](/three-flatland/api/three-flatland/src/type-aliases/effectschema/)

## Properties

### constants

> **constants**: [`EffectConstants`](/three-flatland/api/three-flatland/src/type-aliases/effectconstants/)\<`S`\>

Defined in: [packages/three-flatland/src/pipeline/PassEffect.ts:31](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/PassEffect.ts#L31)

Read-only constants from factory function fields.

***

### uniforms

> **uniforms**: \{ \[K in string \| number \| symbol\]: SchemaToNodeType\<S\[K\]\> \}

Defined in: [packages/three-flatland/src/pipeline/PassEffect.ts:29](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/PassEffect.ts#L29)

TSL uniform nodes for each uniform schema field, keyed by field name.

# PlayOptions

Defined in: [packages/three-flatland/src/animation/types.ts:38](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L38)

Options for playing an animation.

## Properties

### loop?

> `optional` **loop?**: `boolean`

Defined in: [packages/three-flatland/src/animation/types.ts:42](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L42)

Override loop setting

***

### onComplete?

> `optional` **onComplete?**: () => `void`

Defined in: [packages/three-flatland/src/animation/types.ts:46](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L46)

Callback when animation completes (non-looping)

#### Returns

`void`

***

### onEvent?

> `optional` **onEvent?**: (`event`, `frameIndex`) => `void`

Defined in: [packages/three-flatland/src/animation/types.ts:52](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L52)

Callback on frame event

#### Parameters

##### event

`string`

##### frameIndex

`number`

#### Returns

`void`

***

### onFrame?

> `optional` **onFrame?**: (`frameIndex`, `frame`) => `void`

Defined in: [packages/three-flatland/src/animation/types.ts:50](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L50)

Callback on frame change

#### Parameters

##### frameIndex

`number`

##### frame

[`AnimationFrame`](/three-flatland/api/three-flatland/src/interfaces/animationframe/)

#### Returns

`void`

***

### onLoop?

> `optional` **onLoop?**: (`loopCount`) => `void`

Defined in: [packages/three-flatland/src/animation/types.ts:48](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L48)

Callback on each loop

#### Parameters

##### loopCount

`number`

#### Returns

`void`

***

### speed?

> `optional` **speed?**: `number`

Defined in: [packages/three-flatland/src/animation/types.ts:44](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L44)

Override speed multiplier

***

### startFrame?

> `optional` **startFrame?**: `number`

Defined in: [packages/three-flatland/src/animation/types.ts:40](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/animation/types.ts#L40)

Start from a specific frame

# RenderStats

Defined in: [packages/three-flatland/src/pipeline/types.ts:57](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/types.ts#L57)

Sprite-domain render statistics.

Tracks counts the sprite pipeline owns: sprite instance count,
batch count, visible-after-culling count. Does NOT include
renderer-level stats (draw calls, triangles, GPU time) — those live
in the devtools producer (`@three-flatland/debug` subpath), which is
fully tree-shaken in prod builds and therefore doesn't pollute the
prod bundle with stats math. If you want renderer stats, subscribe
to the debug bus's `stats` feature.

## Properties

### batchCount

> **batchCount**: `number`

Defined in: [packages/three-flatland/src/pipeline/types.ts:61](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/types.ts#L61)

Number of batches created

***

### spriteCount

> **spriteCount**: `number`

Defined in: [packages/three-flatland/src/pipeline/types.ts:59](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/types.ts#L59)

Total sprites in the renderer

***

### visibleSprites

> **visibleSprites**: `number`

Defined in: [packages/three-flatland/src/pipeline/types.ts:63](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/types.ts#L63)

Number of visible sprites rendered

# Sprite2DMaterialOptions

Defined in: [packages/three-flatland/src/materials/Sprite2DMaterial.ts:19](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/Sprite2DMaterial.ts#L19)

## Properties

### alphaTest?

> `optional` **alphaTest?**: `number`

Defined in: [packages/three-flatland/src/materials/Sprite2DMaterial.ts:22](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/Sprite2DMaterial.ts#L22)

***

### colorTransform?

> `optional` **colorTransform?**: [`ColorTransformFn`](/three-flatland/api/three-flatland/src/type-aliases/colortransformfn/)

Defined in: [packages/three-flatland/src/materials/Sprite2DMaterial.ts:46](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/Sprite2DMaterial.ts#L46)

Color transform function for custom effects (e.g., lighting)

***

### effectsKey?

> `optional` **effectsKey?**: `string`

Defined in: [packages/three-flatland/src/materials/Sprite2DMaterial.ts:50](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/Sprite2DMaterial.ts#L50)

Effect configuration key for material caching/batching

***

### effectTier?

> `optional` **effectTier?**: `number`

Defined in: [packages/three-flatland/src/materials/Sprite2DMaterial.ts:44](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/Sprite2DMaterial.ts#L44)

Effect buffer tier size in floats.
Buffers are allocated in tiers: 0, 4, 8, 16.
Default is 8 (2 vec4 buffers), covering most effect combinations.
Set to 0 for fully effect-free materials (no effect buffer overhead).

***

### globalUniforms?

> `optional` **globalUniforms?**: [`GlobalUniforms`](/three-flatland/api/three-flatland/src/classes/globaluniforms/)

Defined in: [packages/three-flatland/src/materials/Sprite2DMaterial.ts:48](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/Sprite2DMaterial.ts#L48)

Global uniforms for auto-applying tint, time, etc.

***

### lit?

> `optional` **lit?**: `boolean`

Defined in: [packages/three-flatland/src/materials/Sprite2DMaterial.ts:28](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/Sprite2DMaterial.ts#L28)

Whether sprites using this material receive lighting. Part of the
material identity (batching) key — lit and unlit sprites can't share
a batch. Default `false`.

***

### map?

> `optional` **map?**: [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\>

Defined in: [packages/three-flatland/src/materials/Sprite2DMaterial.ts:20](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/Sprite2DMaterial.ts#L20)

***

### premultipliedAlpha?

> `optional` **premultipliedAlpha?**: `boolean`

Defined in: [packages/three-flatland/src/materials/Sprite2DMaterial.ts:37](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/Sprite2DMaterial.ts#L37)

Use premultiplied alpha blending.
When true, the shader outputs `vec4(rgb * alpha, alpha)` and uses
`CustomBlending` with `OneFactor` / `OneMinusSrcAlphaFactor`.
This eliminates `Discard()` calls, improving performance on WebGL
by preserving early-z optimization. Depth writes are disabled since
transparent pixels produce (0,0,0,0) which blends to nothing.

***

### transparent?

> `optional` **transparent?**: `boolean`

Defined in: [packages/three-flatland/src/materials/Sprite2DMaterial.ts:21](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/Sprite2DMaterial.ts#L21)

# Sprite2DOptions

Defined in: [packages/three-flatland/src/sprites/types.ts:35](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L35)

Options for creating a Sprite2D.

## Properties

### alpha?

> `optional` **alpha?**: `number`

Defined in: [packages/three-flatland/src/sprites/types.ts:45](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L45)

Opacity 0-1, default 1

***

### anchor?

> `optional` **anchor?**: \[`number`, `number`\] \| [`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

Defined in: [packages/three-flatland/src/sprites/types.ts:41](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L41)

Anchor/pivot point (0-1), default [0.5, 0.5] (center)

***

### castsShadow?

> `optional` **castsShadow?**: `boolean`

Defined in: [packages/three-flatland/src/sprites/types.ts:61](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L61)

Whether this sprite contributes to the shadow-caster occlusion pre-pass (default: false — opt in)

***

### flipX?

> `optional` **flipX?**: `boolean`

Defined in: [packages/three-flatland/src/sprites/types.ts:47](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L47)

Flip horizontally

***

### flipY?

> `optional` **flipY?**: `boolean`

Defined in: [packages/three-flatland/src/sprites/types.ts:49](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L49)

Flip vertically

***

### frame?

> `optional` **frame?**: [`SpriteFrame`](/three-flatland/api/three-flatland/src/interfaces/spriteframe/)

Defined in: [packages/three-flatland/src/sprites/types.ts:39](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L39)

Initial frame (optional, defaults to full texture)

***

### layer?

> `optional` **layer?**: `number`

Defined in: [packages/three-flatland/src/sprites/types.ts:51](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L51)

Render layer (for SpriteGroup)

***

### lit?

> `optional` **lit?**: `boolean`

Defined in: [packages/three-flatland/src/sprites/types.ts:57](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L57)

Whether this sprite receives lighting from Flatland's LightEffect (default: true)

***

### material?

> `optional` **material?**: [`Sprite2DMaterial`](/three-flatland/api/three-flatland/src/classes/sprite2dmaterial/)

Defined in: [packages/three-flatland/src/sprites/types.ts:73](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L73)

Custom material (sprites with same material instance batch together)

***

### pixelPerfect?

> `optional` **pixelPerfect?**: `boolean`

Defined in: [packages/three-flatland/src/sprites/types.ts:55](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L55)

Pixel-perfect rendering (snap to pixels)

***

### receiveShadows?

> `optional` **receiveShadows?**: `boolean`

Defined in: [packages/three-flatland/src/sprites/types.ts:59](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L59)

Whether this sprite receives shadows from the SDF shadow pipeline (default: true)

***

### shadowRadius?

> `optional` **shadowRadius?**: `number`

Defined in: [packages/three-flatland/src/sprites/types.ts:71](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L71)

Per-sprite occluder radius in world units. Consumed by shadow-
casting LightEffects (e.g., the SDF sphere-tracer uses it as the
self-silhouette escape distance). When omitted (default), the
batch layer auto-resolves to `max(scale.x, scale.y)` each frame,
which tracks scale changes and animation frame size swaps. Set
explicitly to override — useful when the visible body is tighter
than the quad bounds.

***

### texture?

> `optional` **texture?**: [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\>

Defined in: [packages/three-flatland/src/sprites/types.ts:37](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L37)

Texture to use (can be set later via texture property for R3F compatibility)

***

### tint?

> `optional` **tint?**: `string` \| `number` \| \[`number`, `number`, `number`\] \| [`Color`](https://threejs.org/docs/#api/en/math/Color)

Defined in: [packages/three-flatland/src/sprites/types.ts:43](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L43)

Tint color, default white. Accepts Color, hex string, hex number, or [r, g, b] array (0-1)

***

### zIndex?

> `optional` **zIndex?**: `number`

Defined in: [packages/three-flatland/src/sprites/types.ts:53](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L53)

Z-index within layer

# SpriteFrame

Defined in: [packages/three-flatland/src/sprites/types.ts:7](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L7)

Represents a single frame in a spritesheet atlas.

## Properties

### height

> **height**: `number`

Defined in: [packages/three-flatland/src/sprites/types.ts:17](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L17)

Height in atlas (normalized 0-1)

***

### name

> **name**: `string`

Defined in: [packages/three-flatland/src/sprites/types.ts:9](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L9)

Frame name/identifier

***

### pivot?

> `optional` **pivot?**: `object`

Defined in: [packages/three-flatland/src/sprites/types.ts:23](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L23)

Pivot point (0-1)

#### x

> **x**: `number`

#### y

> **y**: `number`

***

### rotated?

> `optional` **rotated?**: `boolean`

Defined in: [packages/three-flatland/src/sprites/types.ts:25](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L25)

Is frame rotated 90deg in atlas?

***

### sourceHeight

> **sourceHeight**: `number`

Defined in: [packages/three-flatland/src/sprites/types.ts:21](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L21)

Original frame height in pixels

***

### sourceWidth

> **sourceWidth**: `number`

Defined in: [packages/three-flatland/src/sprites/types.ts:19](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L19)

Original frame width in pixels

***

### trimmed?

> `optional` **trimmed?**: `boolean`

Defined in: [packages/three-flatland/src/sprites/types.ts:27](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L27)

Is frame trimmed?

***

### trimOffset?

> `optional` **trimOffset?**: `object`

Defined in: [packages/three-flatland/src/sprites/types.ts:29](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L29)

Trim offset if trimmed

#### height

> **height**: `number`

#### width

> **width**: `number`

#### x

> **x**: `number`

#### y

> **y**: `number`

***

### width

> **width**: `number`

Defined in: [packages/three-flatland/src/sprites/types.ts:15](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L15)

Width in atlas (normalized 0-1)

***

### x

> **x**: `number`

Defined in: [packages/three-flatland/src/sprites/types.ts:11](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L11)

X position in atlas (normalized 0-1)

***

### y

> **y**: `number`

Defined in: [packages/three-flatland/src/sprites/types.ts:13](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L13)

Y position in atlas (normalized 0-1)

# SpriteFrameRect

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:106](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L106)

## Properties

### h

> **h**: `number`

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:110](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L110)

***

### w

> **w**: `number`

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:109](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L109)

***

### x

> **x**: `number`

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:107](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L107)

***

### y

> **y**: `number`

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:108](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L108)

# SpriteGroupOptions

Defined in: [packages/three-flatland/src/pipeline/types.ts:69](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/types.ts#L69)

Options for SpriteGroup.

## Properties

### autoInvalidateTransforms?

> `optional` **autoInvalidateTransforms?**: `boolean`

Defined in: [packages/three-flatland/src/pipeline/types.ts:80](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/types.ts#L80)

Automatically invalidate transforms every frame (default: true).
 Enable for games where sprites move frequently.
 Disable for static UIs and call invalidateTransforms() manually.
 Note: Property changes (tint, alpha, etc.) don't need this - they write directly to buffers.

***

### autoSort?

> `optional` **autoSort?**: `boolean`

Defined in: [packages/three-flatland/src/pipeline/types.ts:73](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/types.ts#L73)

Enable automatic sorting (default: true)

***

### frustumCulling?

> `optional` **frustumCulling?**: `boolean`

Defined in: [packages/three-flatland/src/pipeline/types.ts:75](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/types.ts#L75)

Enable frustum culling (default: true)

***

### maxBatchSize?

> `optional` **maxBatchSize?**: `number`

Defined in: [packages/three-flatland/src/pipeline/types.ts:71](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/types.ts#L71)

Maximum sprites per batch (default: 10000)

# SpriteSheet

Defined in: [packages/three-flatland/src/sprites/types.ts:79](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L79)

Spritesheet data structure.

## Properties

### frames

> **frames**: `Map`\<`string`, [`SpriteFrame`](/three-flatland/api/three-flatland/src/interfaces/spriteframe/)\>

Defined in: [packages/three-flatland/src/sprites/types.ts:83](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L83)

Map of frame name to frame data

***

### height

> **height**: `number`

Defined in: [packages/three-flatland/src/sprites/types.ts:87](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L87)

Atlas height in pixels

***

### normalMap?

> `optional` **normalMap?**: [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\>

Defined in: [packages/three-flatland/src/sprites/types.ts:95](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L95)

Tangent-space normal map, 1:1 co-registered with `texture`.

Populated when the loader is given `normals: true` (or a
descriptor). Binds to `NormalMapProvider.normalMap` on a lit
sprite.

***

### texture

> **texture**: [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)

Defined in: [packages/three-flatland/src/sprites/types.ts:81](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L81)

The texture atlas

***

### width

> **width**: `number`

Defined in: [packages/three-flatland/src/sprites/types.ts:85](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L85)

Atlas width in pixels

## Methods

### getFrame()

> **getFrame**(`name`): [`SpriteFrame`](/three-flatland/api/three-flatland/src/interfaces/spriteframe/)

Defined in: [packages/three-flatland/src/sprites/types.ts:97](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L97)

Get a frame by name

#### Parameters

##### name

`string`

#### Returns

[`SpriteFrame`](/three-flatland/api/three-flatland/src/interfaces/spriteframe/)

***

### getFrameNames()

> **getFrameNames**(): `string`[]

Defined in: [packages/three-flatland/src/sprites/types.ts:99](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L99)

Get all frame names

#### Returns

`string`[]

# SpriteSheetJSONArray

Defined in: [packages/three-flatland/src/sprites/types.ts:126](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L126)

JSON Array format.

## Properties

### frames

> **frames**: `object`[]

Defined in: [packages/three-flatland/src/sprites/types.ts:127](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L127)

#### filename

> **filename**: `string`

#### frame

> **frame**: `object`

##### frame.h

> **h**: `number`

##### frame.w

> **w**: `number`

##### frame.x

> **x**: `number`

##### frame.y

> **y**: `number`

#### pivot?

> `optional` **pivot?**: `object`

##### pivot.x

> **x**: `number`

##### pivot.y

> **y**: `number`

#### rotated

> **rotated**: `boolean`

#### sourceSize

> **sourceSize**: `object`

##### sourceSize.h

> **h**: `number`

##### sourceSize.w

> **w**: `number`

#### spriteSourceSize

> **spriteSourceSize**: `object`

##### spriteSourceSize.h

> **h**: `number`

##### spriteSourceSize.w

> **w**: `number`

##### spriteSourceSize.x

> **x**: `number`

##### spriteSourceSize.y

> **y**: `number`

#### trimmed

> **trimmed**: `boolean`

***

### meta

> **meta**: `object`

Defined in: [packages/three-flatland/src/sprites/types.ts:136](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L136)

#### image

> **image**: `string`

#### scale

> **scale**: `string`

#### size

> **size**: `object`

##### size.h

> **h**: `number`

##### size.w

> **w**: `number`

# SpriteSheetJSONHash

Defined in: [packages/three-flatland/src/sprites/types.ts:105](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L105)

JSON Hash format (TexturePacker default).

## Properties

### frames

> **frames**: `object`

Defined in: [packages/three-flatland/src/sprites/types.ts:106](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L106)

#### Index Signature

\[`name`: `string`\]: `object`

***

### meta

> **meta**: `object`

Defined in: [packages/three-flatland/src/sprites/types.ts:116](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/sprites/types.ts#L116)

#### image

> **image**: `string`

#### scale

> **scale**: `string`

#### size

> **size**: `object`

##### size.h

> **h**: `number`

##### size.w

> **w**: `number`

# SpriteSheetLoaderOptions

Defined in: [packages/three-flatland/src/loaders/SpriteSheetLoader.ts:26](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/SpriteSheetLoader.ts#L26)

Options for loading a spritesheet.

## Extends

- `BakedAssetLoaderOptions`

## Properties

### forceRuntime?

> `optional` **forceRuntime?**: `boolean`

Defined in: [packages/bake/src/types.ts:90](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/bake/src/types.ts#L90)

Generate this asset's derived data in the browser on every load
instead of loading a pre-baked sidecar. The runtime generator
becomes the canonical source — no sidecar probe, no devtime "no
baked sibling" warning, just a fresh generate on every load.

If you ask for the data (e.g. `normals: true`), you always get it.
`forceRuntime` chooses *where* the generation happens — browser vs
CI — it does not choose whether you get the data. The default path
still produces the data on every miss; this flag just commits to
"the browser is always where it's produced for this asset."

Use when runtime really is the right home for the generation:
procedurally varied content, throwaway prototypes, asset bundles
where shipping the sidecar isn't worth the bytes. Not a dev-
iteration knob — the default path (probe → generate on miss + warn
pointing at `flatland-bake`) already handles iteration.

Default `false`. Mirrors `SlugFontLoader.forceRuntime` — one flag
across every baked-asset loader in the codebase.

#### Inherited from

`BakedAssetLoaderOptions.forceRuntime`

***

### normals?

> `optional` **normals?**: `SpriteSheetNormalsOption`

Defined in: [packages/three-flatland/src/loaders/SpriteSheetLoader.ts:38](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/SpriteSheetLoader.ts#L38)

Normal-map generation. When truthy, the loader synthesizes one
region per sprite frame (pixel rects from the sheet JSON), probes
for a baked `<sheet-image>.normal.png` sibling with a matching
descriptor hash, and falls back to an in-memory bake.

The resulting texture is attached to `SpriteSheet.normalMap`,
1:1 co-registered with the atlas.

***

### texture?

> `optional` **texture?**: [`TexturePreset`](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/) \| [`TextureOptions`](/three-flatland/api/three-flatland/src/interfaces/textureoptions/)

Defined in: [packages/three-flatland/src/loaders/SpriteSheetLoader.ts:28](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/SpriteSheetLoader.ts#L28)

Texture preset or custom options. Overrides loader and global defaults.

# TextureLoaderOptions

Defined in: [packages/three-flatland/src/loaders/TextureLoader.ts:12](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/TextureLoader.ts#L12)

Options for loading a texture.

## Properties

### texture?

> `optional` **texture?**: [`TexturePreset`](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/) \| [`TextureOptions`](/three-flatland/api/three-flatland/src/interfaces/textureoptions/)

Defined in: [packages/three-flatland/src/loaders/TextureLoader.ts:14](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/TextureLoader.ts#L14)

Texture preset or custom options. Overrides loader and global defaults.

# TextureOptions

Defined in: [packages/three-flatland/src/loaders/texturePresets.ts:8](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/texturePresets.ts#L8)

Custom texture options for full control

## Properties

### colorSpace?

> `optional` **colorSpace?**: `string`

Defined in: [packages/three-flatland/src/loaders/texturePresets.ts:14](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/texturePresets.ts#L14)

***

### generateMipmaps?

> `optional` **generateMipmaps?**: `boolean`

Defined in: [packages/three-flatland/src/loaders/texturePresets.ts:13](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/texturePresets.ts#L13)

***

### magFilter?

> `optional` **magFilter?**: `1003` \| `1006`

Defined in: [packages/three-flatland/src/loaders/texturePresets.ts:10](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/texturePresets.ts#L10)

***

### minFilter?

> `optional` **minFilter?**: `1003` \| `1006`

Defined in: [packages/three-flatland/src/loaders/texturePresets.ts:9](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/texturePresets.ts#L9)

***

### wrapS?

> `optional` **wrapS?**: [`Wrapping`](https://threejs.org/docs/)

Defined in: [packages/three-flatland/src/loaders/texturePresets.ts:11](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/texturePresets.ts#L11)

***

### wrapT?

> `optional` **wrapT?**: [`Wrapping`](https://threejs.org/docs/)

Defined in: [packages/three-flatland/src/loaders/texturePresets.ts:12](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/texturePresets.ts#L12)

# TileAnimationFrame

Defined in: [packages/three-flatland/src/tilemap/types.ts:22](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L22)

Animation frame for animated tiles.

## Properties

### duration

> **duration**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:26](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L26)

Duration in milliseconds

***

### tileId

> **tileId**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:24](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L24)

Tile ID to display

# TileDefinition

Defined in: [packages/three-flatland/src/tilemap/types.ts:6](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L6)

A single tile definition in a tileset.

## Properties

### animation?

> `optional` **animation?**: [`TileAnimationFrame`](/three-flatland/api/three-flatland/src/interfaces/tileanimationframe/)[]

Defined in: [packages/three-flatland/src/tilemap/types.ts:16](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L16)

Animation frames (if animated)

***

### collision?

> `optional` **collision?**: [`CollisionShape`](/three-flatland/api/three-flatland/src/type-aliases/collisionshape/)[]

Defined in: [packages/three-flatland/src/tilemap/types.ts:12](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L12)

Collision shapes (if any)

***

### id

> **id**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:8](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L8)

Global tile ID (GID)

***

### properties?

> `optional` **properties?**: `Record`\<`string`, `unknown`\>

Defined in: [packages/three-flatland/src/tilemap/types.ts:14](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L14)

Custom properties

***

### uv

> **uv**: `object`

Defined in: [packages/three-flatland/src/tilemap/types.ts:10](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L10)

UV coordinates in atlas (normalized 0-1)

#### height

> **height**: `number`

#### width

> **width**: `number`

#### x

> **x**: `number`

#### y

> **y**: `number`

# TiledLoaderOptions

Defined in: [packages/three-flatland/src/loaders/TiledLoader.ts:123](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/TiledLoader.ts#L123)

Options for loading a Tiled map.

## Extends

- `BakedAssetLoaderOptions`

## Properties

### forceRuntime?

> `optional` **forceRuntime?**: `boolean`

Defined in: [packages/bake/src/types.ts:90](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/bake/src/types.ts#L90)

Generate this asset's derived data in the browser on every load
instead of loading a pre-baked sidecar. The runtime generator
becomes the canonical source — no sidecar probe, no devtime "no
baked sibling" warning, just a fresh generate on every load.

If you ask for the data (e.g. `normals: true`), you always get it.
`forceRuntime` chooses *where* the generation happens — browser vs
CI — it does not choose whether you get the data. The default path
still produces the data on every miss; this flag just commits to
"the browser is always where it's produced for this asset."

Use when runtime really is the right home for the generation:
procedurally varied content, throwaway prototypes, asset bundles
where shipping the sidecar isn't worth the bytes. Not a dev-
iteration knob — the default path (probe → generate on miss + warn
pointing at `flatland-bake`) already handles iteration.

Default `false`. Mirrors `SlugFontLoader.forceRuntime` — one flag
across every baked-asset loader in the codebase.

#### Inherited from

`BakedAssetLoaderOptions.forceRuntime`

***

### normals?

> `optional` **normals?**: `TiledNormalsOption`

Defined in: [packages/three-flatland/src/loaders/TiledLoader.ts:132](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/TiledLoader.ts#L132)

Normal-map generation. Same semantics as
`LDtkLoaderOptions.normals`. Reads `tileDir` / `tileCap*` from
each tile's properties. Each baked normal map is attached to its
`TilesetData.normalMap`.

***

### texture?

> `optional` **texture?**: [`TexturePreset`](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/) \| [`TextureOptions`](/three-flatland/api/three-flatland/src/interfaces/textureoptions/)

Defined in: [packages/three-flatland/src/loaders/TiledLoader.ts:125](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/TiledLoader.ts#L125)

Texture preset or custom options. Overrides loader and global defaults.

# TileInstance

Defined in: [packages/three-flatland/src/tilemap/types.ts:210](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L210)

Tile instance data for rendering.

## Properties

### flipD

> **flipD**: `boolean`

Defined in: [packages/three-flatland/src/tilemap/types.ts:220](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L220)

***

### flipH

> **flipH**: `boolean`

Defined in: [packages/three-flatland/src/tilemap/types.ts:218](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L218)

Flip flags (horizontal, vertical, diagonal)

***

### flipV

> **flipV**: `boolean`

Defined in: [packages/three-flatland/src/tilemap/types.ts:219](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L219)

***

### gid

> **gid**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:216](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L216)

Tile GID

***

### x

> **x**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:212](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L212)

World X position

***

### y

> **y**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:214](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L214)

World Y position

# TileLayerData

Defined in: [packages/three-flatland/src/tilemap/types.ts:78](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L78)

Tile layer data.

## Properties

### data

> **data**: `Uint32Array`

Defined in: [packages/three-flatland/src/tilemap/types.ts:88](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L88)

Tile data (GIDs, 0 = empty)

***

### height

> **height**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:86](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L86)

Layer height in tiles

***

### id

> **id**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:82](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L82)

Layer ID

***

### name

> **name**: `string`

Defined in: [packages/three-flatland/src/tilemap/types.ts:80](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L80)

Layer name

***

### offset?

> `optional` **offset?**: `object`

Defined in: [packages/three-flatland/src/tilemap/types.ts:90](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L90)

Layer offset in pixels

#### x

> **x**: `number`

#### y

> **y**: `number`

***

### opacity?

> `optional` **opacity?**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:92](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L92)

Layer opacity (0-1)

***

### parallax?

> `optional` **parallax?**: `object`

Defined in: [packages/three-flatland/src/tilemap/types.ts:96](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L96)

Parallax factor

#### x

> **x**: `number`

#### y

> **y**: `number`

***

### properties?

> `optional` **properties?**: `Record`\<`string`, `unknown`\>

Defined in: [packages/three-flatland/src/tilemap/types.ts:100](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L100)

Custom properties

***

### tint?

> `optional` **tint?**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:98](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L98)

Tint color

***

### visible?

> `optional` **visible?**: `boolean`

Defined in: [packages/three-flatland/src/tilemap/types.ts:94](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L94)

Layer visibility

***

### width

> **width**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:84](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L84)

Layer width in tiles

# TileLayerOptions

Defined in: [packages/three-flatland/src/tilemap/types.ts:226](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L226)

TileLayer options.

## Properties

### data

> **data**: [`TileLayerData`](/three-flatland/api/three-flatland/src/interfaces/tilelayerdata/)

Defined in: [packages/three-flatland/src/tilemap/types.ts:228](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L228)

Layer data

***

### tileHeight

> **tileHeight**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:232](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L232)

Tile height in pixels

***

### tileWidth

> **tileWidth**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:230](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L230)

Tile width in pixels

# TileMap2DOptions

Defined in: [packages/three-flatland/src/tilemap/types.ts:186](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L186)

TileMap2D options.

## Properties

### baseLayer?

> `optional` **baseLayer?**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:196](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L196)

Render layer for all tile layers (default: 0)

***

### chunkSize?

> `optional` **chunkSize?**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:190](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L190)

Chunk size in tiles for frustum culling (default: 256)

***

### data?

> `optional` **data?**: [`TileMapData`](/three-flatland/api/three-flatland/src/interfaces/tilemapdata/)

Defined in: [packages/three-flatland/src/tilemap/types.ts:188](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L188)

Tilemap data

***

### enableCollision?

> `optional` **enableCollision?**: `boolean`

Defined in: [packages/three-flatland/src/tilemap/types.ts:192](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L192)

Enable collision data extraction (default: true)

***

### pixelPerfect?

> `optional` **pixelPerfect?**: `boolean`

Defined in: [packages/three-flatland/src/tilemap/types.ts:194](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L194)

Pixel perfect rendering (default: false)

# TileMapData

Defined in: [packages/three-flatland/src/tilemap/types.ts:156](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L156)

Complete tilemap data (format-agnostic).

## Properties

### backgroundColor?

> `optional` **backgroundColor?**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:172](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L172)

Background color

***

### height

> **height**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:160](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L160)

Map height in tiles

***

### infinite

> **infinite**: `boolean`

Defined in: [packages/three-flatland/src/tilemap/types.ts:170](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L170)

Infinite map flag

***

### objectLayers

> **objectLayers**: [`ObjectLayerData`](/three-flatland/api/three-flatland/src/interfaces/objectlayerdata/)[]

Defined in: [packages/three-flatland/src/tilemap/types.ts:178](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L178)

Object layers

***

### orientation

> **orientation**: `"orthogonal"` \| `"isometric"` \| `"staggered"` \| `"hexagonal"`

Defined in: [packages/three-flatland/src/tilemap/types.ts:166](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L166)

Map orientation

***

### properties?

> `optional` **properties?**: `Record`\<`string`, `unknown`\>

Defined in: [packages/three-flatland/src/tilemap/types.ts:180](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L180)

Custom properties

***

### renderOrder

> **renderOrder**: `"right-down"` \| `"right-up"` \| `"left-down"` \| `"left-up"`

Defined in: [packages/three-flatland/src/tilemap/types.ts:168](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L168)

Render order

***

### tileHeight

> **tileHeight**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:164](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L164)

Tile height in pixels

***

### tileLayers

> **tileLayers**: [`TileLayerData`](/three-flatland/api/three-flatland/src/interfaces/tilelayerdata/)[]

Defined in: [packages/three-flatland/src/tilemap/types.ts:176](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L176)

Tile layers

***

### tilesets

> **tilesets**: [`TilesetData`](/three-flatland/api/three-flatland/src/interfaces/tilesetdata/)[]

Defined in: [packages/three-flatland/src/tilemap/types.ts:174](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L174)

Tilesets used

***

### tileWidth

> **tileWidth**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:162](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L162)

Tile width in pixels

***

### width

> **width**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:158](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L158)

Map width in tiles

# TileMapObject

Defined in: [packages/three-flatland/src/tilemap/types.ts:124](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L124)

A map object (entity, trigger, etc.).

## Properties

### ellipse?

> `optional` **ellipse?**: `boolean`

Defined in: [packages/three-flatland/src/tilemap/types.ts:146](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L146)

Ellipse flag

***

### gid?

> `optional` **gid?**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:140](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L140)

Tile GID (if tile object)

***

### height

> **height**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:136](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L136)

***

### id

> **id**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:126](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L126)

Object ID

***

### name

> **name**: `string`

Defined in: [packages/three-flatland/src/tilemap/types.ts:128](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L128)

Object name

***

### point?

> `optional` **point?**: `boolean`

Defined in: [packages/three-flatland/src/tilemap/types.ts:148](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L148)

Point flag

***

### polygon?

> `optional` **polygon?**: `object`[]

Defined in: [packages/three-flatland/src/tilemap/types.ts:142](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L142)

Polygon points (if polygon)

#### x

> **x**: `number`

#### y

> **y**: `number`

***

### polyline?

> `optional` **polyline?**: `object`[]

Defined in: [packages/three-flatland/src/tilemap/types.ts:144](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L144)

Polyline points (if polyline)

#### x

> **x**: `number`

#### y

> **y**: `number`

***

### properties?

> `optional` **properties?**: `Record`\<`string`, `unknown`\>

Defined in: [packages/three-flatland/src/tilemap/types.ts:150](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L150)

Custom properties

***

### rotation?

> `optional` **rotation?**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:138](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L138)

Rotation in degrees

***

### type

> **type**: `string`

Defined in: [packages/three-flatland/src/tilemap/types.ts:130](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L130)

Object type/class

***

### width

> **width**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:135](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L135)

Size in pixels

***

### x

> **x**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:132](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L132)

Position in pixels

***

### y

> **y**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:133](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L133)

# TileNormalCustomData

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:36](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L36)

Shape the LDtk / Tiled loader extracts from per-tile custom data
when synthesizing regions. Authors populate these in the map
editor's tile-properties panel.

All fields optional — an untagged tile emits a single flat region
for its cell. Cap thickness values are in pixels; legacy `*Px`
aliases are accepted for back-compat and map to the unsuffixed
canonical fields.

## Properties

### tileBump?

> `optional` **tileBump?**: [`NormalBump`](/three-flatland/api/three-flatland/src/type-aliases/normalbump/)

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:44](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L44)

Bump source override for the face region.

***

### tileCap?

> `optional` **tileCap?**: `number`

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:68](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L68)

Shorthand — when no per-edge field is set, treated as `tileCapTop`.

***

### tileCapBottom?

> `optional` **tileCapBottom?**: `number`

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:62](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L62)

Cap thickness from the bottom edge in pixels.

***

### tileCapBottomLeft?

> `optional` **tileCapBottomLeft?**: `number`

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:80](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L80)

N×N square flat cap at the bottom-left corner.

***

### ~~tileCapBottomPx?~~

> `optional` **tileCapBottomPx?**: `number`

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:88](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L88)

:::caution[Deprecated]
alias of `tileCapBottom`.
:::

***

### tileCapBottomRight?

> `optional` **tileCapBottomRight?**: `number`

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:82](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L82)

N×N square flat cap at the bottom-right corner.

***

### tileCapLeft?

> `optional` **tileCapLeft?**: `number`

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:64](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L64)

Cap thickness from the left edge in pixels.

***

### ~~tileCapLeftPx?~~

> `optional` **tileCapLeftPx?**: `number`

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:90](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L90)

:::caution[Deprecated]
alias of `tileCapLeft`.
:::

***

### ~~tileCapPx?~~

> `optional` **tileCapPx?**: `number`

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:84](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L84)

:::caution[Deprecated]
alias of `tileCap`.
:::

***

### tileCapRight?

> `optional` **tileCapRight?**: `number`

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:66](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L66)

Cap thickness from the right edge in pixels.

***

### ~~tileCapRightPx?~~

> `optional` **tileCapRightPx?**: `number`

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:92](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L92)

:::caution[Deprecated]
alias of `tileCapRight`.
:::

***

### tileCapTop?

> `optional` **tileCapTop?**: `number`

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:60](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L60)

Cap thickness from the top edge in pixels.

***

### tileCapTopLeft?

> `optional` **tileCapTopLeft?**: `number`

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:76](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L76)

Corner cap — N×N square flat cap at the top-left corner of the cell.
Use when the tile art shows a small flat patch at that corner with
the wall face wrapping around it in an L-shape (outer walls facing
outward). Composes with edge caps — union of all cap rects is cap,
complement is face.

***

### ~~tileCapTopPx?~~

> `optional` **tileCapTopPx?**: `number`

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:86](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L86)

:::caution[Deprecated]
alias of `tileCapTop`.
:::

***

### tileCapTopRight?

> `optional` **tileCapTopRight?**: `number`

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:78](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L78)

N×N square flat cap at the top-right corner.

***

### tileDir?

> `optional` **tileDir?**: [`NormalDirection`](/three-flatland/api/three-flatland/src/type-aliases/normaldirection/)

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:38](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L38)

Screen-space direction the face tilts. See `NormalDirection`.

***

### tileDirection?

> `optional` **tileDirection?**: [`NormalDirection`](/three-flatland/api/three-flatland/src/type-aliases/normaldirection/)

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:40](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L40)

Alias of `tileDir`.

***

### tileElevation?

> `optional` **tileElevation?**: `number`

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:58](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L58)

Elevation of the tile's primary surface in [0, 1] (0 = ground
plane, 1 = top-of-wall):

  - Tiles with `tileDir` (wall faces): applies to the face region.
    Caps always bake at 1.0 regardless. Default 0.5 (midway up).
  - Flat tiles (no `tileDir` or `tileDir: 'flat'`): applies to the
    whole cell. Use 1.0 for "all-cap" tiles (wall top viewed
    dead-on, roof patches, pillar caps). Unset → descriptor default,
    which defaults to 0 (ground plane = floor).

***

### tilePitch?

> `optional` **tilePitch?**: `number`

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:42](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L42)

Tilt angle override in radians. Inherits descriptor pitch when absent.

***

### tileStrength?

> `optional` **tileStrength?**: `number`

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:46](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L46)

Gradient strength override for the face region.

# TilesetCell

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:135](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L135)

## Properties

### h

> **h**: `number`

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:143](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L143)

Cell height in pixels.

***

### meta?

> `optional` **meta?**: [`TileNormalCustomData`](/three-flatland/api/three-flatland/src/interfaces/tilenormalcustomdata/)

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:145](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L145)

Optional per-tile custom data. Untagged cells emit a single flat region.

***

### w

> **w**: `number`

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:141](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L141)

Cell width in pixels.

***

### x

> **x**: `number`

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:137](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L137)

Pixel x of the top-left of this cell within the tileset atlas.

***

### y

> **y**: `number`

Defined in: [packages/three-flatland/src/loaders/normalDescriptor.ts:139](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/normalDescriptor.ts#L139)

Pixel y of the top-left of this cell within the tileset atlas.

# TilesetData

Defined in: [packages/three-flatland/src/tilemap/types.ts:41](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L41)

Tileset data structure.

## Properties

### columns

> **columns**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:55](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L55)

Number of columns

***

### firstGid

> **firstGid**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:45](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L45)

First GID for this tileset

***

### imageHeight

> **imageHeight**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:53](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L53)

Tileset image height

***

### imageWidth

> **imageWidth**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:51](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L51)

Tileset image width

***

### margin?

> `optional` **margin?**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:61](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L61)

Margin around tiles

***

### name

> **name**: `string`

Defined in: [packages/three-flatland/src/tilemap/types.ts:43](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L43)

Tileset name

***

### normalMap?

> `optional` **normalMap?**: [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\>

Defined in: [packages/three-flatland/src/tilemap/types.ts:72](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L72)

Tangent-space normal map, 1:1 co-registered with `texture`.

Populated when the loader is given `normals: true` (or a descriptor).
Binds to `NormalMapProvider.normalMap` on a lit tilemap.

***

### spacing?

> `optional` **spacing?**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:59](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L59)

Spacing between tiles

***

### texture?

> `optional` **texture?**: [`Texture`](https://threejs.org/docs/#api/en/textures/Texture)\<`unknown`\>

Defined in: [packages/three-flatland/src/tilemap/types.ts:65](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L65)

Texture atlas

***

### tileCount

> **tileCount**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:57](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L57)

Number of tiles

***

### tileHeight

> **tileHeight**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:49](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L49)

Tile height in pixels

***

### tiles

> **tiles**: `Map`\<`number`, [`TileDefinition`](/three-flatland/api/three-flatland/src/interfaces/tiledefinition/)\>

Defined in: [packages/three-flatland/src/tilemap/types.ts:63](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L63)

Tile definitions

***

### tileWidth

> **tileWidth**: `number`

Defined in: [packages/three-flatland/src/tilemap/types.ts:47](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L47)

Tile width in pixels

# three-flatland/src/react

## Type Aliases

- [EffectElement](/three-flatland/api/three-flatland/src/react/type-aliases/effectelement/)
- [LightEffectElement](/three-flatland/api/three-flatland/src/react/type-aliases/lighteffectelement/)

## Functions

- [attachEffect](/three-flatland/api/three-flatland/src/react/functions/attacheffect/)
- [attachLighting](/three-flatland/api/three-flatland/src/react/functions/attachlighting/)

# attachEffect

> **attachEffect**\<`T`\>(`parent`, `self`): () => `void`

Defined in: [packages/three-flatland/src/react/attach.ts:26](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/react/attach.ts#L26)

R3F attach helper for MaterialEffect instances.
Use as the `attach` prop when adding effects as children of a sprite2D or tileMap2D:

## Type Parameters

### T

`T` *extends* [`MaterialEffect`](/three-flatland/api/three-flatland/src/classes/materialeffect/)

## Parameters

### parent

[`Sprite2D`](/three-flatland/api/three-flatland/src/classes/sprite2d/) \| [`TileMap2D`](/three-flatland/api/three-flatland/src/classes/tilemap2d/)

### self

`T`

## Returns

() => `void`

## Example

```tsx
import { attachEffect } from 'three-flatland/react'

<sprite2D texture={tex}>
  <dissolveEffect attach={attachEffect} />
</sprite2D>

<tileMap2D data={mapData}>
  <autoNormalProvider attach={attachEffect} />
</tileMap2D>
```

# attachLighting

> **attachLighting**\<`T`\>(`parent`, `self`): () => `void`

Defined in: [packages/three-flatland/src/react/attach.ts:44](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/react/attach.ts#L44)

R3F attach helper for LightEffect instances.
Use as the `attach` prop when adding a light effect as a child of a flatland:

## Type Parameters

### T

`T` *extends* [`LightEffect`](/three-flatland/api/three-flatland/src/classes/lighteffect/)

## Parameters

### parent

[`Flatland`](/three-flatland/api/three-flatland/src/classes/flatland/)

### self

`T`

## Returns

() => `void`

## Example

```tsx
import { attachLighting } from 'three-flatland/react'

<flatland ref={flatlandRef} viewSize={400}>
  <defaultLightEffect attach={attachLighting} />
  <light2D lightType="point" position={[50, 50, 0]} color="orange" />
</flatland>
```

# EffectElement

> **EffectElement**\<`T`\> = `ThreeElement`\<`T`\> & `T` *extends* [`MaterialEffectClass`](/three-flatland/api/three-flatland/src/type-aliases/materialeffectclass/)\<infer S\> ? `Partial`\<[`EffectValues`](/three-flatland/api/three-flatland/src/type-aliases/effectvalues/)\<`S`\>\> : `Record`\<`string`, `never`\>

Defined in: [packages/three-flatland/src/react/types.ts:33](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/react/types.ts#L33)

JSX element type for a MaterialEffect with schema-derived props.

`ThreeElement<T>` can't always resolve dynamic properties defined via
`Object.defineProperty` in `createMaterialEffect`. This helper explicitly
surfaces the schema fields so they appear in VS Code autocomplete.

## Type Parameters

### T

`T` *extends* [`MaterialEffectClass`](/three-flatland/api/three-flatland/src/type-aliases/materialeffectclass/)\<`any`\>

## Example

```tsx
declare module '@react-three/fiber' {
  interface ThreeElements {
    dissolveEffect: EffectElement<typeof DissolveEffect>
  }
}

// Now `progress` shows up as a valid prop:
<dissolveEffect attach={attachEffect} progress={0.5} />
```

# LightEffectElement

> **LightEffectElement**\<`T`\> = `ThreeElement`\<`T`\> & `T` *extends* [`LightEffectClass`](/three-flatland/api/three-flatland/src/type-aliases/lighteffectclass/)\<infer S\> ? `Partial`\<[`EffectValues`](/three-flatland/api/three-flatland/src/type-aliases/effectvalues/)\<`S`\>\> : `Record`\<`string`, `never`\>

Defined in: [packages/three-flatland/src/react/types.ts:41](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/react/types.ts#L41)

JSX element type for a LightEffect with schema-derived props.
Surfaces uniform (settable) schema fields as JSX props.

## Type Parameters

### T

`T` *extends* [`LightEffectClass`](/three-flatland/api/three-flatland/src/type-aliases/lighteffectclass/)\<`any`\>

# BlendMode

> **BlendMode** = `"normal"` \| `"additive"` \| `"multiply"` \| `"screen"`

Defined in: [packages/three-flatland/src/pipeline/types.ts:6](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/types.ts#L6)

Blend mode for rendering layers.

# ChannelName

> **ChannelName** = keyof [`ChannelNodeMap`](/three-flatland/api/three-flatland/src/interfaces/channelnodemap/)

Defined in: [packages/three-flatland/src/materials/channels.ts:8](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/channels.ts#L8)

Well-known channel name — named per-fragment data that effects can require.
Users extend via module augmentation on ChannelNodeMap for custom channels.

# CollisionShape

> **CollisionShape** = \{ `height`: `number`; `type`: `"rect"`; `width`: `number`; `x`: `number`; `y`: `number`; \} \| \{ `height`: `number`; `type`: `"ellipse"`; `width`: `number`; `x`: `number`; `y`: `number`; \} \| \{ `points`: `object`[]; `type`: `"polygon"`; \} \| \{ `points`: `object`[]; `type`: `"polyline"`; \}

Defined in: [packages/three-flatland/src/tilemap/types.ts:32](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/tilemap/types.ts#L32)

Collision shape types.

# ColorTransformFn

> **ColorTransformFn** = (`ctx`) => [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/three-flatland/src/materials/EffectMaterial.ts:31](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/EffectMaterial.ts#L31)

A function that transforms the base sprite color.
Receives the base color and context, returns modified color (vec4).

## Parameters

### ctx

[`ColorTransformContext`](/three-flatland/api/three-flatland/src/interfaces/colortransformcontext/)

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

# EffectConstants

> **EffectConstants**\<`S`\> = `{ [K in ConstantKeys<S>]: S[K] extends () => infer R ? R : never }`

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:52](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L52)

Read-only constants from factory function fields.
The reference is frozen at construction time and cannot be reassigned, but the
object's internals are freely mutable and mutations take effect immediately
(e.g. `this.forwardPlus.resize(w, h)` works live — no remove/re-add needed).

## Type Parameters

### S

`S` *extends* [`EffectSchema`](/three-flatland/api/three-flatland/src/type-aliases/effectschema/)

# EffectSchema

> **EffectSchema** = `Record`\<`string`, [`EffectSchemaValue`](/three-flatland/api/three-flatland/src/type-aliases/effectschemavalue/)\>

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:21](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L21)

An effect schema — maps field names to their default values.

# EffectSchemaValue

> **EffectSchemaValue** = `number` \| readonly \[`number`, `number`\] \| readonly \[`number`, `number`, `number`\] \| readonly \[`number`, `number`, `number`, `number`\] \| (() => `unknown`)

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:13](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L13)

A single field value in an effect schema (type inferred from shape).

# EffectValues

> **EffectValues**\<`S`\> = `{ -readonly [K in UniformKeys<S>]: S[K] extends number ? number : S[K] extends readonly [number, number, number, number] ? [number, number, number, number] : S[K] extends readonly [number, number, number] ? [number, number, number] : S[K] extends readonly [number, number] ? [number, number] : never }`

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:34](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L34)

Derive JS value types from an effect schema (uniform fields only, used by property setters).

## Type Parameters

### S

`S` *extends* [`EffectSchema`](/three-flatland/api/three-flatland/src/type-aliases/effectschema/)

# InstanceAttributeType

> **InstanceAttributeType** = `"float"` \| `"vec2"` \| `"vec3"` \| `"vec4"`

Defined in: [packages/three-flatland/src/pipeline/types.ts:16](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/types.ts#L16)

Instance attribute data types.

# LayerName

> **LayerName** = keyof *typeof* [`Layers`](/three-flatland/api/three-flatland/src/variables/layers/)

Defined in: [packages/three-flatland/src/pipeline/layers.ts:35](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/layers.ts#L35)

Layer name type.

# LayerType

> **LayerType** = `number`

Defined in: [packages/three-flatland/src/pipeline/layers.ts:46](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/layers.ts#L46)

Type alias for any valid layer (built-in or custom).
Custom layers can use any number, built-in layers use 0-6.

# LayerValue

> **LayerValue** = *typeof* [`Layers`](/three-flatland/api/three-flatland/src/variables/layers/)\[[`LayerName`](/three-flatland/api/three-flatland/src/type-aliases/layername/)\]

Defined in: [packages/three-flatland/src/pipeline/layers.ts:40](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/layers.ts#L40)

Layer value type.

# Light2DType

> **Light2DType** = `"point"` \| `"directional"` \| `"spot"` \| `"ambient"`

Defined in: [packages/three-flatland/src/lights/Light2D.ts:7](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/Light2D.ts#L7)

Light type for 2D lighting.

# LightEffectClass

> **LightEffectClass**\<`S`\> = [`LightEffect`](/three-flatland/api/three-flatland/src/classes/lighteffect/) & [`EffectValues`](/three-flatland/api/three-flatland/src/type-aliases/effectvalues/)\<`S`\> & [`EffectConstants`](/three-flatland/api/three-flatland/src/type-aliases/effectconstants/)\<`S`\>

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:616](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L616)

Type for a LightEffect class created by the factory.
Instances have typed properties matching the schema.

## Type Parameters

### S

`S` *extends* [`EffectSchema`](/three-flatland/api/three-flatland/src/type-aliases/effectschema/)

> **new LightEffectClass**(): [`LightEffect`](/three-flatland/api/three-flatland/src/classes/lighteffect/) & [`EffectValues`](/three-flatland/api/three-flatland/src/type-aliases/effectvalues/)\<`S`\> & [`EffectConstants`](/three-flatland/api/three-flatland/src/type-aliases/effectconstants/)\<`S`\>

Type for a LightEffect class created by the factory.
Instances have typed properties matching the schema.

## Returns

[`LightEffect`](/three-flatland/api/three-flatland/src/classes/lighteffect/) & [`EffectValues`](/three-flatland/api/three-flatland/src/type-aliases/effectvalues/)\<`S`\> & [`EffectConstants`](/three-flatland/api/three-flatland/src/type-aliases/effectconstants/)\<`S`\>

## Properties

### \_constantFactories

> `readonly` **\_constantFactories**: `Record`\<`string`, () => `unknown`\>

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:625](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L625)

***

### \_fields

> `readonly` **\_fields**: [`EffectField`](/three-flatland/api/three-flatland/src/interfaces/effectfield/)[]

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:623](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L623)

***

### \_initialized

> `readonly` **\_initialized**: `boolean`

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:626](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L626)

***

### \_totalFloats

> `readonly` **\_totalFloats**: `number`

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:624](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L624)

***

### \_trait

> `readonly` **\_trait**: `Trait`

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:622](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L622)

***

### lightName

> `readonly` **lightName**: `string`

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:618](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L618)

***

### lightSchema

> `readonly` **lightSchema**: `S`

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:619](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L619)

***

### needsShadows

> `readonly` **needsShadows**: `boolean`

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:620](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L620)

***

### requires

> `readonly` **requires**: readonly [`ChannelName`](/three-flatland/api/three-flatland/src/type-aliases/channelname/)[]

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:621](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L621)

## Methods

### \_initialize()

> **\_initialize**(): `void`

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:627](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L627)

#### Returns

`void`

***

### buildLightFn()

> **buildLightFn**(`context`): [`ColorTransformFn`](/three-flatland/api/three-flatland/src/type-aliases/colortransformfn/)

Defined in: [packages/three-flatland/src/lights/LightEffect.ts:628](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightEffect.ts#L628)

#### Parameters

##### context

[`LightEffectBuildContext`](/three-flatland/api/three-flatland/src/interfaces/lighteffectbuildcontext/)\<`S`\>

#### Returns

[`ColorTransformFn`](/three-flatland/api/three-flatland/src/type-aliases/colortransformfn/)

# MaterialEffectClass

> **MaterialEffectClass**\<`S`\> = [`MaterialEffect`](/three-flatland/api/three-flatland/src/classes/materialeffect/) & [`EffectValues`](/three-flatland/api/three-flatland/src/type-aliases/effectvalues/)\<`S`\> & [`EffectConstants`](/three-flatland/api/three-flatland/src/type-aliases/effectconstants/)\<`S`\>

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:470](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L470)

Type for a MaterialEffect class created by the factory.
Instances have typed properties matching the schema.

## Type Parameters

### S

`S` *extends* [`EffectSchema`](/three-flatland/api/three-flatland/src/type-aliases/effectschema/)

> **new MaterialEffectClass**(): [`MaterialEffect`](/three-flatland/api/three-flatland/src/classes/materialeffect/) & [`EffectValues`](/three-flatland/api/three-flatland/src/type-aliases/effectvalues/)\<`S`\> & [`EffectConstants`](/three-flatland/api/three-flatland/src/type-aliases/effectconstants/)\<`S`\>

Type for a MaterialEffect class created by the factory.
Instances have typed properties matching the schema.

## Returns

[`MaterialEffect`](/three-flatland/api/three-flatland/src/classes/materialeffect/) & [`EffectValues`](/three-flatland/api/three-flatland/src/type-aliases/effectvalues/)\<`S`\> & [`EffectConstants`](/three-flatland/api/three-flatland/src/type-aliases/effectconstants/)\<`S`\>

## Properties

### \_constantFactories

> `readonly` **\_constantFactories**: `Record`\<`string`, () => `unknown`\>

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:479](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L479)

***

### \_fields

> `readonly` **\_fields**: [`EffectField`](/three-flatland/api/three-flatland/src/interfaces/effectfield/)[]

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:477](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L477)

***

### \_initialized

> `readonly` **\_initialized**: `boolean`

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:481](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L481)

***

### \_nextId

> **\_nextId**: `number`

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:482](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L482)

***

### \_node

> `readonly` **\_node**: (`context`) => [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:480](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L480)

#### Parameters

##### context

[`EffectNodeContext`](/three-flatland/api/three-flatland/src/interfaces/effectnodecontext/)

#### Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

***

### \_totalFloats

> `readonly` **\_totalFloats**: `number`

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:478](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L478)

***

### \_trait

> `readonly` **\_trait**: `Trait`

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:476](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L476)

***

### channelNode

> `readonly` **channelNode**: ((`channelName`, `context`) => [`Node`](https://threejs.org/docs/)) \| `null`

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:475](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L475)

***

### effectName

> `readonly` **effectName**: `string`

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:472](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L472)

***

### effectSchema

> `readonly` **effectSchema**: `S`

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:473](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L473)

***

### provides

> `readonly` **provides**: readonly [`ChannelName`](/three-flatland/api/three-flatland/src/type-aliases/channelname/)[]

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:474](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L474)

## Methods

### \_initialize()

> **\_initialize**(): `void`

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:483](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L483)

#### Returns

`void`

***

### buildNode()

> **buildNode**(`context`): [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:484](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L484)

#### Parameters

##### context

[`EffectNodeContext`](/three-flatland/api/three-flatland/src/interfaces/effectnodecontext/)\<`S`\>

#### Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

# NormalBump

> **NormalBump** = `"alpha"` \| `"luminance"` \| `"red"` \| `"green"` \| `"blue"` \| `"none"`

Defined in: [packages/normals/src/descriptor.ts:115](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/normals/src/descriptor.ts#L115)

Per-texel bump source inside a region. Each non-'none' mode runs a
central-difference gradient on the named channel; the result is
treated as a height field where high values are raised and low
values are sunken. Negative `strength` inverts (dark = raised).

- `'alpha'` — gradient on the source alpha channel (default).
  Preserves sprite silhouette edges — the classic path for
  transparent sprites. Solid opaque regions produce no bump.
- `'luminance'` — gradient on Rec. 709 luminance `(0.2126·R +
  0.7152·G + 0.0722·B)`. Brick faces read as raised; dark mortar
  lines read as sunken grooves. Right mode for solid opaque
  tilesets.
- `'red'` / `'green'` / `'blue'` — gradient on a single color
  channel. Use when your art treats one channel as a height map
  (e.g., packing height into the red channel of a data texture).
- `'none'` — flat fill at the region's tilt direction. No per-texel
  variation; cheapest and useful for uniform surfaces.

# NormalDirection

> **NormalDirection** = `"flat"` \| `"up"` \| `"north"` \| `"down"` \| `"south"` \| `"left"` \| `"west"` \| `"right"` \| `"east"` \| `"up-left"` \| `"north-west"` \| `"up-right"` \| `"north-east"` \| `"down-left"` \| `"south-west"` \| `"down-right"` \| `"south-east"` \| `number`

Defined in: [packages/normals/src/descriptor.ts:32](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/normals/src/descriptor.ts#L32)

Screen-relative direction the surface normal's XY component points.

Mental model: imagine the baked normal as an arrow. `NormalDirection`
is the screen-space direction that arrow tilts toward — equivalently,
the direction the tile's visible face is "pointing." For a wall at
the top of the map (visible face toward the camera below), that's
`'south'` / `'down'`.

Cardinal and compass aliases are equivalent; the canonical form in
the codebase is NSEW. Numbers are interpreted as radians in standard
math convention (0 = +X / right, CCW positive).

# ObservableStrategy

> **ObservableStrategy**\<`T`\> = `object`

Defined in: [packages/three-flatland/src/observable/index.ts:62](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/observable/index.ts#L62)

Strategy that wires an observable value's mutation surface and
captures field snapshots for memoization. The public contract for
teaching the observable system about a custom value type — call
`attach` to make a value reactive, `snapshot` to memoize it.

## Type Parameters

### T

`T`

## Properties

### attach

> `readonly` **attach**: (`value`, `notify`) => `void`

Defined in: [packages/three-flatland/src/observable/index.ts:63](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/observable/index.ts#L63)

#### Parameters

##### value

`T`

##### notify

() => `void`

#### Returns

`void`

***

### snapshot

> `readonly` **snapshot**: (`value`) => [`Snapshot`](/three-flatland/api/three-flatland/src/type-aliases/snapshot/)

Defined in: [packages/three-flatland/src/observable/index.ts:64](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/observable/index.ts#L64)

#### Parameters

##### value

`T`

#### Returns

[`Snapshot`](/three-flatland/api/three-flatland/src/type-aliases/snapshot/)

# PassEffectClass

> **PassEffectClass**\<`S`\> = [`PassEffect`](/three-flatland/api/three-flatland/src/classes/passeffect/) & [`EffectValues`](/three-flatland/api/three-flatland/src/type-aliases/effectvalues/)\<`S`\> & [`EffectConstants`](/three-flatland/api/three-flatland/src/type-aliases/effectconstants/)\<`S`\>

Defined in: [packages/three-flatland/src/pipeline/PassEffect.ts:400](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/PassEffect.ts#L400)

Type for a PassEffect class created by the factory.
Instances have typed properties matching the schema.

## Type Parameters

### S

`S` *extends* [`EffectSchema`](/three-flatland/api/three-flatland/src/type-aliases/effectschema/)

> **new PassEffectClass**(): [`PassEffect`](/three-flatland/api/three-flatland/src/classes/passeffect/) & [`EffectValues`](/three-flatland/api/three-flatland/src/type-aliases/effectvalues/)\<`S`\> & [`EffectConstants`](/three-flatland/api/three-flatland/src/type-aliases/effectconstants/)\<`S`\>

Type for a PassEffect class created by the factory.
Instances have typed properties matching the schema.

## Returns

[`PassEffect`](/three-flatland/api/three-flatland/src/classes/passeffect/) & [`EffectValues`](/three-flatland/api/three-flatland/src/type-aliases/effectvalues/)\<`S`\> & [`EffectConstants`](/three-flatland/api/three-flatland/src/type-aliases/effectconstants/)\<`S`\>

## Properties

### \_constantFactories

> `readonly` **\_constantFactories**: `Record`\<`string`, () => `unknown`\>

Defined in: [packages/three-flatland/src/pipeline/PassEffect.ts:407](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/PassEffect.ts#L407)

***

### \_fields

> `readonly` **\_fields**: [`EffectField`](/three-flatland/api/three-flatland/src/interfaces/effectfield/)[]

Defined in: [packages/three-flatland/src/pipeline/PassEffect.ts:405](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/PassEffect.ts#L405)

***

### \_initialized

> `readonly` **\_initialized**: `boolean`

Defined in: [packages/three-flatland/src/pipeline/PassEffect.ts:408](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/PassEffect.ts#L408)

***

### \_totalFloats

> `readonly` **\_totalFloats**: `number`

Defined in: [packages/three-flatland/src/pipeline/PassEffect.ts:406](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/PassEffect.ts#L406)

***

### \_trait

> `readonly` **\_trait**: `Trait`

Defined in: [packages/three-flatland/src/pipeline/PassEffect.ts:404](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/PassEffect.ts#L404)

***

### passName

> `readonly` **passName**: `string`

Defined in: [packages/three-flatland/src/pipeline/PassEffect.ts:402](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/PassEffect.ts#L402)

***

### passSchema

> `readonly` **passSchema**: `S`

Defined in: [packages/three-flatland/src/pipeline/PassEffect.ts:403](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/PassEffect.ts#L403)

## Methods

### \_initialize()

> **\_initialize**(): `void`

Defined in: [packages/three-flatland/src/pipeline/PassEffect.ts:409](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/PassEffect.ts#L409)

#### Returns

`void`

***

### buildPass()

> **buildPass**(`context`): [`PassEffectFn`](/three-flatland/api/three-flatland/src/type-aliases/passeffectfn/)

Defined in: [packages/three-flatland/src/pipeline/PassEffect.ts:410](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/PassEffect.ts#L410)

#### Parameters

##### context

[`PassEffectContext`](/three-flatland/api/three-flatland/src/interfaces/passeffectcontext/)\<`S`\>

#### Returns

[`PassEffectFn`](/three-flatland/api/three-flatland/src/type-aliases/passeffectfn/)

# PassEffectFn

> **PassEffectFn** = (`input`, `uv`) => [`Node`](https://threejs.org/docs/)\<`"vec4"`\>

Defined in: [packages/three-flatland/src/pipeline/PassEffect.ts:24](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/PassEffect.ts#L24)

A post-processing pass function that transforms scene color.

## Parameters

### input

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

### uv

[`Node`](https://threejs.org/docs/)\<`"vec2"`\>

## Returns

[`Node`](https://threejs.org/docs/)\<`"vec4"`\>

# Snapshot

> **Snapshot** = `Record`\<`string`, `unknown`\>

Defined in: [packages/three-flatland/src/observable/index.ts:54](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/observable/index.ts#L54)

Flat record returned by `snapshot()` for shallow-equal memoization.

# SortMode

> **SortMode** = `"none"` \| `"z-index"` \| `"y-sort"` \| `"custom"`

Defined in: [packages/three-flatland/src/pipeline/types.ts:11](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/types.ts#L11)

Sort mode for sprites within a layer.

# SpriteSortFunction

> **SpriteSortFunction** = (`a`, `b`) => `number`

Defined in: [packages/three-flatland/src/pipeline/types.ts:86](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/types.ts#L86)

Sorting function for custom sort mode.

## Parameters

### a

#### layer

`number`

#### zIndex

`number`

### b

#### layer

`number`

#### zIndex

`number`

## Returns

`number`

# TexturePreset

> **TexturePreset** = `"pixel-art"` \| `"smooth"` \| `"none"`

Defined in: [packages/three-flatland/src/loaders/texturePresets.ts:5](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/texturePresets.ts#L5)

Named texture presets

# TileLookupFn

> **TileLookupFn** = (`tileIndex`, `slotIndex`) => [`Node`](https://threejs.org/docs/)\<`"int"`\>

Defined in: [packages/three-flatland/src/lights/LightStore.ts:32](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/LightStore.ts#L32)

Function that reads a light index from a tile buffer/texture.
Abstracts over WebGPU storage buffers and WebGL2 DataTextures.

## Parameters

### tileIndex

[`Node`](https://threejs.org/docs/)\<`"int"`\>

TSL node for the flat tile index

### slotIndex

[`Node`](https://threejs.org/docs/)\<`"int"`\>

TSL node for the slot within the tile (0..MAX_LIGHTS_PER_TILE-1)

## Returns

[`Node`](https://threejs.org/docs/)\<`"int"`\>

TSL int node containing the 1-based light index (0 = empty)

# UniformKeys

> **UniformKeys**\<`S`\> = `{ [K in keyof S]: S[K] extends (args: never[]) => unknown ? never : K }`\[keyof `S`\]

Defined in: [packages/three-flatland/src/materials/MaterialEffect.ts:24](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/MaterialEffect.ts#L24)

Keys whose schema value is a plain number or tuple (→ TSL uniform, settable at runtime).

## Type Parameters

### S

`S` *extends* [`EffectSchema`](/three-flatland/api/three-flatland/src/type-aliases/effectschema/)

# WithRequiredChannels

> **WithRequiredChannels**\<`C`\> = `{ [K in C[number]]: K extends keyof ChannelNodeMap ? ChannelNodeMap[K] : Node }`

Defined in: [packages/three-flatland/src/materials/channels.ts:44](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/channels.ts#L44)

Narrows a type by adding required channel properties.
Known channels use mapped types; unknown channels fall back to Node.

Used by createLightEffect to type the light callback context —
if requires: ['normal'], then ctx.normal is Node<'vec3'> (guaranteed).

## Type Parameters

### C

`C` *extends* readonly `string`[]

# channelDefaults

> `const` **channelDefaults**: `Record`\<`string`, () => [`Node`](https://threejs.org/docs/)\>

Defined in: [packages/three-flatland/src/materials/channels.ts:54](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/channels.ts#L54)

Default TSL node factories for well-known channels.
When a colorTransform requires a channel but no provider effect supplies it,
the pipeline fills it from this map. Users can register defaults for custom
channels by adding entries.

# DEFAULT_BATCH_SIZE

> `const` **DEFAULT\_BATCH\_SIZE**: `16384` = `16384`

Defined in: [packages/three-flatland/src/pipeline/SpriteBatch.ts:25](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/SpriteBatch.ts#L25)

Default maximum sprites per batch.

16k is the sweet spot across mobile and desktop:
  - ~2MB per batch (matrix + interleaved core + effects). Fits in
    mobile VRAM even with 3–5 materials per scene.
  - Covers indie-scale workloads in a single batch (no draw-call
    overhead from batch splits).
  - Scenes that want 30k+ sprites per material pass an explicit
    `maxBatchSize: 32_768` on `SpriteGroup` — knightmark-style.

# EFFECT_BIT_OFFSET

> `const` **EFFECT\_BIT\_OFFSET**: `0` = `0`

Defined in: [packages/three-flatland/src/materials/effectFlagBits.ts:50](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/effectFlagBits.ts#L50)

Bit index at which the first registered MaterialEffect enable bit
sits within `instanceSystem.w`. The first effect occupies bit 0,
the second bit 1, and so on up to 24 slots.

Kept as an exported constant — and at zero — so callers can compute
per-effect masks as `1 << (EFFECT_BIT_OFFSET + i)` and stay robust
to a future change (e.g., reserving low enable bits for framework
use).

# Layers

> `const` **Layers**: `object`

Defined in: [packages/three-flatland/src/pipeline/layers.ts:15](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/pipeline/layers.ts#L15)

Default render layers for 2D scenes.

These provide semantic layer names for common 2D game scenarios.
You can use these directly or define custom layers.

## Type Declaration

### BACKGROUND

> `readonly` **BACKGROUND**: `0` = `0`

Background elements (sky, distant scenery)

### EFFECTS

> `readonly` **EFFECTS**: `4` = `4`

Visual effects (particles, spell effects)

### ENTITIES

> `readonly` **ENTITIES**: `3` = `3`

Game entities (players, enemies, items)

### FOREGROUND

> `readonly` **FOREGROUND**: `5` = `5`

Foreground elements (overlays, weather)

### GROUND

> `readonly` **GROUND**: `1` = `1`

Ground/floor tiles

### SHADOWS

> `readonly` **SHADOWS**: `2` = `2`

Shadow sprites (render below entities)

### UI

> `readonly` **UI**: `6` = `6`

UI elements (always on top)

## Example

```typescript
import { Layers } from 'three-flatland'

sprite.layer = Layers.ENTITIES
shadow.layer = Layers.SHADOWS
```

# LIT_FLAG_MASK

> `const` **LIT\_FLAG\_MASK**: `number`

Defined in: [packages/three-flatland/src/materials/effectFlagBits.ts:28](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/effectFlagBits.ts#L28)

# MAX_LIGHTS_PER_TILE

> `const` **MAX\_LIGHTS\_PER\_TILE**: `16` = `16`

Defined in: [packages/three-flatland/src/lights/ForwardPlusLighting.ts:43](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/ForwardPlusLighting.ts#L43)

Max lights any single tile can hold. Each tile dedicates
`MAX_LIGHTS_PER_TILE / 4 = 4` RGBA texels to light indices. Caps
the per-fragment shader loop iteration count — the inner loop
breaks early on the empty-slot sentinel, so tiles with fewer lights
pay only for what they hold.

Raising this increases tile-texture footprint and the saturated-
tile shader worst case. Lowering it makes reservoir eviction kick
in sooner in dense scenes.

# observable

> `const` **observable**: `object`

Defined in: [packages/three-flatland/src/observable/index.ts:307](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/observable/index.ts#L307)

Observable strategies for three.js value types. Call a strategy's
`attach(value, notify)` directly to make a value fire `notify` on
in-place mutation (R3F compat).

- `observable.color` — Color (r, g, b)
- `observable.vector2` — Vector2 (x, y)
- `observable.vector3` — Vector3 (x, y, z)
- `observable.euler` — Euler (x, y, z, order) — hooks into three's
  existing `_onChangeCallback` rather than installing accessors

## Type Declaration

### color

> `readonly` **color**: `object`

#### color.attach

> **attach**: (`c`, `notify`) => `void` = `attachColor`

##### Parameters

###### c

[`Color`](https://threejs.org/docs/#api/en/math/Color)

###### notify

() => `void`

##### Returns

`void`

#### color.snapshot

> **snapshot**: (`c`) => [`Snapshot`](/three-flatland/api/three-flatland/src/type-aliases/snapshot/) = `snapshotColor`

##### Parameters

###### c

[`Color`](https://threejs.org/docs/#api/en/math/Color)

##### Returns

[`Snapshot`](/three-flatland/api/three-flatland/src/type-aliases/snapshot/)

### euler

> `readonly` **euler**: `object`

#### euler.attach

> **attach**: (`e`, `notify`) => `void` = `attachEuler`

##### Parameters

###### e

[`Euler`](https://threejs.org/docs/#api/en/math/Euler)

###### notify

() => `void`

##### Returns

`void`

#### euler.snapshot

> **snapshot**: (`e`) => [`Snapshot`](/three-flatland/api/three-flatland/src/type-aliases/snapshot/) = `snapshotEuler`

##### Parameters

###### e

[`Euler`](https://threejs.org/docs/#api/en/math/Euler)

##### Returns

[`Snapshot`](/three-flatland/api/three-flatland/src/type-aliases/snapshot/)

### vector2

> `readonly` **vector2**: `object`

#### vector2.attach

> **attach**: (`v`, `notify`) => `void` = `attachVector2`

##### Parameters

###### v

[`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

###### notify

() => `void`

##### Returns

`void`

#### vector2.snapshot

> **snapshot**: (`v`) => [`Snapshot`](/three-flatland/api/three-flatland/src/type-aliases/snapshot/) = `snapshotVector2`

##### Parameters

###### v

[`Vector2`](https://threejs.org/docs/#api/en/math/Vector2)

##### Returns

[`Snapshot`](/three-flatland/api/three-flatland/src/type-aliases/snapshot/)

### vector3

> `readonly` **vector3**: `object`

#### vector3.attach

> **attach**: (`v`, `notify`) => `void` = `attachVector3`

##### Parameters

###### v

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

###### notify

() => `void`

##### Returns

`void`

#### vector3.snapshot

> **snapshot**: (`v`) => [`Snapshot`](/three-flatland/api/three-flatland/src/type-aliases/snapshot/) = `snapshotVector3`

##### Parameters

###### v

[`Vector3`](https://threejs.org/docs/#api/en/math/Vector3)

##### Returns

[`Snapshot`](/three-flatland/api/three-flatland/src/type-aliases/snapshot/)

# RECEIVE_SHADOWS_MASK

> `const` **RECEIVE\_SHADOWS\_MASK**: `number`

Defined in: [packages/three-flatland/src/materials/effectFlagBits.ts:32](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/materials/effectFlagBits.ts#L32)

# TEXTURE_PRESETS

> `const` **TEXTURE\_PRESETS**: `Record`\<[`TexturePreset`](/three-flatland/api/three-flatland/src/type-aliases/texturepreset/), [`TextureOptions`](/three-flatland/api/three-flatland/src/interfaces/textureoptions/)\>

Defined in: [packages/three-flatland/src/loaders/texturePresets.ts:18](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/loaders/texturePresets.ts#L18)

Preset definitions

# TILE_SIZE

> `const` **TILE\_SIZE**: `16` = `16`

Defined in: [packages/three-flatland/src/lights/ForwardPlusLighting.ts:30](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/lights/ForwardPlusLighting.ts#L30)

Screen-space tile edge in pixels.

16px gives finer-grained coverage of small fill lights (slime glows
~40 world units) so the tile's closest-point score stays
representative of what the fragment would see at the tile center.
32px showed visible blockiness on small fill lights because the
tile AABB could contain the light while its effective reach
barely extends to the tile's opposite corner — the scoring would
keep the light on the light's own side of the tile but evict it
by the far side, producing grid-aligned intensity falloff.

CPU cost at 16px doubles vs 32px (more tiles), but dedup + the
reservoir path keep per-tile work bounded, and the per-fragment
shader loop is unchanged either way (MAX_LIGHTS_PER_TILE caps it).

# VERSION

> `const` **VERSION**: `"0.1.0-alpha.6"` = `'0.1.0-alpha.6'`

Defined in: [packages/three-flatland/src/index.ts:4](https://github.com/thejustinwalsh/three-flatland/blob/main/packages/three-flatland/src/index.ts#L4)

# Branding Assets

> Marketing assets and branding guidelines for three-flatland. Generated live using site styles.

import BrandAsset from '../../components/BrandAsset.astro';
import CaptureModal from '../../components/CaptureModal.astro';

This page provides live-rendered versions of the `three-flatland` marketing assets.

<p><strong>Click an asset below</strong> to open it in a full-resolution capture modal. Once in the modal, right-click the asset, select <strong>Inspect</strong>, and use <strong>Capture node screenshot</strong>.</p>

## Official Icon

<div className="asset-preview-link" data-type="icon-only">
  <BrandAsset id="preview-icon-only" type="icon-only" />
</div>

## Repository Banner (1280x640)

<div className="asset-preview-link" data-type="banner">
  <BrandAsset id="preview-banner" type="banner" />
</div>

## Social Preview Card (1200x630)

<div className="asset-preview-link" data-type="og">
  <BrandAsset id="preview-og" type="og" />
</div>

## Bluesky Banner (3000x1000)

<div className="asset-preview-link" data-type="wide">
  <BrandAsset id="preview-wide" type="wide" />
</div>

## X Card Preview (1200x628)

<div className="asset-preview-link" data-type="social-x">
  <BrandAsset id="preview-social-x" type="social-x" />
</div>

<div className="hidden-capture-targets">
  <BrandAsset id="capture-icon-only" type="icon-only" isCapture={true} />
  <BrandAsset id="capture-banner" type="banner" isCapture={true} />
  <BrandAsset id="capture-og" type="og" isCapture={true} />
  <BrandAsset id="capture-wide" type="wide" isCapture={true} />
  <BrandAsset id="capture-social-x" type="social-x" isCapture={true} />
</div>

<CaptureModal />

# Examples

> Focused single-feature demos of three-flatland — sprites, animation, batch rendering, TSL nodes, pass effects, tilemaps, and Skia integration.

import GalleryGrid from '../../../components/gallery/GalleryGrid.astro'
import GalleryTile from '../../../components/gallery/GalleryTile.astro'

<div class="examples-page not-content">

<header class="examples-header">
  <p class="examples-eyebrow">Examples</p>
  <h1 class="examples-title">Shortcuts to getting started.</h1>
  <p class="examples-tagline">Self contained cloneable templates that demonstrate real world use of three-flatland features.</p>
</header>

<GalleryGrid>
  <GalleryTile
    surface="examples"
    slug="basic-sprite"
    title="Basic Sprite"
    description="A 2D sprite on screen with the smallest possible setup. The starting point."
  />
  <GalleryTile
    surface="examples"
    slug="animation"
    title="Animation"
    description="Spritesheet-driven animation with frame-perfect timing on the GPU."
  />
  <GalleryTile
    surface="examples"
    slug="batch-demo"
    title="Batch Rendering"
    description="Thousands of sprites in a single draw call via automatic batching."
  />
  <GalleryTile
    surface="examples"
    slug="knightmark"
    title="Knightmark"
    description="Animated knights, collisions, spatial hashing — the throughput stress test."
  />
  <GalleryTile
    surface="examples"
    slug="pass-effects"
    title="Pass Effects"
    description="Composable post-processing — CRT, LCD, VHS, and friends — applied per scene."
  />
  <GalleryTile
    surface="examples"
    slug="tsl-nodes"
    title="TSL Nodes"
    description="Custom shader effects authored in Three Shader Language. Per-sprite, batched."
  />
  <GalleryTile
    surface="examples"
    slug="tilemap"
    title="Tilemap"
    description="Tiled-editor JSON loaded as efficient tile layers, animated tiles, collision data."
  />
  <GalleryTile
    surface="examples"
    slug="skia"
    title="Skia"
    description="GPU-accelerated 2D vector graphics via Skia WASM with WebGPU and WebGL."
  />
  <GalleryTile
    surface="examples"
    slug="slug-text"
    title="Slug Text"
    description="Resolution-independent GPU text — Bezier outlines evaluated per-pixel, crisp at any zoom."
  />
  <GalleryTile
    surface="examples"
    slug="lighting"
    title="2D Lighting"
    description="Dynamic Forward+ sprite lighting — draggable point lights, flicker, and animated sprites in a lit dungeon."
  />
</GalleryGrid>

</div>

<style>
{`
  /* MDX-safe — CSS wrapped in a template literal because MDX 3
     treats { and } in raw <style> content as JS expression
     boundaries. Same pattern the landing page (index.mdx) uses. */
  .examples-page {
    max-width: 75rem;
    margin: 0 auto;
    padding-inline: clamp(1rem, 4vw, 2rem);
    padding-block: clamp(2rem, 4vw, 3rem);
  }

  .examples-header {
    margin-block-end: clamp(2rem, 4vw, 3rem);
    max-width: 56rem;
  }

  .examples-eyebrow {
    font-family: 'Inter', system-ui, sans-serif;
    font-size: 0.75rem;
    font-weight: 600;
    color: color-mix(in oklab, var(--diamond) 60%, var(--muted-foreground));
    text-transform: uppercase;
    letter-spacing: 0.08em;
    margin: 0 0 0.5rem 0;
  }

  .examples-title {
    font-family: 'Public Sans', system-ui, sans-serif;
    font-size: clamp(2rem, 4.5vw, 3.25rem);
    font-weight: 200;
    letter-spacing: -0.025em;
    line-height: 1.05;
    color: var(--foreground);
    margin: 0 0 1rem 0;
    text-wrap: balance;
  }

  .examples-tagline {
    font-family: 'Public Sans', system-ui, sans-serif;
    font-size: clamp(1rem, 1.5vw, 1.0625rem);
    font-weight: 400;
    line-height: 1.55;
    color: var(--muted-foreground);
    margin: 0;
    max-width: 48rem;
    text-wrap: balance;
  }
`}
</style>

# Animation

> Animate sprites using spritesheets with three-flatland.

import ExampleDetailLayout from '../../../components/ExampleDetailLayout.astro'
import { loadExample } from '../../../utils/loadExample'

export const threeFiles = loadExample('three', 'animation')
export const reactFiles = loadExample('react', 'animation')

<ExampleDetailLayout
  slug="animation"
  threeFiles={threeFiles}
  reactFiles={reactFiles}
  showCommonFiles={['public/sprites/knight.json', 'public/sprites/coin.json']}
>

## AnimatedSprite2D

The `AnimatedSprite2D` class extends `Sprite2D` with frame-based animation driven by a `SpriteSheet` and an `animationSet` of named animations:

```typescript
import { AnimatedSprite2D, SpriteSheetLoader } from 'three-flatland';

const spriteSheet = await SpriteSheetLoader.load('/sprites/knight.json');

const sprite = new AnimatedSprite2D({
  spriteSheet,
  animationSet: {
    fps: 10, // Default fps for all animations
    animations: {
      idle: { frames: ['idle_0', 'idle_1', 'idle_2', 'idle_3'], fps: 8, loop: true },
      run: { frames: ['run_0', 'run_1', 'run_2', 'run_3'], fps: 12, loop: true },
    },
  },
  animation: 'idle', // Start playing immediately
});
```

## Playback Control

```typescript
sprite.play('run');              // Play by name
sprite.play('hit', {
  onComplete: () => sprite.play('idle'), // Chain after non-looping anim
});
sprite.speed = 1.5;              // 1.5x speed
```

## Animation Update

Advance the animation each frame by calling `update(deltaMs)`:

```typescript
let lastTime = performance.now();

function animate() {
  const now = performance.now();
  const deltaMs = now - lastTime;
  lastTime = now;

  sprite.update(deltaMs);
  renderer.render(scene, camera);
  requestAnimationFrame(animate);
}
```

## Further Reading

- [TSL Nodes](../tsl-nodes/) - Add custom shader effects
- [Tilemap](../tilemap/) - Create tile-based maps

</ExampleDetailLayout>

# Basic Sprite

> Create a simple 2D sprite with three-flatland.

import ExampleDetailLayout from '../../../components/ExampleDetailLayout.astro'
import { loadExample } from '../../../utils/loadExample'

export const threeFiles = loadExample('three', 'basic-sprite')
export const reactFiles = loadExample('react', 'basic-sprite')

<ExampleDetailLayout
  slug="basic-sprite"
  threeFiles={threeFiles}
  reactFiles={reactFiles}
>

## SpriteGroup

The `SpriteGroup` class manages 2D sprite rendering. All sprites must be added to a `SpriteGroup` instance:

```typescript
const spriteGroup = new SpriteGroup();
scene.add(spriteGroup);
spriteGroup.add(sprite);
```

## Sprite2D

The `Sprite2D` class represents a 2D sprite. It requires a texture and supports optional properties like anchor point and size:

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

## Further Reading

- [Animation](../animation/) - Add spritesheet animation
- [Batch Demo](../batch-demo/) - Render thousands of sprites

</ExampleDetailLayout>

# Batch Rendering

> Render thousands of sprites efficiently with automatic batching.

import ExampleDetailLayout from '../../../components/ExampleDetailLayout.astro'
import { loadExample } from '../../../utils/loadExample'

export const threeFiles = loadExample('three', 'batch-demo')
export const reactFiles = loadExample('react', 'batch-demo')

<ExampleDetailLayout
  slug="batch-demo"
  threeFiles={threeFiles}
  reactFiles={reactFiles}
>

## Automatic Batching

`SpriteGroup` automatically batches sprites that share the same material, minimizing draw calls:

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

// All sprites with the same material are batched together
for (let i = 0; i < 1000; i++) {
  const sprite = new Sprite2D({ material: sharedMaterial });
  sprite.position.set(x, y, 0);
  spriteGroup.add(sprite);
}
```

## Layers and Sorting

Use layers and zIndex for proper depth sorting:

```typescript
import { Layers } from 'three-flatland';

sprite.layer = Layers.ENTITIES;
sprite.zIndex = -Math.floor(sprite.position.y); // Y-sort
```

## Stats

Monitor batching performance with the stats object:

```typescript
const { spriteCount, batchCount, visibleSprites } = spriteGroup.stats;
console.log(`Sprites: ${spriteCount}, Batches: ${batchCount}, Visible: ${visibleSprites}`);
```

## Further Reading

- [TSL Nodes](../tsl-nodes/) - Add shader effects
- [Tilemap](../tilemap/) - Efficient tile-based rendering

</ExampleDetailLayout>

# Knightmark

> Sprite benchmark with animated knights, collisions, and spatial hashing.

import ExampleDetailLayout from '../../../components/ExampleDetailLayout.astro'
import { loadExample } from '../../../utils/loadExample'

export const threeFiles = loadExample('three', 'knightmark')
export const reactFiles = loadExample('react', 'knightmark')

<ExampleDetailLayout
  slug="knightmark"
  threeFiles={threeFiles}
  reactFiles={reactFiles}
  showCommonFiles={['public/sprites/knight.json']}
>

## What It Demonstrates

Knightmark is a sprite stress test inspired by classic benchmarks like Bunnymark. It showcases:

- **Batch rendering** — thousands of animated sprites in minimal draw calls
- **AnimatedSprite2D** — frame-based sprite animation with multiple states
- **Spatial hashing** — efficient collision detection between sprites
- **Y-sorting** — depth-correct rendering via `zIndex`

## Key Patterns

### Animated Sprites with State Machines

Each knight has a state machine (walk, roll, trip, idle) driving its animation:

```typescript
const sprite = new AnimatedSprite2D({
  spriteSheet: knightSheet,
  animationSet: knightAnimations,
  animation: 'idle',
  layer: Layers.ENTITIES,
});

sprite.play('run');
sprite.play('death', {
  onComplete: () => sprite.play('idle'),
});
```

### Y-Sort Depth Ordering

Knights render in correct depth order by setting `zIndex` from their Y position:

```typescript
sprite.zIndex = -Math.floor(sprite.position.y);
```

### Spatial Hash for Collisions

A simple spatial hash grid enables O(n) collision checks instead of O(n^2):

```typescript
spatialHash.clear();
for (const knight of knights) spatialHash.insert(knight);

spatialHash.forEachNeighbor(knight, (other) => {
  // Check distance and resolve collision
});
```

## Further Reading

- [Batch Rendering](../batch-demo/) - Learn more about batching
- [Animation](../animation/) - Sprite animation basics

</ExampleDetailLayout>

# 2D Lighting

> Dynamic sprite lighting with draggable point lights.

import ExampleDetailLayout from '../../../components/ExampleDetailLayout.astro'
import { loadExample } from '../../../utils/loadExample'

export const threeFiles = loadExample('three', 'lighting')
export const reactFiles = loadExample('react', 'lighting')

<ExampleDetailLayout
  slug="lighting"
  threeFiles={threeFiles}
  reactFiles={reactFiles}
>

## Interactive Lighting Demo

This example demonstrates dynamic 2D lighting using `DefaultLightEffect` (Forward+ tiled culling), two flickering point lights with draggable indicators, and animated knight sprites:

| Control | Action |
|---------|--------|
| **Torch 1 / 2** | Toggle point lights on/off |
| **Drag** | Move point lights (touch or mouse) |

## Lighting Setup

The scene uses `DefaultLightEffect` (Forward+ tiled culling) for efficient per-tile light culling:

```typescript
import { Flatland, Light2D, Sprite2D } from 'three-flatland'
import { DefaultLightEffect } from '@three-flatland/presets'

const defaultEffect = new DefaultLightEffect()

const flatland = new Flatland({ viewSize: 300, clearColor: 0x0a0a12 })
flatland.setLighting(defaultEffect)

// Two colored torches
const torch1 = new Light2D({
  type: 'point',
  position: [-80, 50],
  color: 0xff6600,
  intensity: 1.2,
  distance: 150,
  decay: 2,
})

const torch2 = new Light2D({
  type: 'point',
  position: [80, 50],
  color: 0xffaa00,
  intensity: 1.0,
  distance: 150,
  decay: 2,
})

flatland.add(torch1)
flatland.add(torch2)

// Dim ambient so unlighted areas aren't pure black
flatland.add(new Light2D({
  type: 'ambient',
  color: 0x111122,
  intensity: 0.15,
}))
```

## Sprites

All sprites receive lighting by default when a LightEffect is active. Set `lit: false` to opt out (e.g., for UI elements):

```typescript
const knight = new Sprite2D({
  texture: knightSheet.texture,
  frame: knightSheet.getFrame('idle_0'),
})
flatland.add(knight)

// UI indicator — always full brightness
const indicator = new Sprite2D({ texture: circleTexture, lit: false })
```

## React: Declarative Lighting

In React, use `attachLighting` to wire the LightEffect to Flatland, `attachEffect` for normal providers, and `light2D` JSX elements for lights:

```tsx
import { extend } from '@react-three/fiber/webgpu'
import {
  Flatland, Light2D, Sprite2D, attachLighting, attachEffect,
} from 'three-flatland/react'
import { DefaultLightEffect, NormalMapProvider } from '@three-flatland/presets'
import '@three-flatland/presets/react'

extend({ Flatland, Sprite2D, Light2D, DefaultLightEffect, NormalMapProvider })

<flatland ref={flatlandRef} viewSize={300} clearColor={0x0a0a12}>
  <defaultLightEffect attach={attachLighting} />

  <light2D lightType="point" position={[-80, 50, 0]}
    color={0xff6600} intensity={1.2} distance={150} decay={2} />
  <light2D lightType="point" position={[80, 50, 0]}
    color={0xffaa00} intensity={1.0} distance={150} decay={2} />
  <light2D lightType="ambient" color={0x111122} intensity={0.15} />

  <sprite2D texture={tex}>
    <normalMapProvider attach={attachEffect} />
  </sprite2D>
</flatland>
```

## Further Reading

- [2D Lighting Guide](../../guides/lighting-setup/) — Full reference for `DefaultLightEffect`, normal providers, and shadow controls
- [2D Lighting Concept](../../guides/lighting/) — How Forward+ tiling and the slot budget work
- [Pass Effects](../pass-effects/) — Post-processing after lighting
- [TSL Nodes](../tsl-nodes/) — Per-sprite shader effects

</ExampleDetailLayout>

# Pass Effects

> Dynamic post-processing with composable PassEffects.

import { Tabs, TabItem } from 'starlight-theme/components'
import ExampleDetailLayout from '../../../components/ExampleDetailLayout.astro'
import { loadExample } from '../../../utils/loadExample'

export const threeFiles = loadExample('three', 'pass-effects')
export const reactFiles = loadExample('react', 'pass-effects')

<ExampleDetailLayout
  slug="pass-effects"
  threeFiles={threeFiles}
  reactFiles={reactFiles}
>

## What This Example Shows

This example demonstrates the **Pass Effect** system for full-screen post-processing. Switch between 5 presets to see different effect chains applied to a sprite scene:

| Preset | Passes | Description |
|--------|--------|-------------|
| Clean | 0 | No post-processing |
| CRT Arcade | 1 | Full CRT composite — curvature, scanlines, bloom, vignette, and color bleed |
| Handheld | 4 | Posterize + LCD grid + backlight bleed + vignette |
| VHS Tape | 3 | VHS distortion + static noise + chromatic aberration |
| Retro PC | 3 | Color quantize + scanlines + vignette |

## Defining Pass Effects

Use `createPassEffect` with a schema for parameters and a TSL node builder:

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { createPassEffect } from 'three-flatland'
    import { crtComplete } from '@three-flatland/nodes'
    import { convertToTexture } from 'three/tsl'

    const CRTPass = createPassEffect({
      name: 'crt',
      schema: {
        curvature: 0.08,
        scanlineIntensity: 0.18,
        vignetteIntensity: 0.3,
        bloomIntensity: 0.15,
        colorBleed: 0.0012,
      },
      pass: ({ uniforms }) => (input, uv) => {
        const tex = convertToTexture(input)
        return crtComplete(tex, uv, {
          curvature: uniforms.curvature,
          scanlineIntensity: uniforms.scanlineIntensity,
          vignetteIntensity: uniforms.vignetteIntensity,
          bloomIntensity: uniforms.bloomIntensity,
          colorBleed: uniforms.colorBleed,
        })
      },
    })
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { createPassEffect } from 'three-flatland/react'
    import { crtComplete } from '@three-flatland/nodes'
    import { convertToTexture } from 'three/tsl'

    const CRTPass = createPassEffect({
      name: 'crt',
      schema: {
        curvature: 0.08,
        scanlineIntensity: 0.18,
        vignetteIntensity: 0.3,
        bloomIntensity: 0.15,
        colorBleed: 0.0012,
      },
      pass: ({ uniforms }) => (input, uv) => {
        const tex = convertToTexture(input)
        return crtComplete(tex, uv, {
          curvature: uniforms.curvature,
          scanlineIntensity: uniforms.scanlineIntensity,
          vignetteIntensity: uniforms.vignetteIntensity,
          bloomIntensity: uniforms.bloomIntensity,
          colorBleed: uniforms.colorBleed,
        })
      },
    })
    ```
  </TabItem>
</Tabs>

## Adding Passes at Runtime

Instantiate a pass and add it to Flatland. Passes chain in order — each receives the previous output:

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    const crt = new CRTPass()
    flatland.addPass(crt)

    // Animate parameters in the render loop
    crt.curvature = 0.12

    // Swap presets by clearing and adding new passes
    flatland.clearPasses()
    flatland.addPass(new PosterizePass()).addPass(new VignettePass())
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { useEffect, useRef } from 'react'
    import { useFrame } from '@react-three/fiber/webgpu'

    function FlatlandScene({ preset }) {
      const flatlandRef = useRef(null)

      useEffect(() => {
        const flatland = flatlandRef.current
        flatland.clearPasses()
        const active = createPreset(preset)
        for (const p of active.passes) flatland.addPass(p)
      }, [preset])

      useFrame(() => {
        flatlandRef.current?.render(gl)
      }, { phase: 'render' })

      return (
        <flatland ref={flatlandRef} viewSize={80} clearColor={0x1a1a2e}>
          {/* sprites */}
        </flatland>
      )
    }
    ```
  </TabItem>
</Tabs>

## Further Reading

- [Pass Effects Guide](../../guides/pass-effects/) — Full API reference and pass chain architecture
- [TSL Nodes](../tsl-nodes/) — Per-sprite material effects

</ExampleDetailLayout>

# Skia

> GPU-accelerated 2D vector graphics via Skia WASM with WebGPU and WebGL.

import { Tabs, TabItem } from 'starlight-theme/components'
import ExampleDetailLayout from '../../../components/ExampleDetailLayout.astro'
import { loadExample } from '../../../utils/loadExample'

export const threeFiles = loadExample('three', 'skia')
export const reactFiles = loadExample('react', 'skia')

<ExampleDetailLayout
  slug="skia"
  threeFiles={threeFiles}
  reactFiles={reactFiles}
>

## What It Demonstrates

- **SkiaCanvas** — off-screen texture rendering and screen-space overlay modes
- **Drawing nodes** — `SkiaRect`, `SkiaCircle`, `SkiaLine`, `SkiaPathNode`, `SkiaTextNode`, `SkiaGroup`
- **SkiaPaint** — custom gradient shaders applied to drawing nodes
- **SkiaPath** — programmatic paths with boolean operations (difference, intersect, union, xor)
- **SkiaTypeface / SkiaFontLoader** — font loading with `useLoader`, sized fonts via `atSize()`
- **attachSkiaTexture** — R3F attach helper for compositing Skia output onto 3D mesh materials
- **useFrame phases** — `{ before: 'render' }` and `{ after: 'render' }` for render pipeline control

## Key Patterns

### Texture Mode

Render Skia shapes to a texture and apply it to a 3D mesh:

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { Skia, SkiaPaint } from '@three-flatland/skia'
    import { SkiaCanvas, SkiaRect, SkiaGroup } from '@three-flatland/skia/three'

    const skia = await Skia.init(renderer)
    const canvas = new SkiaCanvas({ renderer, width: 1024, height: 880 })
    canvas.add(new SkiaRect()) // add shapes

    // In animation loop:
    canvas.render()
    material.map = canvas.texture
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { SkiaCanvas, SkiaRect, attachSkiaTexture } from '@three-flatland/skia/react'

    <mesh>
      <meshBasicMaterial transparent premultipliedAlpha>
        <SkiaCanvas attach={attachSkiaTexture} renderer={renderer}
                    width={1024} height={880}>
          <skiaRect x={0} y={0} width={100} height={100}
                    fill={[1, 0, 0, 1]} />
        </SkiaCanvas>
      </meshBasicMaterial>
    </mesh>
    ```
  </TabItem>
</Tabs>

### Overlay Mode

Draw directly on top of the 3D scene (HUD, debug text):

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    const overlay = new SkiaCanvas({
      renderer,
      width: window.innerWidth * dpr,
      height: window.innerHeight * dpr,
      overlay: true,
    })

    // Render AFTER the 3D scene:
    renderer.render(scene, camera)
    overlay.render()
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    // SkiaCanvas with overlay renders to the screen framebuffer.
    // Use useFrame with { after: 'render' } to draw after the 3D scene.
    const overlayRef = useRef<SkiaCanvasRef>(null)

    useFrame(() => {
      overlayRef.current?.render()
    }, { after: 'render' })

    <SkiaCanvas ref={overlayRef} renderer={renderer}
                width={pw} height={ph} overlay>
      <skiaTextNode text="Hello" font={font}
                    fill={[1, 1, 1, 1]} x={10} y={30} />
    </SkiaCanvas>
    ```
  </TabItem>
</Tabs>

### Custom Paints (Gradients, Shaders)

For effects beyond flat fill/stroke, create a `SkiaPaint` and assign it to a node's `paint` prop:

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { SkiaPaint } from '@three-flatland/skia'

    const paint = new SkiaPaint(skia).setFill()
    paint.setLinearGradient(0, 0, 200, 0,
      [0xFFFF0000, 0xFF0000FF], [0, 1])

    rect.paint = paint
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { SkiaPaint } from '@three-flatland/skia'
    import { useSkiaContext } from '@three-flatland/skia/react'

    function GradientRect() {
      const skia = useSkiaContext()!
      const [paint] = useState(() => new SkiaPaint(skia).setFill())

      useFrame(({ elapsed }) => {
        paint.setLinearGradient(0, 0, 200, 0,
          [0xFFFF0000, 0xFF0000FF], [0, 1])
      })

      return <skiaRect paint={paint} x={0} y={0} width={200} height={50} />
    }
    ```
  </TabItem>
</Tabs>

:::tip[useState for WASM Objects]
In React, create `SkiaPaint` and `SkiaPath` with `useState(() => ...)` initializers instead of `useMemo`. The `useState` initializer runs exactly once and survives React strict mode double-mounts, while `useMemo` can re-evaluate and cause WASM handles to be disposed unexpectedly.
:::

## Further Reading

- [Skia Guide](../../guides/skia/) — Concepts and API reference
- [Basic Sprite](../basic-sprite/) — Three-flatland sprites
- [TSL Nodes](../tsl-nodes/) — Shader nodes

</ExampleDetailLayout>

# Slug Text

> GPU-accelerated resolution-independent text rendering.

import { Tabs, TabItem } from 'starlight-theme/components'
import ExampleDetailLayout from '../../../components/ExampleDetailLayout.astro'
import { loadExample } from '../../../utils/loadExample'

export const threeFiles = loadExample('three', 'slug-text')
export const reactFiles = loadExample('react', 'slug-text')

<ExampleDetailLayout slug="slug-text" threeFiles={threeFiles} reactFiles={reactFiles}>

## What This Example Shows

This example demonstrates [`@three-flatland/slug`](../../guides/slug-text/) — GPU-accelerated text rendering that stays crisp at any zoom. Glyphs are evaluated as quadratic Bezier curves per-pixel in the fragment shader; there's no SDF atlas, no bitmap textures, no resolution ceiling.

| Feature                 | Demonstrated                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------- |
| Pixel-perfect rendering | A long Lorem passage at multiple sizes                                                |
| Multi-font fallback     | `SlugFontStack` mixing Inter + FontAwesome icons in one paragraph                     |
| Outlines                | `SlugText.outline` with runtime-uniform width + color, 60 % grey default              |
| Measurement             | Live `font.measureText` overlay aligned to the rendered text                          |
| Decorations             | Underline / strikethrough / super-sub via `StyleSpan[]`                               |
| Canvas2D compare        | Onion / split / diff modes against `CanvasRenderingContext2D` for visual parity check |

## Loading a Font

`SlugFontLoader.load()` is the single entry point. It tries baked data (a single `.slug.glb`) first and falls back to runtime parsing of TTF/OTF/WOFF — opentype.js is dynamic-imported only on the runtime path, so baked-only bundles ship without it.

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { SlugFontLoader } from '@three-flatland/slug'

    const font = await SlugFontLoader.load('/fonts/Inter-Regular.ttf')
    ```

  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { useLoader } from '@react-three/fiber/webgpu'
    import { SlugFontLoader } from '@three-flatland/slug/react'

    // Inside a component within <Canvas>, wrapped in <Suspense>
    const font = useLoader(SlugFontLoader, '/fonts/Inter-Regular.ttf')
    ```

  </TabItem>
</Tabs>

## Rendering Text

`SlugText` extends `InstancedMesh` — each glyph is an instanced quad evaluated per-pixel by the Slug fragment shader. Set `.text`, `.fontSize`, `.align` etc. and call `.update(camera)` once per frame.

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { SlugText } from '@three-flatland/slug'

    const text = new SlugText({
      font,
      text: 'Hello, Slug!',
      fontSize: 48,
      color: 0xffffff,
      align: 'center',
    })
    scene.add(text)

    function animate() {
      requestAnimationFrame(animate)
      text.update(camera)
      renderer.render(scene, camera)
    }
    ```

  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { extend, useFrame, useThree } from '@react-three/fiber/webgpu'
    import { SlugText } from '@three-flatland/slug/react'
    import { useRef } from 'react'

    extend({ SlugText })

    function Text({ font }) {
      const ref = useRef(null)
      const camera = useThree((s) => s.camera)
      useFrame(() => ref.current?.update(camera))

      return (
        <slugText
          ref={ref}
          font={font}
          text="Hello, Slug!"
          fontSize={48}
          color={0xffffff}
          align="center"
        />
      )
    }
    ```

  </TabItem>
</Tabs>

## Outlines

Pass an `outline` option (or set `.outline` at runtime) to add a stroked outline behind the fill. Width and color are runtime uniforms — scrub them live, no rebuild.

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    const text = new SlugText({
      font,
      text: 'Hello, Slug!',
      fontSize: 96,
      color: 0xffffff,
      outline: { width: 0.025, color: 0x999999 },
    })

    // Animate later — uniform-only, no rebuild
    text.setOutlineWidth(0.05)
    text.setOutlineColor(0xff0000)
    ```

  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    <slugText
      font={font}
      text="Hello, Slug!"
      fontSize={96}
      color={0xffffff}
      outline={{ width: 0.025, color: 0x999999 }}
    />
    ```
  </TabItem>
</Tabs>

## Multi-font Fallback

`SlugFontStack` composes multiple fonts and resolves missing codepoints per-character. `SlugStackText` renders one `InstancedMesh` per backing font, all parented under a `Group`.

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { SlugFontStack, SlugStackText } from '@three-flatland/slug'

    const [inter, faIcons] = await Promise.all([
      SlugFontLoader.load('/fonts/Inter-Regular.ttf'),
      SlugFontLoader.load('/fonts/fa-solid-900.ttf'),
    ])
    const stack = new SlugFontStack([inter, faIcons])

    const text = new SlugStackText({
      fontStack: stack,
      text: 'Lorem  search', // last char is a FontAwesome icon
      fontSize: 48,
    })
    ```

  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { extend } from '@react-three/fiber/webgpu'
    import { SlugStackText, SlugFontStack } from '@three-flatland/slug/react'

    extend({ SlugStackText })

    function StackedText({ fonts }) {
      const stack = useMemo(() => new SlugFontStack(fonts), [fonts])
      return <slugStackText fontStack={stack} text="Lorem  search" fontSize={48} />
    }
    ```

  </TabItem>
</Tabs>

## Further Reading

- [Slug Text Guide](../../guides/slug-text/) — Full API reference and patterns (measurement, decorations, pre-baking).
- [TSL Nodes](../tsl-nodes/) — Custom shader effects via Three Shader Language.

</ExampleDetailLayout>

# Tilemap

> Render tile-based maps efficiently with three-flatland.

import ExampleDetailLayout from '../../../components/ExampleDetailLayout.astro'
import { loadExample } from '../../../utils/loadExample'

export const threeFiles = loadExample('three', 'tilemap')
export const reactFiles = loadExample('react', 'tilemap')

<ExampleDetailLayout
  slug="tilemap"
  threeFiles={threeFiles}
  reactFiles={reactFiles}
>

## Tilemap Setup

Load a map file and create a `TileMap2D`. Both `TiledLoader` and `LDtkLoader` return a `TileMapData` structure that `TileMap2D` consumes:

```typescript
import { TileMap2D, TiledLoader } from 'three-flatland';

const mapData = await TiledLoader.load('/maps/level1.json');

const tilemap = new TileMap2D({
  data: mapData,
  chunkSize: 16, // Tiles per chunk (default: 16)
});

scene.add(tilemap);
```

This example procedurally generates its own `TileMapData` at runtime to show how to build a dungeon from scratch without a Tiled file — see `main.ts` for the BSP generator.

## Layers

Access individual layers by index to toggle visibility or read/write tiles:

```typescript
const groundLayer = tilemap.getLayerAt(0);
const wallsLayer = tilemap.getLayerAt(1);

// Toggle visibility
groundLayer.visible = false;

// Read/write tiles at a position
const gid = groundLayer.getTileAt(x, y);
wallsLayer.setTileAt(x, y, newGid);
```

## Animated Tiles

Call `update(deltaMs)` each frame to advance tile animations defined in the source map:

```typescript
function animate() {
  const deltaMs = /* time since last frame */;
  tilemap.update(deltaMs);
  renderer.render(scene, camera);
}
```

## Further Reading

- [Tilemaps Guide](../../guides/tilemaps/) - Advanced tilemap features
- [Batch Rendering](../batch-demo/) - Other optimization techniques

</ExampleDetailLayout>

# TSL Nodes

> Create custom shader effects using Three Shader Language nodes.

import { Tabs, TabItem } from 'starlight-theme/components'
import ExampleDetailLayout from '../../../components/ExampleDetailLayout.astro'
import { loadExample } from '../../../utils/loadExample'

export const threeFiles = loadExample('three', 'tsl-nodes')
export const reactFiles = loadExample('react', 'tsl-nodes')

<ExampleDetailLayout
  slug="tsl-nodes"
  threeFiles={threeFiles}
  reactFiles={reactFiles}
>

## What This Example Shows

This example demonstrates the **Material Effect** system — the recommended way to create per-sprite shader effects. It showcases 8 visual modes on an animated sprite:

| Effect | Description |
|--------|-------------|
| Normal | No effect — base sprite rendering |
| Damage Flash | Additive white flash that fades out |
| Dissolve | Pixelated noise-based dissolve |
| Powerup | Continuous hue rotation (rainbow) |
| Petrify | Desaturation to grayscale |
| Select | Green outline around sprite |
| Shadow | Dark blue tint with reduced alpha |
| Pixelate | Resolution reduction and restoration |

## Defining Effects

Effects are defined with `createMaterialEffect`, which takes a schema for per-sprite data and a TSL node builder:

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { createMaterialEffect } from 'three-flatland'
    import { tintAdditive, hueShift } from '@three-flatland/nodes'
    import { vec4 } from 'three/tsl'

    const DamageFlash = createMaterialEffect({
      name: 'damageFlash',
      schema: { intensity: 1 } as const,
      node: ({ inputColor, attrs }) => {
        const flashed = tintAdditive(inputColor, [1, 1, 1], attrs.intensity)
        return vec4(flashed.rgb.mul(inputColor.a), inputColor.a)
      },
    })

    const Powerup = createMaterialEffect({
      name: 'powerup',
      schema: { angle: 0 } as const,
      node: ({ inputColor, attrs }) => hueShift(inputColor, attrs.angle),
    })
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { createMaterialEffect } from 'three-flatland/react'
    import { tintAdditive, hueShift } from '@three-flatland/nodes'
    import { vec4 } from 'three/tsl'

    const DamageFlash = createMaterialEffect({
      name: 'damageFlash',
      schema: { intensity: 1 } as const,
      node: ({ inputColor, attrs }) => {
        const flashed = tintAdditive(inputColor, [1, 1, 1], attrs.intensity)
        return vec4(flashed.rgb.mul(inputColor.a), inputColor.a)
      },
    })

    const Powerup = createMaterialEffect({
      name: 'powerup',
      schema: { angle: 0 } as const,
      node: ({ inputColor, attrs }) => hueShift(inputColor, attrs.angle),
    })
    ```
  </TabItem>
</Tabs>

## Applying Effects at Runtime

Instantiate an effect, add it to a sprite, and animate its properties:

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    const flash = new DamageFlash()
    sprite.addEffect(flash)

    // Animate in render loop
    flash.intensity = Math.max(0, 1 - elapsed / 0.3)

    // Switch effects
    sprite.removeEffect(flash)
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    const flash = useMemo(() => new DamageFlash(), [])

    useEffect(() => {
      sprite.addEffect(flash)
      return () => sprite.removeEffect(flash)
    }, [sprite, flash])

    useFrame((_, delta) => {
      flash.intensity = Math.max(0, flash.intensity - delta / 0.3)
    })
    ```
  </TabItem>
</Tabs>

## Further Reading

- [TSL Nodes Guide](../../guides/tsl-nodes/) - Full node reference and Material Effect documentation
- [Tilemap](../tilemap/) - Tile-based map rendering

</ExampleDetailLayout>

# Installation

> Install three-flatland in your project.

import { Tabs, TabItem, Aside } from 'starlight-theme/components';

<Aside type="caution" title="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.
</Aside>

## Package Manager

<Tabs syncKey="pkg">
  <TabItem label="npm" icon="simple-icons:npm">
    ```bash
    npm install three-flatland three koota
    ```
  </TabItem>
  <TabItem label="pnpm" icon="simple-icons:pnpm">
    ```bash
    pnpm add three-flatland three koota
    ```
  </TabItem>
  <TabItem label="yarn" icon="simple-icons:yarn">
    ```bash
    yarn add three-flatland three koota
    ```
  </TabItem>
  <TabItem label="bun" icon="simple-icons:bun">
    ```bash
    bun add three-flatland three koota
    ```
  </TabItem>
  <TabItem label="agents" icon="lucide:sparkles">
    ```text title="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
    ```
  </TabItem>
</Tabs>

### React Three Fiber (Optional)

React is not required. If you're using React Three Fiber, add the additional dependencies:

<Tabs syncKey="pkg">
  <TabItem label="npm" icon="simple-icons:npm">
    ```bash
    npm install three-flatland @react-three/fiber@alpha
    ```
  </TabItem>
  <TabItem label="pnpm" icon="simple-icons:pnpm">
    ```bash
    pnpm add three-flatland @react-three/fiber@alpha
    ```
  </TabItem>
  <TabItem label="yarn" icon="simple-icons:yarn">
    ```bash
    yarn add three-flatland @react-three/fiber@alpha three koota react react-dom
    ```
  </TabItem>
  <TabItem label="bun" icon="simple-icons:bun">
    ```bash
    bun add three-flatland @react-three/fiber@alpha
    ```
  </TabItem>
  <TabItem label="agents" icon="lucide:sparkles">
    ```text title="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
    ```
  </TabItem>
</Tabs>

## 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](/three-flatland/llm-prompts/) for more prompts and machine-readable documentation.

# Introduction

> High-performance 2D sprite and effects library for Three.js using WebGPU and TSL.

import FeatureList from '../../../components/FeatureList.astro';
import { Aside } from 'starlight-theme/components';

**three-flatland** is a high-performance 2D sprite and effects library for [Three.js](https://threejs.org/) and [React Three Fiber](https://r3f.docs.pmnd.rs/), using WebGPU and TSL (Three Shader Language).

If you're already in a Three.js project and just want pixels on screen, jump to the [Quick Start](../quick-start/) — you'll be back here later for the *why*.

<Aside type="caution" title="Alpha">
  three-flatland is in active development. We're exploring performant, maintainable, and extensible patterns for GPU-driven 2D rendering with WebGPU. The API will evolve as we refine these systems. [Follow along on GitHub](https://github.com/thejustinwalsh/three-flatland) — your feedback shapes what we build.
</Aside>

## Features

<FeatureList features={[
  { icon: "lightbulb", title: "WebGPU + WebGL", description: "One TSL node graph emits both WebGPU and WebGL2 at 1:1 parity" },
  { icon: "list", title: "Batch Rendering", description: "Automatic batching for thousands of sprites" },
  { icon: "user", title: "React Three Fiber", description: "First-class R3F integration with JSX components" },
  { icon: "play-circle", title: "Animation System", description: "Spritesheet support with frame-based timing" },
  { icon: "sparkles", title: "TSL Shader Nodes", description: "Composable effects: palette swaps, outlines, glow" },
  { icon: "map", title: "Tilemap Support", description: "Tiled editor format with animated tiles" },
]} />

## Packages

| Package | Description |
|---------|-------------|
| `three-flatland` | Core sprite system, materials, rendering, and React Three Fiber integration |
| `@three-flatland/nodes` | TSL shader nodes for custom effects |
| `@three-flatland/presets` | Pre-configured effect presets |

## Requirements

- **Three.js** >= 0.183.1 (required for TSL/WebGPU support)
- **React** >= 19.2.0 (for React packages)
- **@react-three/fiber** >= 10.0.0-alpha.2 (for React packages)

## Next steps

- [Quick Start](../quick-start/) — pixels on screen in a few lines.
- [Sprites](../../guides/sprites/), [2D Lighting](../../guides/lighting/), and [Batch Rendering](../../guides/batch-rendering/) — the core guides.
- [API Reference](/three-flatland/api/) — generated type docs for every package.

# Quick Start

> Get up and running with three-flatland in minutes.

import { Tabs, TabItem } from 'starlight-theme/components';

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

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { WebGPURenderer } from 'three/webgpu';
    import { Scene, OrthographicCamera } from 'three';
    import { Sprite2D, TextureLoader } from 'three-flatland';

    async function main() {
      // Create scene and camera
      const scene = new Scene();
      const aspect = window.innerWidth / window.innerHeight;
      const camera = new OrthographicCamera(-200 * aspect, 200 * aspect, 200, -200, 0.1, 1000);
      camera.position.z = 100;

      // Create WebGPU renderer
      const renderer = new WebGPURenderer({ antialias: true });
      renderer.setSize(window.innerWidth, window.innerHeight);
      document.body.appendChild(renderer.domElement);
      await renderer.init();

      // 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();
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { Suspense } from 'react';
    import { Canvas, extend, useLoader } from '@react-three/fiber/webgpu';
    import { Sprite2D, TextureLoader } from 'three-flatland/react';

    extend({ Sprite2D });

    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={{ zoom: 5, position: [0, 0, 100] }}>
          <Suspense>
            <Sprite />
          </Suspense>
        </Canvas>
      );
    }
    ```
  </TabItem>
</Tabs>

:::caution[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](../../guides/sprites/) - Position, scale, and customize sprites
- [Add animation](../../guides/animation/) - Animate sprites with spritesheets
- [Batch rendering](../../guides/batch-rendering/) - Optimize for thousands of sprites
- [Browse examples](../../examples/basic-sprite/) - Interactive code examples

Want a live performance dashboard during development? See the [Devtools guide](../../guides/devtools/).

# Animation

> Animate sprites using spritesheets and frame-based animation.

import { Tabs, TabItem } from 'starlight-theme/components';
import Diagram from '../../../components/Diagram.astro';
import animationPipeline from '../../../assets/diagrams/animation-pipeline.svg?raw';

**What you'll learn**
- How to load a spritesheet (TexturePacker / Aseprite JSON) and define an `animationSet`
- How to drive playback with `play / pause / resume / stop` plus `onFrame` and `onComplete` callbacks
- How `update(deltaMs)` fits into your render loop and how `speed` scales it

---

three-flatland supports frame-based animation using spritesheets. The `AnimatedSprite2D` class works with `SpriteSheetLoader` to load and play animations.

If you've ever wired up sprite animation by hand — frame timers, wraparound math, swap textures on each tick — this is the part you don't have to write anymore.

<Diagram caption="The animation data path — atlas frames are grouped into named clips, then play() picks the active clip and update(deltaMs) advances its frames over time." src={animationPipeline} />

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { AnimatedSprite2D, SpriteSheetLoader, Layers } from 'three-flatland';

    // Load spritesheet (texture presets automatically applied)
    const spriteSheet = await SpriteSheetLoader.load('/sprites/character.json');

    // Create animated sprite
    const sprite = new AnimatedSprite2D({
      spriteSheet,
      animationSet: {
        fps: 10, // Default fps for all animations
        animations: {
          idle: {
            frames: ['idle_0', 'idle_1', 'idle_2', 'idle_3'],
            fps: 8,
            loop: true,
          },
          run: {
            frames: ['run_0', 'run_1', 'run_2', 'run_3'],
            fps: 12,
            loop: true,
          },
          jump: {
            frames: ['jump_0', 'jump_1', 'jump_2'],
            fps: 10,
            loop: false,
          },
        },
      },
      animation: 'idle', // Start with idle animation
      layer: Layers.ENTITIES,
    });

    sprite.scale.set(64, 64, 1);
    scene.add(sprite);

    // In your animation loop
    function animate() {
      const deltaMs = /* time since last frame */;
      sprite.update(deltaMs);
      renderer.render(scene, camera);
    }
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { Suspense, useRef } from 'react';
    import { extend, useFrame, useLoader } from '@react-three/fiber/webgpu';
    import { AnimatedSprite2D, SpriteSheetLoader, Layers } from 'three-flatland/react';

    extend({ AnimatedSprite2D });

    function Character() {
      // useLoader suspends while loading, presets applied automatically
      const spriteSheet = useLoader(SpriteSheetLoader, '/sprites/character.json');
      const spriteRef = useRef<AnimatedSprite2D>(null);

      useFrame((_, delta) => {
        spriteRef.current?.update(delta * 1000);
      });

      return (
        <animatedSprite2D
          ref={spriteRef}
          spriteSheet={spriteSheet}
          animationSet={{
            fps: 10,
            animations: {
              idle: { frames: ['idle_0', 'idle_1', 'idle_2', 'idle_3'], fps: 8, loop: true },
              run: { frames: ['run_0', 'run_1', 'run_2', 'run_3'], fps: 12, loop: true },
            },
          }}
          animation="idle"
          layer={Layers.ENTITIES}
          scale={[64, 64, 1]}
        />
      );
    }

    // Wrap with Suspense in parent
    function App() {
      return (
        <Suspense fallback={null}>
          <Character />
        </Suspense>
      );
    }
    ```
  </TabItem>
</Tabs>

## Animation Set Definition

The `animationSet` option provides a structured way to define multiple animations:

```typescript
animationSet: {
  fps: 12, // Default fps (optional)
  animations: {
    idle: {
      frames: ['frame_0', 'frame_1', 'frame_2'], // Frame names from spritesheet
      fps: 8,           // Override default fps (optional)
      loop: true,       // Loop animation (default: true)
      pingPong: false,  // Play forward then backward (optional)
    },
    attack: {
      frames: ['attack_0', 'attack_1', 'attack_2'],
      fps: 15,
      loop: false,
    },
  },
}
```

## Playback Control

```typescript
sprite.play('run');              // Play animation by name
sprite.pause();                  // Pause at current frame
sprite.resume();                 // Resume paused animation
sprite.stop();                   // Stop and reset
sprite.gotoFrame(3);             // Jump to specific frame

// Check animation state
sprite.isPlaying();              // Is any animation playing?
sprite.isPlaying('run');         // Is 'run' animation playing?
sprite.currentAnimation;         // Get current animation name
```

## Playback Speed

```typescript
sprite.speed = 1.5;  // 1.5x speed
sprite.speed = 0.5;  // Half speed
sprite.speed = 2;    // Double speed
```

## Animation Callbacks

Use the `play()` method's options to handle animation events:

```typescript
sprite.play('attack', {
  onFrame: (frameIndex) => {
    console.log('Frame:', frameIndex);
    if (frameIndex === 2) {
      // Trigger damage on specific frame
      dealDamage();
    }
  },
  onComplete: () => {
    // Animation finished (non-looping only)
    sprite.play('idle');
  },
});
```

## Loading Spritesheets

The `SpriteSheetLoader` supports Aseprite JSON format. Texture presets (like `NearestFilter` for pixel art) are automatically applied:

```typescript
import { SpriteSheetLoader } from 'three-flatland';

// Load spritesheet (presets automatically applied)
const spriteSheet = await SpriteSheetLoader.load('/sprites/character.json');

// Access frame data
const frame = spriteSheet.getFrame('idle_0');
console.log(frame); // { x, y, width, height, sourceWidth, sourceHeight, ... }
```

:::tip[Texture Configuration]
See the [Loaders guide](../loaders/#texture-presets) to configure presets for smooth or pixel-art rendering.
:::

## Update Loop

The `update(deltaMs)` method must be called each frame to advance the animation:

```typescript
let lastTime = performance.now();

function animate() {
  const now = performance.now();
  const deltaMs = now - lastTime;
  lastTime = now;

  // Update all animated sprites
  sprite.update(deltaMs);

  renderer.render(scene, camera);
  requestAnimationFrame(animate);
}
```

## Next steps

- [Animation example](../../examples/animation/) — a spritesheet-driven `AnimatedSprite2D` in a runnable scene.
- [`AnimatedSprite2D` API reference](/three-flatland/api/three-flatland/src/classes/animatedsprite2d/) — the full animation-set and playback surface.
- [Sprites](../sprites/) for the underlying `Sprite2D`, and [Loaders](../loaders/) for loading spritesheets.

# Baking

> Offline asset-baking pipeline — flatland-bake CLI, sidecar files, hash stamps, and dev-time staleness warnings.

import { Tabs, TabItem } from 'starlight-theme/components';
import Diagram from '../../../components/Diagram.astro';
import bakedNormalPipeline from '../../../assets/diagrams/baked-normal-pipeline.svg?raw';

**What you'll learn**
- How `flatland-bake` produces sidecar PNGs (`<asset>.normal.png`) with stamped content hashes
- How the runtime probe decides between the baked sidecar and an in-memory bake fallback
- How to wire baking into a CI / build script so production never pays runtime bake cost

---

`@three-flatland/bake` is a generic asset-pipeline framework: discovery, sidecar PNGs with stamped hashes, and dev-time staleness warnings. It ships standalone today with one consumer — `@three-flatland/normals`, which contributes the offline normal-map baker via the `flatland-bake normal` subcommand. Future bake types (lightmap atlases, font SDFs, occlusion atlases) plug into the same machinery.

You only need this page when you're ready to *ship*. During development, the runtime bake fallback handles everything — no CLI step, no extra files. Read on when first-paint cost shows up in production.

For the runtime side of the same pipeline — how `SpriteSheetLoader` and `LDtkLoader` consume baked siblings via `normals: true` — see the [Baked Normal Pipeline](../loaders/#baked-normal-pipeline) section of the Loaders guide. This page is the *workflow* counterpart: how to run the baker offline, integrate it into CI, and reason about staleness.

## The Bake Pipeline at a Glance

<Diagram caption="The baked-normal pipeline — probe for a hash-stamped sidecar, load it on a match, or fall back to an in-memory bake; forceRuntime skips the probe." src={bakedNormalPipeline} />

- **Source asset** — a sprite sheet PNG (plus its TexturePacker JSON), an LDtk tileset, or any other texture the runtime wants enriched. Lives in your project's `public/` (or equivalent) directory.
- **Bake step** — `flatland-bake <type> <source>` runs the registered baker (currently `normal`) and writes a sidecar file (`<source>.normal.png`) next to the source. The sidecar carries the descriptor's content hash stamped into a PNG `tEXt` chunk under the `flatland` keyword.
- **Runtime** — a sidecar-aware loader (`SpriteSheetLoader` / `LDtkLoader` with `normals: true`, or `resolveNormalMap` directly) hashes the descriptor it would have used, range-fetches the sidecar's first ~4 KB to read the stamp, and uses the baked file when the hashes match. On miss it falls back to an in-memory bake and emits a dev-time warning.

The pipeline is fully renderer-agnostic — the baker doesn't depend on Three.js, and the sidecar is a plain RGBA PNG with metadata. Any 2D engine can consume the same files.

## CLI

The `flatland-bake` binary is the entry point. It walks `node_modules` (and the cwd package), discovers any package with a `flatland.bake` manifest in its `package.json`, and dispatches `<subcommand>` to the matching baker.

```bash
# List every baker installed in the current project
npx flatland-bake --list

# Run the normal-map baker on a single PNG
npx flatland-bake normal ./public/sprites/knight.png

# Per-baker help (forwards `--help` to the registered baker)
npx flatland-bake normal --help
```

### `flatland-bake normal`

Contributed by `@three-flatland/normals`. Reads an RGBA PNG, derives a tangent-space normal map, and writes `<input>.normal.png` (or the second positional path) stamped with the descriptor hash.

```bash
npx flatland-bake normal <input.png> [output.png] [options]

# Flat-tilt convenience flags (whole-image)
--direction <dir>      flat | up | down | left | right | north | … (default: flat)
--pitch <radians>      tilt angle from flat (default: π/4)
--bump <mode>          alpha | none (default: alpha)
--strength <n>         gradient multiplier (default: 1)

# Region-aware baking
--descriptor <path>    JSON descriptor — frames, tiles, cap/face splits, per-region tilt
```

Use the flat flags for simple per-frame work. For tilemaps where each tile carries different cap/face geometry, write a JSON descriptor and pass it via `--descriptor`. The `scripts/bake-dungeon-normals.ts` script in the repo is a worked example: it reads tile `customData` out of an LDtk project, synthesizes a region-aware descriptor with `tilesetToRegions`, and bakes the tileset PNG.

## Sidecar Files & Hash Stamping

The baker writes a sibling PNG next to the source. Naming follows a fixed convention per baker type:

| Source | Sidecar |
|--------|---------|
| `knight.png` | `knight.normal.png` |
| `Dungeon_Tileset.png` | `Dungeon_Tileset.normal.png` |

The hash lives **inside the PNG itself** as a `tEXt` chunk under the keyword `flatland`. The chunk's value is JSON: `{"hash":"<fnv1a64 of the descriptor>","v":1}`. Placement is intentional — the chunk is injected immediately after `IHDR`, near the head of the file, so a runtime probe can range-fetch the first ~4 KB and read the stamp without downloading the whole image.

The hash itself (`hashDescriptor` in the public API) is an FNV-1a 64-bit hash over a canonical (sorted-keys) JSON stringification of the descriptor. Stable across browser and node, no dependencies, no cryptographic guarantees — just a cheap content fingerprint for invalidation.

When the runtime probes the sidecar:

1. `HEAD` request to confirm the sibling exists.
2. `Range: bytes=0-4095` to read the PNG header chunks.
3. Parse the `flatland` `tEXt` chunk and compare its `hash` to what the loader would have used.
4. **Match** → load the baked PNG directly. **Mismatch** → re-bake in memory and warn.

## Dev-Time Staleness Warnings

`devtimeWarn` is the shared warning channel — gated on `NODE_ENV !== 'production'` and deduped per `(category, url)` so the same message never fires twice. Sidecar-aware loaders use it uniformly across the ecosystem (currently just `normal`; future bakers slot into the same surface).

Two warning shapes you'll see while iterating:

```
[normal] /sprites/knight.normal.png exists but its descriptor hash is stale — re-baking in memory.
         Run `npx flatland-bake normal /sprites/knight.png --descriptor <descriptor>.json` to refresh.

[normal] No baked sibling at /sprites/knight.normal.png — baking in memory.
         Run `npx flatland-bake normal` in production to skip this path.
```

The canonical fix is to **re-bake** — run `flatland-bake` with the same descriptor your loader is using, the hash matches, the warning goes away. Don't reach for `forceRuntime` here: that flag declares "this asset's normal map is generated in the browser as a matter of architecture" (see [Browser-generated assets](#browser-generated-assets) below), not "shut this warning up while I iterate." Silencing the warn the wrong way buries the signal — the engine still gives you the data, but future maintainers lose the breadcrumb pointing at the missing bake step.

## CI / Build Integration

`flatland-bake` is CLI-only today — there's no Vite or Rollup plugin yet. The recommended pattern is a `package.json` script that runs ahead of your main build:

```json
{
  "scripts": {
    "bake:assets": "flatland-bake normal ./public/sprites/knight.png && flatland-bake normal ./public/sprites/enemies.png",
    "build": "pnpm bake:assets && vite build"
  }
}
```

For tilemaps and other multi-region descriptors, drive the bake from a small `tsx` script that synthesizes the descriptor and calls `bakeNormalMapFile` directly — see `scripts/bake-dungeon-normals.ts` in the repo for a worked LDtk example. Commit the resulting `*.normal.png` (and the `*.normal.json` descriptor, if you keep one) alongside your source assets so deploys don't have to re-bake.

The output PNGs are deterministic for a given descriptor — same input, same hash stamp, same bytes. Re-running the bake is a no-op when nothing changed, which makes incremental builds and `git diff` review straightforward.

## When to Bake Offline vs Runtime

:::tip[Performance note]
Both paths produce identical pixel data — the in-memory bake and `flatland-bake` share the same `bakeNormalMap` core. The choice is about *when* the work happens, not what comes out. Iterate runtime; ship offline.
:::

The choice is about *when* the work happens:

| Mode | Cost | Best For |
|------|------|----------|
| **Offline** (`flatland-bake` in CI) | Zero startup cost, deterministic, ships a slightly larger asset bundle (the sidecar) | Production builds, demos, anything user-facing |
| **Runtime** (in-memory fallback) | Burns first-load CPU on `fetch` + decode + bake; non-deterministic timing | Development iteration, tweaking descriptors, experimenting with custom data |
| **Browser-generated** (`forceRuntime: true`) | Same as runtime, plus no probe round-trip and no warning | Assets whose normal map is produced in the browser by design — procedural content, throwaway prototypes, asset bundles where the sidecar isn't worth shipping |

In production, ship baked siblings and the loader becomes a single-image-fetch with no decode overhead. In development, skip the bake step entirely and let the runtime regenerate — much faster than re-running the CLI on every descriptor tweak.

## Browser-Generated Assets

`forceRuntime: true` declares **the browser is where this asset's normal map is produced** — not the CI bake step. The contract that "if you ask for normals, you get normals" doesn't change; only *where* the bake runs does.

It's a project-level architectural choice about a specific asset, not a dev-iteration shortcut. Typical reasons to make that choice:

- **Procedurally varied content** — the descriptor changes per session, so a pre-baked sidecar wouldn't match anyway.
- **Throwaway prototypes** — you don't want to add a CI step for something you'll delete next week.
- **Lean asset bundles** — the runtime CPU cost on first load is cheaper than the bytes the sidecar would add.

```typescript
// "This sheet's normal map is produced in the browser. No sidecar exists."
const sheet = await SpriteSheetLoader.load('./sprites/proc-tiles.json', {
  normals: true,
  forceRuntime: true,
})
```

If you just want to silence a stale-sidecar warning while iterating, **re-bake** instead. `forceRuntime` is the wrong tool for that — it silences the warn but it also tells every future maintainer "this asset's normals are produced in the browser, on purpose, forever," which is a different statement about the project's architecture.

## Adding a New Bake Type

`@three-flatland/bake` is the generic framework; `@three-flatland/normals` is the model implementation. A new bake type lives in its own package, declares a `flatland.bake` manifest entry in its `package.json` pointing at a default-exported `Baker`, and reuses `hashDescriptor` + `writeSidecarPng` from `@three-flatland/bake/node` to stamp its outputs. On the runtime side it imports `bakedSiblingURL`, `probeBakedSibling`, and `devtimeWarn` from `@three-flatland/bake` to wire up the same probe-then-fallback flow. Once published, `flatland-bake --list` picks up the subcommand automatically — no central registry, no version coupling.

## Related Reading

- **Runtime side of the normal pipeline** — [Loaders → Baked Normal Pipeline](../loaders/#baked-normal-pipeline)
- **Wiring baked normals into lighting** — [Lighting → NormalMapProvider](../lighting-setup/#normalmapprovider)
- **Elevation channel and elevation-aware shadows** — [Shadows → Elevation-Aware Shadows](../shadows/#elevation-aware-shadows)

# Batch Rendering

> How automatic batching works and tips for optimal performance.

import { Tabs, TabItem } from 'starlight-theme/components';
import Diagram from '../../../components/Diagram.astro';
import batchingPipeline from '../../../assets/diagrams/batching-pipeline.svg?raw';

SpriteGroup automatically batches sprites that share the same material into single draw calls. You don't need to do anything special—just add sprites and the batching happens behind the scenes.

The defaults are tuned for the common case (thousands of sprites, one or two materials). You almost never need to think about batching — but on the day you do, this page is the map.

## How It Works

When you add sprites to a `SpriteGroup`, they're grouped by material and layer into efficient GPU batches. Systems run automatically during Three.js rendering — no manual `update()` call needed.

<Diagram caption="The batch pipeline — sprites group by material and layer into instanced batches packed in one interleaved buffer, with a bucketed dirty tracker and branchless effect gating." src={batchingPipeline} />

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { Sprite2D, SpriteGroup, Sprite2DMaterial } from 'three-flatland';

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

    // These sprites share a material, so they batch together
    const material = new Sprite2DMaterial({ map: spriteSheet });

    for (let i = 0; i < 1000; i++) {
      const sprite = new Sprite2D({ material });
      sprite.position.set(Math.random() * 100, Math.random() * 100, 0);
      spriteGroup.add(sprite);
    }

    // In your render loop — no update() call needed
    function animate() {
      renderer.render(scene, camera);
      requestAnimationFrame(animate);
    }
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { useMemo } from 'react';
    import { extend } from '@react-three/fiber/webgpu';
    import { Sprite2D, SpriteGroup, Sprite2DMaterial } from 'three-flatland/react';

    extend({ Sprite2D, SpriteGroup, Sprite2DMaterial });

    function Particles({ count = 1000, spriteSheet }) {
      // Create shared material
      const material = useMemo(() => new Sprite2DMaterial({ map: spriteSheet }), [spriteSheet]);

      // Generate random positions once
      const positions = useMemo(
        () => Array.from({ length: count }, () => [Math.random() * 100, Math.random() * 100, 0]),
        [count]
      );

      return (
        <spriteGroup>
          {positions.map((pos, i) => (
            <sprite2D key={i} material={material} position={pos} />
          ))}
        </spriteGroup>
      );
    }
    ```
  </TabItem>
</Tabs>

## Renderer Options

The `SpriteGroup` constructor accepts optional batch configuration:

```typescript
const spriteGroup = new SpriteGroup({
  maxBatchSize: 8192,        // Max sprites per batch (default: 8192)
  autoSort: true,            // Enable automatic sorting (default: true)
  frustumCulling: true,      // Enable frustum culling (default: true)
  autoInvalidateTransforms: true, // Auto-sync transforms every frame (default: true)
});
scene.add(spriteGroup);
```

## Automatic Change Detection

Property changes on sprites are detected automatically through the ECS. When you update a sprite's tint, alpha, flip, frame, layer, or position, the renderer syncs only the changed data to the GPU on the next frame. No manual invalidation needed.

```typescript
// Just change properties — the renderer handles the rest
sprite.tint = [1, 0, 0];
sprite.alpha = 0.5;
sprite.layer = Layers.UI;
sprite.position.x += 10;
```

## Performance Monitoring

Check batch efficiency with the `stats` property:

```typescript
const stats = spriteGroup.stats;

console.log(`Sprites: ${stats.spriteCount}`);
console.log(`Batches: ${stats.batchCount}`);
console.log(`Visible: ${stats.visibleSprites}`);

// Draw calls aren't part of stats — read them from the renderer:
console.log(`Draw calls: ${renderer.info.render.calls}`);
```

**Goal:** Keep `batchCount` low relative to `spriteCount`. If you have 1000 sprites but 100 batches, you're not batching efficiently.

## Optimization Tips

### Share Materials

:::tip[Performance note]
Sprites only batch together when they share the **same material instance** — not just the same texture, the same `new Sprite2DMaterial(...)` reference. Allocating a fresh material per sprite is the easiest way to silently tank batching.
:::

```typescript
// Good: One material, one batch
const material = new Sprite2DMaterial({ map: atlas });
sprites.forEach(s => s.material = material);

// Bad: Many materials, many batches
sprites.forEach(s => {
  s.material = new Sprite2DMaterial({ map: atlas }); // Creates new batch each time!
});
```

### Use Texture Atlases

Combine textures into a single atlas. All sprites using the atlas can share one material:

```typescript
// Load a sprite sheet with frame data
const { texture, frames } = await SpriteSheetLoader.load('/sprites/atlas.json');

const material = new Sprite2DMaterial({ map: texture });

// Different frames, same material = same batch
const player = new Sprite2D({ material, frame: frames.get('player') });
const enemy = new Sprite2D({ material, frame: frames.get('enemy') });
```

### Organize by Layer

Sprites are sorted by layer before batching. Keep related sprites on the same layer:

```typescript
import { Layers } from 'three-flatland';

// Background sprites batch together
backgrounds.forEach(s => s.layer = Layers.BACKGROUND);

// Entity sprites batch together
entities.forEach(s => s.layer = Layers.ENTITIES);
```

## Custom Materials

If you're authoring a custom `Sprite2DMaterial` subclass — or a stand-alone TSL shader that consumes the same per-instance data — you read from the interleaved instance buffer that every batch shares.

### Interleaved instance buffer layout

import bufferDataflow from '../../../assets/diagrams/instance-buffer-dataflow.svg?raw';

<Diagram caption="Per-instance data flow: CPU → GPU → TSL accessors" src={bufferDataflow} />

Each `SpriteBatch` allocates a single `InstancedInterleavedBuffer` with **stride = 16 floats per instance**. Four named attribute views look into that buffer:

| Attribute | Type | Floats | Contents |
|-----------|------|--------|----------|
| `instanceUV` | `vec4` | 0..3 | Atlas UV rect — `x, y, w, h` for the sprite's frame in the atlas. |
| `instanceColor` | `vec4` | 4..7 | Per-instance tint and alpha — `r, g, b, a`. |
| `instanceSystem` | `vec4` | 8..11 | `[flipX, flipY, systemFlags, enableBits]`. |
| `instanceExtras` | `vec4` | 12..15 | `[shadowRadius, reserved, reserved, reserved]`. |

`flipX` and `flipY` are `+1` (unflipped) or `-1` (flipped). `systemFlags` is an integer bitfield:

| Bit | Mask | Meaning |
|-----|------|---------|
| 0 | `LIT_FLAG_MASK` | Sprite receives lighting. |
| 1 | `RECEIVE_SHADOWS_MASK` | Sprite's lit fragments may be darkened by the shadow trace. |
| 2 | `CAST_SHADOW_MASK` | Sprite contributes to the occlusion pre-pass. |
| 3..23 | reserved | — |

`enableBits` is the active-MaterialEffect bitmask: bit `N` is set while the `N`th registered effect is active on the instance (24 slots, see `EFFECT_BIT_OFFSET`). System bits and effect-enable bits live in different vec4 components on purpose so adding system flags never costs an effect slot.

Effect-specific data — the per-instance uniform fields declared in a `MaterialEffect` schema — lives on **separate** instanced attributes named `effectBuf0`, `effectBuf1`, … allocated only when at least one registered effect declares per-instance fields. This is a change from the previous layout where system data and effect data shared `effectBuf0`.

### TSL helpers

`packages/three-flatland/src/materials/instanceAttributes.ts` exports the recommended accessors for use inside TSL nodes. They hide the packed layout and stay forward-compatible if the buffer is rearranged:

| Helper | Returns | Reads |
|--------|---------|-------|
| `readFlip()` | `vec2` | `instanceSystem.xy` (±1 per axis) |
| `readSystemFlags()` | `int` | `instanceSystem.z` (raw bitfield) |
| `readEnableBits()` | `int` | `instanceSystem.w` (effect-active mask) |
| `readShadowRadius()` | `float` | `instanceExtras.x` |
| `readLitFlag()` | `bool` | bit 0 of system flags |
| `readReceiveShadowsFlag()` | `bool` | bit 1 of system flags |
| `readCastShadowFlag()` | `bool` | bit 2 of system flags |

Don't call `attribute('instanceSystem', 'vec4')` directly unless you specifically need the raw vec4 — the helpers keep the call site readable and survive layout changes.

### Example — fade unlit sprites with `colorTransform`

A custom `colorTransform` that crossfades between two tints based on each sprite's `lit` flag, applied per-instance from the same batch:

```typescript
import { vec4 } from 'three/tsl'
import { Sprite2DMaterial, readLitFlag } from 'three-flatland'

const material = new Sprite2DMaterial({
  map: atlas,
  colorTransform: (ctx) => {
    const litColor = ctx.color.rgb
    const dimColor = ctx.color.rgb.mul(0.4)
    const isLit = readLitFlag()
    return vec4(isLit.select(litColor, dimColor), ctx.color.a)
  },
})
```

Lit sprites in this batch render at full color; sprites with `lit = false` render dimmed — all from the same draw call.

For the broader `colorTransform` / `MaterialEffect` API and where it sits in the pipeline, see the [Pass Effects guide](../pass-effects/). For the Sprite2D-side accessors that drive these flags (`lit`, `receiveShadows`, `castsShadow`, `shadowRadius`), see the [Sprites guide](../sprites/).

## Next Steps

- [Flatland Guide](../flatland/) — Wrap SpriteGroup with camera, post-processing, and global uniforms
- [Sprites Guide](../sprites/) — Sprite2D properties and configuration
- [Pass Effects Guide](../pass-effects/) — MaterialEffect / colorTransform reference

# Devtools

> Vite plugin, browser dashboard, and in-page Tweakpane pane for live performance monitoring, batch inspection, and per-frame instrumentation.

import { Tabs, TabItem } from 'starlight-theme/components';
import DevtoolsDemo from '../../../components/DevtoolsDemo.astro';

**What you'll learn**
- How to wire the Vite plugin and open the browser dashboard at `/.devtools`
- How to mount the in-page Tweakpane via `createPane` / `usePane` with the auto-cycling stats graph
- How to register custom CPU arrays and GPU textures in the dashboard with `registerDebug*`

---

three-flatland ships a unified devtools system: a vite plugin plus a browser dashboard for live performance monitoring and per-frame instrumentation, and an in-page Tweakpane pane (`createPane` / `usePane`) that auto-mounts a cycling FPS/MS/GPU/MEM graph and a compact stats row. Both surfaces talk to your scene over the same `BroadcastChannel` bus — your scene is the **provider**, the dashboard and the pane are **consumers**. The producer side stays decoupled from any UI; you can run either, both, or neither.

## Try it

The lighting example is running below — click the button to pop the dashboard into a new tab. Move it to a side window, then drive the example: drag a torch, toggle a preset, scrub the slime count. Every counter updates in real time.

<DevtoolsDemo type="three" name="lighting" />

If you've never opened the dashboard before, that's the loop — your scene is the provider, the new tab is the consumer, and the bus connects them automatically because they share an origin. Most performance questions answer themselves once you can see the graph.

When enabled, your scene exposes per-frame stats (FPS, CPU ms, GPU ms, draw calls, triangles, geometries, textures, heap), the active batch list, and any custom CPU buffers or GPU textures you choose to register.

import AnnotatedImage from '../../../components/AnnotatedImage.astro';

<AnnotatedImage
  src="/three-flatland/diagrams/devtools-dashboard.png"
  alt="three-flatland devtools dashboard showing stats bar, buffers, texture preview, batches, registry, and protocol log"
  hotspots={[
    { x: 22, y: 5, label: 'Stats bar — FPS, CPU, GPU, draws, tris, geos, tex, heap with sparklines' },
    { x: 8, y: 24, label: 'Buffers — registered CPU arrays, click an entry to preview' },
    { x: 42, y: 26, label: 'Texture preview — selected DataTexture or RenderTarget rendered live' },
    { x: 30, y: 60, label: 'Batches — active sprite batches grouped by material with pass breakdown' },
    { x: 30, y: 86, label: 'Registry + LightStore.data — registered debug arrays with histograms' },
    { x: 84, y: 30, label: 'Protocol log — bus traffic stream, filterable and pausable' },
  ]}
  caption="Each panel is independently subscribable — collapsing a panel stops the corresponding data collection on the producer side too."
/>

## Vite Plugin Setup

The dashboard is served as middleware by your Vite dev server. Add the plugin to your `vite.config.ts`:

```ts
import { defineConfig } from 'vite'
import { threeFlatlandDevtools } from '@three-flatland/devtools/vite'

export default defineConfig({
  plugins: [
    threeFlatlandDevtools(),
    // ...your other plugins
  ],
})
```

That's it. Run `vite dev` and open the dashboard at `http://localhost:<port>/.devtools` — the plugin logs the URL on startup.

### Options

```ts
threeFlatlandDevtools({
  path: '/.devtools', // URL the dashboard mounts under (default)
})
```

| Option | Default | Description |
|--------|---------|-------------|
| `path` | `'/.devtools'` | URL path the dashboard is served under. Change if `/.devtools` collides with one of your app routes. |

:::note[Dev-only]
The plugin sets `apply: 'serve'` internally — it's inert during production builds. The dashboard's source files (Preact UI, vendored deps) never reach your bundle. If you also disable the build-time `DEVTOOLS_BUNDLED` flag (see [Production Gating](#production-gating) below), every devtools branch in your scene code is dead-code-eliminated too.
:::

:::caution[Microfrontend / proxy setups]
The dashboard's own assets are served by Vite via `/@fs/`, `/@vite/client`, and `node_modules/.vite/` — none of which are namespaced under the mount path. If your app sits behind a proxy (microfrontends, reverse proxy, etc.), open the dashboard at the underlying Vite port directly rather than the proxy origin.
:::

## Scene-Side Wiring (Flatland)

Flatland users have nothing to wire up. When `DEVTOOLS_BUNDLED` is true (Vite sets `import.meta.env.DEV` in dev) and `isDevtoolsActive()` returns true at runtime, Flatland constructs its own `DevtoolsProvider` in its constructor and pumps stats into the bus on every `flatland.render(renderer)` call:

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```ts
    import { Flatland } from 'three-flatland'
    import { WebGPURenderer } from 'three/webgpu'

    const renderer = new WebGPURenderer()
    await renderer.init()

    const flatland = new Flatland({ viewSize: 400 })
    // ...add sprites, lights, passes...

    function animate() {
      requestAnimationFrame(animate)
      flatland.render(renderer) // begin/end frame happens inside
    }
    animate()
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { Canvas, useFrame, useThree, extend } from '@react-three/fiber/webgpu'
    import { Flatland } from 'three-flatland/react'
    import { useRef } from 'react'
    import type { WebGPURenderer } from 'three/webgpu'

    extend({ Flatland })

    function Scene() {
      const flatlandRef = useRef(null)
      const gl = useThree((s) => s.gl)
      useFrame(() => {
        flatlandRef.current?.render(gl as unknown as WebGPURenderer)
      }, { phase: 'render' })
      return <flatland ref={flatlandRef} viewSize={80}>{/* ... */}</flatland>
    }

    export default function App() {
      return (
        <Canvas orthographic camera={{ zoom: 5, position: [0, 0, 100] }}>
          <Scene />
        </Canvas>
      )
    }
    ```
  </TabItem>
</Tabs>

Open `http://localhost:5173/.devtools` (or wherever your Vite server is listening) and the dashboard discovers the Flatland-system provider automatically.

The runtime gate `isDevtoolsActive()` returns `false` when `window.__FLATLAND_DEVTOOLS__ === false`, giving you a per-page opt-out without rebuilding.

:::tip[Performance note]
The provider is a no-op stub when devtools isn't active, so per-frame cost stays negligible even when no dashboard is connected. Leaving devtools wiring in your scene code is free in production.
:::

## Scene-Side Wiring (Plain Three.js)

If you're driving three.js directly — no Flatland — call `createDevtoolsProvider()` from `three-flatland` and bracket your render call with `beginFrame` / `endFrame`:

```ts
import { createDevtoolsProvider } from 'three-flatland'
import { WebGPURenderer } from 'three/webgpu'

const renderer = new WebGPURenderer()
await renderer.init()

const devtools = createDevtoolsProvider({ name: 'my-app' })

function animate() {
  requestAnimationFrame(animate)
  devtools.beginFrame(performance.now(), renderer)
  renderer.render(scene, camera)
  devtools.endFrame(renderer)
}
animate()

// On teardown:
devtools.dispose()
```

The handle exposes:

| Method | Description |
|--------|-------------|
| `beginFrame(now, renderer)` | Mark the start of a logical frame. `now` should be `performance.now()`. |
| `endFrame(renderer)` | Mark the end of the frame. Resolves GPU timestamps and kicks any subscribed texture readbacks. |
| `dispose()` | Tear down the bus connection. Idempotent. |
| `disposed` | Becomes `true` after `dispose()`. |

Multi-pass renderers (SDF pass, occlusion pass, post-processing) work correctly: every `renderer.render()` between `beginFrame` and `endFrame` aggregates into one logical frame's `renderer.info` delta — they don't get counted as separate frames.

In production (when `DEVTOOLS_BUNDLED` is `false`), `createDevtoolsProvider` returns a no-op stub; `beginFrame`/`endFrame`/`dispose` all become empty calls that minify away.

## In-Page Tweakpane Controls

`@three-flatland/devtools` wraps [Tweakpane v4](https://tweakpane.github.io/docs/) with a Flatland-themed pane that mounts directly into your page. Because it consumes the same bus as the standalone dashboard, the pane needs no scene wiring of its own — it discovers any provider the page has constructed and streams stats from it.

:::note[Alpha package]
The examples in this repo consume `@three-flatland/devtools` via workspace linking today. An npm release is planned; until then, copy `packages/devtools/src/` into your own monorepo.
:::

### Installation

<Tabs syncKey="pkg">
  <TabItem label="npm">
    ```bash
    npm install @three-flatland/devtools tweakpane @tweakpane/plugin-essentials
    ```
  </TabItem>
  <TabItem label="pnpm">
    ```bash
    pnpm add @three-flatland/devtools tweakpane @tweakpane/plugin-essentials
    ```
  </TabItem>
  <TabItem label="yarn">
    ```bash
    yarn add @three-flatland/devtools tweakpane @tweakpane/plugin-essentials
    ```
  </TabItem>
  <TabItem label="bun">
    ```bash
    bun add @three-flatland/devtools tweakpane @tweakpane/plugin-essentials
    ```
  </TabItem>
</Tabs>

Peer dependencies: `three >= 0.183`, `tweakpane ^4.0.5`, `@tweakpane/plugin-essentials ^0.2.1`. For the React entry: `@react-three/fiber >= 10.0.0-alpha.2`, `react >= 19`.

Two entry points:

- `@three-flatland/devtools` — vanilla: `createPane`, `DevtoolsClient`, `applyTheme`, `FLATLAND_THEME`.
- `@three-flatland/devtools/react` — hooks: `usePane`, `usePaneFolder`, `usePaneInput`, `usePaneButton`, `useFpsGraph`.

### What You Get

Calling `createPane()` (or `usePane()`) gives you:

1. **Collapsible header** with a pin toggle — the pane dims while the cursor is elsewhere and pins fully opaque when clicked.
2. **Cycling stats graph** — click to cycle `fps → ms → gpu → mem`. GPU mode only shows up when the renderer supports timestamp queries (see below). Values are interpolated between batches so the polyline scrolls smoothly rather than stepping 4× per second.
3. **Compact stats row** — five columns: `draws · triangles · primitives · geometries · textures`, auto-formatted (`1.2K`, `10M`).
4. **Multi-provider switcher** — a `◀ name ▶` blade that appears automatically when two or more providers are present on the bus.
5. **Flatland theme** matching the docs aesthetic.

There are no extra wiring calls. The pane has zero knowledge of your scene, your renderer, or your frame loop — it discovers a provider on the bus and streams stats. If your app already constructs a Flatland (or calls `createDevtoolsProvider` per the section above), the pane just works.

### Three.js Usage

```typescript
import { WebGPURenderer } from 'three/webgpu'
import { createPane } from '@three-flatland/devtools'

const renderer = new WebGPURenderer()
await renderer.init()

const { pane, update: updateDevtools } = createPane({ driver: 'manual' })

const params = { speed: 1.0, color: '#99d9ef' }
pane.addBinding(params, 'speed', { min: 0, max: 5 })
pane.addBinding(params, 'color')

function animate() {
  requestAnimationFrame(animate)
  flatland.render(renderer)   // or your own renderer.render() call
  updateDevtools()            // drives the graph's interpolation RAF
}
animate()
```

`driver: 'manual'` disables the pane's fallback `requestAnimationFrame`; you drive the graph from your existing loop, avoiding a second rAF (which Safari throttles on backgrounded tabs). If you omit `driver`, the pane starts its own rAF and `update()` becomes a no-op — fine for quick throwaway apps, preferred to avoid in anything production-shaped.

#### GPU timing

You don't enable GPU timing yourself. When devtools is active the provider opts the renderer into timestamp queries on its own; when devtools is off no queries are issued, so production builds never accumulate an undrained query pool. Don't pass `trackTimestamp: true` on the renderer.

On WebGPU, the adapter must expose `GPUFeatureName.TimestampQuery` (most desktop browsers). On WebGL2, `EXT_disjoint_timer_query_webgl2` must be present. Values trail by ~1 frame because the readback is async. The pane silently hides `gpu` from the mode cycle when unsupported.

### React Usage

The React hook is R3F-aware: it internally forces `driver: 'manual'` and registers a `useFrame(update, 1000)` at a late priority so the graph tick runs AFTER R3F's auto-render, capturing the true end-of-frame `renderer.info`.

```tsx
import { Canvas, useFrame } from '@react-three/fiber/webgpu'
import {
  usePane,
  usePaneFolder,
  usePaneInput,
  usePaneButton,
} from '@three-flatland/devtools/react'

function Scene() {
  const { pane } = usePane()

  const folder = usePaneFolder(pane, 'Sprite')
  const [speed] = usePaneInput(folder, 'speed', 1.0, { min: 0, max: 5 })
  const [color] = usePaneInput(folder, 'color', '#99d9ef')
  usePaneButton(folder, 'Reset', () => console.log('reset'))

  useFrame((_, delta) => {
    // use `speed` / `color` — each input change triggers a React re-render
  })

  return <>{/* sprites, meshes */}</>
}

export default function App() {
  return (
    <Canvas>
      <Scene />
    </Canvas>
  )
}
```

:::caution[Must live inside `<Canvas>`]
`usePane` calls `useFrame` under the hood, so the component using it has to render inside `<Canvas>`. The pane DOM is mounted to `document.body` with `z-index: 1000` so it still floats above the canvas.
:::

#### React hook reference

| Hook | Purpose |
|---|---|
| `usePane(options?)` | Create the pane. Returns `{ pane, update }`. Internally runs `useFrame(update, 1000)` — you don't need to call `update` yourself. |
| `usePaneFolder(parent, title, options?)` | Collapsible folder. Returns `FolderApi`. |
| `usePaneInput(parent, key, initial, options?)` | Bind an input. Returns `[value, setValue]` — each change triggers a React re-render. |
| `usePaneButton(parent, title, onClick)` | Button blade. Uses a callback ref so `onClick` is never stale. |
| `useFpsGraph(parent)` | Standalone cycling stats graph when you aren't using `usePane`. |

All hooks create bindings synchronously during render (so controls appear without pop-in) and defer disposal across React Strict Mode's cleanup / re-mount cycle.

### Bus Architecture (for the curious)

The pane, the dashboard, and the provider all communicate via two `BroadcastChannel`s:

- **Discovery channel** (`flatland-debug`) — carries only `provider:announce` / `provider:query` / `provider:gone`. Lightweight, shared by everyone.
- **Per-provider data channel** (`flatland-debug:<providerId>`) — one per provider. Carries `subscribe` / `subscribe:ack` / `ack` / `unsubscribe` / `data` / `ping`. Scoped by name so subscribers only see their chosen provider's traffic; providers don't field unrelated clients' messages.

Stats samples are collected per frame into pre-allocated typed-array ring buffers on the provider side (scaled encodings: `fps × 10` as `Int16`, `ms × 100` as `Uint16`, counts as `Uint32`) and flushed in batches every `STATS_BATCH_MS` (default 250 ms). The client decodes into Float32 rings on arrival and exposes both a per-frame series (for the polyline) and a scalar batch mean (for the text label — naturally smoothed).

The graph's RAF reads from those rings and slides the visible window through the newest samples over the inter-batch window, producing smooth motion from a 4 Hz batch stream.

### Theme

```typescript
import { Pane } from 'tweakpane'
import { applyTheme, FLATLAND_THEME } from '@three-flatland/devtools'

const pane = new Pane({ title: 'Controls' })
applyTheme(pane.element, FLATLAND_THEME)
```

`applyTheme` sets CSS custom properties on the pane element — fork `FLATLAND_THEME` (it's a plain object) to tweak colours without touching the package.

### Pane Options

```typescript
createPane({
  title: 'Controls',    // Pane header title (default: 'Controls')
  expanded: true,       // Initial expansion state (default: true)
  driver: 'manual',     // 'manual' (caller drives update()) or 'raf' (fallback rAF)
  container,            // Custom container element (optional)
})
```

## Dashboard Panels

The dashboard renders four panels driven by feature subscriptions. Each panel is independently subscribable — collapse a panel and its data stops being collected on the producer side too.

### Stats panel

A grid of cards, one per counter. Each card shows the current value and a sparkline of recent samples:

| Counter | What it measures |
|---------|------------------|
| `fps` | End-to-end frame rate from `endFrame` intervals. |
| `cpu` | `endFrame - beginFrame` (full frame CPU cost). |
| `gpu` | GPU timestamp delta — `—` unless the adapter supports timestamp queries (devtools enables tracking itself when active). |
| `draws` | `renderer.info.render.calls` delta over the frame. |
| `tris` | Triangle count. |
| `prims` | Primitive count. |
| `geos` | Live `BufferGeometry` count. |
| `tex` | Live `Texture` count. |
| `heap` | JS heap used (Chromium only — falls back to `—` elsewhere). |

Click a card to open a detail histogram with min, p50, mean, p95, p99, and max over the recent window.

### Batches panel

Live list of active sprite batches grouped by material, plus per-batch counts and any `kind` / `label` annotations the engine attaches (e.g. `chunk(0,2)` for tile chunks). Useful for confirming that sprites you expect to share a material actually do — see the [Batch Rendering guide](../batch-rendering/) for the underlying behavior.

### Buffers panel

Registered CPU arrays — `Float32Array`, `Uint32Array`, `Int32Array`. Each entry shows its label, length, kind (`float` / `uint` / `int`), and a small histogram. The engine itself uses this to expose tile-light counts, scoring buffers, and similar internal state; you can register your own (see below).

### Texture registry

Registered `DataTexture` and `RenderTarget` outputs, viewable as images. Readbacks are async — the dashboard only triggers them when a texture is selected for preview, so leaving things registered is free until somebody actually opens the panel.

## Custom Debug Instrumentation

Anything your scene already keeps in CPU memory or in a render target can show up in the dashboard. The `register*` calls are no-op when devtools isn't bundled, so they're safe to leave permanently in engine code.

### CPU arrays

Use `registerDebugArray` once, then `touchDebugArray` whenever you mutate the contents in place. Don't allocate a new buffer per frame — pass a stable reference and let the registry pick up changes:

```ts
import {
  registerDebugArray,
  touchDebugArray,
  unregisterDebugArray,
} from 'three-flatland'

const tileCounts = new Uint32Array(numTiles)

registerDebugArray('forwardPlus.tileCounts', tileCounts, 'uint', {
  label: 'Forward+ tile light counts',
})

function updateTiles() {
  // ...mutate tileCounts in place...
  touchDebugArray('forwardPlus.tileCounts')
}

// On dispose:
unregisterDebugArray('forwardPlus.tileCounts')
```

| Argument | Type | Notes |
|----------|------|-------|
| `name` | `string` | Stable identifier — also the key passed to `touch*` / `unregister*`. |
| `ref` | `Float32Array \| Uint32Array \| Int32Array` | Held by reference; the registry reads it lazily on flush. |
| `kind` | `'float' \| 'uint' \| 'int'` | Drives the dashboard's histogram + formatting. |
| `opts.label` | `string?` | Human-readable label shown in the panel. |
| `opts.length` | `number?` | Logical length when the typed array is over-sized (capacity vs. live count). |

### Textures and render targets

Same pattern, with `registerDebugTexture` / `touchDebugTexture` / `unregisterDebugTexture`. Accepts a `DataTexture` directly, or any `{ width, height, texture }` object — `RenderTarget`s satisfy that shape:

```ts
import {
  registerDebugTexture,
  touchDebugTexture,
  unregisterDebugTexture,
} from 'three-flatland'

// CPU-backed texture
registerDebugTexture('lightStore.lights', lightsDataTexture, 'rgba32f', {
  label: 'Lights DataTexture',
})

// Render target (any object with width/height/texture)
registerDebugTexture('shadowMap', shadowRT, 'rgba16f', {
  label: 'Shadow trace output',
  display: 'colors',
})

function updateLights() {
  // ...write to the texture...
  touchDebugTexture('lightStore.lights')
}
```

Pixel types: `'rgba8'` (default) | `'rgba16f'` | `'rgba32f'` | `'r32f'` | `'r32u'` | `'r32i'`. Display modes hint at how the dashboard should render the data (heatmap vs. raw colors).

### How the engine itself uses this

The lighting and tile pipelines lean on the same APIs. Treat them as canonical examples:

- **`LightStore`** registers `'lightStore.data'` (the row-packed Float32 backing array) and `'lightStore.lights'` (the DataTexture itself), then calls `touchDebugArray` / `touchDebugTexture` after every write.
- **`ForwardPlusLighting`** registers per-tile light counts, scoring buffers, and fill-in-range arrays — handy when tuning the [per-category fill quotas](../lighting-setup/#per-category-quota-tuning), because the dashboard surfaces exactly which buckets are saturated.

Both unregister on dispose to keep the registry tidy across hot-reloads.

## Production Gating

Two layers turn the entire devtools subsystem off:

### Build-time: `DEVTOOLS_BUNDLED`

A module-scoped `const` evaluated from `import.meta.env.DEV` and `import.meta.env.VITE_FLATLAND_DEVTOOLS` at build time. When both are falsy, the constant folds to `false`, every `if (DEVTOOLS_BUNDLED) { ... }` branch becomes dead code, and terser removes it. The Tweakpane theme, the bus transport, the readback paths — none of it ends up in your production bundle.

| Build flag | `window.__FLATLAND_DEVTOOLS__` | Result |
|------------|-------------------------------|--------|
| `DEV=true` or `VITE_FLATLAND_DEVTOOLS=true` | `undefined` | Enabled (default on in dev) |
| `DEV=true` or `VITE_FLATLAND_DEVTOOLS=true` | `false` | Disabled at runtime |
| `DEV=true` or `VITE_FLATLAND_DEVTOOLS=true` | `true` | Enabled (explicit) |
| Neither | (anything) | Dead code — not in bundle |

You can force-enable devtools in a non-dev environment by setting `VITE_FLATLAND_DEVTOOLS=true` in `.env.production` or similar — useful for staging builds where you want the dashboard available without `DEV` semantics.

### Runtime: `isDevtoolsActive()`

Only reachable when `DEVTOOLS_BUNDLED` is true. Reads `window.__FLATLAND_DEVTOOLS__` as an opt-out — set it to `false` before three-flatland loads and Flatland skips constructing its provider, even though the code is in the bundle. You can flip it per-page:

```html
<script>window.__FLATLAND_DEVTOOLS__ = false</script>
```

This is a one-way switch: rogue clients can't enable devtools that wasn't bundled, so it's safe even if `__FLATLAND_DEVTOOLS__` somehow leaks into a production bundle.

## Next Steps

- [Pass Effects guide](../pass-effects/) — Many of the lighting fields you'll see in the dashboard come from `DefaultLightEffect`'s schema.
- [Batch Rendering guide](../batch-rendering/) — Background for what the dashboard's Batches panel is showing you.
- [Basic Sprite example](../../examples/basic-sprite/) — See `createPane` + `driver: 'manual'` in context.
- [Pass Effects example](../../examples/pass-effects/) — Same pattern inside a custom render phase.

# Flatland

> Self-contained 2D rendering pipeline with camera, post-processing, and global uniforms.

import { Tabs, TabItem } from 'starlight-theme/components';

`Flatland` is the high-level entry point for three-flatland. It wraps a `SpriteGroup` with an orthographic camera, global uniforms, post-processing pipeline, and render target support into a single object.

If you're new and not sure whether you need `Flatland` or `SpriteGroup` — start here. The table below tells you when to graduate.

## When to Use Flatland vs SpriteGroup

| | Flatland | SpriteGroup |
|---|---------|-------------|
| **Use case** | Self-contained 2D pipeline | Embed sprites into your own scene |
| **Camera** | Internal orthographic camera | You provide the camera |
| **Post-processing** | Built-in pass effect pipeline | Not included |
| **Global uniforms** | Automatic time, viewport, tint | Not included |
| **Render call** | `flatland.render(...)` | `renderer.render(...)` |

Use `Flatland` when you want a complete 2D rendering setup. Use `SpriteGroup` when you need to mix sprites into an existing 3D scene with your own camera and render loop.

## Basic Setup

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { WebGPURenderer } from 'three/webgpu'
    import { Flatland, Sprite2D, TextureLoader } from 'three-flatland'

    const renderer = new WebGPURenderer()
    await renderer.init()
    document.body.appendChild(renderer.domElement)

    const flatland = new Flatland({ viewSize: 400, clearColor: 0x1a1a2e })
    const texture = await new TextureLoader().loadAsync('/sprites/hero.png')

    flatland.add(new Sprite2D({ texture }))

    function animate() {
      flatland.resize(window.innerWidth, window.innerHeight)
      flatland.render(renderer)
      requestAnimationFrame(animate)
    }
    animate()
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { useRef, useEffect } from 'react'
    import { Canvas, extend, useFrame, useThree } from '@react-three/fiber/webgpu'
    import { Flatland, Sprite2D, Sprite2DMaterial } from 'three-flatland/react'
    import type { Flatland as FlatlandType } from 'three-flatland/react'
    import type { WebGPURenderer } from 'three/webgpu'

    extend({ Flatland, Sprite2D, Sprite2DMaterial })

    function Scene() {
      const flatlandRef = useRef<FlatlandType>(null)
      const { renderer, size } = useThree()

      useEffect(() => {
        flatlandRef.current?.resize(size.width, size.height)
      }, [size.width, size.height])

      // Render in the 'render' phase so R3F skips its own render
      useFrame(() => {
        flatlandRef.current?.render(renderer as unknown as WebGPURenderer)
      }, { phase: 'render' })

      return (
        <flatland ref={flatlandRef} viewSize={400} clearColor={0x1a1a2e}>
          <sprite2D texture={texture} />
        </flatland>
      )
    }

    export default function App() {
      return (
        <Canvas renderer={{ antialias: false }}>
          <Scene />
        </Canvas>
      )
    }
    ```
  </TabItem>
</Tabs>

:::caution[R3F render phase]
In React Three Fiber, register `flatland.render()` in the **render phase** (`{ phase: 'render' }`). This tells R3F to skip its default render and lets Flatland control rendering. Game logic and ECS updates should run in the default update phase.
:::

## Constructor Options

```typescript
const flatland = new Flatland({
  viewSize: 400,         // Orthographic view height in world units
  clearColor: 0x1a1a2e,  // Background color
  clearAlpha: 1,          // Background alpha (< 1 for transparent)
  autoClear: true,        // Clear before each render
  postProcessing: false,  // Enable post-processing pipeline
  aspect: 1,              // Initial aspect ratio (use resize() to update)
  camera: null,           // Custom OrthographicCamera (null = internal)
  renderTarget: null,     // RenderTarget (null = render to viewport)
})
```

See the [FlatlandOptions API reference](/three-flatland/api/interfaces/flatlandoptions/) for full type details.

## Adding Objects

`flatland.add()` routes objects automatically:

- **Sprite2D** instances go to the internal `SpriteGroup` for batched rendering
- **Light2D** instances are tracked for the lighting system
- **Other Object3D** instances are added directly to the internal scene

```typescript
// Sprite2D → batched via SpriteGroup
const sprite = new Sprite2D({ texture, anchor: [0.5, 0.5] })
flatland.add(sprite)

// Light2D → tracked by lighting system
const light = new Light2D({ type: 'point', position: [50, 50], color: 0xff6600 })
flatland.add(light)

// Other Three.js objects → added to internal scene
const mesh = new Mesh(geometry, material)
flatland.add(mesh)
```

Global uniforms are automatically wired to each sprite's material on `add()`.

## Lighting

Flatland manages 2D lighting with `Light2D` sources and a `LightEffect` pipeline. Activate lighting by calling `setLighting()` with a preset:

```typescript
import { DefaultLightEffect } from '@three-flatland/presets'

flatland.setLighting(new DefaultLightEffect())
```

All sprites receive lighting by default. Set `lit: false` to opt out:

```typescript
const indicator = new Sprite2D({ texture, lit: false }) // always full brightness
```

| Method / Property | Description |
|--------|-------------|
| `setLighting(effect)` | Set the active LightEffect (or `null` to disable) |
| `lighting` | Current LightEffect (read-only) |
| `lights` | All tracked Light2D instances (read-only) |

See the [2D Lighting guide](../lighting/) for preset comparisons, Light2D types, and custom effects.

## Render Loop

import Diagram from '../../../components/Diagram.astro';
import framePipeline from '../../../assets/diagrams/frame-pipeline.svg?raw';

<Diagram caption="Per-frame render pipeline" src={framePipeline} />

Each frame, call `resize()` to sync the aspect ratio, then `render()` to draw:

```typescript
function animate() {
  flatland.resize(canvas.width, canvas.height)
  flatland.render(renderer)
  requestAnimationFrame(animate)
}
```

`resize()` updates the internal camera frustum and render target dimensions. `render()` syncs global uniforms (time, viewport), updates sprite batches, and draws everything.

## Global Uniforms

Every Flatland instance exposes a `globals` object with shared uniforms. These update once per frame and are available to all sprite materials via TSL nodes.

| Uniform | Description |
|---------|-------------|
| `time` | Elapsed seconds (`undefined` = auto) |
| `globalTint` | Color tint for all sprites |
| `viewportSize` | Viewport size in pixels |
| `pixelRatio` | Device pixel ratio |
| `wind` | Wind direction and strength |
| `fogColor` | Fog color |
| `fogRange` | Fog near/far range |

### Auto vs Manual Time

By default, `time` is `undefined` and Flatland accumulates elapsed time automatically. Set it to a number for manual control:

```typescript
// Auto mode (default) — time accumulates each frame
flatland.globals.time = undefined

// Manual mode — set exact value
flatland.globals.time = performance.now() / 1000
```

### Using Uniforms in TSL

Access the TSL node directly for custom material effects:

```typescript
import { Sprite2DMaterial } from 'three-flatland'

const material = new Sprite2DMaterial({
  colorTransform: (ctx) => {
    // Use the global tint node in a custom effect
    const tinted = ctx.color.rgb.mul(flatland.globals.globalTintNode)
    return tinted.toVec4(ctx.color.a)
  }
})
```

Each global has a corresponding TSL node: `timeNode`, `globalTintNode`, `viewportSizeNode`, `pixelRatioNode`, `windNode`, `fogColorNode`, `fogRangeNode`.

## Statistics

Monitor batching with `flatland.spriteGroup.stats`:

```typescript
const stats = flatland.spriteGroup.stats

console.log(`Sprites: ${stats.spriteCount}`)
console.log(`Batches: ${stats.batchCount}`)
console.log(`Visible: ${stats.visibleSprites}`)
```

Draw calls aren't part of `stats` — read them from the renderer after a frame: `renderer.info.render.calls` reflects actual GPU work.

## Post-Processing

Add full-screen pass effects with `addPass()`:

```typescript
import { Flatland, createPassEffect } from 'three-flatland'
import { posterize } from '@three-flatland/nodes'

const PosterizePass = createPassEffect({
  name: 'posterize',
  schema: { bands: 6 },
  pass: ({ uniforms }) => (input, uv) => posterize(input, uniforms.bands),
})

const flatland = new Flatland({ viewSize: 400 })
const post = new PosterizePass()
flatland.addPass(post)

// Zero-cost parameter updates
post.bands = 10
```

The render pipeline auto-initializes on the first `addPass()` call. Passes chain in insertion order — each receives the previous pass's output.

:::tip[Performance note]
Adding the first pass switches Flatland onto the render-pipeline path: the scene renders to an offscreen target, then each pass runs as a full-screen draw. One or two passes are cheap; a long chain costs a full-screen sample per pass per frame, so fuse effects into a single pass where you can.
:::

| Method | Description |
|--------|-------------|
| `addPass(pass, order?)` | Add a pass effect |
| `removePass(pass)` | Remove a specific pass |
| `clearPasses()` | Remove all passes |
| `passes` | Read-only array of current passes |

See the [Pass Effects guide](../pass-effects/) for creating custom effects and the full node library.

## Render to Texture

Render Flatland output to a texture for use in 3D scenes:

```typescript
import { RenderTarget } from 'three'

const target = new RenderTarget(512, 512)
const flatland = new Flatland({ renderTarget: target })

// Use the texture on a 3D mesh
mesh.material.map = flatland.texture

// Each frame: render 2D first, then 3D
flatland.render(renderer)
renderer.render(scene3D, camera3D)
```

## Disposal

Clean up all resources when done:

```typescript
flatland.dispose()
```

This destroys the ECS world, sprite batches, render pipeline, and all pass effect entities.

## Next Steps

- [2D Lighting](../lighting/) — Light2D sources and LightEffect presets
- [Pass Effects](../pass-effects/) — Full-screen post-processing effects
- [Batch Rendering](../batch-rendering/) — How sprite batching works under the hood
- [TSL Nodes](../tsl-nodes/) — Per-sprite material effects and low-level TSL usage
- [Breakout Showcase](../../showcases/breakout/) — A complete game built with Flatland

# 2D Lighting

> How Flatland's Forward+ tiled lighting works — Light2D sources, the per-tile slot budget, and the SDF shadow pass.

import Compare from '../../../components/Compare.astro';
import Diagram from '../../../components/Diagram.astro';
import tileSlotBudget from '../../../assets/diagrams/tile-slot-budget.svg?raw';
import lightingDataflow from '../../../assets/diagrams/lighting-dataflow.svg?raw';

<Compare
  beforeSrc="/three-flatland/diagrams/lighting-off.webm"
  afterSrc="/three-flatland/diagrams/lighting-on.webm"
  beforePoster="/three-flatland/diagrams/lighting-off-poster.jpg"
  afterPoster="/three-flatland/diagrams/lighting-on-poster.jpg"
  beforeLabel="Lighting off"
  afterLabel="DefaultLightEffect on"
  aspectRatio="1497 / 807"
  zoom={1.5}
  alt="Two synchronized recordings of the dungeon scene — same animations, same point in time, with and without DefaultLightEffect bound."
/>

three-flatland provides a complete 2D lighting system. Add `Light2D` instances as light sources, choose a `LightEffect` preset to control how lights affect sprites, and all sprites receive lighting by default.

You don't need to understand Forward+, SDF tracing, or per-tile slot allocation to make a torch work — drop a `DefaultLightEffect` in, add a `Light2D`, your sprite gets lit. This page is the mental model: how lights reach the GPU, why dense scenes have a slot budget, and where shadows fit. For the step-by-step setup, the `Light2D` field reference, and the quota-tuning knobs, see the [Lighting guide](../lighting-setup/).

## How It Works

1. **Light2D** — scene graph objects that define light sources (point, spot, directional, ambient)
2. **LightEffect** — a shader pipeline that reads all lights and produces per-fragment lighting
3. **Sprites** — all sprites receive lighting by default when a LightEffect is active (set `lit: false` to opt out)

Flatland manages the lifecycle: it collects lights, syncs them to a GPU texture each frame, and applies the active LightEffect to all lit sprites.

<Diagram caption="The per-frame light data path — Light2D instances are collected and synced to a GPU light store, which the LightEffect shader reads to light every sprite." src={lightingDataflow} />

`DefaultLightEffect`, the recommended preset, runs Forward+ tiled lighting: the screen is divided into tiles, each tile culls the lights that can't reach it, and the fragment shader iterates only the survivors. The per-fragment cost scales with lights *per tile*, not lights in the scene — a room with 200 lights costs the same per fragment as a room with 16, as long as no single tile is oversubscribed.

## Tiled Lighting and the Slot Budget

Forward+ gives each tile at most `MAX_LIGHTS_PER_TILE` (default `16`) light slots. In a sparsely lit room that ceiling is invisible — every torch fits in every tile and ranking doesn't matter. Pack the same room with 1000 glowing slimes and the picture changes: the tile budget becomes the bottleneck, and a misallocation will visibly push hero torches out of slots, dropping rooms into darkness despite the physical light still being present. The natural failure mode is a checkerboard of dark tiles where cosmetic fills won the slots and lit tiles where they didn't.

<Diagram caption="Each tile's 16-slot budget — heroes (castsShadow: true) reserve slots first and can't be evicted; fills then compete within per-category quotas, and over-quota fills are dropped. The three levers keep dense scenes readable." src={tileSlotBudget} />

Three `Light2D` fields tame this together. They do nothing in small scenes; they make dense scenes readable:

- **Split** lights into heroes and fills (`castsShadow`). Heroes claim slots in a pass that runs before fills are considered, so a torch can never be evicted by a slime aura. Fills also skip the per-light SDF shadow trace — the dominant per-light GPU cost — so flipping cosmetic lights to fills is usually the biggest perf win available.
- **Bias** the rank score for the lights that matter (`importance`). A multiplicative weight on the tile-rank score, so a key light wins slots against a cluster of equal-distance fills. It never touches the illuminance math; a light looks identical once it holds a slot.
- **Bucket** fills by category for independent per-tile quotas (`category`). Tagging slime auras as one bucket and water shimmer as another stops 200 slimes in one tile from crowding out the shimmer next to them. Each bucket gets its own slot quota.

The mechanism is worth understanding because the failure mode is visual and the fix is a field, not a redesign. The fields themselves, their defaults, and the quota-tuning API live in the [Lighting guide](../lighting-setup/#shadow-casting-importance--categories).

:::tip[You will not need any of this on your first scene]
For scenes with under ~20 lights total, the defaults are fine — every light fits in every tile and ranking doesn't matter. `importance` and `category` start to pay off once cosmetic fills (slimes, particles, water) outnumber the slot budget per tile.
:::

## Shadows

Hero lights (`castsShadow: true`) trace shadows against a signed-distance field built from occluder sprites. The SDF is a screen-space field the fragment shader sphere-traces toward each light — a single field serves every hero light, so the occlusion cost is shared rather than per-light-per-occluder. Fills opt out of the trace entirely.

For the occlusion pipeline, occluder setup, and the per-light tracing math, see [Shadows](../shadows/).

## Normal-Based Diffuse Shading

`DefaultLightEffect` reads a per-fragment normal when one is available, giving sprites directional diffuse response instead of flat illumination. Normals come from a baked normal-map atlas attached via `NormalMapProvider`; without one, surfaces are treated as flat (facing the camera) and lighting still works. The atlas's blue channel encodes elevation, which the effect consumes for elevation-aware shading.

The provider setup and the baked-vs-runtime normal pipeline are covered in the [Lighting guide](../lighting-setup/#normal-providers).

## Custom LightEffect

The presets are built on the same public factory you can use to author your own lighting pipeline. `createLightEffect` takes a schema (runtime-settable uniforms) and a `light` builder that returns a TSL shader graph:

```typescript
import { createLightEffect } from 'three-flatland'

const MyLighting = createLightEffect({
  name: 'myLighting',
  schema: {
    ambient: 0.1,      // Uniform: runtime-settable
  },
  light: ({ uniforms, lightStore }) => {
    // Build TSL shader graph once — uniforms close over nodes
    return (ctx) => {
      // ctx.color, ctx.worldPosition, ctx.atlasUV available
      // lightStore.readLightData(i) reads per-light data
      // Return Node<'vec4'> with final lit color
    }
  },
})
```

The shader graph is built once and the uniforms close over its nodes, so runtime updates are plain uniform writes with no recompilation. See the [preset source code](https://github.com/thejustinwalsh/three-flatland/tree/main/packages/presets/src/lighting) for complete examples.

## Performance

The tiled architecture is what makes the lighting scale, and a few habits keep it cheap:

- `DefaultLightEffect` is the canonical preset; its per-tile culling keeps the per-fragment cost flat as the scene grows. Lighter-weight and global-illumination variants are tracked in a follow-up PR.
- Cosmetic lights belong as fills (`castsShadow: false`) — they skip the SDF trace and only compete inside their category quota.
- Ambient light gives base illumination for one uniform add; reach for it before scattering many dim point lights.
- Toggle `light.enabled` rather than adding and removing lights; a disabled light is culled before the per-tile upload.
- Set `lit: false` on sprites that never need lighting (UI, light indicators) so they skip the effect entirely.

## Next Steps

- [Lighting guide](../lighting-setup/) — Setup, `Light2D` types, presets, animation, and quota tuning
- [Lighting Example](../../examples/lighting/) — Interactive demo with draggable lights
- [Shadows](../shadows/) — How the SDF occlusion pass and per-light tracing fit together
- [Pass Effects](../pass-effects/) — Post-processing, plus the full `DefaultLightEffect` schema
- [TSL Nodes](../tsl-nodes/) — Per-sprite shader effects

# Lighting

> Add Light2D sources, pick a LightEffect preset, animate lights, and tune per-tile slot allocation for dense scenes.

import { Tabs, TabItem } from 'starlight-theme/components';
import Diagram from '../../../components/Diagram.astro';
import light2dTypes from '../../../assets/diagrams/light2d-types.svg?raw';

This guide covers the practical side of 2D lighting: adding `Light2D` sources, picking a `LightEffect` preset, animating and dragging lights, and tuning per-tile slot allocation for dense scenes. For the mental model behind Forward+ tiling, the slot budget, and the SDF shadow pass, see [2D Lighting](../lighting/).

## Basic Setup

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { WebGPURenderer } from 'three/webgpu'
    import { Flatland, Light2D, Sprite2D } from 'three-flatland'
    import { DefaultLightEffect } from '@three-flatland/presets'

    const renderer = new WebGPURenderer({ antialias: false })
    await renderer.init()
    document.body.appendChild(renderer.domElement)

    const flatland = new Flatland({ viewSize: 400, clearColor: 0x050508 })

    // Activate lighting — choose a preset
    flatland.setLighting(new DefaultLightEffect())

    // Add a point light
    const torch = new Light2D({
      type: 'point',
      position: [0, 50],
      color: 0xff6600,
      intensity: 2.0,
      distance: 250,
      decay: 2,
    })
    flatland.add(torch)

    // Add ambient light for base illumination
    flatland.add(new Light2D({
      type: 'ambient',
      color: 0x181828,
      intensity: 0.3,
    }))

    // Sprites receive lighting by default
    const sprite = new Sprite2D({ texture })
    flatland.add(sprite)

    function animate() {
      flatland.render(renderer)
      requestAnimationFrame(animate)
    }
    animate()
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { Suspense, useRef, useEffect } from 'react'
    import { Canvas, extend, useFrame, useThree } from '@react-three/fiber/webgpu'
    import type { WebGPURenderer } from 'three/webgpu'
    import {
      Flatland, Light2D, Sprite2D, attachLighting,
    } from 'three-flatland/react'
    import { DefaultLightEffect } from '@three-flatland/presets'
    import '@three-flatland/presets/react'

    extend({ Flatland, Sprite2D, Light2D, DefaultLightEffect })

    function Scene() {
      const flatlandRef = useRef<Flatland>(null)
      const { renderer, size } = useThree()

      useEffect(() => {
        flatlandRef.current?.resize(size.width, size.height)
      }, [size.width, size.height])

      useFrame(() => {
        flatlandRef.current?.render(renderer as unknown as WebGPURenderer)
      }, { phase: 'render' })

      return (
        <flatland ref={flatlandRef} viewSize={400} clearColor={0x050508}>
          {/* Attach lighting effect to Flatland */}
          <defaultLightEffect attach={attachLighting} />

          {/* Light sources */}
          <light2D
            lightType="point"
            position={[0, 50, 0]}
            color={0xff6600}
            intensity={2.0}
            distance={250}
            decay={2}
          />
          <light2D lightType="ambient" color={0x181828} intensity={0.3} />

          {/* Sprites receive lighting by default */}
          <sprite2D texture={texture} />
        </flatland>
      )
    }

    export default function App() {
      return (
        <Canvas renderer={{ antialias: false }}>
          <Suspense fallback={null}>
            <Scene />
          </Suspense>
        </Canvas>
      )
    }
    ```
  </TabItem>
</Tabs>

:::tip[Lighting is opt-out]
All sprites receive lighting by default when a `LightEffect` is active. Set `lit: false` on sprites that should render at full brightness (e.g., UI elements, light indicators).
:::

## Light2D Types

<Diagram caption="The four Light2D types and their emission shapes — point (radial falloff), directional (parallel rays), spot (soft-edged cone), and ambient (uniform fill)" src={light2dTypes} />

### Point Light

Radiates light from a position with distance-based falloff:

```typescript
const torch = new Light2D({
  type: 'point',
  position: [100, 100],      // World position [x, y]
  color: 'orange',           // Any Three.js ColorRepresentation
  intensity: 1.5,            // Brightness multiplier
  distance: 200,             // Max light distance (0 = no cutoff)
  decay: 2,                  // Attenuation exponent (2 = quadratic)
})
```

### Directional Light

Parallel rays from a direction (like sunlight):

```typescript
const sun = new Light2D({
  type: 'directional',
  direction: [1, -1],        // Light direction (normalized automatically)
  color: 0xffffcc,
  intensity: 0.8,
})
```

### Spot Light

Cone of light from a position in a direction:

```typescript
const spotlight = new Light2D({
  type: 'spot',
  position: [0, 100],
  direction: [0, -1],        // Points downward
  color: 0xffffff,
  intensity: 2.0,
  distance: 300,
  angle: Math.PI / 6,        // 30-degree cone
  penumbra: 0.2,             // Soft edge (0-1)
})
```

### Ambient Light

Uniform illumination — affects all lit sprites equally:

```typescript
const ambient = new Light2D({
  type: 'ambient',
  color: 0x222233,
  intensity: 0.3,
})
```

## LightEffect Presets

`@three-flatland/presets` ships a lighting preset for the recommended rendering path:

| Preset | Tiled | Shadows | GI | Best For |
|--------|-------|---------|-----|----------|
| `DefaultLightEffect` | Yes | SDF (WIP) | No | Recommended — scales well |

`DefaultLightEffect` supports normal-based diffuse shading when a normal channel is provided (see [Normal Providers](#normal-providers) below).

### DefaultLightEffect

Forward+ tiled lighting — the recommended preset. Uses per-tile light culling for O(lights per tile) per fragment. Full feature set: bands, pixel-snapping, glow, rim lighting, and shadow support.

```typescript
import { DefaultLightEffect } from '@three-flatland/presets'

const lighting = new DefaultLightEffect()
flatland.setLighting(lighting)

// Optional stylization (zero-cost uniform updates)
lighting.bands = 4              // Cel-shading bands
lighting.pixelSize = 4          // Pixel-snap light sampling
lighting.glowRadius = 2         // Broad secondary falloff
lighting.glowIntensity = 0.3
lighting.lightHeight = 0.75     // Simulated Z-height for diffuse (0-2)
lighting.rimIntensity = 0.3     // Edge highlights from light direction

// Shadow parameters (SDF pipeline)
lighting.shadowStrength = 0.8
lighting.shadowBias = 0.5
lighting.shadowMaxDistance = 300
```

For the full `DefaultLightEffect` schema (uniforms vs compile-time constants, removed fields, the `categoryQuotas` accessor), see the [Pass Effects guide](../pass-effects/#defaultlighteffect-schema).

## Animating Lights

Update Light2D properties at any time — they sync to the GPU automatically each frame:

```typescript
let flickerTimer = 0

function animate(delta: number) {
  flickerTimer += delta

  // Combine sine waves for organic flicker
  const flicker = 1 +
    Math.sin(flickerTimer * 15) * 0.1 +
    Math.sin(flickerTimer * 23) * 0.05

  torch.intensity = 1.2 * flicker

  // Slight position wobble
  torch.position.set(
    baseX + Math.sin(flickerTimer * 7) * 2,
    baseY + Math.sin(flickerTimer * 11) * 1,
    0
  )
}
```

## Draggable Lights

Make lights interactive by converting screen coordinates to world space:

```typescript
let draggingLight: Light2D | null = null

canvas.addEventListener('mousedown', (e) => {
  const worldPos = screenToWorld(e.clientX, e.clientY)
  for (const light of flatland.lights) {
    if (light.position2D.distanceTo(worldPos) < 20) {
      draggingLight = light
      break
    }
  }
})

canvas.addEventListener('mousemove', (e) => {
  if (draggingLight) {
    draggingLight.position2D = screenToWorld(e.clientX, e.clientY)
  }
})

canvas.addEventListener('mouseup', () => {
  draggingLight = null
})
```

## Light2D Properties

:::note[`type` vs `lightType`]
The constructor option is `type` (`new Light2D({ type: 'point' })`); the instance property and the R3F prop are `lightType` (`<light2D lightType="point" />`). Both set the same thing — the constructor just uses the shorter key.
:::

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `lightType` | `'point' \| 'directional' \| 'spot' \| 'ambient'` | `'point'` | Light type |
| `color` | `ColorRepresentation` | `0xffffff` | Light color |
| `intensity` | `number` | `1` | Brightness multiplier |
| `distance` | `number` | `0` | Max range (0 = no cutoff) |
| `decay` | `number` | `2` | Attenuation exponent |
| `direction` | `Vector2 \| [number, number]` | `[0, -1]` | Direction (spot/directional) |
| `angle` | `number` | `Math.PI/4` | Cone angle in radians (spot) |
| `penumbra` | `number` | `0` | Soft edge 0-1 (spot) |
| `enabled` | `boolean` | `true` | Toggle without removing |
| `castsShadow` | `boolean` | `true` | Whether this light traces shadows |
| `importance` | `number` | `1` | Tile-rank score multiplier (Forward+) |
| `category` | `string \| undefined` | `undefined` | Bucket tag for fill-light quotas |
| `position2D` | `Vector2` | `(0, 0)` | 2D position helper |

## Shadow Casting, Importance & Categories

Three Light2D fields control how lights compete for per-tile slots in dense scenes: `castsShadow` splits lights into heroes and fills, `importance` biases the rank score, and `category` buckets fills into independent quotas. They do nothing in small scenes; they make dense scenes readable. For why the slot budget exists and when these knobs start to matter, see [Tiled lighting and the slot budget](../lighting/#tiled-lighting-and-the-slot-budget).

:::tip[You will not need any of this on your first scene]
For scenes with under ~20 lights total, the defaults are fine — every light fits in every tile and ranking doesn't matter. `importance` and `category` start to pay off once cosmetic fills (slimes, particles, water) outnumber the slot budget per tile.
:::

### `castsShadow` — the hero / fill split

```typescript
// Hero — full per-light SDF shadow trace, never evicted by fills
const torch = new Light2D({
  type: 'point',
  color: 0xff6600,
  intensity: 1.8,
  distance: 140,
  decay: 2,
  // castsShadow defaults to true
})

// Fill — skips the SDF trace, competes only inside its category quota
const slimeGlow = new Light2D({
  type: 'point',
  color: 0x33ff66,
  intensity: 0.25,
  distance: 40,
  decay: 2,
  castsShadow: false,
})
```

**Heroes** (`castsShadow: true`, the default) compete only with each other for tile slots. Forward+ runs the hero pass first and reserves slots before fills are even considered — they can't be evicted by fills regardless of count.

**Fills** (`castsShadow: false`) skip the per-light SDF sphere-trace entirely on the GPU and compete only within their own category bucket. The 32-tap trace is the dominant per-light cost in dense scenes; flipping cosmetic lights to fills is often the single biggest perf win available.

**Recommendation:** torches, key lights, and anything where the *shape* of the shadow matters → heroes. Slime auras, particle glows, magic VFX, ambient shimmer → fills.

### `importance` — bias tile-slot allocation

```typescript
const torch = new Light2D({
  /* ... */
  importance: 10,   // 10× weight against importance-1 fills in slot ranking
})
```

`importance: number` defaults to `1` (neutral). It's a multiplicative bias on the tile-rank score during slot allocation. Use `importance: 10` on hero lights you want resilient to dense fill clusters; `10` is plenty in practice, numbers above ~50 don't measurably improve outcomes.

`importance` is **score-only** — it never appears in the fragment shader's illuminance math. A light's appearance once it's in a tile slot is identical regardless of its importance value.

:::tip[Performance note]
Heroes claim slots in a separate pass before fills are allocated, so a hero can't be evicted by a fill regardless of importance. `importance` only matters when *heroes* compete with *heroes* — which only happens when more than `MAX_LIGHTS_PER_TILE` (16) hero lights overlap one tile. For most scenes that's a fallback safety, not a routine knob.
:::

### `category` — independent quotas for fill clusters

`Light2D.category: string | undefined` is an opaque tag, hashed via djb2 to one of `FILL_CATEGORY_COUNT` (4) buckets at the property setter — no per-frame hash cost; the cost is paid once per unique string and cached for every Light2D that shares it.

```typescript
// 1000 slime fills, all sharing one quota bucket
for (const slime of slimes) {
  flatland.add(new Light2D({
    type: 'point',
    color: 0x33ff66,
    intensity: 0.25,
    distance: 40,
    decay: 2,
    castsShadow: false,
    category: 'slime',
  }))
}
```

In React the same fields are JSX props:

```tsx
<light2D
  lightType="point"
  color={0xff6600}
  intensity={1.8}
  distance={140}
  decay={2}
  importance={10}
/>

<light2D
  lightType="point"
  color={0x33ff66}
  intensity={0.25}
  distance={40}
  decay={2}
  castsShadow={false}
  category="slime"
/>
```

Each unique category string maps to one of 4 buckets, and Forward+ enforces a per-tile, per-category quota — 200 slime lights in one tile can't crowd out the water shimmer next to them. Lights without a category share bucket 0 with all other un-tagged fills. Heroes (`castsShadow: true`) ignore `category` entirely.

**Bucket count is 4.** A 5th distinct category collides into one of the first 4 — graceful degradation, not an error. If you have more than 4 cosmetic light types, pick the 4 most visually distinct ones to bucket separately and let the rest collide.

### Per-category quota tuning

The default per-category quota is `MAX_FILL_LIGHTS_PER_TILE` (2) slots per tile. To raise or lower it:

```typescript
// Imperative — direct call on the ForwardPlusLighting instance
lighting.forwardPlus.setFillQuota('slime', 4)
console.log(lighting.forwardPlus.getFillQuota('slime')) // → 4
lighting.forwardPlus.resetFillQuotas()                  // back to default 2
```

`DefaultLightEffect` exposes a declarative sugar accessor that's nicer for JSX:

```tsx
<defaultLightEffect
  attach={attachLighting}
  categoryQuotas={{ slime: 4 }}
/>
```

Setting `categoryQuotas` is the **authoritative quota state**, not a delta. Each assignment first calls `forwardPlus.resetFillQuotas()` to clear all four buckets back to default, then re-applies the record. Going from `{ slime: 4 }` → `{}` actually drops the slime quota back to 2 — without the reset, stale per-bucket overrides would leak across re-renders in surprising ways.

**Range:** `0..MAX_LIGHTS_PER_TILE` (clamped). Setting a quota to `0` disables that bucket entirely (those fills contribute nothing). Setting it above `16` doesn't help — `16` is the per-tile slot total.

In the `examples/react/lighting/` demo, the slime-quota slider drives `categoryQuotas={{ slime: props.slimeQuota }}` — drag it from `0` (slime lights dark) through `2` (default — visible checkerboarding in dense clusters) up to `16` (every slime in range contributes, at a per-fragment cost) and watch the artifact shift in real time.

### Tuning notes

- **Slime-quota above ~6 hits diminishing returns.** At `4` the visible "fill got evicted" checkerboard is already rare; at `6` it's basically gone. Going higher costs shader iterations per fragment in saturated tiles without meaningfully improving the picture.
- **Torch importance `10` is plenty.** Numbers above ~50 don't matter unless your fills also have non-1 importance, in which case the relative ratio is what matters, not the absolute value.
- **Score-ranked eviction within a quota is intuitive.** When a category's quota is full and another fill of that category enters range, the closer / brighter one wins the slot. Tweaking individual fill `intensity` indirectly affects who survives in saturated tiles.
- **Fills are cheap to leave on.** `light.enabled = false` is a zero-cost cull (rejected before per-tile upload), but a `castsShadow: false` fill that's just dim and far away is also nearly free — Forward+ won't even rank it into a tile it can't reach. Don't over-engineer toggling.

## Normal Providers

`DefaultLightEffect` supports normal-based directional diffuse shading. To enable it, add a normal provider effect to your sprites.

### NormalMapProvider

Uses a pre-baked normal map texture for higher-quality normals:

```typescript
import { NormalMapProvider } from '@three-flatland/presets'

const provider = new NormalMapProvider()
provider.normalMap = myNormalMapTexture
sprite.addEffect(provider)
```

To produce a normal-map texture from a sprite sheet or LDtk tileset, see the [Baked Normal Pipeline](../loaders/#baked-normal-pipeline) — `SpriteSheetLoader` and `LDtkLoader` both accept `normals: true` to expose a co-registered `normalMap` on the loaded asset. The atlas's blue channel encodes per-fragment elevation, which `DefaultLightEffect` consumes for elevation-aware lighting. (See [Loaders](../loaders/#baked-normal-pipeline) for the runtime side and the [Baking guide](../baking/) for the offline `flatland-bake` workflow.)

Without a normal provider, lighting still works — surfaces are treated as flat (facing the camera).

### Runtime bake fallback

`NormalMapProvider` is fed by a baked `.normal.png` atlas. The high-level
loaders (`SpriteSheetLoader({ normals: true })`, `LDtkLoader` with `normals: true`)
handle the fallback for you: if the baked sibling is missing or its descriptor
hash is stale, the loader bakes the atlas in memory on first load (lazy-importing
the baker, so the cost is paid only when needed) and emits a dev-mode warning
pointing at `npx flatland-bake normal`.

For assets whose normal map is produced in the browser by design
(procedurally varied tilesets, throwaway prototypes, asset bundles where
shipping a sidecar isn't worth the bytes), pass `forceRuntime: true` on
the loader. The in-memory bake runs on every load; the probe and "no
baked sibling" warn are skipped. You still get the same normal-map data
— the flag just commits to "the browser is where it's produced for this
asset." Mirrors `SlugFontLoader.forceRuntime`; one flag across every
baked-asset loader. Not a dev-iteration knob — the default path already
handles iteration (probe → bake on miss + warn pointing at
`flatland-bake`).

:::note
The dev-mode warning is suppressed in production (`NODE_ENV === 'production'`),
so leaving the runtime-bake fallback enabled is safe for sites where sidecars
are always present — the bake path stays dormant.
:::

## Next Steps

- [2D Lighting](../lighting/) — The mental model: Forward+ tiling, the slot budget, and the SDF shadow pass
- [Lighting Example](../../examples/lighting/) — Interactive demo with draggable lights and a live slime-quota slider
- [Shadows](../shadows/) — How the SDF occlusion pass and per-light tracing fit together
- [Pass Effects](../pass-effects/) — Post-processing, plus the full `DefaultLightEffect` schema

# Loaders

> Load spritesheets and tilemaps with configurable texture presets.

import { Tabs, TabItem } from 'starlight-theme/components';
import Diagram from '../../../components/Diagram.astro';
import bakedNormalPipeline from '../../../assets/diagrams/baked-normal-pipeline.svg?raw';

**What you'll learn**
- How to load textures, spritesheets, Tiled `.tmj`, and LDtk `.ldtk` files with the right filtering preset
- How the `TextureConfig → Loader → Instance` preset hierarchy lets you set defaults once
- How `normals: true` produces a baked normal-map atlas for `NormalMapProvider` lighting

---

three-flatland provides loaders for common 2D asset formats. All loaders share a unified texture configuration system with hierarchical presets.

The default preset is `pixel-art` — `NearestFilter`, no mipmaps, clamp wrap. If you're shipping pixel art (most three-flatland projects), you don't have to configure anything.

## Available Loaders

| Loader | Format | Use Case |
|--------|--------|----------|
| `TextureLoader` | PNG, JPG, SVG, etc. | Single textures with preset support |
| `SpriteSheetLoader` | TexturePacker JSON | Spritesheets and atlases |
| `TiledLoader` | Tiled .json/.tmj | Tile-based maps |
| `LDtkLoader` | LDtk .ldtk | Level design with entities |

## TextureLoader

Load textures with automatic preset application. Works seamlessly with R3F's `useLoader`.

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { TextureLoader, Sprite2D } from 'three-flatland';

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

    const sprite = new Sprite2D({ texture });
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { useLoader } from '@react-three/fiber/webgpu';
    import { TextureLoader, Sprite2D } from 'three-flatland/react';
    import { extend } from '@react-three/fiber/webgpu';

    extend({ Sprite2D });

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

      return <sprite2D texture={texture} />;
    }
    ```
  </TabItem>
</Tabs>

### Multiple Textures

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { TextureLoader } from 'three-flatland';

    // Preload multiple textures
    const textures = await TextureLoader.preload([
      '/sprites/player.png',
      '/sprites/enemy.png',
      '/sprites/items.png',
    ]);
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { useLoader } from '@react-three/fiber/webgpu';
    import { TextureLoader } from 'three-flatland/react';

    // Define URLs at module level for stable references
    const TEXTURE_URLS = ['/sprites/player.png', '/sprites/enemy.png', '/sprites/items.png'];

    function Game() {
      // Load multiple textures at once
      const [playerTex, enemyTex, itemsTex] = useLoader(TextureLoader, TEXTURE_URLS);
      // ...
    }
    ```
  </TabItem>
</Tabs>

### Override Presets

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    // Override preset for specific texture
    const smoothTexture = await TextureLoader.load('/sprites/hd-ui.png', {
      texture: 'smooth'
    });
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    // Override preset via extension callback
    const smoothTexture = useLoader(TextureLoader, '/sprites/hd-ui.png', (loader) => {
      loader.preset = 'smooth';
    });
    ```
  </TabItem>
</Tabs>

## SpriteSheetLoader

Load spritesheets exported from [TexturePacker](https://www.codeandweb.com/texturepacker) or compatible tools.

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { SpriteSheetLoader, Sprite2D } from 'three-flatland';

    const sheet = await SpriteSheetLoader.load('/sprites/player.json');

    // Access frames
    const idleFrame = sheet.getFrame('player_idle_0');
    const allFrames = sheet.getFrameNames();

    // Use with Sprite2D
    const sprite = new Sprite2D({ texture: sheet.texture });
    sprite.setFrame(idleFrame);
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { Suspense } from 'react';
    import { useLoader } from '@react-three/fiber/webgpu';
    import { SpriteSheetLoader, Sprite2D } from 'three-flatland/react';
    import { extend } from '@react-three/fiber/webgpu';

    extend({ Sprite2D });

    function Player() {
      // useLoader suspends while loading, presets applied automatically
      const sheet = useLoader(SpriteSheetLoader, '/sprites/player.json');
      const frame = sheet.getFrame('player_idle_0');

      return <sprite2D texture={sheet.texture} frame={frame} />;
    }

    // Wrap with Suspense
    <Suspense fallback={null}>
      <Player />
    </Suspense>
    ```
  </TabItem>
</Tabs>

### Multiple Spritesheets

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    const sheets = await SpriteSheetLoader.preload([
      '/sprites/player.json',
      '/sprites/enemies.json',
    ]);
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    // Define URLs at module level for stable references
    const SHEET_URLS = ['/sprites/player.json', '/sprites/enemies.json'];

    function Game() {
      const [playerSheet, enemySheet] = useLoader(SpriteSheetLoader, SHEET_URLS);
      // ...
    }
    ```
  </TabItem>
</Tabs>

### Supported Formats

- **JSON Hash** (TexturePacker default) - Frames as object properties
- **JSON Array** - Frames as array with `filename` property

## TiledLoader

Load maps from [Tiled Map Editor](https://www.mapeditor.org/). See the [Tilemaps guide](../tilemaps/) for detailed usage.

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { TiledLoader, TileMap2D } from 'three-flatland';

    const mapData = await TiledLoader.load('/maps/level1.json');
    const tilemap = new TileMap2D({ data: mapData });
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { Suspense } from 'react';
    import { useLoader } from '@react-three/fiber/webgpu';
    import { TiledLoader, TileMap2D } from 'three-flatland/react';
    import { extend } from '@react-three/fiber/webgpu';

    extend({ TileMap2D });

    function Level() {
      const mapData = useLoader(TiledLoader, '/maps/level1.json');
      return <tileMap2D data={mapData} />;
    }

    // Wrap with Suspense
    <Suspense fallback={null}>
      <Level />
    </Suspense>
    ```
  </TabItem>
</Tabs>

### Features

- Embedded and external tilesets
- Tile layers with flip flags
- Object layers for entities and collision
- Tile animations
- Infinite maps with chunks

## LDtkLoader

Load projects from [LDtk](https://ldtk.io/). See the [Tilemaps guide](../tilemaps/) for detailed usage.

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { LDtkLoader, TileMap2D } from 'three-flatland';

    // Load a specific level
    const mapData = await LDtkLoader.load('/maps/world.ldtk', 'Level_0');
    const tilemap = new TileMap2D({ data: mapData });

    // List all levels in project
    const levelIds = await LDtkLoader.getLevelIds('/maps/world.ldtk');
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { Suspense } from 'react';
    import { useLoader } from '@react-three/fiber/webgpu';
    import { LDtkLoader, TileMap2D } from 'three-flatland/react';
    import { extend } from '@react-three/fiber/webgpu';

    extend({ TileMap2D });

    function Level() {
      // Loads first level by default
      const mapData = useLoader(LDtkLoader, '/maps/world.ldtk');
      return <tileMap2D data={mapData} />;
    }

    // Specify level via extension callback
    function SpecificLevel() {
      const mapData = useLoader(LDtkLoader, '/maps/world.ldtk', (loader) => {
        loader.levelId = 'Level_1';
      });
      return <tileMap2D data={mapData} />;
    }

    // Wrap with Suspense
    <Suspense fallback={null}>
      <Level />
    </Suspense>
    ```
  </TabItem>
</Tabs>

### Features

- Multi-level projects
- Tile layers (Tiles, AutoLayer, IntGrid)
- Entity layers with custom fields
- IntGrid collision data
- Tile flip flags

## Baked Normal Pipeline

three-flatland's lighting wants per-fragment **normal vectors** (for N·L diffuse) and an **elevation** scalar (for elevation-aware wall caps in `DefaultLightEffect`). Authoring a normal-map atlas alongside the diffuse atlas covers the easy case; for tilemaps, where per-tile orientation is decided in the level editor, `LDtkLoader` goes a step further and *bakes* a per-tileset normal atlas at load time from per-tile custom data.

<Diagram caption="The baked-normal pipeline — a hash-stamped .normal.png sidecar is probed and loaded on a match, with an in-memory bake fallback feeding NormalMapProvider." src={bakedNormalPipeline} />

Both `SpriteSheetLoader` and `LDtkLoader` accept a `normals: true` option. The resulting texture lands on the loaded asset (`sheet.normalMap`, `tileset.normalMap`) and is consumed by [`NormalMapProvider`](../lighting-setup/#normalmapprovider) — a `MaterialEffect` from `@three-flatland/presets` — which feeds the `normal` and `elevation` channels into [`DefaultLightEffect`](../lighting-setup/#defaultlighteffect)'s lighting math.

The atlas encoding is RGB+A: R/G hold the tangent-space normal XY in `[0, 1]` (decoded to `[-1, 1]` at sample time, with Z reconstructed as `sqrt(1 − x² − y²)`), B holds elevation in `[0, 1]`, and A passes through the source alpha.

### Resolution Strategy

Both loaders use the same resolution path for the baked atlas:

1. **Hash the descriptor** — every tile/frame's region geometry plus its tilt direction, cap thickness, elevation, etc. produces a stable hash.
2. **Probe a baked sibling** — look for `<source-image>.normal.png` next to the diffuse, with a matching hash stamp. If present, load it directly.
3. **In-memory bake fallback** — fetch the diffuse, decode pixels, run the bake, and wrap the result in a `DataTexture`.

Run `npx flatland-bake normal <source>` ahead of time to skip the in-memory path in production. For the offline workflow — running `flatland-bake` ahead of time, sidecar staleness warnings, CI integration — see the [Baking guide](../baking/).

The `normals` option accepts:

- `true` — auto-synthesize the descriptor from the asset's frame/tile layout
- `NormalSourceDescriptor` — pass a hand-authored descriptor
- `false` (default) — no normal map is loaded or generated

`forceRuntime: true` is a sibling option (not nested inside `normals`) that declares **the browser is where this asset's normal map is produced** — not the CI bake step. The in-memory bake runs on every load; the sidecar probe and "no baked sibling" warn are skipped. The data is always there, the same as the default path; this flag just commits to "the browser is where it's produced for this asset, on purpose." Use it for procedurally varied tilesets, throwaway prototypes, or asset bundles where shipping the sidecar isn't worth the bytes. Same flag every baked-asset loader exposes (`SlugFontLoader.forceRuntime`). **Not a dev-iteration knob** — the default path (probe → bake on miss + warn) already handles iteration.

The in-memory bake path is lazy-imported, so its bundle cost is not paid unless the fallback fires. A dev-mode warning (`NODE_ENV !== 'production'`) points at `npx flatland-bake normal` when the sidecar is absent. See the [Runtime bake fallback](../lighting-setup/#runtime-bake-fallback) section for the full story.

### `SpriteSheetLoader.normals: true`

For sprite sheets, the loader synthesizes one flat region per frame rect (read from the sheet JSON) and hands the descriptor to the baker. Region-local alpha clamping in the baker keeps adjacent frames from bleeding gradients into each other. The resulting atlas is exposed as `sheet.normalMap` (a `THREE.Texture`), 1:1 co-registered with `sheet.texture`.

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { SpriteSheetLoader } from 'three-flatland'

    const knightSheet = await SpriteSheetLoader.load('./sprites/knight.json', {
      normals: true,
    })

    // sheet.normalMap is a Texture aligned to sheet.texture
    console.log(knightSheet.normalMap)
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    const knightSheet = useLoader(SpriteSheetLoader, './sprites/knight.json', (l) => {
      l.normals = true
    })
    ```
  </TabItem>
</Tabs>

For sprites whose individual frames want different per-frame tilt/bump (rare — most character sheets stay flat with alpha-derived shading) pass a `NormalSourceDescriptor` instead of `true` and provide your own `regions`. For an atlas whose normal map is generated in the browser by design (procedural variation, throwaway prototype, lean bundle), set `forceRuntime: true`:

```typescript
// Three.js
const sheet = await SpriteSheetLoader.load('./sprites/proc-tiles.json', {
  normals: true,
  forceRuntime: true,
})

// R3F useLoader
const sheet = useLoader(SpriteSheetLoader, './sprites/proc-tiles.json', (l) => {
  l.normals = true
  l.forceRuntime = true
})
```

### `LDtkLoader.normals: true`

For LDtk projects, the loader walks every tile cell of every used tileset and reads the tile's free-form custom data string. Where that string parses as a JSON object containing the recognized fields, the baker carves the cell into cap and face regions:

| Custom-data field | Effect |
|-------------------|--------|
| `tileDir` | Direction the face tilts (`'up'`, `'down'`, `'left'`, `'right'`, `'flat'`, etc.) |
| `tilePitch` | Override the tilt angle in radians |
| `tileCap` | Shorthand cap thickness (top edge by default) in pixels |
| `tileCapTop` / `tileCapBottom` / `tileCapLeft` / `tileCapRight` | Per-edge cap strip thickness in pixels |
| `tileCapTopLeft` / `tileCapTopRight` / `tileCapBottomLeft` / `tileCapBottomRight` | Square N×N corner caps for L-shaped wall-cap geometry |
| `tileElevation` | Elevation override in `[0, 1]` (0 = floor plane, 1 = top of wall) |
| `tileBump` / `tileStrength` | Bump source / gradient strength override |

A wall tile tagged `{ "tileDir": "down", "tileCap": 4 }` bakes a 4px flat strip at the top of the cell at elevation 1 (the wall *top*), and the rest of the cell as a face region tilted "down" at the default mid-wall elevation. Untagged tiles bake as a single flat region — floors stay flat, no further work required.

The atlas lands on each tileset as `tileset.normalMap`:

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { LDtkLoader } from 'three-flatland'

    const mapData = await LDtkLoader.load('./maps/dungeon.ldtk', undefined, {
      normals: true,
    })

    // One normalMap per tileset, co-registered with tileset.texture
    const tilesetNormals = mapData.tilesets[0]?.normalMap
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    const mapData = useLoader(LDtkLoader, './maps/dungeon.ldtk', (l) => {
      l.normals = true
    })
    ```
  </TabItem>
</Tabs>

The blue (elevation) channel feeds `DefaultLightEffect`'s elevation-aware diffuse — wall caps physically sit *above* `lightHeight` in the lighting math, so torches geometrically miss them. See the [Shadows guide](../shadows/#elevation-aware-shadows) for the elevation-channel story.

### Wiring to the Lighting System

Once the normal map is loaded, attach a `NormalMapProvider` MaterialEffect to the consuming `Sprite2D` / `AnimatedSprite2D` / `TileMap2D`. The provider feeds the `normal` and `elevation` channels into the active `LightEffect` (typically `DefaultLightEffect`).

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import {
      Flatland, Sprite2D, AnimatedSprite2D, TileMap2D,
      SpriteSheetLoader, LDtkLoader,
    } from 'three-flatland'
    import {
      DefaultLightEffect, NormalMapProvider,
    } from '@three-flatland/presets'

    const flatland = new Flatland({ viewSize: 400 })
    flatland.setLighting(new DefaultLightEffect())

    const [knightSheet, mapData] = await Promise.all([
      SpriteSheetLoader.load('./sprites/knight.json', { normals: true }),
      LDtkLoader.load('./maps/dungeon.ldtk', undefined, { normals: true }),
    ])

    // Tilemap — baked tileset normals drive directional lighting
    // (walls tilt toward their visible face, floors stay flat).
    const tilemap = new TileMap2D({ data: mapData })
    const tilemapNormals = new NormalMapProvider()
    tilemapNormals.normalMap = mapData.tilesets[0]?.normalMap ?? null
    tilemap.addEffect(tilemapNormals)
    flatland.add(tilemap)

    // Hero — sheet.normalMap lights every animation frame consistently.
    const hero = new AnimatedSprite2D({ spriteSheet: knightSheet, /* ... */ })
    const heroNormals = new NormalMapProvider()
    heroNormals.normalMap = knightSheet.normalMap ?? null
    hero.addEffect(heroNormals)
    flatland.add(hero)
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { useLoader } from '@react-three/fiber/webgpu'
    import {
      SpriteSheetLoader, LDtkLoader, AnimatedSprite2D, TileMap2D,
      attachEffect, attachLighting,
    } from 'three-flatland/react'
    import { DefaultLightEffect, NormalMapProvider } from '@three-flatland/presets'
    import '@three-flatland/presets/react'

    extend({ AnimatedSprite2D, TileMap2D, DefaultLightEffect, NormalMapProvider })

    function Scene() {
      const knightSheet = useLoader(SpriteSheetLoader, './sprites/knight.json', (l) => {
        l.normals = true
      })
      const mapData = useLoader(LDtkLoader, './maps/dungeon.ldtk', (l) => {
        l.normals = true
      })

      return (
        <flatland viewSize={400}>
          <defaultLightEffect attach={attachLighting} />

          {/* Floor + walls — baked tileset normals from per-tile
              `tileDir` / `tileCap*` custom data. */}
          <tileMap2D data={mapData}>
            <normalMapProvider
              attach={attachEffect}
              normalMap={mapData.tilesets[0]?.normalMap ?? null}
            />
          </tileMap2D>

          {/* Hero — sheet's baked atlas lights every frame consistently. */}
          <animatedSprite2D
            texture={knightSheet.texture}
            spriteSheet={knightSheet}
            /* ... */
          >
            <normalMapProvider
              attach={attachEffect}
              normalMap={knightSheet.normalMap ?? null}
            />
          </animatedSprite2D>
        </flatland>
      )
    }
    ```
  </TabItem>
</Tabs>

For the broader lighting story, see the [Lighting guide](../lighting/) (presets and Light2D types) and the [Shadows guide](../shadows/) (elevation-aware shaping and the SDF trace). For the `NormalMapProvider` MaterialEffect in context with the rest of the effect system, see [Pass Effects](../pass-effects/#the-three-effect-layers).

## Texture Presets

All loaders use a unified texture configuration system. Presets control filtering, wrapping, and mipmaps.

### Available Presets

| Preset | Filtering | Wrap | Mipmaps | Best For |
|--------|-----------|------|---------|----------|
| `'pixel-art'` | Nearest | Clamp | Off | Pixel art, retro games, tilemaps |
| `'smooth'` | Linear | Clamp | On | HD sprites, smooth graphics |
| `'none'` | — | — | — | Full manual control |

### Configuration Hierarchy

Texture options follow a hierarchy (highest to lowest priority):

```
Instance preset/options  →  Loader.options  →  TextureConfig.options  →  'pixel-art'
     (highest)                (middle)            (lowest)              (default)
```

For `TextureLoader` with R3F's `useLoader`, the instance preset is set via the extension callback:

```tsx
// Instance-level override via extension
const texture = useLoader(TextureLoader, '/sprite.png', (loader) => {
  loader.preset = 'smooth';  // Highest priority
});
```

Each level overrides the ones below it. If nothing is set, `'pixel-art'` is used.

### Global Configuration

Set a system-wide default for all loaders:

```typescript
import { TextureConfig } from 'three-flatland';

// Change global default
TextureConfig.options = 'smooth';

// All loaders now use smooth filtering
const sheet = await SpriteSheetLoader.load('/sprites/player.json');
const mapData = await TiledLoader.load('/maps/level.json');

// Reset to system default
TextureConfig.reset();  // Back to 'pixel-art'
```

### Per-Loader Configuration

Override the default for a specific loader type:

```typescript
import { TextureLoader, SpriteSheetLoader, TiledLoader } from 'three-flatland';

// HD textures with smooth filtering
TextureLoader.options = 'smooth';

// HD sprites with smooth filtering
SpriteSheetLoader.options = 'smooth';

// Tilemaps stay pixel-perfect
TiledLoader.options = 'pixel-art';

// Now these use different settings
const texture = await TextureLoader.load('/sprites/hd-player.png');    // smooth
const sprites = await SpriteSheetLoader.load('/sprites/ui.json');      // smooth
const mapData = await TiledLoader.load('/maps/dungeon.json');          // pixel-art
```

### Per-Instance Configuration

Override for a specific load call:

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    // One-off override
    const hdSheet = await SpriteSheetLoader.load('/sprites/hd-ui.json', {
      texture: 'smooth'
    });

    // Custom options
    const customSheet = await SpriteSheetLoader.load('/sprites/special.json', {
      texture: {
        minFilter: LinearFilter,
        magFilter: NearestFilter,  // Mix filtering modes
      }
    });
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    // Override preset via extension callback
    const hdSheet = useLoader(SpriteSheetLoader, '/sprites/hd-ui.json', (loader) => {
      loader.preset = 'smooth';
    });

    // Custom options
    const customSheet = useLoader(SpriteSheetLoader, '/sprites/special.json', (loader) => {
      loader.preset = {
        minFilter: LinearFilter,
        magFilter: NearestFilter,
      };
    });
    ```
  </TabItem>
</Tabs>

### Full Manual Control

Use `'none'` for complete control via `.then()`:

```typescript
import { RepeatWrapping } from 'three';

const sheet = await SpriteSheetLoader.load('/sprites/tiles.json', {
  texture: 'none'
}).then(s => {
  // Full manual configuration
  s.texture.wrapS = RepeatWrapping;
  s.texture.wrapT = RepeatWrapping;
  s.texture.anisotropy = 16;
  return s;
});
```

### Common Patterns

**Pixel Art Game (default)**
```typescript
// Just use defaults - pixel-art is the system default
const sheet = await SpriteSheetLoader.load('/sprites/player.json');
const mapData = await TiledLoader.load('/maps/level.json');
```

**HD Game**
```typescript
// Set global default once at startup
TextureConfig.options = 'smooth';

// All loads now use smooth filtering
const sheet = await SpriteSheetLoader.load('/sprites/player.json');
```

**Mixed Styles**
```typescript
// Configure each loader type
SpriteSheetLoader.options = 'smooth';  // HD sprites
TiledLoader.options = 'pixel-art';     // Pixel tilemaps

// Or override per-instance
const pixelSprite = await SpriteSheetLoader.load('/sprites/retro.json', {
  texture: 'pixel-art'
});
```

## Caching

:::tip[Performance note]
All loaders cache results by URL and texture options. Calling `SpriteSheetLoader.load(url)` from ten components on the same page is one fetch, ten promise-resolutions — not ten round-trips. Don't pre-load defensively; just call where you need it.
:::

```typescript
// First load - fetches from network
const sheet1 = await SpriteSheetLoader.load('/sprites/player.json');

// Second load - returns cached result instantly
const sheet2 = await SpriteSheetLoader.load('/sprites/player.json');

console.log(sheet1 === sheet2);  // true
```

Different texture options create separate cache entries:

```typescript
// These are cached separately
const pixelSheet = await SpriteSheetLoader.load('/sprites/ui.json', { texture: 'pixel-art' });
const smoothSheet = await SpriteSheetLoader.load('/sprites/ui.json', { texture: 'smooth' });

console.log(pixelSheet === smoothSheet);  // false
```

Clear the cache when needed:

```typescript
TextureLoader.clearCache();
SpriteSheetLoader.clearCache();
TiledLoader.clearCache();
LDtkLoader.clearCache();
```

## Preloading

Load multiple assets in parallel:

```typescript
// Preload spritesheets
const sheets = await SpriteSheetLoader.preload([
  '/sprites/player.json',
  '/sprites/enemies.json',
  '/sprites/items.json',
]);

// Preload maps
const maps = await TiledLoader.preload([
  '/maps/level1.json',
  '/maps/level2.json',
]);
```

With texture options:

```typescript
const sheets = await SpriteSheetLoader.preload(
  ['/sprites/ui.json', '/sprites/hud.json'],
  { texture: 'smooth' }
);
```

# Pass Effects

> Full-screen post-processing with composable pass effects.

import { Tabs, TabItem } from 'starlight-theme/components';
import Compare from '../../../components/Compare.astro';

<Compare
  beforeSrc="/three-flatland/diagrams/passfx-off.webm"
  afterSrc="/three-flatland/diagrams/passfx-on.webm"
  beforePoster="/three-flatland/diagrams/passfx-off-poster.jpg"
  afterPoster="/three-flatland/diagrams/passfx-on-poster.jpg"
  beforeLabel="Raw scene"
  afterLabel="CRT pass applied"
  aspectRatio="1351 / 1001"
  zoom={1.0}
  alt="Same scene with no post-process vs a single CRT pass — barrel curvature, scanlines, and vignette all from one chain."
/>

**What you'll learn**
- The three effect layers (MaterialEffect / LightEffect / PassEffect) and which job each owns
- How to author a `PassEffect` with `createPassEffect` and chain multiple in insertion order
- The full `DefaultLightEffect` schema — uniforms vs compile-time constants, removed fields, `categoryQuotas`

---

Pass Effects are full-screen post-processing effects applied after sprite rendering. They transform the entire scene output — CRT curvature, scanlines, color quantization, VHS distortion, and more. Pass effects require a [Flatland](../flatland/) instance.

## The Three Effect Layers

import Diagram from '../../../components/Diagram.astro';
import effectLayers from '../../../assets/diagrams/effect-layers.svg?raw';
import passChainFusion from '../../../assets/diagrams/passeffect-chain-fusion.svg?raw';

<Diagram caption="Three effect layers in the render pipeline" src={effectLayers} />

three-flatland's effect system is layered, and the layers are easy to conflate because they share a factory shape (`createXEffect`) and a schema-driven API. Pick the right one for the job:

| Layer | Factory | Scope | When to Reach For It |
|-------|---------|-------|----------------------|
| **MaterialEffect** | `createMaterialEffect` | Per-sprite fragment shader | Damage flash, outline, dissolve, hue shift — anything that transforms one sprite's color. Channel providers (`NormalMapProvider`) are also MaterialEffects — see the [Baked Normal Pipeline](../loaders/#baked-normal-pipeline) for how to get a normal-map texture into `NormalMapProvider`. |
| **LightEffect** | `createLightEffect` | Scene singleton — drives every lit sprite | Choose or author the lighting model: tiled Forward+, GI, banded cel, etc. Exactly one is bound to a Flatland instance via `setLighting()`. See the [Lighting guide](../lighting/). |
| **PassEffect** | `createPassEffect` | Full-screen post-process | CRT, LCD grid, scanlines, VHS, chromatic aberration. Chained on the rendered scene after lighting. |

The rest of this guide focuses on PassEffect; for LightEffect authoring see the Lighting guide, and for MaterialEffect see the [TSL Nodes guide](../tsl-nodes/).

:::note[Quick disambiguation]
**MaterialEffects** and **PassEffects** both transform color, but at different scales: a MaterialEffect runs once per sprite fragment with access to that sprite's UVs and atlas frame, a PassEffect runs once per screen fragment with access to the composited scene texture. **LightEffects** are different again — they're not a transform, they're the lighting model itself, consumed by every lit sprite's MaterialEffect chain.
:::

## Creating a Pass Effect

Use `createPassEffect` with a name, a schema defining parameters, and a pass builder function:

```typescript
import { createPassEffect } from 'three-flatland'
import { posterize } from '@three-flatland/nodes'

const PosterizePass = createPassEffect({
  name: 'posterize',
  schema: { bands: 6 },
  pass: ({ uniforms }) => (input, uv) => {
    return posterize(input, uniforms.bands)
  },
})
```

The `pass` callback receives a context with TSL uniform nodes for each schema field and returns a `PassEffectFn`:

```typescript
type PassEffectFn = (input: Node<'vec4'>, uv: Node<'vec2'>) => Node<'vec4'>
```

- `input` — the scene color (or previous pass output)
- `uv` — screen-space UV coordinates

Schema fields become typed properties on instances with zero-cost uniform updates — changing a value updates the GPU uniform directly without rebuilding the shader graph.

## Using Pass Effects

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { Flatland, createPassEffect } from 'three-flatland'
    import { posterize, crtVignette } from '@three-flatland/nodes'

    const PosterizePass = createPassEffect({
      name: 'posterize',
      schema: { bands: 6 },
      pass: ({ uniforms }) => (input, uv) => posterize(input, uniforms.bands),
    })

    const VignettePass = createPassEffect({
      name: 'vignette',
      schema: { intensity: 0.4, curvature: 2 },
      pass: ({ uniforms }) => (input, uv) =>
        crtVignette(input, uv, uniforms.intensity, uniforms.curvature),
    })

    const flatland = new Flatland({ viewSize: 400, clearColor: 0x1a1a2e })

    // Add passes — they chain in insertion order
    const post = new PosterizePass()
    const vig = new VignettePass()
    flatland.addPass(post).addPass(vig)

    // Zero-cost parameter updates
    post.bands = 10
    vig.intensity = 0.25
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { useEffect, useRef } from 'react'
    import { extend, useFrame, useThree } from '@react-three/fiber/webgpu'
    import { Flatland, createPassEffect } from 'three-flatland/react'
    import { posterize, crtVignette } from '@three-flatland/nodes'
    import type { WebGPURenderer } from 'three/webgpu'

    extend({ Flatland })

    const PosterizePass = createPassEffect({
      name: 'posterize',
      schema: { bands: 6 },
      pass: ({ uniforms }) => (input, uv) => posterize(input, uniforms.bands),
    })

    const VignettePass = createPassEffect({
      name: 'vignette',
      schema: { intensity: 0.4, curvature: 2 },
      pass: ({ uniforms }) => (input, uv) =>
        crtVignette(input, uv, uniforms.intensity, uniforms.curvature),
    })

    function Scene() {
      const flatlandRef = useRef(null)
      const gl = useThree((s) => s.gl)

      useEffect(() => {
        const flatland = flatlandRef.current
        const post = new PosterizePass()
        post.bands = 10
        const vig = new VignettePass()
        vig.intensity = 0.25
        flatland.addPass(post).addPass(vig)
        return () => flatland.clearPasses()
      }, [])

      useFrame(() => {
        flatlandRef.current?.render(gl as unknown as WebGPURenderer)
      }, { phase: 'render' })

      return (
        <flatland ref={flatlandRef} viewSize={80} clearColor={0x1a1a2e}>
          {/* sprites */}
        </flatland>
      )
    }
    ```
  </TabItem>
</Tabs>

## Pass Chaining :badge[Advanced]{variant=note}

Multiple passes compose into a single pipeline. Each pass receives the previous pass's output:

<Diagram caption="Pass-chain cost — color-math passes fuse into one GPU program; a UV-sampling pass forces a convertToTexture boundary (render to texture, then sample)." src={passChainFusion} />

```typescript
flatland.addPass(posterize)   // 1. Reduce color bands
flatland.addPass(lcdGrid)     // 2. Apply LCD pixel grid
flatland.addPass(backlight)   // 3. Add backlight bleed
flatland.addPass(vignette)    // 4. Darken edges
```

:::tip[Performance note]
Passes that only do color math (posterize, quantize, scanlines, vignette) merge into a single shader — TSL compiles the chain into one GPU program. Passes that call `convertToTexture(input)` internally (CRT curvature, VHS distortion, chromatic aberration) introduce an intermediate texture sample because they need to read at different UVs. Stack the cheap ones freely; reach for the texture-sampling ones with intent.
:::

### Dynamic Switching

Swap pass chains at runtime:

```typescript
flatland.clearPasses()

// Apply a new preset
const crt = new CRTPass()
flatland.addPass(crt)
```

### Pass Management API

| Method | Description |
|--------|-------------|
| `flatland.addPass(pass, order?)` | Add a pass (optional explicit order) |
| `flatland.removePass(pass)` | Remove a specific pass |
| `flatland.clearPasses()` | Remove all passes |
| `flatland.passes` | Read-only array of current passes |
| `pass.enabled` | Toggle a pass without removing it |

## Effects That Need Texture Sampling

Some effects distort UVs — they read pixels at offset positions. These require `convertToTexture(input)` to create a sampable texture from the node graph:

```typescript
import { convertToTexture } from 'three/tsl'
import { createPassEffect } from 'three-flatland'
import { vhsDistortion } from '@three-flatland/nodes'

const VHSPass = createPassEffect({
  name: 'vhs',
  schema: { time: 0, intensity: 0.012, noiseAmount: 0.05 },
  pass: ({ uniforms }) => (input, uv) => {
    const tex = convertToTexture(input)
    return vhsDistortion(tex, uv, uniforms.time, uniforms.intensity, uniforms.noiseAmount)
  },
})
```

Effects that need `convertToTexture`: `crtComplete`, `crtCurvature`, `vhsDistortion`, `chromaticAberration`.

Effects that work directly on the color node: `posterize`, `quantize`, `scanlines`, `lcdGrid`, `crtVignette`, `lcdBacklightBleed`, `staticNoise`.

## Animating Parameters

Schema properties update the GPU uniform directly — no shader recompilation:

```typescript
const vhs = new VHSPass()
flatland.addPass(vhs)

// In the render loop
vhs.time = elapsed        // Drive distortion animation
vhs.intensity = 0.02      // Adjust strength
```

## Available TSL Nodes

All post-processing nodes are exported from `@three-flatland/nodes`:

### CRT Display

| Node | Description |
|------|-------------|
| `crtComplete` | Full CRT simulation (curvature + scanlines + bloom + vignette + color bleed) |
| `crtCurvature` | Barrel distortion for curved screen |
| `crtVignette` | Edge darkening |
| `crtBloom` | Glow from bright pixels |
| `crtColorBleed` | RGB channel offset |
| `crtConvergence` | RGB convergence offset |

### Scanlines

| Node | Description |
|------|-------------|
| `scanlinesSmooth` | Sine-wave scanline overlay |
| `scanlines` | Hard scanline pattern |
| `scanlinesGlow` | Bright scanline edges |
| `scanlinesInterlaced` | Alternating-field interlace |

### LCD Display

| Node | Description |
|------|-------------|
| `lcdGrid` | Visible pixel grid (handheld console) |
| `lcdBacklightBleed` | Uneven backlight glow |
| `dotMatrix` | Dot matrix display pattern |
| `lcdPocket` | Game Boy-style LCD |
| `lcdGBC` | Game Boy Color LCD |

### Retro Color

| Node | Description |
|------|-------------|
| `posterize` | Reduce color bands |
| `quantize` | 8-bit color reduction |
| `bayerDither4x4` | Ordered dithering |
| `palettize` | Map to a color palette |

### Analog Video

| Node | Description |
|------|-------------|
| `vhsDistortion` | VHS tracking errors and wave distortion |
| `staticNoise` | Analog TV snow |
| `chromaticAberration` | RGB channel separation |
| `ntscComposite` | NTSC signal artifacts |
| `analogGlitch` | Random glitch bands |

## DefaultLightEffect Schema

`DefaultLightEffect` is a LightEffect, not a PassEffect — but it's the most heavily-customized effect in the preset set, and its schema is documented here as the canonical place readers will look for "what knobs does the recommended lighting actually have?". For an introduction to LightEffects in general, see the [Lighting guide](../lighting/#how-it-works).

The schema splits cleanly into two flavors: **uniforms** that update at zero cost, and **compile-time constants** that trigger a shader rebuild when assigned.

### Uniforms (live-tunable, no rebuild)

Assigning these is a `.value =` write on a TSL uniform node — costs nothing. Animate them in your render loop without thinking about cost.

| Uniform | Default | Description |
|---------|---------|-------------|
| `shadowStrength` | `0.6` | Lerp factor from lit → traced shadow. `0` disables shadow contribution; `1` is full opacity. |
| `shadowBias` | `0.5` | Hit epsilon (world units) — SDF samples below this count as an occluder strike, terminating the trace. |
| `shadowStartOffsetScale` | `1` | Multiplier on each sprite's per-instance `shadowRadius` when the trace origin sits inside that caster's silhouette. Nudge above 1.0 if you see residual self-shadow on elongated sprites. |
| `shadowMaxDistance` | `0` | Max world-space distance a shadow extends from the receiver before fading. `0` disables falloff (binary shadow at any distance). Typical: 100–300 — keeps near-caster shadows solid while hiding cone-fan artifacts far from the caster. |
| `shadowPixelSize` | `0` | Snap the shadow trace's surface position to a world-unit block grid (1/2/4/8). Purely aesthetic — does NOT reduce GPU cost. |
| `bands` | `8` | Cel-band count for the direct-light contribution. |
| `pixelSize` | `0` | Surface-position snap cell width for the lighting math. |
| `glowRadius` | `0` | Broad secondary falloff radius (multiplied into per-light effective distance). |
| `glowIntensity` | `0` | Strength of the broad glow added to point/spot attenuation. |
| `lightHeight` | `0.75` | Universal +Z component added to every light's direction — higher reads as more top-lit. |
| `rimIntensity` | `0` | Strength of the rim-lighting accumulator. Rim power is fixed at `(1 − N·L)²`. |

### Compile-Time Constants (writable, but each write rebuilds)

These are stored as primitive constants on the effect instance. Setting them is legal at runtime, but each assignment triggers a shader rebuild and emits a dev-mode warning:

```
[three-flatland] defaultLight.glowEnabled changed at runtime — triggers shader rebuild
```

The payoff: when off, the gated branch never reaches the GPU, so a scene that doesn't use glow / rim / snap pays zero ops for those features.

| Constant | Default | What it gates |
|----------|---------|---------------|
| `glowEnabled` | `false` | Broad-falloff "glow" added to point/spot attenuation. ~9 ops per light per fragment when on. |
| `rimEnabled` | `false` | Rim-lighting accumulator + the inner `(1 − N·L)²` per-light term. ~6 ops per light per fragment when on. |
| `pixelSnapEnabled` | `false` | Surface-position snap for the lighting math (chunky cel cells). |
| `shadowPixelSnapEnabled` | `false` | Surface-position snap for the shadow trace origin (blocky shadow silhouettes). |
| `bandsEnabled` | `true` | Cel-band quantization of the direct-light contribution. |

Pattern in the example: derive the boolean from the uniform crossing zero, so the shader rebuilds on the 0 → N transition and live-updates while the slider stays above 0.

```typescript
const bandsEnabled = bands > 0
const pixelSnapEnabled = pixelSize > 0
const shadowPixelSnapEnabled = shadowPixelSize > 0
const glowEnabled = glowRadius > 0
const rimEnabled = rimIntensity > 0
```

:::caution[Cel quantization is mean-preserving but visually inflates mid-tones]
The cel formula `floor(x*N + 0.5)/N` rounds mid-tones up to the next quantization step — the boost is visible, while the compensating darkenings happen at very low values where they read as "still black." Net effect: cel mode looks BRIGHTER than smooth mode for the same physical scene values. **Disabling `bandsEnabled` may make a calibrated scene look dimmer** until you retune intensities (torches, fills, ambient) upward to compensate. The smooth branch is doing nothing wrong — the cel branch was inflating mid-tones.
:::

### Removed Fields

The following fields existed in earlier versions and have been removed. If you're migrating, delete the assignments — they'll be silently undefined now.

- **`rimPower`** — rim sharpness is now hardcoded as `(1 − N·L)²`. Saves a per-light `pow()` (an SFU instruction) for the case nobody actually slid at runtime. Fork the effect if you need a different curve.
- **`capShadowStrength`** / **`capShadowThreshold`** — the manual wall-cap darkening hack is replaced by elevation-aware N·L. Walls whose elevation exceeds `lightHeight` physically receive a negative L.z, clamp N·L to zero, and end up with only ambient — no special-case uniform required.

### `categoryQuotas` — JSX-Only Sugar

`DefaultLightEffect` instances expose a `categoryQuotas` accessor that proxies to the underlying `forwardPlus.setFillQuota(category, quota)` API. It's purely a declarative convenience for JSX users who don't want to grab a ref and reach into `forwardPlus`:

```tsx
<defaultLightEffect
  attach={attachLighting}
  categoryQuotas={{ slime: 4 }}
/>
```

Each set RESETS all buckets to default first, then applies the record — so removing a key between renders correctly clears that bucket's quota override (rather than leaving it stuck at the previous value).

For the full story on what these buckets are and how `category` maps onto them — including the per-category quota tuning APIs — see [Shadow Casting, Importance & Categories](../lighting-setup/#shadow-casting-importance--categories) in the Lighting guide.

## Next Steps

- [Pass Effects Example](../../examples/pass-effects/) — Interactive demo with 5 presets
- [Lighting Guide](../lighting/) — What a LightEffect actually is, plus Light2D fields
- [TSL Nodes Guide](../tsl-nodes/) — Per-sprite material effects and low-level TSL usage

# Shadows & Occlusion

> How Flatland's per-light SDF-traced soft shadows work — the occlusion mask, the JFA-generated distance field, and elevation-aware light shaping.

import Diagram from '../../../components/Diagram.astro';
import shadowTrace from '../../../assets/diagrams/shadow-sdf-trace.svg?raw';
import shadowElevation from '../../../assets/diagrams/shadow-elevation.svg?raw';

three-flatland renders per-light, SDF-traced soft shadows. Casters silhouette themselves into a screen-space mask each frame; a Jump Flood Algorithm (JFA) converts that mask into a signed distance field; lit fragments sphere-trace toward each light through the SDF and darken if a caster gets in the way. Shadows are soft, elevation-aware, and runtime-toggleable per light and per sprite — there are no shadow maps, no light-space cameras, and no per-light passes.

If your scene doesn't have shadows yet, you don't need this page. Come back when your hero is on screen and you want a proper torch-on-wall moment. This page is the mental model: how the pipeline turns casters into a distance field and how the trace reads it. For opting sprites and tiles in or out, the `shadowRadius` knobs, and the tuning uniforms, see the [Shadows guide](../shadows-setup/).

## How Shadows Work

The shadow pipeline runs as a pre-pass before the main scene render:

1. **OcclusionPass** renders every shadow-casting sprite and tile into an offscreen render target, masked by each instance's `castsShadow` bit. The output is a binary alpha silhouette of all casters in screen space.
2. **SDFGenerator** runs JFA over that alpha mask and produces a *signed* distance field — each texel stores world-space distance to the nearest caster (positive outside, negative inside).
3. **Lit fragment shader** (e.g. `DefaultLightEffect`) sphere-traces from each fragment toward each light through the SDF. If the trace hits an occluder before reaching the light, the fragment is shadowed for that light.

The SDF is recomputed every frame at half-resolution by default (the silhouette is binary, so quarter-area is plenty), and the trace runs at full resolution per-fragment per-light — but only when the fragment actually needs it (see [Performance](#performance)).

A single distance field serves every hero light, so occlusion cost is shared across lights rather than paid per-light-per-occluder. Fill lights (`castsShadow: false`) skip the trace entirely and contribute pure attenuated diffuse.

<Diagram caption="The shadow pipeline — casters become an occlusion mask, JFA builds a signed distance field, and each lit fragment sphere-traces toward the light through it" src={shadowTrace} />

## Self-Shadowing

The first time you mark a sprite as a caster, a question arises: the sprite *is* an occluder, so the shadow trace starts inside its own silhouette. Without an escape, every fragment of every caster would self-shadow against itself.

three-flatland handles this with a per-instance `shadowRadius` — the world-units distance the trace skips before sampling the SDF. A 64-unit knight needs ~64 units of escape; a 32-unit slime needs ~32. Manually tuning this per-sprite would be tedious, so the value is auto-derived every frame from the sprite's scale at batch-write time:

```ts
shadowRadius = max(Math.abs(scale.x), Math.abs(scale.y))
```

This tracks scale changes automatically and covers animated sprites whose source frame size differs (e.g. `AnimatedSprite2D` updates `scale` from `frame.sourceWidth/Height`). For most scenes you set `castsShadow = true` and never think about `shadowRadius` again. When you do need to override it — transparent art padding, non-uniform scale, a tighter escape — the [Shadows guide](../shadows-setup/#self-shadow-and-shadowradius) covers the manual knobs.

## Elevation-Aware Shadows

<Diagram caption="Why elevated wall caps go dark — a light's +Z component is lightHeight − elevation, so caps above the torch get a negative L.z and N·L clamps to zero." src={shadowElevation} />

`DefaultLightEffect` treats every light as a 3D direction with a `+Z` component (`lightHeight`, default `0.75`). When a sprite provides a per-fragment `elevation` channel — typically through `NormalMapProvider` reading the normal-map's blue channel — the elevation is subtracted from `lightHeight` before the diffuse `N·L` calculation:

```ts
L = normalize(vec3(toLight2D, lightHeight - elevation))
```

When `elevation > lightHeight`, `L.z` goes negative, `N·L` clamps to zero, and the fragment receives no direct light from that source. In practice this means **wall caps physically don't receive direct light** — they're elevated above the torch height, so the torch's contribution geometrically misses them. Floor fragments at `elevation = 0` see the full `lightHeight`, get strong diffuse, and behave like normal lit ground.

This replaces the older `capShadowStrength` / `capShadowThreshold` post-hoc darkening hack (now removed): instead of darkening caps after the fact, the geometry of the light direction does it for free. Elevation-aware shaping is automatic once your sprites carry a baked elevation channel and you're using `DefaultLightEffect` (which declares `requires: ['normal', 'elevation']`). For how to produce that channel and turn the feature on, see [Enabling Elevation-Aware Shadows](../shadows-setup/#enabling-elevation-aware-shadows).

## Performance

The per-light shadow trace is gated on the GPU by four runtime conditions, all of which must be true for the trace to run:

```ts
isAmbient === false
NdotL > 0
atten > 0.01
lightCastsShadow > 0.5
```

In practice this means most fragments skip the trace cheaply:

- **Ambient lights** never trace (they don't have a direction).
- **Back-faces** (`N·L ≤ 0`, including elevated wall caps under low torches) skip the trace — they're already dark.
- **Distant fragments** (`atten < 0.01`, sub-visible attenuation) skip the trace — the light couldn't make a visible delta anyway.
- **`castsShadow: false` lights** unconditionally skip the trace.

This is why flipping cosmetic fills to `castsShadow: false` is the dominant shadow-perf lever: the 32-tap SDF trace is the per-light cost, and a fill that skips it is nearly free. The [Shadows guide](../shadows-setup/#performance-knobs) covers the practical knobs (occlusion-mask resolution, caster counts).

## Next Steps

- [Shadows guide](../shadows-setup/) — Opt-in flags, `shadowRadius`, elevation setup, and tuning uniforms
- [2D Lighting](../lighting/) — The Forward+ pipeline shadows plug into
- [Sprites](../sprites/) — per-sprite flags including `castsShadow`, `receiveShadows`, and `shadowRadius`
- [Pass Effects](../pass-effects/) — the `DefaultLightEffect` schema and the shadow uniforms in context

# Shadows

> Opt sprites and tiles into the shadow pipeline, set shadowRadius, enable elevation-aware shaping, and tune DefaultLightEffect's shadow uniforms.

import { Tabs, TabItem } from 'starlight-theme/components';

This guide covers the practical side of shadows: opting sprites and tilemap tiles in or out, the self-shadow `shadowRadius` knobs, enabling elevation-aware shaping for top-down maps, and the shadow uniforms on `DefaultLightEffect`. For the pipeline itself — how the occlusion mask, the JFA-generated SDF, and the per-light sphere-trace fit together — see [Shadows & Occlusion](../shadows/).

## Opting In and Out

Three flags control who participates in the shadow pipeline. All three are zero-cost runtime toggles — flipping them takes effect on the next frame with no shader rebuild.

### Per-light: `Light2D.castsShadow`

Default: `true`. When set to `false`, the per-light SDF sphere-trace is skipped entirely on the GPU — that light contributes pure attenuated diffuse only. This is the recommended setting for cosmetic fill lights (slime auras, particle glows, magic VFX) where the shadow would be invisible against the surrounding fill anyway.

```typescript
const slimeGlow = new Light2D({
  type: 'point',
  color: 0x33ff66,
  intensity: 0.25,
  distance: 40,
  decay: 2,
  castsShadow: false,  // skip the 32-tap SDF trace for this light
})
```

The 32-tap SDF trace is the dominant per-light cost in dense scenes — turning it off for fills can be the difference between 60 fps and 30 fps when slime counts run high. See the [Lighting guide](../lighting-setup/#castsshadow--the-hero--fill-split) for the broader context on light categorization.

### Per-sprite caster: `Sprite2D.castsShadow`

Default: `false`. Set to `true` to contribute the sprite's silhouette to the occlusion mask. Most sprites should *not* cast (UI, particles, indicators); opt in for hero, enemies, props that need to throw shadows.

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    const knight = new AnimatedSprite2D({
      spriteSheet: knightSheet,
      animationSet: knightAnimations,
      animation: 'idle',
    })
    knight.castsShadow = true
    flatland.add(knight)
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    <animatedSprite2D
      texture={knightSheet.texture}
      spriteSheet={knightSheet}
      animationSet={knightAnimations}
      animation="idle"
      castsShadow
    />
    ```
  </TabItem>
</Tabs>

### Per-sprite receiver: `Sprite2D.receiveShadows`

Default: `true`. Set to `false` to opt the sprite out of shadow darkening — the sprite still renders lit, but the per-light shadow trace is bypassed for its fragments. Useful for foreground UI, particle effects, or any sprite that should never look dimmed by the world geometry.

```typescript
const uiPanel = new Sprite2D({ texture: uiTex })
uiPanel.receiveShadows = false
```

## Tilemap Occluders

Tilemap walls are the bulk of static occluders in most scenes. Rather than tagging tiles one-by-one, mark whole categories of tiles by their LDtk `obj.type`:

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    const mapData = await LDtkLoader.load('/maps/dungeon.ldtk', 'Level_0')
    const tilemap = new TileMap2D({ data: mapData })
    flatland.add(tilemap)

    // Mark every 'collision' IntGrid tile as a shadow caster.
    tilemap.markOccluders(['collision'])
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    function Level() {
      const mapData = useLoader(LDtkLoader, '/maps/dungeon.ldtk')
      const tilemapRef = useRef<TileMap2D>(null)

      useEffect(() => {
        tilemapRef.current?.markOccluders(['collision'])
      }, [mapData])

      return <tileMap2D ref={tilemapRef} data={mapData} />
    }
    ```
  </TabItem>
</Tabs>

`markOccluders(typeNames, layerIndex?)` walks every object layer, finds objects whose `type` matches, and flips the per-tile cast-shadow bit on the matching tile in the target layer (default: layer `0`). See the [Tilemaps guide](../tilemaps/#shadow-casting) for the deeper story on per-tile flag bits and how they interact with layer-level toggles.

## Self-Shadow and `shadowRadius`

A caster *is* an occluder, so the shadow trace starts inside its own silhouette. Each caster carries a per-instance `shadowRadius` — the world-units distance the trace skips before sampling the SDF — to escape self-shadowing. By default it auto-derives from the sprite's scale every frame (`max(|scale.x|, |scale.y|)`), so for most scenes you set `castsShadow = true` and never touch it. For why the escape is needed and how auto-derivation works, see [Self-Shadowing](../shadows/#self-shadowing).

### Manual override

Set `shadowRadius` explicitly when:

- The sprite art has transparent padding (auto-derive picks up the quad bounds, not the visible body)
- The sprite is non-uniformly scaled and the worst-case diagonal exit exceeds `max(scale.x, scale.y)`
- You want a tighter or looser self-shadow escape for a specific instance

```typescript
const sprite = new Sprite2D({ texture, castsShadow: true })
sprite.shadowRadius = 28  // tighter than auto-derived ~64
```

### Effect-level multiplier

`DefaultLightEffect` exposes `shadowStartOffsetScale` (default `1`) — a scene-wide multiplier on every sprite's resolved `shadowRadius`. Leave it alone unless you see residual self-shadow on elongated sprites (nudge above `1`) or the default over-pushes past nearby occluders (nudge below `1`).

```typescript
lighting.shadowStartOffsetScale = 1.2
```

## Enabling Elevation-Aware Shadows

`DefaultLightEffect` shapes light by elevation automatically once a sprite provides a per-fragment `elevation` channel — wall caps stop receiving direct light because they sit above the torch in the lighting math. The mechanism and the `L = normalize(vec3(toLight2D, lightHeight - elevation))` math live in [Elevation-Aware Shadows](../shadows/#elevation-aware-shadows). To turn it on:

1. Attach a `NormalMapProvider` with a baked normal map whose blue channel encodes elevation (see [Lighting → NormalMapProvider](../lighting-setup/#normalmapprovider)).
2. Use `DefaultLightEffect`, which declares `requires: ['normal', 'elevation']`.

The fastest way to get a normal map with a populated elevation channel is `LDtkLoader`'s [Baked Normal Pipeline](../loaders/#baked-normal-pipeline) — tagging tiles with `tileDir` / `tileCap*` / `tileElevation` custom data produces a per-tileset atlas where wall caps bake at elevation 1 and faces at the configured face elevation. The elevation channel is populated via the same offline pipeline `flatland-bake` ships — see the [Baking guide](../baking/) for running it ahead of time.

Tune `lightHeight` to taste — `0.75` reads as "torches sit above the floor, below the wall caps." Raising it to `1.5` lights everything (sun-like); lowering toward `0` makes torches barely scrape the floor and dramatically extends shadows.

```typescript
lighting.lightHeight = 0.75
```

## Tuning

`DefaultLightEffect` exposes the full set of shadow uniforms. All are zero-cost to update — they're TSL uniform nodes, not compile-time constants. For the full schema (which fields are uniforms vs constants, the `categoryQuotas` accessor, etc.), see the [Pass Effects guide](../pass-effects/).

| Uniform | Default | Description |
|---------|---------|-------------|
| `shadowStrength` | `0.6` | Lerp from lit to traced. `0` = no shadow, `1` = pure trace. |
| `shadowBias` | `0.5` | Hit epsilon (world units). Below this SDF value counts as a strike. |
| `shadowMaxDistance` | `0` | World-space max reach. `0` = no falloff (binary at any distance); `>0` fades shadows beyond this distance. |
| `shadowStartOffsetScale` | `1` | Multiplier on per-instance `shadowRadius`. |
| `shadowPixelSize` | `0` | Snap the trace origin to a world-unit block grid. `0` = per-fragment trace; `>0` = chunky shadow silhouettes (aesthetic only — does *not* reduce GPU cost). |
| `lightHeight` | `0.75` | `+Z` component of every light direction (used in elevation math). |

```typescript
const lighting = new DefaultLightEffect()
flatland.setLighting(lighting)

lighting.shadowStrength = 0.8
lighting.shadowBias = 0.5
lighting.shadowMaxDistance = 300  // fade shadows beyond 300 world units
```

`shadowMaxDistance` is the cheapest way to hide point-light cone-fan artifacts far from a caster: close shadows stay solid, distant shadows fade to lit. Typical values are `100`–`300` world units depending on viewport size.

`shadowPixelSize` is purely cosmetic — it produces blocky pixel-art shadow silhouettes by snapping the trace origin to a coarse grid. It does not reduce GPU cost; every fragment still traces. Use it for retro aesthetics, not for performance.

## Performance Knobs

The per-light trace is gated on the GPU so most fragments skip it cheaply (see [the gating conditions](../shadows/#performance) in the concept page for the full mechanism). The two knobs you control directly:

:::tip[The biggest win]
Setting `castsShadow: false` on cosmetic fill lights (slime auras, particle glows, magic VFX) is the single biggest perf win available — the 32-tap SDF trace is the dominant per-light cost in dense scenes. Save it for the lights whose *shadow shape* matters.
:::

- Per-sprite `castsShadow` controls the silhouette mask, which is rendered once per frame regardless of light count. Adding more caster sprites grows the mask render cost; adding more lights grows the trace cost.
- The OcclusionPass defaults to `resolutionScale: 0.5` (half-res silhouette mask). Drop to `0.25` on low-end mobile if shadow cost dominates and a blockier silhouette is acceptable.

## Next Steps

- [Shadows & Occlusion](../shadows/) — The mental model: occlusion mask, JFA-generated SDF, and the per-light trace
- [Lighting guide](../lighting-setup/) — `Light2D` types, presets, and the hero/fill split
- [Sprites](../sprites/) — per-sprite flags including `castsShadow`, `receiveShadows`, and `shadowRadius`
- [Tilemaps](../tilemaps/) — `markOccluders` and per-tile cast-shadow bits

# Skia

> GPU-accelerated 2D vector graphics with Skia WASM — shapes, text, gradients, and path operations.

import { Tabs, TabItem } from 'starlight-theme/components';
import Diagram from '../../../components/Diagram.astro';
import skiaRenderModes from '../../../assets/diagrams/skia-render-modes.svg?raw';

**What you'll learn**
- How to initialize Skia, mount a `SkiaCanvas` in texture or overlay mode, and render shapes
- How to load fonts and apply custom paints (gradients, blend modes, blur, drop shadow)
- How to perform programmatic path operations — `union`, `intersect`, `difference`, `xor`

---

:::caution[Experimental]
The `@three-flatland/skia` API isn't settled yet. We're dogfooding it across the examples and folding in [community feedback](https://github.com/thejustinwalsh/three-flatland/issues?q=is%3Aissue+label%3Askia) to stabilize it, so it can shift between releases. Pin an exact version for now.
:::

`@three-flatland/skia` brings Skia's GPU-accelerated vector rendering to Three.js via WASM, built with Zig. It auto-detects WebGPU or WebGL from your renderer and supports both Three.js and React Three Fiber.

You probably don't need this page yet. Skia earns its WASM weight when you need real vector graphics in 3D — UI overlays, dynamic text, path operations, gradients. For static images and animated sprites, plain `Sprite2D` is the right answer.

Includes a native WebGPU backend (Graphite/Dawn) — CanvasKit's npm package ships WebGL only. At **857 KB** (WebGPU) / **1 MB** (WebGL) brotli vs CanvasKit's 2.2 MB.

## Installation

<Tabs syncKey="pkg">
  <TabItem label="npm">
    ```bash
    npm install @three-flatland/skia
    ```
  </TabItem>
  <TabItem label="pnpm">
    ```bash
    pnpm add @three-flatland/skia
    ```
  </TabItem>
  <TabItem label="yarn">
    ```bash
    yarn add @three-flatland/skia three
    ```
  </TabItem>
  <TabItem label="bun">
    ```bash
    bun add @three-flatland/skia
    ```
  </TabItem>
  <TabItem label="agents">
    Paste this into your agent to add Skia drawing support:
    ~~~
    Add @three-flatland/skia to the project for GPU-accelerated 2D vector
    graphics (shapes, text, gradients, path ops) rendered via Skia WASM.

    Read the API reference: https://thejustinwalsh.com/three-flatland/llms-full.txt

    Install: npm install @three-flatland/skia
    Requires: three >= 0.183.1, auto-detects WebGPU or WebGL from renderer
    Import from: "@three-flatland/skia" (core), "@three-flatland/skia/three" (scene nodes), "@three-flatland/skia/react" (R3F integration)

    Key APIs:
    - Skia.init(renderer) — initialize WASM, returns SkiaContext
    - SkiaCanvas — root render target (texture mode or overlay mode)
    - Drawing nodes: SkiaRect, SkiaCircle, SkiaLine, SkiaPathNode, SkiaTextNode, SkiaGroup
    - SkiaPaint — custom gradients, shaders, effects (assign to node.paint)
    - SkiaPath — programmatic paths, boolean ops (difference, intersect, union, xor)
    - SkiaFontLoader — loads SkiaTypeface (useLoader compatible, cached by URL)
    - SkiaTypeface.atSize(n) — derive sized SkiaFont from a loaded typeface

    React patterns:
    - <SkiaCanvas> wrapper provides context to children via useSkiaContext()
    - useLoader(SkiaFontLoader, url) returns SkiaTypeface, call .atSize(n) for sized fonts
    - attachSkiaTexture — R3F attach helper for texture-on-material
    - useState(() => new SkiaPaint(skia)) for WASM objects (survives strict mode)
    - useFrame with { before: 'render' } / { after: 'render' } for render pipeline

    WASM setup: works zero-config with Vite dev server.
    For production, copy WASM to public: npx skia-wasm public/skia
    Override URL: Skia.init(renderer, { wasmUrl: '/skia/skia-gl.wasm' })
    ~~~
  </TabItem>
</Tabs>

Peer dependencies: `three >= 0.183.1`. For React: `@react-three/fiber >= 10.0.0-alpha.2` and `react >= 19.0.0`.

### WASM Setup

Skia ships ~1 MB WASM binaries (one for WebGL, one for WebGPU). **Vite handles this automatically** in dev — no config needed. For production builds or other bundlers, copy the WASM to your public directory:

```bash
npx skia-wasm public/skia
```

This copies `skia-gl.wasm` and `skia-wgpu.wasm` to `public/skia/`. Then tell Skia where to find them:

```typescript
// Option 1: pass the URL directly
const skia = await Skia.init(renderer, { wasmUrl: '/skia/skia-gl.wasm' })

// Option 2: set env vars (replaced at build time by your bundler)
// webpack.config.js
const { DefinePlugin } = require('webpack')
module.exports = {
  plugins: [
    new DefinePlugin({
      'process.env.SKIA_WASM_URL_GL': JSON.stringify('/skia/skia-gl.wasm'),
      'process.env.SKIA_WASM_URL_WGPU': JSON.stringify('/skia/skia-wgpu.wasm'),
    }),
  ],
}
```

:::tip[Zero Config with Vite]
During development, Vite resolves `import.meta.url` correctly so the WASM loads from `node_modules` with no extra setup. You only need the copy step for production builds or non-Vite bundlers.
:::

## Initialization

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { Skia } from '@three-flatland/skia'
    import { SkiaCanvas, SkiaRect } from '@three-flatland/skia/three'

    // Auto-detects WebGL or WebGPU from the renderer
    const skia = await Skia.init(renderer)

    const canvas = new SkiaCanvas({ renderer, width: 512, height: 512 })
    canvas.add(new SkiaRect())

    // In your animation loop:
    canvas.invalidate()
    canvas.render()
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { useThree } from '@react-three/fiber/webgpu'
    import { SkiaCanvas, SkiaRect, useSkiaContext } from '@three-flatland/skia/react'

    // SkiaCanvas initializes Skia and provides context to children.
    // Child components access it via useSkiaContext().
    function MyScene() {
      const renderer = useThree((s) => s.gl)
      return (
        <SkiaCanvas renderer={renderer} width={512} height={512}>
          <skiaRect x={10} y={10} width={100} height={50} fill={[1, 0, 0, 1]} />
        </SkiaCanvas>
      )
    }
    ```
  </TabItem>
</Tabs>

:::tip[Import Paths]
Three.js: import from `@three-flatland/skia` (core) and `@three-flatland/skia/three` (scene graph nodes).
React: import from `@three-flatland/skia/react` which re-exports everything plus hooks and attach helpers.
:::

## SkiaCanvas :badge[Alpha]{variant=caution}

The root node that owns the render target and walks children to draw. Two modes:

<Diagram caption="SkiaCanvas render modes — texture mode draws before the scene and feeds a mesh map; overlay mode composites onto the framebuffer after the scene." src={skiaRenderModes} />

| Mode | Description | Use Case |
|------|-------------|----------|
| **Texture** | Renders to an off-screen texture (`canvas.texture`) | Apply Skia output to 3D mesh materials |
| **Overlay** | Renders to the screen framebuffer | HUD, debug text, UI on top of 3D |

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    // Texture mode (default)
    const shapes = new SkiaCanvas({ renderer, width: 1024, height: 880 })

    // Overlay mode
    const overlay = new SkiaCanvas({
      renderer,
      width: window.innerWidth * dpr,
      height: window.innerHeight * dpr,
      overlay: true,
    })
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    // Texture mode — use attachSkiaTexture to apply to a material
    <meshBasicMaterial transparent premultipliedAlpha>
      <SkiaCanvas attach={attachSkiaTexture} renderer={renderer}
                  width={1024} height={880}>
        {/* shapes */}
      </SkiaCanvas>
    </meshBasicMaterial>

    // Overlay mode
    <SkiaCanvas ref={overlayRef} renderer={renderer}
                width={pw} height={ph} overlay>
      {/* HUD elements */}
    </SkiaCanvas>
    ```
  </TabItem>
</Tabs>

### Render Pipeline

SkiaCanvas does not auto-render. Call `render()` each frame — it automatically marks the canvas dirty and draws:

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    function animate() {
      // 1. Render Skia shapes to texture
      shapesCanvas.render()

      // 2. Apply texture to mesh
      material.map = shapesCanvas.texture

      // 3. Render 3D scene
      renderer.render(scene, camera)

      // 4. Overlay on top
      overlay.render()
    }
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    // Shapes texture — render before Three.js scene
    useFrame(() => {
      canvasRef.current?.render()
    }, { before: 'render' })

    // Overlay — render after Three.js scene
    useFrame(() => {
      overlayRef.current?.render()
    }, { after: 'render' })
    ```
  </TabItem>
</Tabs>

## Drawing Nodes :badge[Alpha]{variant=caution}

All nodes extend `SkiaNode` (which extends Three.js `Object3D`) and accept inline paint props.

### Common Paint Props

| Prop | Type | Description |
|------|------|-------------|
| `fill` | `[r, g, b, a]` | Fill color (0-1 floats) |
| `stroke` | `[r, g, b, a]` | Stroke color |
| `strokeWidth` | `number` | Stroke width in pixels |
| `opacity` | `number` | 0-1 opacity |
| `blur` | `number` | Gaussian blur sigma |
| `blendMode` | `BlendMode` | Compositing blend mode |
| `paint` | `SkiaPaint` | Explicit paint (overrides all above) |

### Shape Nodes

```tsx
{/* Rectangle with rounded corners */}
<skiaRect x={10} y={10} width={200} height={100}
          cornerRadius={12} fill={[0.2, 0.4, 1, 1]} />

{/* Circle */}
<skiaCircle cx={150} cy={150} r={60} fill={[1, 0.3, 0.3, 1]} />

{/* Ellipse */}
<skiaOval x={100} y={100} width={200} height={120}
          stroke={[1, 0.8, 0.2, 1]} strokeWidth={3} />

{/* Line */}
<skiaLine x1={10} y1={10} x2={200} y2={100}
          stroke={[1, 1, 1, 0.5]} strokeWidth={2} />
```

### Path Node

Accepts SVG path data or an explicit `SkiaPath` reference:

```tsx
{/* From SVG data string */}
<skiaPathNode d="M10 80 Q95 10 180 80" fill={[1, 1, 1, 1]} />

{/* From SkiaPath reference (for dynamic paths, boolean ops) */}
<skiaPathNode path={myPath} fill={[0.9, 0.3, 0.3, 0.9]} />
```

### Text Node

Requires a `SkiaFont` loaded via `SkiaFontLoader`:

```tsx
<skiaTextNode text="Hello Skia" font={font}
              fill={[1, 1, 1, 1]} x={20} y={40} />
```

## SkiaGroup :badge[Alpha]{variant=caution}

Groups apply 2D transforms, clipping, and layer effects to all children:

```tsx
<skiaGroup position={[100, 50, 0]} scale={[2, 2, 1]}>
  <skiaRect fill={[1, 0, 0, 1]} width={50} height={50} />
</skiaGroup>
```

Uses standard Object3D `position`, `scale`, and `rotation.z` (radians). The `degrees` prop is a convenience shorthand.

| Prop | Description |
|------|-------------|
| `position` | Translation (Object3D — `[x, y, z]`) |
| `rotation` | Rotation (Object3D — `rotation.z` in radians) |
| `degrees` | Rotation in degrees (convenience, overrides `rotation.z`) |
| `scale` | Scale (Object3D — `[x, y, z]`) |
| `skewX`, `skewY` | Skew (Skia-specific, no Object3D equivalent) |
| `opacity` | Layer opacity |
| `blur` | Gaussian blur on group |
| `shadow` | Drop shadow (`{ dx, dy, blur, color }`) |
| `clipRect` | `[x, y, w, h]` clip rectangle |
| `backdropBlur` | Frosted glass effect |

## Font Loading

:::tip[Performance note]
The typeface is cached by URL, and sized fonts are cached internally on the typeface — so calling `.atSize(14)` and `.atSize(32)` from many components shares a single font fetch and a single set of size objects. No need to memoize.
:::

`SkiaFontLoader` loads a `SkiaTypeface` — the font data independent of size. Call `.atSize(n)` to get a sized `SkiaFont`.

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { SkiaFontLoader } from '@three-flatland/skia/three'

    const typeface = await SkiaFontLoader.load('/fonts/Inter.ttf')
    const titleFont = typeface.atSize(32)
    const bodyFont = typeface.atSize(14)
    textNode.font = titleFont
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { useLoader } from '@react-three/fiber/webgpu'
    import { SkiaFontLoader } from '@three-flatland/skia/react'

    function TextComponent() {
      // useLoader caches the typeface by URL — one fetch, multiple sizes
      const typeface = useLoader(SkiaFontLoader, '/fonts/Inter.ttf')
      const titleFont = typeface.atSize(32)
      const bodyFont = typeface.atSize(14)

      return <>
        <skiaTextNode text="Title" font={titleFont} fill={[1, 1, 1, 1]} />
        <skiaTextNode text="Body" font={bodyFont} fill={[0.8, 0.8, 0.8, 1]} />
      </>
    }
    ```
  </TabItem>
</Tabs>

The typeface resolves the `SkiaContext` lazily — if no context is available when `atSize()` is called, it falls back to the global `SkiaContext.instance` singleton. Inside a `<SkiaCanvas>` subtree, this is always available.

## Custom Paints

For gradients, shaders, and effects beyond flat fill/stroke, create a `SkiaPaint`:

```typescript
import { SkiaPaint } from '@three-flatland/skia'

const paint = new SkiaPaint(skia)
  .setFill()
  .setLinearGradient(0, 0, 200, 0,
    [0xFFFF0000, 0xFF0000FF], [0, 1])

rect.paint = paint // overrides inline fill/stroke props
```

In React, use `useState` initializer to create paints that survive strict mode:

```tsx
const skia = useSkiaContext()!
const [paint] = useState(() => new SkiaPaint(skia).setFill())

useFrame(({ elapsed }) => {
  // Animate the gradient each frame
  paint.setLinearGradient(...)
})

return <skiaRect paint={paint} x={0} y={0} width={200} height={50} />
```

## Path Operations

Create paths programmatically and perform boolean operations:

```typescript
import { SkiaPath } from '@three-flatland/skia'

const a = new SkiaPath(skia).addCircle(100, 100, 40)
const b = new SkiaPath(skia).addCircle(130, 100, 40)
const result = new SkiaPath(skia)

a.opInto(b, 'intersect', result) // 'difference' | 'intersect' | 'union' | 'xor'
pathNode.path = result
```

Operations: `difference`, `intersect`, `union`, `xor`, `reverse-difference`.

## Texture Attachment (React)

`attachSkiaTexture` is an R3F attach helper that grabs `.texture` from a `SkiaCanvas` and assigns it to the parent material's `map`:

```tsx
import { SkiaCanvas, attachSkiaTexture } from '@three-flatland/skia/react'

<meshBasicMaterial transparent premultipliedAlpha>
  <SkiaCanvas attach={attachSkiaTexture} renderer={renderer}
              width={1024} height={880}>
    {/* Skia shapes rendered to texture */}
  </SkiaCanvas>
</meshBasicMaterial>
```

## Next Steps

- [Skia Example](../../examples/skia/) — Full interactive demo
- [Sprites Guide](../sprites/) — Three-flatland 2D sprites

# Slug Text

> GPU-accelerated, resolution-independent text rendering using the Slug algorithm.

import { Tabs, TabItem } from 'starlight-theme/components'
import Diagram from '../../../components/Diagram.astro'
import slugFontLoading from '../../../assets/diagrams/slug-font-loading.svg?raw'

The `@three-flatland/slug` package renders crisp, resolution-independent text on the GPU using the [Slug algorithm](https://jcgt.org/published/0006/02/02/). Font outlines are rasterized per-pixel from quadratic Bezier curves — no texture atlases, no SDF approximations, no blurry edges at any zoom level.

:::caution[Experimental]
The `@three-flatland/slug` API isn't settled yet. We're dogfooding it and folding in [community feedback](https://github.com/thejustinwalsh/three-flatland/issues?q=is%3Aissue+label%3Aslug) to stabilize it, so it can shift between releases. Pin an exact version for now.
:::

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { WebGPURenderer } from 'three/webgpu';
    import { SlugFontLoader, SlugText } from '@three-flatland/slug';

    const font = await SlugFontLoader.load('/fonts/Inter-Regular.ttf');
    const text = new SlugText({
      font,
      text: 'Hello, Slug!',
      fontSize: 48,
      color: 0xffffff,
      align: 'center',
    });

    scene.add(text);

    // Per-frame update (required for dilation + dirty rebuild)
    function animate() {
      requestAnimationFrame(animate);
      text.update(camera);
      renderer.render(scene, camera);
    }
    ```

  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { Canvas, extend, useFrame, useLoader, useThree } from '@react-three/fiber/webgpu';
    import { SlugText, SlugFontLoader } from '@three-flatland/slug/react';

    extend({ SlugText });

    function TextScene() {
      const font = useLoader(SlugFontLoader, '/fonts/Inter-Regular.ttf');
      const ref = useRef<SlugText>(null);
      const { camera, size } = useThree();

      useEffect(() => {
        ref.current?.setViewportSize(size.width, size.height);
      }, [size]);

      useFrame(() => {
        ref.current?.update(camera);
      });

      return (
        <slugText
          ref={ref}
          font={font}
          text="Hello, Slug!"
          fontSize={48}
          color={0xffffff}
          align="center"
        />
      );
    }
    ```

  </TabItem>
</Tabs>

:::tip[WebGPU & WebGL2]
Slug text works with both the WebGPU renderer and its WebGL2 fallback. The TSL shaders compile to WGSL or GLSL ES 3.0 automatically.
:::

## Loading Fonts

`SlugFontLoader` is the single entry point for loading fonts. It automatically tries pre-baked data first (a single `.slug.glb`), and falls back to runtime parsing from the `.ttf` if baked data isn't available.

<Diagram caption="SlugFontLoader resolution — a baked .slug.glb loads directly and skips opentype.js; a miss falls back to fetching and parsing the .ttf at runtime." src={slugFontLoading} />

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { SlugFontLoader } from '@three-flatland/slug';

    const font = await SlugFontLoader.load('/fonts/MyFont.ttf');
    ```

  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { useLoader } from '@react-three/fiber/webgpu';
    import { SlugFontLoader } from '@three-flatland/slug/react';

    // Inside a component within <Canvas>, with <Suspense> boundary
    const font = useLoader(SlugFontLoader, '/fonts/MyFont.ttf');
    ```

  </TabItem>
</Tabs>

After loading, the font provides:

- `font.glyphs` — parsed glyph data (`Map<number, SlugGlyphData>`)
- `font.curveTexture` — GPU texture with Bezier control points
- `font.bandTexture` — GPU texture with spatial acceleration data
- `font.unitsPerEm`, `font.ascender`, `font.descender`, `font.capHeight` — font metrics
- `font.measureText(text, fontSize)`, `font.measureParagraph(text, fontSize, opts)`, `font.wrapText(text, fontSize, maxWidth)` — measurement helpers

## SlugText Properties

`SlugText` extends `InstancedMesh` — each glyph is an instanced quad evaluated per-pixel by the Slug fragment shader.

| Property     | Type                            | Default     | Description                                      |
| ------------ | ------------------------------- | ----------- | ------------------------------------------------ |
| `font`       | `SlugFont \| null`              | `null`      | Font to render with                              |
| `text`       | `string`                        | `''`        | Text content                                     |
| `fontSize`   | `number`                        | `16`        | Font size in scene units                         |
| `color`      | `Color \| number`               | `0xffffff`  | Text color                                       |
| `opacity`    | `number`                        | `1.0`       | Fill opacity                                     |
| `align`      | `'left' \| 'center' \| 'right'` | `'left'`    | Horizontal alignment                             |
| `lineHeight` | `number`                        | `1.2`       | Line height multiplier                           |
| `maxWidth`   | `number \| undefined`           | `undefined` | Max width for word wrapping                      |
| `styles`     | `StyleSpan[]`                   | `[]`        | Underline / strike / super-sub spans (see below) |
| `outline`    | `SlugOutlineOptions \| null`    | `null`      | Optional stroke outline (see below)              |

All properties can be set after construction. Changes are applied on the next `update()` call.

## Per-Frame Updates

`SlugText.update(camera)` does two things:

1. **Rebuilds geometry** if any property changed (dirty flag)
2. **Updates the MVP matrix** for vertex dilation — this must happen every frame since the camera or object may move

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    function animate() {
      requestAnimationFrame(animate);
      text.update(camera);
      renderer.render(scene, camera);
    }
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    useFrame(() => {
      ref.current?.update(camera);
    });
    ```
  </TabItem>
</Tabs>

## Viewport Size

For correct edge dilation (half-pixel anti-aliasing at quad boundaries), call `setViewportSize` when the viewport changes:

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    text.setViewportSize(window.innerWidth, window.innerHeight);

    window.addEventListener('resize', () => {
      text.setViewportSize(window.innerWidth, window.innerHeight);
    });
    ```

  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    const { size } = useThree();

    useEffect(() => {
      ref.current?.setViewportSize(size.width, size.height);
    }, [size]);
    ```

  </TabItem>
</Tabs>

## Dynamic Text

Change any property and the text rebuilds on the next `update()`:

```typescript
text.text = 'New content'
text.fontSize = 96
text.align = 'right'
text.color = 0xff0000
// Geometry rebuilds automatically on next update() call
```

## Multi-line & Word Wrap

Set `maxWidth` to enable automatic word wrapping. Line breaks (`\n`) are also supported:

```typescript
const text = new SlugText({
  font,
  text: 'This is a long paragraph that will wrap automatically.',
  fontSize: 24,
  maxWidth: 400,
  lineHeight: 1.4,
})
```

## Measurement

`SlugFont` exposes a measurement API mirroring `CanvasRenderingContext2D.measureText` for layouts that don't need GPU geometry — overlays, hit-testing, fitting text inside a box.

```typescript
const m = font.measureText('Hello, Slug!', 48)
// m.width
// m.actualBoundingBoxLeft / .actualBoundingBoxRight
// m.actualBoundingBoxAscent / .actualBoundingBoxDescent
// m.fontBoundingBoxAscent / .fontBoundingBoxDescent
```

For wrapped paragraphs:

```typescript
const para = font.measureParagraph(longText, 24, {
  maxWidth: 400,
  lineHeight: 1.4, // matches SlugText's default — measurements agree with rendering
})
// para.width (widest line), para.height (block height)
// para.lines: [{ text, width }, ...]
```

`font.wrapText(text, fontSize, maxWidth)` exposes the same wrap policy `SlugText` uses internally — useful when you need to compare line breaks against another renderer (Canvas2D, DOM).

## Decorations (underline, strikethrough, super/sub)

Apply `StyleSpan[]` over half-open `[start, end)` UTF-16 ranges:

```typescript
const text = new SlugText({
  font,
  text: 'Bold and underlined and ²',
  fontSize: 48,
  styles: [
    { start: 9, end: 21, underline: true }, // "underlined"
    { start: 24, end: 25, scriptLevel: 2 }, // superscript "2"
  ],
})
```

| Field          | Type      | Description                                                                                        |
| -------------- | --------- | -------------------------------------------------------------------------------------------------- |
| `start`, `end` | `number`  | Half-open code-unit range.                                                                         |
| `underline`    | `boolean` | Underline rect at the font's `underlinePosition`.                                                  |
| `strike`       | `boolean` | Strikethrough rect at the font's `strikethroughPosition`.                                          |
| `scriptLevel`  | `number`  | Slug `script(n)` level. Positive = superscript, negative = sub. Magnitude ∈ `[1, 3]` is the depth. |

Decoration rects render through the same instance pipeline as glyphs (no second draw call) — they short-circuit the fragment shader to solid coverage via a sentinel bit on the instance attributes.

## Multi-font fallback (`SlugFontStack` / `SlugStackText`)

Render strings whose codepoints span multiple loaded fonts. The first font in the stack with a non-zero glyphId for a given codepoint wins (per-character, automatic — authors don't tag runs).

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { SlugFontLoader, SlugFontStack, SlugStackText } from '@three-flatland/slug';

    const [inter, fa] = await Promise.all([
      SlugFontLoader.load('/fonts/Inter-Regular.ttf'),
      SlugFontLoader.load('/fonts/FontAwesome-Regular.ttf'),
    ]);

    const stack = new SlugFontStack([inter, fa]);

    const text = new SlugStackText({
      fontStack: stack,
      text: 'Lorem  search',  // last char is an FA icon
      fontSize: 48,
    });
    scene.add(text);
    ```

  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { extend } from '@react-three/fiber/webgpu';
    import { SlugStackText, SlugFontStack } from '@three-flatland/slug/react';

    extend({ SlugStackText });

    function StackedText({ fonts }: { fonts: SlugFont[] }) {
      const stack = useMemo(() => new SlugFontStack(fonts), [fonts]);
      return <slugStackText fontStack={stack} text="Lorem  search" fontSize={48} />;
    }
    ```

  </TabItem>
</Tabs>

`SlugStackText` renders one `InstancedMesh` per backing font — one extra draw call per fallback font. It has full `SlugText` parity (`styles`, `outline`, `setOpacity`, `dispose`).

:::caution[Color emoji not supported]
COLR / CPAL / CBDT (color-glyph tables) are out of scope. Emoji glyphs render as their outline if present, otherwise notdef. A roadmap entry tracks this.
:::

## Outline

Add a stroked outline behind the fill:

```typescript
const text = new SlugText({
  font,
  text: 'Hello, Slug!',
  fontSize: 96,
  color: 0xffffff,
  outline: {
    width: 0.025, // em-space half-width (~5% em total stroke width)
    color: 0x000000,
  },
})
```

Width and color update at runtime via uniforms — no rebuild:

```typescript
text.setOutlineWidth(0.05)
text.setOutlineColor(0xff0000)
```

Outline-only text:

```typescript
text.setOpacity(0) // hide fill, keep outline visible
```

The current dynamic shader uses `min(distance)` over the glyph's curves, producing a clean **bevel** at exterior corners. Interior corners stay crisp by construction. Miter / round joins, caps, dashing, and a 1× fill cost baked path are landing in [Phase 5 (#37)](https://github.com/thejustinwalsh/three-flatland/issues/37); the dynamic shader will stay as `outline.mode = 'dynamic'` for live width scrubbing.

## Material Options

`SlugText` creates a `SlugMaterial` internally. Several shader-level options are available at construction time (some compile-time constants, some runtime uniforms):

| Option        | Type      | Default | Description                              |
| ------------- | --------- | ------- | ---------------------------------------- |
| `evenOdd`     | `boolean` | `false` | Even-odd fill rule (compile-time).       |
| `weightBoost` | `boolean` | `false` | `sqrt()` coverage boost (compile-time).  |
| `stemDarken`  | `number`  | `0`     | Stem darkening strength; ~0.4 is subtle. |
| `thicken`     | `number`  | `0`     | Coverage thickening at low ppem.         |
| `pixelSnap`   | `boolean` | `true`  | Snap glyph positions to pixel grid.      |
| `supersample` | `boolean` | `false` | 2×2 supersampling (expensive).           |

## Pre-baking Fonts

For production, use `slug-bake` to pre-process fonts offline. This eliminates opentype.js at runtime and lets you subset to only the glyphs you need:

```bash
# Install (or use npx)
npx slug-bake Inter-Regular.ttf

# Subset to ASCII only — 32 KB with Brotli
npx slug-bake Inter-Regular.ttf --range ascii

# Latin extended
npx slug-bake Inter-Regular.ttf --range latin

# Multiple ranges
npx slug-bake Inter-Regular.ttf -r latin -r 0x2000-0x206F
```

Place the `.slug.glb` file alongside the font. `SlugFontLoader.load()` detects it automatically — no code changes needed. The `.ttf` is never fetched when baked data is present, and opentype.js never enters the bundle.

| Range   | Glyphs | Raw      | Brotli |
| ------- | ------ | -------- | ------ |
| All     | 2,849  | 12.78 MB | 724 KB |
| `latin` | 523    | 2.15 MB  | 208 KB |
| `ascii` | 95     | 412 KB   | 32 KB  |

:::tip[CDN Compression]
Rely on your CDN's gzip/brotli — the browser decompresses automatically with zero JS cost. ASCII-only Inter with Brotli is **32 KB** for resolution-independent text at any zoom level.
:::

Missing glyphs render as a fallback rectangle. Named ranges: `ascii`, `latin`, `latin+`. Custom ranges use hex (`0x20-0x7E`) or decimal (`32-126`).

## How It Works

The Slug algorithm renders each pixel by:

1. Casting dual rays (horizontal + vertical) from the pixel center
2. Solving quadratic equations to find Bezier curve intersections
3. Computing winding number from intersection results
4. Producing fractional coverage for anti-aliased edges

Spatial band structures accelerate the per-pixel curve lookup, and vertex dilation expands each glyph quad by half a pixel to ensure boundary fragments are evaluated.

# Sprites

> Learn how to create and customize 2D sprites.

import { Tabs, TabItem } from 'starlight-theme/components';
import Diagram from '../../../components/Diagram.astro';
import spriteAnatomy from '../../../assets/diagrams/sprite-anatomy.svg?raw';

**What you'll learn**
- How to create, position, anchor, and scale a `Sprite2D`
- How to opt sprites into the lighting and shadow pipeline (`lit`, `castsShadow`, `shadowRadius`)
- How layers and z-index control render order independently of scene-graph order

---

The `Sprite2D` class is the foundation for 2D rendering in three-flatland. If your scene only ever needs static images on screen, this is the only class you need to learn.

<Diagram caption="Anatomy of a Sprite2D — anchor sets the pivot the quad hangs from, scale gives it pixel size, tint multiplies the sampled texture, and layer plus zIndex decide draw order." src={spriteAnatomy} />

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { Sprite2D, SpriteGroup } from 'three-flatland';

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

    spriteGroup.add(sprite);
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    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>
      );
    }
    ```
  </TabItem>
</Tabs>

:::tip[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](../loaders/) for details.
:::

## Properties

### Position

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

```typescript
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 geometry is a unit plane — display size comes from `scale`. Set `scale.set(width, height, 1)` in pixels:

```typescript
const sprite = new Sprite2D({ texture: myTexture });
sprite.scale.set(64, 64, 1);
```

To sample a sub-region of a texture atlas, pass a `frame` from a `SpriteSheet`:

```typescript
const sprite = new Sprite2D({
  texture: sheet.texture,
  frame: sheet.getFrame('player_idle_0'),
});
```

## SpriteGroup

For batched rendering with many sprites, use `SpriteGroup`:

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    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);
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    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>
      );
    }
    ```
  </TabItem>
</Tabs>

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

:::tip[Flatland]
For a complete 2D pipeline with camera, post-processing, and global uniforms, use [Flatland](../flatland/) instead of adding a SpriteGroup to your scene manually.
:::

## Lighting and shadows

Sprites integrate with the active `LightEffect` and the SDF shadow pipeline through four properties. All four are also accepted as constructor options and as JSX props on `<sprite2D>`.

| Property | Type | Default | Purpose |
|----------|------|---------|---------|
| `lit` | `boolean` | `true` | Receive lighting from the attached `LightEffect`. |
| `receiveShadows` | `boolean` | `true` | Allow lit fragments to be darkened by the SDF shadow trace. |
| `castsShadow` | `boolean` | `false` | Contribute the sprite's silhouette to the SDF occlusion pre-pass. |
| `shadowRadius` | `number \| undefined` | `undefined` (auto) | Per-instance occluder radius in world units. |

```typescript
const hero = new Sprite2D({ texture, castsShadow: true })
hero.lit = true              // (default) reacts to lights
hero.receiveShadows = false  // opt out of being darkened by shadow zones
```

In React:

```tsx
<sprite2D
  texture={myTexture}
  castsShadow
  lit
  receiveShadows={false}
/>
```

`lit`, `receiveShadows`, and `castsShadow` are bit flags packed into `instanceSystem.z` of the interleaved instance buffer (see [Batch Rendering](../batch-rendering/) for material authors).

:::tip[Performance note]
Flipping `lit`, `receiveShadows`, or `castsShadow` at runtime takes effect on the next frame with no shader rebuild. Toggle them per frame if you need to — they're zero-cost runtime knobs, not compile-time decisions.
:::

### shadowRadius

`shadowRadius` is the world-space size of the sprite as a shadow occluder. It's consumed by SDF shadow tracers as the **self-silhouette escape distance** — the value the trace steps "out of" when the sample point starts on top of the caster.

When left `undefined` (the default), `transformSyncSystem` auto-derives it each frame from `max(|scale.x|, |scale.y|)` so it tracks scale changes (including animation frames whose source sizes differ). Set it explicitly when:

- The visible body is tighter than the quad's bounds (e.g., a sprite with transparent padding shouldn't use its full bounding-box scale as the silhouette radius).
- The anchor pushes the silhouette off-center and you need a different effective size.

```typescript
sprite.shadowRadius = 12   // override
sprite.shadowRadius = undefined  // back to auto
```

:::tip[Shadow internals]
For the full occlusion pipeline — caster pre-pass, SDF generation, and how the trace consumes `shadowRadius` — see the [Shadows guide](../shadows/).
:::

## Layers

Use the `Layers` enum to control render order:

```typescript
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.EFFECTS` - Particles and effect sprites
- `Layers.FOREGROUND` - Foreground elements
- `Layers.UI` - User interface

## Next steps

- [Basic Sprite example](../../examples/basic-sprite/) — texture loading, anchor, and interaction in a runnable scene.
- [`Sprite2D` API reference](/three-flatland/api/three-flatland/src/classes/sprite2d/) — every constructor option and property.
- [Animation](../animation/) for spritesheet playback, and [Batch Rendering](../batch-rendering/) for thousands of sprites in a few draw calls.

# Tilemaps

> Render tile-based maps efficiently with three-flatland.

import { Tabs, TabItem } from 'starlight-theme/components';
import Diagram from '../../../components/Diagram.astro';
import tilemapStructure from '../../../assets/diagrams/tilemap-structure.svg?raw';

**What you'll learn**
- How to load a Tiled or LDtk map and render it via `TileMap2D` with chunked rendering
- How to mark wall tiles as shadow occluders with `markOccluders(['collision'])`
- How to read and modify tiles at runtime, and convert between world / tile coordinates

---

Tilemaps allow you to render large tile-based environments efficiently using chunked rendering. The `TileMap2D` class handles maps with multiple layers and automatic chunking for performance.

For your first map, you don't need to think about chunks, layers, or culling. Drop a Tiled or LDtk file in, point the loader at it, you have a level.

<Diagram caption="How TileMap2D builds a map — a tile atlas plus per-layer grid data become chunked geometry, stacked by layer for depth, with markOccluders flagging wall tiles as shadow casters." src={tilemapStructure} />

## Creating a Tilemap

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { TileMap2D, TiledLoader } from 'three-flatland';

    // Load a Tiled map
    const mapData = await TiledLoader.load('/maps/level1.json');

    // Create tilemap
    const tilemap = new TileMap2D({
      data: mapData,
      chunkSize: 512,  // Tiles per chunk (default: 512)
    });

    scene.add(tilemap);

    // In your animation loop
    function animate() {
      tilemap.update(deltaMs);  // Update animated tiles
      renderer.render(scene, camera);
    }
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { Suspense, useRef } from 'react';
    import { extend, useFrame, useLoader } from '@react-three/fiber/webgpu';
    import { TileMap2D, TiledLoader } from 'three-flatland/react';

    extend({ TileMap2D });

    function Level() {
      // useLoader suspends while loading, presets applied automatically
      const mapData = useLoader(TiledLoader, '/maps/level1.json');
      const tilemapRef = useRef<TileMap2D>(null);

      useFrame((_, delta) => {
        tilemapRef.current?.update(delta * 1000);
      });

      return <tileMap2D ref={tilemapRef} data={mapData} chunkSize={512} />;
    }

    // Wrap with Suspense in parent
    function App() {
      return (
        <Suspense fallback={null}>
          <Level />
        </Suspense>
      );
    }
    ```
  </TabItem>
</Tabs>

## Map Data Structure

The `TileMapData` interface describes the map format:

```typescript
interface TileMapData {
  width: number;           // Map width in tiles
  height: number;          // Map height in tiles
  tileWidth: number;       // Tile width in pixels
  tileHeight: number;      // Tile height in pixels
  orientation: 'orthogonal' | 'isometric' | 'staggered' | 'hexagonal';
  renderOrder: 'right-down' | 'right-up' | 'left-down' | 'left-up';
  infinite: boolean;       // Infinite map flag
  tilesets: TilesetData[];
  tileLayers: TileLayerData[];
  objectLayers: ObjectLayerData[];
  properties?: Record<string, unknown>;
}
```

## Loading Maps

### Tiled Editor (.json/.tmj)

Load maps created with the [Tiled Map Editor](https://www.mapeditor.org/):

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { TileMap2D, TiledLoader } from 'three-flatland';

    const mapData = await TiledLoader.load('/maps/level1.json');
    const tilemap = new TileMap2D({ data: mapData });
    scene.add(tilemap);
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { Suspense } from 'react';
    import { extend, useLoader } from '@react-three/fiber/webgpu';
    import { TileMap2D, TiledLoader } from 'three-flatland/react';

    extend({ TileMap2D });

    function TiledMap() {
      const mapData = useLoader(TiledLoader, '/maps/level1.json');
      return <tileMap2D data={mapData} />;
    }

    // Usage with Suspense
    <Suspense fallback={<LoadingIndicator />}>
      <TiledMap />
    </Suspense>
    ```
  </TabItem>
</Tabs>

### LDtk Editor (.ldtk)

Load maps created with [LDtk](https://ldtk.io/):

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { TileMap2D, LDtkLoader } from 'three-flatland';

    // Load a specific level by name
    const mapData = await LDtkLoader.load('/maps/world.ldtk', 'Level_0');
    const tilemap = new TileMap2D({ data: mapData });
    scene.add(tilemap);

    // List all levels in project
    const levelIds = await LDtkLoader.getLevelIds('/maps/world.ldtk');
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { Suspense } from 'react';
    import { extend, useLoader } from '@react-three/fiber/webgpu';
    import { TileMap2D, LDtkLoader } from 'three-flatland/react';

    extend({ TileMap2D });

    function LDtkMap() {
      // Loads first level by default
      const mapData = useLoader(LDtkLoader, '/maps/world.ldtk');
      return <tileMap2D data={mapData} />;
    }

    // Specify level via extension callback
    function SpecificLevel() {
      const mapData = useLoader(LDtkLoader, '/maps/world.ldtk', (loader) => {
        loader.levelId = 'Level_0';
      });
      return <tileMap2D data={mapData} />;
    }

    // Usage with Suspense
    <Suspense fallback={<LoadingIndicator />}>
      <LDtkMap />
    </Suspense>
    ```
  </TabItem>
</Tabs>

:::tip[Texture Configuration]
See the [Loaders guide](../loaders/#texture-presets) to configure texture filtering for pixel-art or smooth rendering.
:::

## Working with Layers

Access and manipulate tile layers:

```typescript
// Get layer by index
const groundLayer = tilemap.getLayerAt(0);
const wallsLayer = tilemap.getLayerAt(1);

// Toggle visibility
groundLayer.visible = false;

// Get layer count
console.log(tilemap.layerCount);
```

## Tile Operations

Read and modify tiles at runtime:

```typescript
// Get layer
const layer = tilemap.getLayerAt(0);

// Read tile at position
const tileGid = layer.getTileAt(x, y);

// Set tile at position
layer.setTileAt(x, y, newTileGid);
```

## Shadow Casting

Tilemaps participate in the lighting pipeline as shadow occluders. Rather than tagging tiles one by one, you mark whole categories of tiles by their LDtk `obj.type` — typically the `'collision'` IntGrid identifier that LDtk assigns to wall tiles by default.

Call `tilemap.markOccluders(typeNames, layerIndex?)` after the map data is loaded. It walks every object layer, finds objects whose `type` is in `typeNames`, and flips the per-tile cast-shadow bit for the matching tile in the target layer (default: layer `0`).

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    import { TileMap2D, LDtkLoader } from 'three-flatland'

    const mapData = await LDtkLoader.load('/maps/dungeon.ldtk', 'Level_0')
    const tilemap = new TileMap2D({ data: mapData })
    scene.add(tilemap)

    // Mark all 'collision' IntGrid tiles as shadow casters
    tilemap.markOccluders(['collision'])
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { useEffect, useRef } from 'react'
    import { useLoader } from '@react-three/fiber/webgpu'
    import { LDtkLoader, TileMap2D } from 'three-flatland/react'

    function Level() {
      const mapData = useLoader(LDtkLoader, './maps/dungeon.ldtk')
      const tilemapRef = useRef<TileMap2D>(null)

      useEffect(() => {
        // Mark all 'collision' IntGrid tiles as shadow casters
        tilemapRef.current?.markOccluders(['collision'])
      }, [mapData])

      return <tileMap2D ref={tilemapRef} data={mapData} />
    }
    ```
  </TabItem>
</Tabs>

Marked tiles get the `CAST_SHADOW_MASK` bit set in their interleaved `instanceSystem.z` attribute. The OcclusionPass picks this up during the SDF pre-pass — flagged tiles render into the shadow silhouette mask and produce real shadows in lit fragments.

You can pass multiple type names to mark several categories at once, e.g. `markOccluders(['collision', 'pillar'])`. Pass a `layerIndex` if your wall geometry lives on a layer other than the first:

```typescript
tilemap.markOccluders(['collision'], 1) // mark layer index 1
```

:::tip[Per-tile bits survive layer toggles]
Per-tile cast-shadow flags are preserved when you toggle layer-level state like `layer.lit` or `layer.receiveShadows`. The layer flag-sync only writes its own bits and merges them into each tile's existing flag word, so toggling lit/receiveShadows after `markOccluders` won't silently un-mark wall tiles.
:::

For the broader story on how the SDF pre-pass, occlusion mask, and shadow tracing fit together, see the [Shadows guide](../shadows/). For the per-sprite analogue (`Sprite2D` instances opting in/out as occluders), see the [Sprites guide](../sprites/).

## Coordinate Conversion

Convert between world and tile coordinates:

```typescript
// World position to tile position
const tilePos = tilemap.worldToTile(worldX, worldY);
console.log(tilePos.x, tilePos.y);

// Tile position to world position
const worldPos = tilemap.tileToWorld(tileX, tileY);
console.log(worldPos.x, worldPos.y);
```

## Statistics

Get information about the tilemap:

```typescript
console.log('Total tiles:', tilemap.totalTileCount);
console.log('Total chunks:', tilemap.totalChunkCount);
console.log('Layer count:', tilemap.layerCount);
```

## Chunked Rendering

Tilemaps use chunked rendering for performance. Configure the chunk size based on your needs:

```typescript
const tilemap = new TileMap2D({
  data: mapData,
  chunkSize: 512,  // tiles per chunk (default)
});
```

Smaller chunks = more draw calls but finer culling. Larger chunks = fewer draw calls but coarser culling. The default of 512 keeps most maps in a single chunk; lower it only for very large maps where finer culling pays off.

## Animated Tiles

Tiles with animation data (from Tiled) are automatically animated. Call `update()` each frame:

```typescript
function animate() {
  const deltaMs = /* time since last frame */;
  tilemap.update(deltaMs);
  renderer.render(scene, camera);
}
```

## Disposing

Clean up resources when done:

```typescript
scene.remove(tilemap);
tilemap.dispose();
```

# TSL Nodes

> Create custom shader effects using Three Shader Language.

import { Tabs, TabItem } from 'starlight-theme/components';
import Diagram from '../../../components/Diagram.astro';
import tslNodeChain from '../../../assets/diagrams/tsl-node-chain.svg?raw';

**What you'll learn**
- How to author a `MaterialEffect` with typed per-instance parameters (`createMaterialEffect`)
- The catalog of effect nodes from `@three-flatland/nodes` — color, retro, dissolve, outline, dithering
- How to compose multiple effects on a single sprite via `addEffect()` / `removeEffect()`

---

TSL (Three Shader Language) is a node-based shader system in Three.js that enables custom GPU effects without writing raw WGSL/GLSL code.

If you've been writing GLSL strings or `onBeforeCompile` hacks for years, this page is the unlearning. Composition replaces concatenation; the type system catches you.

three-flatland provides two ways to use TSL:

1. **Material Effects** (recommended) — define reusable, per-sprite effects with `createMaterialEffect` and apply them via `addEffect()` / `removeEffect()`
2. **Raw TSL nodes** — compose low-level node functions directly for full shader control

TSL node functions (tint, hueShift, outline, dissolve, etc.) are exported from `@three-flatland/nodes`. The effect system (`createMaterialEffect`, `createPassEffect`) and core classes are exported from `three-flatland`.

<Diagram caption="Composing a sprite's effect chain — the base texture color flows through each effect node as inputColor and out as a vec4, chaining in addEffect order into one node material." src={tslNodeChain} />

## Material Effects :badge[Recommended]{variant=success}

The Material Effect system lets you define shader effects as reusable classes with typed, animatable properties. Effects are composed into the sprite's shader pipeline automatically.

### Defining an Effect

Use `createMaterialEffect` with a schema (per-sprite data) and a TSL node builder:

```typescript
import { createMaterialEffect } from 'three-flatland';
import { tintAdditive, hueShift } from '@three-flatland/nodes';
import { vec4 } from 'three/tsl';

// Damage flash — additive white tint that fades
const DamageFlash = createMaterialEffect({
  name: 'damageFlash',
  schema: { intensity: 1 } as const,
  node: ({ inputColor, attrs }) => {
    const flashed = tintAdditive(inputColor, [1, 1, 1], attrs.intensity);
    return vec4(flashed.rgb.mul(inputColor.a), inputColor.a);
  },
});

// Hue rotation — continuous rainbow effect
const Powerup = createMaterialEffect({
  name: 'powerup',
  schema: { angle: 0 } as const,
  node: ({ inputColor, attrs }) => hueShift(inputColor, attrs.angle),
});
```

The `node` callback receives:
- `inputColor` — the previous color in the effect chain (TSL vec4 node)
- `inputUV` — atlas UV coordinates (TSL vec2 node)
- `attrs` — TSL nodes for each schema field, automatically packed into GPU buffers

### Using Effects

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ```typescript
    // Create instance and add to sprite
    const flash = new DamageFlash();
    sprite.addEffect(flash);

    // Animate properties in your render loop
    flash.intensity = Math.max(0, 1 - elapsed / 0.3);

    // Remove when done
    sprite.removeEffect(flash);
    ```
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ```tsx
    import { useMemo, useEffect } from 'react';
    import { useFrame } from '@react-three/fiber/webgpu';

    function FlashingSprite({ spriteRef }) {
      const flash = useMemo(() => new DamageFlash(), []);

      useEffect(() => {
        const sprite = spriteRef.current;
        sprite.addEffect(flash);
        return () => sprite.removeEffect(flash);
      }, [spriteRef, flash]);

      useFrame((_, delta) => {
        flash.intensity = Math.max(0, flash.intensity - delta / 0.3);
      });
    }
    ```
  </TabItem>
</Tabs>

### Closure-Captured Textures

Effects that need texture references can capture them via closures. The `node` callback runs once during shader compilation:

```typescript
const noiseTexture = createNoiseTexture();

const Dissolve = createMaterialEffect({
  name: 'dissolve',
  schema: { progress: 0 } as const,
  node: ({ inputColor, attrs }) =>
    dissolvePixelated(inputColor, uv(), attrs.progress, noiseTexture, 16),
});
```

See the [TSL Nodes example](../../examples/tsl-nodes/) for all 8 effects in action.

## Low-Level TSL Usage :badge[Advanced]{variant=note}

For full shader control, you can compose TSL nodes directly on a `MeshBasicNodeMaterial`. This is useful for custom materials outside the sprite pipeline:

```typescript
import { MeshBasicNodeMaterial } from 'three/webgpu';
import { texture as sampleTexture, uv, Fn } from 'three/tsl';
import { SpriteSheetLoader } from 'three-flatland';
import { outline8, spriteUV } from '@three-flatland/nodes';

const spriteSheet = await SpriteSheetLoader.load('/sprites/character.json');

const material = new MeshBasicNodeMaterial();
material.transparent = true;

material.colorNode = Fn(() => {
  const frameUV = spriteUV(frameUniform);
  const color = sampleTexture(spriteSheet.texture, frameUV);
  return outline8(color, frameUV, spriteSheet.texture, {
    color: [1, 0, 0, 1],
    thickness: 0.003,
  });
})();
```

## Sprite Sampling Nodes

### `sampleSprite`

Sample a texture with frame coordinates and optional alpha test:

```typescript
import { sampleSprite } from '@three-flatland/nodes';

// Sample with alpha test (discard transparent pixels)
const color = sampleSprite(texture, frameUniform, { alphaTest: 0.01 });

// Sample without alpha test
const color = sampleSprite(texture, frameUniform);
```

### `spriteUV`

Convert frame uniform to UV coordinates:

```typescript
import { spriteUV } from '@three-flatland/nodes';

const frameUV = spriteUV(frameUniform);
// Use frameUV for texture sampling or effects
```

## Color Nodes

### `tint` / `tintAdditive`

Apply color tint to a sprite:

```typescript
import { tint, tintAdditive } from '@three-flatland/nodes';

// Multiplicative tint (darkens)
const tinted = tint(color, [1.0, 0.5, 0.5]); // Pink

// Additive tint with strength (damage flash)
const flashed = tintAdditive(color, [1, 1, 1], flashStrength);
```

### `hueShift`

Rotate hue (rainbow effect):

```typescript
import { hueShift } from '@three-flatland/nodes';

// Shift by radians (animate timeUniform for rainbow)
const shifted = hueShift(color, timeUniform.mul(3.0));
```

### `saturate` / `grayscale`

Adjust saturation:

```typescript
import { saturate, grayscale } from '@three-flatland/nodes';

// Full grayscale (petrified effect)
const gray = saturate(color, 0);

// Increase saturation
const vivid = saturate(color, 1.5);

// Direct grayscale conversion
const gray = grayscale(color);
```

### `brightness` / `contrast`

Adjust brightness and contrast:

```typescript
import { brightness, contrast } from '@three-flatland/nodes';

// Brighten
const bright = brightness(color, 0.2);

// Increase contrast
const contrasty = contrast(color, 1.5);
```

## Effect Nodes

### `outline8`

Add outline around sprite (8-direction sampling):

```typescript
import { outline8 } from '@three-flatland/nodes';

const outlined = outline8(color, uv, texture, {
  color: [0.3, 1, 0.3, 1],  // Green outline
  thickness: 0.003,          // Outline width
});
```

### `pixelate`

Apply pixelation effect:

```typescript
import { pixelate, pixelateBySize } from '@three-flatland/nodes';

// By pixel count
const pixelatedUV = pixelate(uv, vec2(32, 32));

// By pixel size
const pixelatedUV = pixelateBySize(uv, vec2(0.03125));
```

### `dissolve`

Dissolve effect with noise texture:

```typescript
import { dissolve, dissolvePixelated, dissolveDirectional } from '@three-flatland/nodes';

// Basic dissolve
const dissolved = dissolve(color, uv, progress, noiseTexture);

// Pixelated dissolve (retro style)
const dissolved = dissolvePixelated(color, uv, progress, noiseTexture, 16);

// Directional dissolve
const dissolved = dissolveDirectional(color, uv, progress, direction);
```

## Retro Effect Nodes

### `colorReplace`

Replace one color with another:

```typescript
import { colorReplace, colorReplaceHard, colorReplaceMultiple } from '@three-flatland/nodes';

// Soft replacement with tolerance
const replaced = colorReplace(color, oldColor, newColor, 0.1);

// Hard replacement (exact match)
const replaced = colorReplaceHard(color, oldColor, newColor);

// Replace multiple colors
const replaced = colorReplaceMultiple(color, colorPairs, 0.1);
```

### `bayerDither`

Ordered dithering (retro style):

```typescript
import { bayerDither2x2, bayerDither4x4, bayerDither8x8 } from '@three-flatland/nodes';

// 2x2 matrix dithering
const dithered = bayerDither2x2(color, levels, scale);

// 4x4 matrix (default)
const dithered = bayerDither4x4(color, levels, scale);

// 8x8 matrix (finest)
const dithered = bayerDither8x8(color, levels, scale);
```

### `palettize`

Map colors to a palette:

```typescript
import { palettize, palettizeDithered, palettizeNearest } from '@three-flatland/nodes';

// With dithering (smooth gradients)
const paletted = palettizeDithered(color, paletteTexture);

// Nearest color (hard edges)
const paletted = palettizeNearest(color, paletteTexture);
```

### `posterize`

Reduce color levels:

```typescript
import { posterize } from '@three-flatland/nodes';

// Reduce to 4 levels per channel
const posterized = posterize(color, 4);
```

## Combining Effects

With Material Effects, multiple effects can be active simultaneously. Each effect chains through the previous color:

```typescript
const flash = new DamageFlash();
const select = new Select();

sprite.addEffect(flash);
sprite.addEffect(select);

// Both effects are active — select runs after flash in the shader
```

For low-level TSL, chain node functions directly:

```typescript
material.colorNode = Fn(() => {
  const color = sampleSprite(texture, frameUniform, { alphaTest: 0.01 });
  const shifted = hueShift(color, timeUniform);
  const outlined = outline8(shifted, spriteUV(frameUniform), texture, {
    color: [1, 1, 0, 1],
    thickness: 0.002,
  });
  return outlined;
})();
```

## Performance Tips

:::tip[Performance note]
Material Effects pack per-sprite data into fixed-size GPU buffers, so adding effects to thousands of sprites doesn't cost extra draw calls — it costs shader ops per fragment. Reach for `addEffect()` freely. Compose, don't worry.
:::

- Complex node graphs increase shader compile time
- Use `uniform()` for values that change frequently
- Cache compiled materials when reusing effects
- Avoid dynamic branching in hot paths

## Next Steps

- [TSL Nodes Example](../../examples/tsl-nodes/) — Interactive demo of 8 material effects
- [Pass Effects Guide](../pass-effects/) — Full-screen post-processing with CRT, LCD, VHS, and more

# LLMs

> LLM-readable context and copy-paste prompts for AI coding assistants building with three-flatland.

import { Aside, Tabs, TabItem } from 'starlight-theme/components';

three-flatland provides machine-readable documentation so AI coding assistants can help you write correct code from the start. This page explains what's available and includes ready-to-use prompts.

## Machine-Readable Documentation

three-flatland publishes two files that AI assistants can consume directly:

| File | What it contains | When to use it |
|------|------------------|----------------|
| [`llms.txt`](/three-flatland/llms.txt) | Links to all docs pages, guides, and examples | AI tools that can browse and follow links |
| [`llms-full.txt`](/three-flatland/llms-full.txt) | Self-contained API reference with imports, classes, effects, and examples | AI tools that need everything in one file |

These follow the [llms.txt standard](https://llmstxt.org/) — a convention for providing LLM-friendly documentation alongside your website.

<Aside type="tip" title="How this helps">
Without context, AI assistants often generate three-flatland code with wrong imports, missing `await renderer.init()`, or using `WebGLRenderer` instead of `WebGPURenderer`. These files prevent those common mistakes by giving the AI the right patterns upfront.
</Aside>

## Prompts

Copy a prompt below, paste it into your AI assistant, and replace the placeholder at the end with your task.

### Getting Started

The general-purpose prompt. Works with any AI assistant that can fetch URLs.

~~~
I'm working with three-flatland, a 2D sprite and effects library for Three.js
using WebGPU and TSL (Three Shader Language). It's currently in alpha.

Read this reference for the API:
https://thejustinwalsh.com/three-flatland/llms-full.txt

Key things to know:
- Three.js users import from "three-flatland"
- React Three Fiber users import from "three-flatland/react"
- TSL effect nodes come from "@three-flatland/nodes"
- Install: npm install three-flatland three koota
- Requires three.js >= 0.183.1, koota, and WebGPURenderer from "three/webgpu"

Help me with the following:
[Describe your task here]
~~~

### Build from an Example

Start from a working example and adapt it. The AI reads the actual source code from GitHub, so it builds on patterns that are known to work.

<Tabs syncKey="framework">
  <TabItem label="Three.js" icon="simple-icons:threedotjs">
    ~~~
    I'm building a project with three-flatland (2D sprites for Three.js/WebGPU).

    Read the API reference: https://thejustinwalsh.com/three-flatland/llms-full.txt

    Then fetch this example source from GitHub:
    https://raw.githubusercontent.com/thejustinwalsh/three-flatland/main/examples/three/EXAMPLE_NAME/main.ts

    Adapt it for my needs:
    [Describe what you want to build]
    ~~~
  </TabItem>
  <TabItem label="React" icon="simple-icons:react">
    ~~~
    I'm building a React Three Fiber project with three-flatland (2D sprites for Three.js/WebGPU).

    Read the API reference: https://thejustinwalsh.com/three-flatland/llms-full.txt

    Then fetch this example source from GitHub:
    https://raw.githubusercontent.com/thejustinwalsh/three-flatland/main/examples/react/EXAMPLE_NAME/App.tsx

    Adapt it for my needs:
    [Describe what you want to build]
    ~~~
  </TabItem>
</Tabs>

Replace `EXAMPLE_NAME` with one of these:

| Example | What it demonstrates |
|---------|---------------------|
| `basic-sprite` | Texture loading, sprite creation, interaction |
| `animation` | Spritesheet animation with `AnimatedSprite2D` |
| `batch-demo` | Thousands of sprites in few draw calls |
| `tsl-nodes` | Per-sprite effects with `MaterialEffect` and TSL nodes |
| `pass-effects` | Full-screen post-processing with `PassEffect` |
| `tilemap` | Tiled/LDtk tilemap loading and rendering |
| `lighting` | 2D lighting, draggable point lights, preset comparison |
| `skia` | Skia WASM vector graphics — shapes, text, paths, gradients |
| `slug-text` | GPU-rendered vector text with the Slug font pipeline |
| `knightmark` | Sprite benchmark with batching stress test |

### Deep Context (File Access Required)

For AI assistants that can read local files — Claude Code, Cursor, Copilot workspace. The AI reads the project's own documentation files and explores the source code based on your task.

~~~
I'm working in the three-flatland repository.

Start by reading these files:
1. CLAUDE.md — Project instructions, architecture, build commands
2. README.md — API overview and quick start examples

Then explore based on what I need:
- API details: read packages/three-flatland/src/index.ts and follow exports
- Effect nodes: read packages/nodes/src/ category directories
- Examples: read examples/three/ or examples/react/
- React integration: read packages/three-flatland/src/react.ts

Help me with the following:
[Describe your task here]
~~~

## Common Pitfalls

These are the mistakes AI assistants make most often with three-flatland. If you see any of these in generated code, correct the AI:

| Mistake | Fix |
|---------|-----|
| `new THREE.WebGLRenderer()` | Use `new WebGPURenderer()` from `'three/webgpu'` |
| `import { ... } from '@three-flatland/core'` | Import from `'three-flatland'` (or `'three-flatland/react'`) |
| Missing `await renderer.init()` | WebGPU requires async initialization before rendering |
| Using `THREE.Sprite` | Use `Sprite2D` from three-flatland — different API entirely |
| `renderer.render(scene, camera)` with Flatland | Use `flatland.render(renderer)` — Flatland manages its own scene and camera |

# Showcases

> Full-scale apps and games built with three-flatland. Source available, runnable in-browser.

import ShowcaseGrid from '../../../components/gallery/ShowcaseGrid.astro'
import GalleryTile from '../../../components/gallery/GalleryTile.astro'

<div class="showcases-page not-content">

<header class="showcases-header">
  <p class="showcases-eyebrow">Showcases</p>
  <h1 class="showcases-title">Full apps, full source.</h1>
  <p class="showcases-tagline">Each showcase is a complete app built with three-flatland and shipped as a public mini package. Hover any tile for a live preview; click through to play it inline and read the source.</p>
</header>

<ShowcaseGrid>
  <GalleryTile
    surface="showcases"
    slug="breakout"
    title="Breakout"
    description="The classic, rebuilt as a koota-driven ECS using SpriteGroup, batched sprite effects, and a single draw call."
    color="ruby"
    aspect="16 / 10"
  />
</ShowcaseGrid>

</div>

<style>
{`
  .showcases-page {
    max-width: 75rem;
    margin: 0 auto;
    padding-inline: clamp(1rem, 4vw, 2rem);
    padding-block: clamp(2rem, 4vw, 3rem);
  }

  .showcases-header {
    margin-block-end: clamp(2rem, 4vw, 3rem);
    max-width: 56rem;
  }

  .showcases-eyebrow {
    font-family: 'Inter', system-ui, sans-serif;
    font-size: 0.75rem;
    font-weight: 600;
    color: color-mix(in oklab, var(--ruby) 60%, var(--muted-foreground));
    text-transform: uppercase;
    letter-spacing: 0.08em;
    margin: 0 0 0.5rem 0;
  }

  .showcases-title {
    font-family: 'Public Sans', system-ui, sans-serif;
    font-size: clamp(2rem, 4.5vw, 3.25rem);
    font-weight: 200;
    letter-spacing: -0.025em;
    line-height: 1.05;
    color: var(--foreground);
    margin: 0 0 1rem 0;
    text-wrap: balance;
  }

  .showcases-tagline {
    font-family: 'Public Sans', system-ui, sans-serif;
    font-size: clamp(1rem, 1.5vw, 1.0625rem);
    font-weight: 400;
    line-height: 1.55;
    color: var(--muted-foreground);
    margin: 0;
    max-width: 48rem;
    text-wrap: balance;
  }
`}
</style>

# Breakout

> A complete Breakout arcade game built with three-flatland and Koota ECS.

import ShowcaseDetailLayout from '../../../components/ShowcaseDetailLayout.astro';
import ShowcaseGame from '../../../components/ShowcaseGame';

<ShowcaseDetailLayout slug="breakout" sourcePath="minis/breakout" gem="ruby">
  <ShowcaseGame slot="preview" client:load />

## Architecture

The breakout mini-game is built on three-flatland and [Koota ECS](https://github.com/pmndrs/koota). All game state lives in ECS traits, all logic runs in pure-function systems, and all rendering flows through a single Flatland instance.

### Game Loop

A 4-state machine drives the top-level loop. Each state runs a different subset of systems per frame:

| State | Systems | Behavior |
|-------|---------|----------|
| **attract** | AI input, physics, collision, effects | AI plays indefinitely — predicts ball landing with wall-bounce simulation, smoothed through three layers of lerp (goal → mouse → paddle) |
| **ready** | paddle movement, countdown, effects | 3-2-1 countdown with flash pulses on each tick. Ball sits on the paddle and tracks its X position so the player can aim before launch |
| **playing** | input, physics, collision, scoring, effects | Full game. Ball speeds up on each block hit (`+0.1 units/sec`). Streak counter tracks consecutive hits — multiplier grows on an inverse curve (`x2` at 8, `x3` at 24, `x4` at 48...) |
| **gameover** | effects only | Score displayed, dissolving blocks finish animating, auto-returns to attract after 2.5s |

State transitions are explicit — `startGame`, `levelClear`, `loseLife`, `gameOver`, `returnToAttract` — each one resets the appropriate entities and spawns new ones.

### Collision Detection

The game uses swept line-segment vs AABB testing (slab method) to prevent tunneling at high ball speeds:

1. Before integration, `moveBall` stores the ball's current position in a `PrevPosition` trait
2. After integration, collision systems test the line segment from `PrevPosition` to `Position` against Minkowski-expanded AABBs (block AABB inflated by ball half-extents, reducing the ball to a point)
3. The slab method finds the earliest intersection time `t ∈ [0,1]` and which axis was hit
4. For blocks, all candidates are tested and the closest `t` wins — the ball is placed at the contact point and velocity is reflected on the hit axis

Paddle collision adds angle control: the horizontal offset from paddle center maps to a launch angle (up to 60 degrees), and paddle velocity at the moment of contact applies english to the ball's trajectory.

### Rendering Pipeline

All sprites render through a single `<flatland>` element:

```tsx
<flatland ref={flatlandRef} viewSize={5} clearColor={0x0a0a23} clearAlpha={0}>
  <WallsRenderer wallMaterial={materials.wall} />
  <BlocksRenderer material={materials.blocks[0]!} />
  <BallRenderer material={materials.ball} />
  <PaddleRenderer material={materials.paddle} />
</flatland>
```

Game logic runs in R3F's default update phase. Flatland renders in the **render phase** (`{ phase: 'render' }`), which tells R3F to skip its own render pass. This separation ensures all ECS trait values are synced to `MaterialEffect` instances before the draw call.

### Material Effects

Two custom effects built with `createMaterialEffect` provide visual feedback without shader recompilation:

**FlashEffect** — Mixes sprite color toward white based on an `amount` uniform. The `BallFlash` trait is added on collision with an initial intensity (1.0 for blocks, 0.7 for paddle, 0.5 for walls) and a `decaySpeed` that fades it each frame. When `amount` reaches zero the trait is removed.

**BlockDissolveEffect** — Uses `dissolvePixelated` (a TSL node that samples a shared 32x32 noise texture at quantized UVs) to progressively discard pixels. The `Dissolving` trait drives `progress` from 0 → 1.2 — the entity is destroyed after the shader has fully discarded all fragments, avoiding a visual pop.

Both effects are registered on their materials at creation time. Each component's `useFrame` reads the ECS trait value and writes it to the effect instance ref — a one-line sync per entity per frame.

### Dithered Shading

All sprite materials use a `colorTransform` that applies Bayer 4x4 ordered dithering with a diagonal self-shadow. The dither grid is scaled by sprite world-size so cells are square regardless of aspect ratio. UVs are quantized to cell centers, then a diagonal gradient (upper-left = light, lower-right = shadow) modulates brightness through the dither pattern. The result is a retro shading style with no textures needed beyond the base sprite.

### ECS Trait Design

Traits fall into four categories:

- **Data traits** — `Position`, `Velocity`, `Bounds`, `BlockState`, `PaddleState` — plain structs with numeric fields
- **Tag traits** — `Ball`, `Paddle`, `Block` — zero-field markers used in queries (`world.query(Ball, Position, Velocity)`)
- **Temporary traits** — `Dissolving`, `BallFlash`, `PrevPosition` — added on events, removed when their purpose completes. `PrevPosition` is added on the first `moveBall` call and persists; `Dissolving` is added on block hit and triggers entity destruction; `BallFlash` is added on any collision and removed when fully decayed
- **Singleton traits** — `GameState`, `Input`, `AttractAI` — added to the world itself (not entities), accessed via `world.get(GameState)`

The `GameState` singleton carries score, lives, level, countdown timer, streak counter, multiplier, carried ball speed across levels, and high score (persisted to `localStorage`).

### Attract Mode AI

The AI uses three layers of smoothing to mimic human play:

1. **Goal** — raw prediction of where the ball will land (accounts for wall bounces via modular fold), lerped at 3.0/sec toward the latest prediction. Occasionally biased toward the nearest remaining block column
2. **Virtual mouse** — lerps at 5.0/sec toward the goal, like a hand moving a physical mouse
3. **Paddle** — the same `updatePaddle` function used by the player lerps the paddle toward the virtual mouse at 12 units/sec

A slow-drifting offset (re-randomized every 4-8 seconds) adds subtle imperfection so the AI doesn't look robotic.

### Project Structure

```
minis/breakout/
├── src/
│   ├── index.ts          # Library entry point
│   ├── Game.tsx           # Main game component + R3F Canvas
│   ├── materials.ts       # FlashEffect, BlockDissolveEffect, dither transform
│   ├── textures.ts        # Canvas-generated textures
│   ├── world.ts           # Koota world factory
│   ├── types.ts           # MiniGameProps, PlaySoundFn, GameMode
│   ├── traits/
│   │   └── index.ts       # All ECS traits
│   ├── components/
│   │   ├── Ball.tsx        # Ball renderer + flash sync
│   │   ├── Blocks.tsx      # Block grid renderer + dissolve sync
│   │   ├── Paddle.tsx      # Paddle renderer
│   │   ├── UI.tsx          # Score/lives HTML overlay
│   │   └── Walls.tsx       # Wall sprites
│   └── systems/
│       ├── collision.ts    # Swept AABB collision (wall, paddle, block)
│       ├── constants.ts    # World dimensions, speeds, scoring
│       ├── game.ts         # State machine, spawning, high score
│       ├── physics.ts      # Ball integration, paddle lerp, AI
│       └── sounds.ts       # Sound player factory
└── public/assets/          # SVG sprites (ball, block, paddle)
```

:::note[Portability]
The mini-game is designed to be importable by the docs site as a library package. This drove two design choices: all textures are generated at runtime via `CanvasTexture` (zero network requests), and sound is injected as a `zzfx` prop function so the host controls audio context and volume.
:::

### External Dependencies

- [Koota](https://github.com/pmndrs/koota) — Entity Component System
- [React Three Fiber](https://r3f.docs.pmnd.rs/) — React renderer for Three.js
- [ZzFX](https://github.com/KilledByAPixel/ZzFX) — Tiny sound generator

## Next Steps

- [Flatland Guide](../../guides/flatland/) — Deep dive into the Flatland API used by this game
- [TSL Nodes Guide](../../guides/tsl-nodes/) — Custom material effects like the flash and dissolve
- [Pass Effects Guide](../../guides/pass-effects/) — Full-screen post-processing

</ShowcaseDetailLayout>