# wyq0918dev/flutter_godot architecture

> Architecture diagram of the GitHub repository wyq0918dev/flutter_godot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wyq0918dev/flutter_godot
- Repository: https://github.com/wyq0918dev/flutter_godot

## Overview

##### Project Type and Purpose
- This is a federated Flutter plugin (“flutter_godot”) whose purpose is to embed a Godot game engine instance as a Widget inside a Flutter application and support two-way communication between Dart and Godot.
- The plugin itself lives in the root, with:
- `/lib` containing the Dart API and platform interface
- `/android` containing the Android-side implementation in Kotlin
- stubs for web and “unsupported” platforms under `lib/src`
- an `example` subproject demonstrating usage on Android, iOS, macOS, Linux, Windows, web

##### File Structure Analysis
- Top‐level directories:
- `android/` – plugin’s Android platform code (FlutterGodotPlugin.kt)
- `lib/` – Dart entrypoint (`flutter_godot.dart` & `flutter_godot_web.dart`), plus `src/` for the federated plugin platform interface and implementations
- `example/` – a full Flutter application with platform folders (android/, ios/, etc.) illustrating how to consume the plugin
- `test/` – unit tests for the Dart code
- The Android folder shows this plugin uses Flutter’s PlatformView and MethodChannel to host and communicate with Godot.
- `pubspec.yaml` indicates dependency management and plugin registration.

##### README Insights
- Defines two modes for packaging Godot content:
a. Integrated mode: raw Godot project assets under `android/app/src/main/assets`
b. Independent mode: `.pck` file delivered in Flutter assets
- Only Android is fully supported; other platforms have no-ops or stub implementations to avoid crashes.

##### Main Components
a. Flutter/Dart Layer
- Application Widget tree
- `flutter_godot` Dart API
- Platform Interface (abstract class in `lib/src/platform_interface.dart`)
b. Platform Channel Layer
- MethodChannel (in `lib/src/method_channel.dart`)
- MessageCodec and JSON‐like payloads for commands/events
c. Android Native Layer
- Kotlin plugin (`FlutterGodotPlugin.kt`) implementing MethodCallHandler
- Godot Engine Native Library (AAR or SO loaded at runtime)
- Android PlatformView (SurfaceView or TextureView embedding Godot rendering)
d. Godot Game Asset Layer
- `.pck` or raw project assets under `assets/`
- Godot scripting entries (`main.gd`)
e. Example App
- Frontend Flutter code in `example/lib` calling plugin APIs for demonstration

##### Relationships and Interactions
- Dart API → Platform Interface → MethodChannel
- MethodChannel → Kotlin Plugin (Android side)
- Kotlin Plugin → Godot native library (load, initialize, render)
- Godot Engine → Kotlin Plugin (events, callbacks) → MethodChannel → Dart API → Flutter UI
- For unsupported platforms: MethodChannel calls routed to stub implementations (no-ops)

##### Architectural Patterns and Principles
- Federated Plugin Pattern: separation of platform‐independent interface (in Dart) from platform‐specific implementations
- PlatformView Pattern: embedding a native view (Godot’s rendering surface) into Flutter’s UI tree
- Method Channel IPC: clear two-way messaging interface, serializable payloads
- Asset Packaging Modes: integrated vs. independent to support different workflows

##### Technologies, Frameworks, Libraries
- Flutter framework (Dart, Widgets)
- Platform Channels (`MethodChannel`)
- Android tooling (Kotlin, AndroidManifest.xml, gradle)
- Godot Engine C++ library for Android, scripting via GDScript
- Example apps leverage multiple Flutter platforms (iOS, macOS, Linux, Windows, Web)

- UI → API calls
- API → PlatformChannel
- PlatformChannel → Native plugin → Godot
- Godot → Plugin → API → UI for callbacks

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Flutter Layer
    subgraph "Flutter Application" 
        direction TB
        FlutterUI["Flutter UI\n(main.dart)"]:::example
        flutter_godot_dart["flutter_godot.dart"]:::dart
        flutter_godot_web["flutter_godot_web.dart"]:::dart
    end

    %% Dart Plugin Core
    subgraph "Dart Plugin Core"
        direction TB
        platform_interface["platform_interface.dart"]:::dart
        method_channel["method_channel.dart"]:::ipc
        godot_player["godot_player.dart"]:::dart
        listen_callback["listen_callback.dart"]:::dart
        unsupported["unsupported.dart"]:::stub
    end

    %% Android Native Layer
    subgraph "Android Native Plugin" 
        direction TB
        FlutterGodotPlugin["FlutterGodotPlugin.kt"]:::android
        AndroidManifest["AndroidManifest.xml"]:::android
        AndroidPlatformView["PlatformView\n(SurfaceView)"]:::android
        GodotEngine["Godot Engine Native\n(AAR/SO)"]:::godot
    end

    %% Example App Assets
    subgraph "Example App Assets" 
        direction TB
        main_gd["main.gd"]:::godot
        main_tscn["main.tscn"]:::godot
        project_godot["project.godot"]:::godot
        game_pck["game.pck"]:::godot
    end

    %% Example App Host
    subgraph "Example App Host" 
        direction TB
        exampleHostManifest["AndroidManifest.xml"]:::example
    end

    %% Tests
    test["flutter_godot_test.dart"]:::test

    %% Relationships
    FlutterUI -->|"uses API"| flutter_godot_dart
    FlutterUI -->|"uses API (web)"| flutter_godot_web

    flutter_godot_dart -->|"calls"| platform_interface
    flutter_godot_web -->|"calls stub"| unsupported

    platform_interface -->|"to IPC"| method_channel
    godot_player -->|"wraps calls"| method_channel
    method_channel -->|"MethodChannel"| FlutterGodotPlugin
    method_channel -->|"stubbed"| unsupported

    FlutterGodotPlugin -->|"registers View"| AndroidPlatformView
    FlutterGodotPlugin -->|"loads"| GodotEngine
    AndroidPlatformView -->|"renders"| GodotEngine
    GodotEngine -->|"events/callbacks"| FlutterGodotPlugin
    FlutterGodotPlugin -->|"callbacks"| method_channel
    method_channel -->|"events"| listen_callback
    listen_callback -->|"delivers"| flutter_godot_dart
    flutter_godot_dart -->|"updates"| FlutterUI

    %% Asset flows
    main_gd --> GodotEngine
    main_tscn --> GodotEngine
    project_godot --> GodotEngine
    game_pck --> GodotEngine

    %% Example host integration
    exampleHostManifest --> FlutterGodotPlugin

    %% Tests linkage
    test --> flutter_godot_dart

    %% Click Events
    click FlutterUI "https://github.com/wyq0918dev/flutter_godot/blob/master/example/lib/main.dart"
    click flutter_godot_dart "https://github.com/wyq0918dev/flutter_godot/blob/master/lib/flutter_godot.dart"
    click flutter_godot_web "https://github.com/wyq0918dev/flutter_godot/blob/master/lib/flutter_godot_web.dart"
    click platform_interface "https://github.com/wyq0918dev/flutter_godot/blob/master/lib/src/platform_interface.dart"
    click method_channel "https://github.com/wyq0918dev/flutter_godot/blob/master/lib/src/method_channel.dart"
    click godot_player "https://github.com/wyq0918dev/flutter_godot/blob/master/lib/src/godot_player.dart"
    click listen_callback "https://github.com/wyq0918dev/flutter_godot/blob/master/lib/src/listen_callback.dart"
    click unsupported "https://github.com/wyq0918dev/flutter_godot/blob/master/lib/src/unsupported.dart"
    click FlutterGodotPlugin "https://github.com/wyq0918dev/flutter_godot/blob/master/android/src/main/kotlin/com/wyq0918dev/flutter_godot/FlutterGodotPlugin.kt"
    click AndroidManifest "https://github.com/wyq0918dev/flutter_godot/blob/master/android/src/main/AndroidManifest.xml"
    click main_gd "https://github.com/wyq0918dev/flutter_godot/blob/master/example/android/app/src/main/assets/main.gd"
    click main_tscn "https://github.com/wyq0918dev/flutter_godot/blob/master/example/android/app/src/main/assets/main.tscn"
    click project_godot "https://github.com/wyq0918dev/flutter_godot/blob/master/example/android/app/src/main/assets/project.godot"
    click game_pck "https://github.com/wyq0918dev/flutter_godot/blob/master/example/assets/game.pck"
    click exampleHostManifest "https://github.com/wyq0918dev/flutter_godot/blob/master/example/android/app/src/main/AndroidManifest.xml"
    click test "https://github.com/wyq0918dev/flutter_godot/blob/master/test/flutter_godot_test.dart"

    %% Styles
    classDef dart fill:#D0E8F2,stroke:#007ACC,color:#000
    classDef ipc fill:#E8F2D0,stroke:#7CAC00,color:#000
    classDef android fill:#F2D0E8,stroke:#CC007A,color:#000
    classDef godot fill:#F2E8D0,stroke:#CC7A00,color:#000
    classDef example fill:#D0F2E8,stroke:#00ACC0,color:#000
    classDef stub fill:#F0F0F0,stroke:#888888,color:#444
    classDef test fill:#FFE8D0,stroke:#CC7A00,color:#000
```
