roadsman #

Baccarat / Dragon Tiger / Sic Bo "road map" (bead-road) visualization for Flutter.

What it does #

Turns a shoe's raw round-by-round results (banker/player/tie + pair/natural marks) into the industry-standard "roads" used at real tables:

• Bead Plate — one bead per round, in play order, no merging.
• Big Road — consecutive same-winner runs merged into columns; the base every derived road builds on.
• Big Eye Boy / Small Road / Cockroach Pig — three derived roads sharing one parametric algorithm, differing only in the column-offset k and marker shape.
• Pair Road / Natural Road — dedicated roads for banker/player-pair and natural (8/9) hands.
• Derived Trio / Compact Road Sheet — the three derived roads (optionally plus Big Road) combined onto one scoreboard-style grid.
• Stats Panel — banker/player/tie counts and percentages, longest streaks, current streak.

Baked-in support for Baccarat, Dragon Tiger, and Sic Bo via a pluggable GameSpec — the engine, plugins, and renderer don't hardcode baccarat semantics anywhere.

Architecture #

Three layers: core (pure Dart, zero Flutter dependency — computes data and layout) → render (RoadPainter, a CustomPainter that draws a DrawCommand list; plus renderToSvg, a pure function for server-side rendering) → panel (RoadPanel widget: gestures, viewport physics, per-cell animation, replay, UX extras).

Full diagrams are in ARCHITECTURE.md.

Quick start #

import 'package:flutter/material.dart' hide Theme;
import 'package:roadsman/roadsman.dart';

class BigRoadDemo extends StatefulWidget {
  const BigRoadDemo({super.key});
  @override
  State<BigRoadDemo> createState() => _BigRoadDemoState();
}

class _BigRoadDemoState extends State<BigRoadDemo> {
  final engine = createEngine(['bigRoad']);
  final store = createStore();
  ComputeOutput? output;

  @override
  void initState() {
    super.initState();
    store.subscribe((_) => setState(_recompute));
    store.append(const RawResult(no: 1, winner: 'B', bankerPair: false, playerPair: false));
  }

  void _recompute() {
    final cfg = LayoutConfig(cellSize: 18, rows: 6, theme: resolveTheme());
    output = engine.compute(store.getResults(), cfg);
  }

  @override
  Widget build(BuildContext context) {
    final layout = output?.layouts['bigRoad'];
    if (layout == null) return const SizedBox.shrink();
    return RoadPanel(
      cells: layout.cells,
      decorations: layout.decorations ?? const [],
      contentWidth: layout.contentWidth,
      contentHeight: layout.contentHeight,
      theme: resolveTheme(),
      panelWidth: 360,
      panelHeight: 108,
      eventType: RoadUpdateKind.append,
    );
  }
}

See example/ for a complete demo app: game-type switching, road checkboxes, manual "add a round", replay, ask-the-road (predict), and UX toggles.

Run the demo #

cd example
flutter pub get
flutter run

Theming #

Three built-in themes — defaultTheme (dark), darkTheme, lightTheme — plus resolveTheme() for overriding any field without touching plugin code:

final theme = resolveTheme(palette: (p) => p.copyWith(banker: 0xFFFF0000));

Colors are ARGB 32-bit integers throughout core and render (not CSS strings) — core never imports dart:ui, so the same theme values work in renderToSvg on a server with no Flutter runtime at all.

Engine robustness #

If a plugin's derive/layout/predict throws, that road's error is recorded in ComputeOutput.errors and every other road keeps rendering — no blank screen from one bad plugin.

API reference #

Everything below is exported from the roadsman barrel (import 'package:roadsman/roadsman.dart').

Core types (core/types.dart) #

Theme (core/theme.dart) #

Theme, Palette, CanvasTheme, GridTheme, CellTheme, LabelsTheme, FontsTheme, RoadTheme — structure types, each with a copyWith. defaultTheme, darkTheme, lightTheme — built-in instances. resolveTheme({base, palette, canvas, grid, cell, labels, fonts, roads}) — layer overrides onto a base theme via per-field mapper callbacks.

Engine (core/engine.dart) #

createEngine(enabledIds, {spec}) — resolves transitive plugin dependencies, topologically sorts them, returns an Engine. Engine.compute(results, cfg) returns a ComputeOutput (layouts, data, predictions, errors).

Viewport (core/viewport.dart) #

Pure state-machine functions: createViewport(), dragBy(), endDrag(), stepViewport(), computeBounds(), zoomAt(), startAutoScroll(), plus defaultViewportConfig.

Animation (core/animation.dart) #

diffLayout(prev, next) → List<Transition> (EnterTransition/MoveTransition/ExitTransition). sampleEnter/sampleMove/sampleExit sample interpolated commands at a given progress; registerEnterAnimation/registerMoveAnimation/registerExitAnimation add custom named animations. Easing (linear/easeOutCubic/easeOutBack/spring). applyWindow clips a layout to a scrolling column window. translateCommands/translateCommand for manual composition.

Store (core/store.dart) #

createStore({onOutOfSync}) → RoadmapStore with setResults/append/patch/getResults/subscribe. UpdateKind (full/append/patch) tags each ChangeEvent.

Pipeline (core/pipeline.dart) #

createPipeline() / globalPipeline — an ordered, named CommandTransform chain between compute output and the renderer. Built-ins: watermarkTransform(text, opts), grayscaleTransform().

Predict (core/predict.dart) #

predictNextOutcome(results) — statistical next-round tendency (independent of the per-road "ask the road" mechanism above).

Grid layout (core/grid_layout.dart) #

placeOnGrid, placeSequential, cellToPixel, gridCommands, contentSize, roundTo.

Game rules (core/game_spec.dart, stream.dart, game_specs/*) #

GameSpec, GenericResult, OutcomeDef, MarkerDef, StreamSelector (sealed: OutcomeSelector/RangeSelector/MarkSelector), StreamDef, validateGameSpecJson. resolveToken, colorForToken, labelForToken, getStreamDef. Built-in specs: baccaratSpec, dragonTigerSpec, sicboSpec.

Road plugins (core/roads/*) #

12 built-in plugins registered in roadRegistry (Map<String, RoadPlugin>), auto-resolved by createEngine via dependsOn:

deriveRoad(bigRoad, k) and mergeBands(bands) are the shared algorithms behind the derived roads and the combined-grid plugins, respectively.

Renderer (render/*) #

RoadPainter (CustomPainter) — the only built-in Flutter renderer. renderToSvg(layout, theme, {width, height, grid}) — pure-function SVG export, no dart:ui import.

Paint hooks — RoadPainter/RoadFramePainter (and RoadPanel, see below) accept four optional callbacks for custom drawing layered under/over the built-in paint, without replacing it:

• onBeforePaintGridCell/onAfterPaintGridCell (GridCellPaintCallback) — fire once per background tile, GridStyle.tile only. Carry a GridCellPaintInfo with the live Canvas, the tile's rect/color, and its loop-order row/col (handy for checkerboard-style custom fills).
• onBeforePaintCommand/onAfterPaintCommand (CommandPaintCallback) — fire once per DrawCommand (circle/line/slash/dot/badge/rect, including overlay commands). Carry a CommandPaintInfo with the live Canvas and the exact command — switch on its runtime type for every coordinate/size/color field.

before draws underneath the built-in shape, after draws on top — that's the whole z-order control surface. Leaving all four null (the default) costs nothing: the Picture-cache fast paths for the grid layer and content layer are untouched. Setting any of them makes that layer fall back to direct per-frame drawing for that frame (Picture playback can't invoke a Dart callback), trading some drag/inertia-frame performance for correctness.

Panel (panel/*) #

RoadPanel — the widget. FollowTail (none/hard/ease) and RoadUpdateKind (setResults/append/patch) control tail-following and whether insert animations play. createReplayer(fullResults, store, {opts}) → Replayer with play/pause/seek/stop. Exposes the same four paint hooks as RoadPainter (see above) — set them on RoadPanel and they're threaded straight through to its internal painter.

UX add-ons (panel/ux/*) #

createPulseEffect, createCelebrationEffect, EmptyStateOverlay widget, createHapticsEffect, createDoubleTapToTail, prefersReducedMotion(context), createSkeletonRenderer/defaultSkeletonAdapter. These are intentionally lighter than their TS counterparts — see ARCHITECTURE.md for why.

Development #

flutter pub get
flutter analyze
flutter test

License #

MIT