GUIDE // THREE.JS

How to calculate UV coordinates for a sprite sheet in three.js

For your grid of C columns and R rows, set texture.repeat to 1/C by 1/R. Frame n sits in column n mod C and row n / C, rounded down. Set offset.x to column / C and offset.y to 1 - (row + 1) / R, since three.js flips loaded images so the top row stays on top.

  • Godot 4 Available
  • Unity Manual setup
  • Unreal Engine Manual setup
  • Roblox Studio Manual setup
  • three.js Available

A draft compile is from $0.05, and new accounts start with $5 of usage.

FIRE_WHIRLFINAL
First frame of the fire_whirl bake
Fire whirl, 4.4 x 7.1 m, compiled with Spatial Compiler. Spec →

01 // HOW TO

From frame number to offset

  1. Read the grid from the sheet, or from layout.json: 8 columns and 8 rows for a default compile.
  2. Set texture.repeat.set(1 / 8, 1 / 8) once, so the sprite shows one cell.
  3. For each frame, find its column with frame % 8 and its row with Math.floor(frame / 8), counting rows from the top.
  4. Call setFrame whenever the frame changes, so texture.offset moves to the new cell.
setFrame.js
export function setFrame(texture, frame, cols = 8, rows = 8) {
  const col = frame % cols;
  const row = Math.floor(frame / cols);
  texture.offset.set(col / cols, 1 - (row + 1) / rows);
}

On an 8 x 8 sheet, frame 0 lands at (0, 0.875), frame 7 at (0.875, 0.875), frame 8 at (0, 0.75) and frame 63 at (0.875, 0).

02 // IN A SHADER

The same math in GLSL

With a ShaderMaterial on a plane, do the lookup in the fragment shader and pass the frame as a uniform.

flipbook.frag
uniform sampler2D map;
uniform float frame; // whole number, 0 to 63
varying vec2 vUv;

void main() {
  vec2 cell = vec2(mod(frame, 8.0), 7.0 - floor(frame / 8.0));
  gl_FragColor = texture2D(map, (vUv + cell) / 8.0);
}

Textures loaded with flipY set to false, such as those inside a glTF file, keep the top row at the bottom of UV space. For those, offset.y is row / rows.

03 // FRAME ORDER

Check the order before you trust the math

The formula assumes frames run from the top-left cell across each row and then down. Spatial Compiler records the frame order and times in layout.json, so read them there rather than guessing from the image.

Godot 4 gets a ready scene that relights the smoke. three.js uses the documented snippet. A native six-way material is not built yet.

05 // FAQ

three.js sprite sheet UV questions

All questions →

README.THREEJS_SPRITE_SHEET_UV
How do I calculate UV coordinates for a sprite sheet with rows and columns in three.js?

Set texture.repeat to 1/C by 1/R. Compute column n % C and row Math.floor(n / C), then offset X by column / C and Y from the top.

How do I set the number of rows and columns for a three.js flipbook texture?

Set texture.repeat.set(1 / columns, 1 / rows). three.js has no built in grid setting, so your code tracks the column and row counts.

How does a three.js shader know how many frames are in a sprite sheet?

You pass the counts through uniforms or constants. Spatial Compiler records the grid and frame count in layout.json so your code can read them instead of hardcoding.

Is there a simple three.js sprite sheet example?

Yes. Load the texture, set repeat to 1/8 by 1/8 and update texture.offset in your animation loop using the column and row of the current frame.

Compile your first effect

You pay per compile and see the price before it runs. New accounts start with $5 of usage.

All effects, guides and explainers →