slosh + sloshgen

Bake liquid animations. Play them in Flutter.

• sloshgen generates compact 2D liquid keyframes from a vector container, timed rotation, fill amount, and layered wave settings.
• slosh plays those assets with Flutter painting and interpolation. The application does not run a fluid solver or parse the source SVG.

Packages live under packages/ and are prepared for their initial 0.1.0 release. See publishing instructions.

Try it

With Flutter 3.44.2 / Dart 3.12.2 (the verified toolchain):

cd packages/sloshgen
dart pub get
dart run tool/regenerate.dart
cd ../slosh/example
flutter pub get
flutter run -d macos

The example opens with a clockwise circle, a blue pool and amber beads carried up the left wall before falling back. Switch wall-friction presets or recolor pool and droplets independently. Other scenes cover a low-fill bead, translation/rotation shaking, merging, layered waves, tilts and an off-center pivot. Pause, seek or change playback speed. Generated assets are checked in, so regeneration is optional when first launching the example. Chrome is another available example target (flutter run -d chrome).

Generate an animation

From packages/sloshgen:

dart run sloshgen generate ../../fixtures/recipes/rolling-circle.json --output water.slosh.json

The command prints a short success message. Add --debug for the JSON validation report with size, geometric errors and event diagnostics.

For a GIF preview, use --output water.gif --size 256 --fps 25. The generator renders the same baked motion and colors without Flutter or FFmpeg. Recipes resolve SVG paths relative to the recipe file. See the complete format and example recipes.

Play in Flutter

Declare the generated file under your application's flutter.assets, then:

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:slosh/slosh.dart';

final water = SloshAsset.decode(
  await rootBundle.loadString('assets/water.slosh.json'),
);
// Return this from a widget build after loading the asset once:
Slosh(asset: water, size: 80, repeat: water.loopSafe);

Use SloshController(vsync: this, asset: water) for play, pause, seek, and positive rate changes. A supplied controller is owned by the caller; remove its widget and dispose it when finished. Without a controller the widget owns and disposes its ticker. SloshPainter accepts a time callback in seconds and a repaint Listenable for integration with another animation clock.

For v2 assets, named styles let you recolor pool and droplets independently:

Slosh(
  asset: water,
  size: 80,
  styleColors: {
    'water': const Color(0xff318ce7),
    'spray': const Color(0xffffb347),
  },
);

styleColors and styleOpacities use the style IDs in the recipe. Seeds and emitters can reference additional named styles without changing the motion. colors and opacities provide the legacy layer-level fallback. shellColor, shellWidth, and backgroundColor configure the vessel. Resizing preserves aspect ratio and fits the complete swept shape.

Boundaries

This is a prescribed, stylized 2D animation system. Multiple waves suggest depth. Change fill, pivot, motion or liquid settings by regenerating the asset. Playback rate changes replay speed; they do not recalculate the physical response. The player owns the baked rotation. It does not infer arbitrary ancestor transforms or simulate gesture-driven motion.

Version 2 uses a pool waterline plus bounded rounded droplets, with stylized sticky wall pickup, carry, release and reabsorption. Rapid translation/rotation reversals drive droplet breakup and recombination. Optional translation keys add x/y vessel motion; pool and droplet colors remain independently configurable. It conserves scalar liquid amount; visible area is approximate (5% default tolerance). Version 1 retains its original clipped-surface model and format.

The v2 pool supports a connected basin; difficult concavities, tight clearances or motions that exceed contour/error budgets fail generation explicitly. Spilling, arbitrary breaking waves, full fluid dynamics and 3D are out of scope. Unsupported SVG features fail explicitly. See the source asset's provenance before redistributing the branded example.

Verify

cd packages/sloshgen
dart test
dart analyze
cd ../slosh
flutter test
flutter analyze
cd example
flutter test
flutter analyze

Performance and visual validation records measured results and limitations. No universal frame-rate guarantee is made.