DOCSEARCHbyAlgolia
Submit Docs

FlNodes Framework

repository·main·Indexed 41 days ago

https://github.com/williamkaroldicioccio/fl_nodes

A modular, scalable ecosystem for building node-based applications in Flutter, such as visual scripting editors, workflow designers, and graph-based UIs. The framework includes fl_nodes_core for low-level engine control and fl_nodes as a high-level API proxy. It provides capabilities for hardware-accelerated rendering, viewport management, and graph data structures. The ecosystem also includes fl_context_menu for creating structured, stylable context menus with support for submenus and search bars.

Tokens
12.3K
Snippets
40
Records
57
Agent score
51%

What's inside FlNodes

  1. Understand the purpose of fl_nodes_core

    main

    fl_nodes_core is the low-level engine of the FlNodes Framework. It is intended for advanced users with specialized requirements who need direct control over the framework's internals.

    Most developers should instead use Domain Packages (such as fl_nodes_visual_scripting or fl_nodes_mind_maps) which are pre-built for specific use cases.

    Core capabilities provided by fl_nodes_core include:

    • Low-level rendering: Hardware-accelerated canvas operations.
    • Node controller: Manages state and lifecycle.
    • Graph data structures: Handles nodes, ports, edges, and relationships.
    • Input handling: Processes mouse, touch, and gesture inputs.
    • Hit testing: Performs efficient spatial queries for user interaction.
    • Viewport management: Handles pan, zoom, and coordinate transformations.
    • Serialization foundation: Provides the infrastructure for saving and loading graphs.

  2. Explore fl_nodes use cases

    main

    The FlNodes framework is designed for building various graph-based and node-based user interfaces, including:

    • Visual Scripting Editors: Game logic, automation flows, and state machines.
    • Workflow & Process Designers: Business rules, decision trees, and automation.
    • Shader & Material Graphs: Visual shader creation.
    • Dataflow Tools: ETL pipelines, AI workflows, and processing graphs.
    • ML Architecture Visualizers: Neural network visualization.
    • Modular Audio Systems: Synthesizers, effect chains, and sequencers.
    • Graph-Based UIs: Mind maps, dependency trees, and hierarchies.

  3. Understand the FlNodes Framework architecture

    main

    FlNodes is a modular ecosystem organized as a monorepo. It is split into specialized packages to allow for different levels of abstraction:

    • fl_nodes_core: The underlying engine that powers the framework.
    • fl_nodes: A proxy export package designed for backward compatibility, providing access to the modular architecture through a high-level API.

    Future specialized packages include fl_nodes_visual_scripting, fl_nodes_mind_maps, and fl_nodes_flow_graphs.

  4. Understand the fl_nodes proxy package and migration

    main

    The fl_nodes package currently acts as a compatibility layer (proxy export package) for the FlNodes Framework. It re-exports all public APIs from fl_nodes_core to maintain the same import paths and API surface for existing projects.

    Migration Options:

    • For existing projects: Continue using fl_nodes to ensure a smooth transition without breaking changes.
    • For new/advanced projects: Use fl_nodes_core directly if you require more granular control or want to leverage the framework's modular monorepo architecture.

  5. Install fl_nodes_core

    main

    To use the foundational engine of the FlNodes Framework, add fl_nodes_core to your pubspec.yaml dependencies.

    Important: You must also register the required shader asset in your pubspec.yaml to enable hardware-accelerated rendering features like the grid background.

    dependencies:
  fl_nodes_core: ^latest_version

flutter:
  shaders:
    - packages/fl_nodes_core/shaders/grid.frag

    Then run:

    flutter pub get

  6. Customize the iOS Launch Screen assets

    main

    To change the image displayed during the app's launch on iOS, you can either replace the image files directly in the filesystem or use Xcode.

    Option 1: Filesystem replacement Replace the existing image files within the examples/fl_nodes_example/ios/Runner/Assets.xcassets/LaunchImage.imageset/ directory with your own assets.

    Option 2: Using Xcode

    1. Open the iOS workspace using: open ios/Runner.xcworkspace.
    2. In the Xcode Project Navigator, navigate to Runner/Assets.xcassets.
    3. Drag and drop your desired images into the asset catalog.
    open ios/Runner.xcworkspace

  9. Customize iOS launch screen assets

    main

    To change the image displayed during the app's launch on iOS, you can either replace the image files directly in the project directory or use Xcode for a more visual approach.

    Method 1: Direct File Replacement

    Replace the existing image files within the ios/Runner/Assets.xcassets/LaunchImage.imageset/ directory with your own assets.

    Method 2: Using Xcode (Recommended)

    1. Open the iOS workspace in Xcode by running: open ios/Runner.xcworkspace.
    2. In the Xcode Project Navigator, navigate to Runner/Assets.xcassets.
    3. Drag and drop your desired images into the asset catalog to replace the current launch images.
    open ios/Runner.xcworkspace

  10. Install the FlNodes Framework

    main

    You can install FlNodes using one of two packages depending on your requirements:

    1. fl_nodes: Recommended for most users. It provides a high-level API with full features.
    2. fl_nodes_core: For advanced users who require low-level control over the engine.

    Important: Regardless of the package chosen, you must include the required shader asset in your pubspec.yaml to ensure proper rendering.

    dependencies:
  # For most users - high-level API with full features
  fl_nodes: ^latest_version

  # For advanced users needing low-level control
  fl_nodes_core: ^latest_version

flutter:
  shaders:
    - packages/fl_nodes_core/shaders/grid.frag

    Then, run:

    flutter pub get

  11. Implement custom node logic with onExecute

    main

    When defining a node's behavior, the onExecute callback is the primary entry point. It is called by the FlNodesExecutionHelper during the execution phase.

    The callback provides access to:

    1. Input Ports: A map of port IDs to their current data.
    2. Fields: A map of field IDs to their current data.
    3. Execution State: A local map (_execState) to store node-specific persistent state across steps.
    4. Control Flow Callback: A function to signal which control ports should be activated next.
    5. Data Output Callback: A function to push data to connected data ports.

    Control Flow Signature: void Function(Set<String> portIdNames, {bool definitive = false})

    • Passing definitive: true marks the node as completed.
    • Passing definitive: false marks the node as stepped (useful for feedback loops/cycles).

    Data Output Signature: void Function(Set<(String, dynamic)> idNamesAndData) _put

    • Used to propagate data to connected nodes via data ports.

  12. Manage Port Connection Compatibility

    main

    When building custom port types, you can override compatibleWith(FlPortPrototype other) in your prototype to define custom connection rules.

    Additionally, FlPortDataModel.canLinkTo(FlPortDataModel other) performs the following checks:

    1. Self-connection: Prevents a port from connecting to itself.
    2. Prototype Compatibility: Calls the prototype's compatibleWith method.
    3. Multiplicity: Checks if either port has allowsMultipleLinks == false and already has an existing link.