SchemaX #

SchemaX is a Flutter + GraphX rendering engine that turns structured schema data into highly interactive canvases. Provide a JSON schema describing the background and elements of your scene and SchemaX delivers a widget with panning, zooming, animation hooks, and a plugin system.

Build touch-friendly, schema-driven canvases for Flutter. SchemaX handles viewport math so you can focus on the story your scene tells.

Highlights #

• Schema-first workflow — Encode backgrounds, element bounds, and custom metadata with Schema/SchemaElement. SchemaX restores the layout on any screen and enforces clamped bounds.
• Smooth gestures — Dragging, pinch-to-zoom, focus points, and tweenTo/tweenBack animations are built in, making it easy to guide the user to a specific element.
• Extensible plugins — Implement InteractivePlugin to react to gestures and render overlays such as coordinate axes or visibility trackers (ViewportVisibilityPlugin).
• Event hooks — Use renderer.onClick/renderer.onZoom to coordinate Flutter UI with GraphX nodes.
• Utility toolbox — Helpers for image caching, zoom compensation, looping animations, and more reduce glue code.

Installation #

dependencies:
  schemax: ^1.1.0 # use the published version when available
  # or when developing locally:
  # schemax:
  #   path: ../schemax

flutter pub get

Quick Start #

1. Register a custom element

   class BuildingElement extends SchemaElement {
     BuildingElement(super.config);
   
     static void register() {
       SchemaElement.registerType('building', BuildingElement.new);
     }
   
     @override
     Future<GDisplayObject> build(RendererCore renderer) async {
       final rect = renderer.rectTransformWithConfig(this);
       final sprite = GSprite()..setPosition(rect.x, rect.y);
       // Draw anything you need inside the sprite.
       sprite.onTap.add((_) => renderer.triggerTap(this));
       return sprite;
     }
   }
   

2. Load the schema

   final schemaJson =
       jsonDecode(await rootBundle.loadString('assets/schema.json'));
   final schema = Schema.fromMap(schemaJson);
   

3. Render with RendererWidget

   class SocialMap extends HookWidget {
     const SocialMap({super.key});
   
     @override
     Widget build(BuildContext context) {
       socialMapInit(); // registers SchemaElement types
       final schema = Schema.fromMap(kMySchema);
       return RendererWidget(
         schema: schema,
         interactivePlugins: [
           CoordinateAxisPlugin(valueMode: AxisValueMode.transformed),
           ViewportVisibilityPlugin(
             onVisible: (element) => debugPrint('visible ${element?.id}'),
           ),
         ],
         onControllerReady: (controller) {
           controller.renderer.onClick((payload) {
             if (payload is BuildingSprite) payload.showInfo();
           });
         },
       );
     }
   }
   

Schema Structure #

Register new element types via SchemaElement.registerType, then override build to return any GDisplayObject. See example/lib/social_map for an end-to-end implementation.

Plugin System #

InteractivePlugin exposes onAttach, onMove, and onScale. The RendererPluginManager dispatches every gesture to each plugin in order, letting you render overlays or react to viewport changes without touching gesture logic.

Built-in plugins include:

• CoordinateAxisPlugin — draws top/left axes with ticks and labels using either schema coordinates or transformed stage values.
• ViewportVisibilityPlugin — reports which element meets a visibility threshold within the current viewport.

Plugins have full access to RendererCore helpers (stageToViewportX/Y, stageToSchemaX/Y, rectTransform*, etc.) so you can position overlays precisely.

Controller & Core APIs #

• RendererWidget — wraps SceneBuilderWidget with a GestureDetector, instantiating a RendererController unless you provide one.
• RendererController — holds the RendererCore, translates Flutter gestures to renderer interactions, and forwards events to plugins.
• RendererCore essentials:
  • onClick / onZoom to listen for tap propagation and zoom changes (ZoomEventData).
  • tweenTo(Base, ViewportAnimationConfig) / tweenBack() for focus animations.
  • resetTransform() / resetContentInitialPosition() to return to the starting view.
  • rectTransform*, stageToSchema*, stageToViewport* for converting between coordinate spaces.

Utilities & Animation Helpers #

• helper/zoom.keepElementSize keeps an overlay visually stable while the canvas zooms; calcKeepSizeZoom returns the compensation factor.
• utils/animate.breathingAnimation plus utils/utils.LoopManager produce looping tween sequences (used by the sample “breathing” indicator).
• utils/image.loadImage wraps network/local image loading with caching; utils/file.loadImageFromPath leverages DefaultCacheManager.

Example App #

The example/ directory ships with a “social map” demo. It showcases schema parsing, a custom building element, animated info cards, and plugin overlays.

cd example
flutter run

Development & Testing #

• flutter analyze — static analysis.
• flutter test — run unit/widget tests (add your own as needed).

License #

SchemaX is distributed under the MIT License (see LICENSE).