sloshgen #

Offline Dart generator for baked 2D liquid animations. Author a shape, fill and motion trail; bake wave surfaces or fixed droplet contours; play the result with slosh.

Requires Dart 3.12 or later. The generator runs on the Dart VM and has no Flutter dependency; it is a build-time tool, not a web runtime simulator.

Install #

For a command-line tool:

dart pub global activate sloshgen
sloshgen generate recipe.json --output assets/water.slosh.json

Or add it to a project as a development dependency:

dart pub add --dev sloshgen
dart run sloshgen generate recipe.json --output assets/water.slosh.json

First recipe #

Save this as recipe.json:

{
  "version": 1,
  "shape": {
    "polygon": [[0, 0], [100, 0], [100, 100], [0, 100]],
    "viewBox": [0, 0, 100, 100]
  },
  "pivot": [50, 50],
  "duration": 4,
  "fill": 0.5,
  "loop": false,
  "rotation": [
    {"time": 0, "angle": 0, "easing": "smooth"},
    {"time": 1, "angle": 0.8},
    {"time": 4, "angle": 0.8}
  ],
  "layers": [{"id": "water", "amplitude": 0, "color": 4281437415}]
}

Angles are unwrapped radians, positive clockwise in screen coordinates. Fill is 0..1. Shape points and pivot use source coordinates. Relative SVG references resolve from the recipe file, not the process working directory.

Normal output is a short success message. Add --debug for detailed JSON validation reports:

sloshgen generate recipe.json --output assets/water.slosh.json --debug

Dart API #

import 'package:sloshgen/sloshgen.dart';

void main() {
  final result = generateFile('recipe.json', outputPath: 'water.slosh.json');
  print(result.asset['duration']);
}

For in-memory recipes, use generate(Recipe.fromJson(map), baseUri: recipeUri). BakeResult exposes the asset, encoded JSON, validation report and dense v1 reference frames (empty for v2). Failed generation throws; the CLI returns a nonzero exit code and preserves an existing output file.

The standalone example bakes the bundled recipe:

dart run example/sloshgen_example.dart water.slosh.json

Models and limits #

Version 1 bakes damped wave surfaces. Version 2 adds surface, droplet and hybrid policies, optional x/y translation tracks, and independent named colors. Sticky rolling picks beads up from a wetted rising wall, carries them with the edge and releases them under gravity. Rapid motion changes can split droplets; contact recombines them. Clockwise rotation lifts the left wall.

appearance.styles, poolStyle, dropletStyle and seed/emission styleId references control appearance separately from motion. Colors can be overridden by the player without regenerating geometry.

Both formats validate interpolation and loop seams. V2 additionally checks contour containment, contacts, approximate visible area and bounded body/event counts. Scalar liquid amounts are conserved; rendered area is approximate (5% default v2 tolerance). Tight geometry or exhausted budgets reject the bake. SVG arcs, transforms, holes, multiple subpaths and 3D are unsupported.

See the format guide for defaults and limits, and the rolling/shaking recipes for v2 examples. Repository-only tests, regeneration tools and fixtures are not included in the published package; clone the repository to run them.

Export a GIF #

Use a .gif output path to bake and render a shareable preview:

sloshgen generate recipe.json --output water.gif --size 256 --fps 25
# Or from a project dependency:
dart run sloshgen generate recipe.json --output water.gif --background "#ffffff" --shell "#455a64"

GIF export runs in Dart without Flutter or FFmpeg. It uses the retained v1/v2 keyframes, including rotation, translation, topology changes and independent pool/droplet styles. Configure liquid colors in the recipe's layers or named appearance.styles; --shell none hides the vessel outline. Detailed bake reports still require --debug.

The defaults are 256×256 at 25 fps, with a white canvas and dark vessel outline. --size accepts 16..1024; --fps accepts 1..50. GIF has a limited color palette and centisecond frame delays, so colors and timing are approximations. Alpha is composited onto the solid --background (six-digit RGB); transparent GIF backgrounds are not supported in this release. Loop-safe recipes repeat forever; other animations play once and finish on the last pose. Larger exports take more time and space; requests above 3000 frames or 100 million output pixels must use a smaller size or frame rate.

The Dart API can reuse an existing bake without rerunning simulation:

import 'dart:io';
import 'package:sloshgen/sloshgen.dart';

// `result` is the BakeResult returned by generate or generateFile.
final bytes = encodeGif(result, options: const GifOptions(size: 256, fps: 25));
File('water.gif').writeAsBytesSync(bytes);

Or use generateGifFile('recipe.json', outputPath: 'water.gif') to bake and write atomically. Keep .slosh.json for recolorable vector playback in Flutter; a GIF contains pre-rendered pixels and needs no slosh player.