Stoatworks Labs

Flipbook

Play a sprite sheet in Resolume

Stablev1.0.0Plugin & ModuleC++ / GLSL
Flipbook — Play a sprite sheet in Resolume
Four configurations rendered by the plugin's own offline harness, which drives the real plugin class through a headless GL context — not a Resolume screen capture. Clockwise from top left: a burst chasing round a ring, a grid of tiles each a frame further through the run, one cell filling the raster, and the same burst scattered. Both sheets are generated by a script in the repo.

What it does

Point it at a page of stills, tell it how many columns and rows, and it plays the cells as an animation — in Resolume Arena and Avenue, and in DaVinci Resolve, Nuke, Natron and Vegas from the same code. It ships as two plugins rather than one, because FFGL resolves a single entry point per binary: Flipbook is a source that plays a sheet over its own background, and Flipbook Over is an effect that plays one over the clip it sits on — or takes that clip as the sheet, so Resolume's own media management does the file handling.

It plays most of what already exists. VFX sheets — explosions, muzzle flashes, impacts, smoke — usually 5×5 or 8×8 and usually on white or black rather than with an alpha channel, which is what the Luma key handles. Game sprite sheets with a walk, a run and an idle on separate rows: Start Frame and Frame Count cut one run out, so a four-frame idle and an eight-frame run are two parameter sets on the same sheet. Pixel art kept as pixel art, at nearest-neighbour, so a 32px sprite scales to a metre of LED wall with its edges intact. Pages of whole frames, where one cell covers the raster. And animated GIFs, which bring their own frame count and lay themselves out.

The frame on screen is a closed-form function of the clock. Nothing is advanced, there is no counter, and no state carries between frames — which matters more than it sounds. Twelve frames at twelve frames a second is one second of animation, and if you have cued that against a bar you expect the loop to land on the bar line every time. A player that advanced a counter once per rendered frame would instead run at whatever rate Resolume managed that night: fine in the preview, a quarter of a frame short per bar once the show gets heavy, and visibly adrift by the end of the track. Closed-form, the loop point cannot drift however far the frame rate falls, and locking to the host's beat or bar is a different clock rather than a second code path.

The control worth finding first is Stagger. Up to sixty-four copies arrange themselves in a grid, a ring or a scatter, and Stagger offsets each copy's position in the run by a fixed number of frames — so instead of a wallpaper of sprites doing the same thing at the same instant, one animation travels through the field.

There is a browser demo that runs the plugin's own playback and placement in WebGL2, and it takes your own sprite sheet: drop a file on the page and it plays, with nothing uploaded anywhere.

  • Two plugins from one core — a source with its own background, and an effect over the clip
  • PNG, JPEG, GIF, BMP, TGA and PSD; an animated GIF brings its own frame count
  • Start Frame and Frame Count cut any contiguous run out of a sheet, wrapping past the last cell
  • Loop, ping-pong or once-and-hold, free-running or locked to the host's beat or bar
  • Up to 64 copies in a grid, a ring or a scatter, with a stagger that turns the field into a chase
  • Alpha, luma or colour keying, for the sheets that ship on white or on one flat backdrop
  • Nearest-neighbour sampling that keeps pixel art as pixel art at any size
  • Native, fill or stretch fit, so a sprite and a page of whole frames both land right
  • Universal macOS bundle (Apple Silicon and Intel), a Windows DLL, and an OpenFX bundle

Where it stands

Released at v0.1.0. Verified entirely by its own offline harness, which renders real frames and identifies the cell actually on screen against an independent prediction, measures every copy against where the solver said it would land, and checks that no cell bleeds into its neighbour under either filter. It has never been loaded into Resolume or Resolve, so check it in your own rig before trusting it in a show.

Watch it running

Flipbook video thumbnail

Nothing loads from YouTube until you press play.Watch it there instead