blobatar for Dart and Flutter #

Deterministic geometric blobatars from any string. This is the official Dart/Flutter port of blobatar, maintained in the upstream monorepo with the same frozen generation-2 seed-to-look contract.

The same name and options always produce the same avatar. The port renders directly with Dart and Flutter Canvas primitives; it does not wrap browser SVG markup or a web view.

Install #

flutter pub add blobatar

The package exposes two libraries:

• package:blobatar/blobatar.dart contains deterministic normalization, hashing, traits, palette, geometry, expressions, and elapsed-time motion. It imports neither Flutter nor dart:ui.
• package:blobatar/flutter.dart adds static and animated Flutter widgets, painters, and Canvas renderers, and re-exports the common core values.

The published package requires the Flutter SDK because it ships both layers; applications that only need calculations can import the core library without pulling Flutter types into their source.

Static Widget #

import 'package:blobatar/flutter.dart';

Blobatar(
  name: user.email,
  size: 64,
  semanticLabel: 'Avatar of ${user.displayName}',
  options: const BlobatarOptions(
    background: Backdrop.squircle,
    expression: happy,
  ),
)

size pins a square edge. Without it, the widget expands to its constraints and centers the generation-2 100-by-100 view box inside the largest square. semanticLabel labels the image for assistive technology.

Animated Widget #

AnimatedBlobatar(
  name: user.email,
  size: 120,
  animation: BlobatarAnimation.always,
  options: const BlobatarOptions(expression: thinking),
)

AnimatedBlobatar(
  name: user.email,
  animation: BlobatarAnimation.hover,
)

BlobatarAnimation.always runs seeded breathe, bob, blink, and saccade motion continuously. BlobatarAnimation.hover ramps ambient motion and lift in while a pointer is over the widget; it stays idle in non-interacted lists. Expression changes morph with the upstream timing and easing, including held thinking seesaw and mad tremor loops.

Set active: false when an application knows a widget is off-screen. The widget also follows TickerMode, disposes every controller with its state, and uses the static rendering path when MediaQuery.disableAnimations requests reduced motion. Set respectReducedMotion: false only when the application provides an equivalent accessibility control.

Options #

Options are immutable and forwarded to the core without adapter-specific defaults:

BlobatarOptions(
  background: Backdrop.circle,
  hue: 210,
  tone: 0.8,
  palette: const {'eye': '#ffffff'},
  traits: const {
    'shape': 0.99,
    'eye.ratio': 0,
  },
  normalize: true,
  contrast: true,
  expression: love,
)

All expression values are exported from either library: idle, happy, sad, mad, surprised, wink, sleepy, smug, unsure, scared, love, shy, sick, and thinking.

Core API #

import 'package:blobatar/blobatar.dart';

final traits = traitsFor('alain@example.com');
final layout = layoutFor('alain@example.com');
final colors = ramp(210);
final frame = motionAt(
  motionSeedsFor('alain@example.com'),
  1200,
  1,
);

• traitsFor exposes the deterministic trait reader.
• layoutFor, partsFor, and resolve expose resolved generation-2 output.
• ramp and palette expose the authored OKLCh palette pipeline.
• superellipse, blobPath, and polygon expose structured path primitives.
• motionSeedsFor and motionAt expose deterministic motion without a Flutter controller.

Parity #

The port is pinned to blobatar 2.4.0, generation 2. That package major owns the frozen seed-to-look mapping, so adding this SDK does not move any existing name to a different avatar and does not modify the TypeScript golden fixture.

test/fixtures/reference-vectors.json is a checked-in, self-describing, repository-only artifact exported once from the TypeScript implementation by ../../tools/export-reference-vectors.ts. It contains 1,570 layout cases, 42 expression cases, every silhouette band, normalization and non-ASCII inputs, palette/tone edges, and trait overrides. The Dart tests only read it; they never update it from port output, and test/ is excluded from the published package archive.

Known Rendering Differences #

• Dart VM trigonometric functions call the host C math library. IEEE 754 does not require one bit-exact sin/cos implementation, so trig-derived layout floats use the fixture's tight 1e-9 relative tolerance. Rounded path data, hash values, traits, palette hex, and expression channels remain exact.
• Flutter and browser engines rasterize vector edges with different antialiasing implementations. Geometry and draw order match; individual edge pixels are not promised to match an SVG browser screenshot.
• NFC is provided by unorm_dart. The parity fixture covers the normalization cases that affect the upstream paste-a-name contract; a future Unicode data update must be checked against new upstream vectors before changing output.

Supported Platforms #

The supported SDK floor is Dart 3.6 / Flutter 3.27. CI checks the minimum Flutter 3.27 line and the latest stable Flutter 3.x release.

Example #

example/ is an interactive Blobatar Studio for changing the name, shape, expression, hue, backdrop, and motion mode. It also demonstrates held expression loops, a hover-animated gallery, reduced continuous list work, and the fixed Claude/Codex web easter eggs.

cd packages/flutter/example
flutter pub get
flutter run -d chrome

See example/README.md for device and test commands.

Development #

cd packages/flutter
flutter pub get
dart format --output=none --set-exit-if-changed .
dart analyze
dart test test/dart
flutter test test/flutter
dart doc

cd example
flutter pub get
flutter analyze
flutter test

Regenerate the reference artifact only from a checkout of the pinned upstream release, never from this Dart implementation:

BLOBATAR_TS_SRC=/path/to/blobatar-v2.4.0/packages/blobatar/src \
  bun ../../tools/export-reference-vectors.ts

License and Maintenance #

MIT licensed, matching the upstream project. Blobatar was created by Alain; the Dart/Flutter implementation is maintained by 404khai with upstream approval. The blobatar pub.flutter-io.cn name was approved in Alain00/blobatar#29. Publishing remains manual and is not performed by this repository's npm release workflow.