# flame-engine/flame architecture

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

- Interactive diagram: https://gitdiagram.com/flame-engine/flame
- Repository: https://github.com/flame-engine/flame

## Overview

##### Project Type and Purpose
- This is a monorepo containing “Flame” – a Flutter-based 2D/3D game engine – plus a host of bridge packages (audio, physics, Lottie, ECS, Tiled maps, etc.), documentation, examples, and CI/CD pipelines.
- It’s not a single app, but an open-source SDK/toolkit for game developers, organized with Melos for multi-package management.

##### File-Structure Analysis
– Top-level folders:
- .github & workflows: GitHub Actions CI/CD, benchmarks, spell checking, release pipelines.
- doc (_sphinx): Sphinx-based docs sources, custom extensions to generate the website at docs.flame-engine.org.
- examples: dozens of runnable sample games and storybooks demonstrating core/bridge features.
- packages: each subfolder (flame, flame_3d, flame_audio, flame_forge2d, flame_bloc, etc.) is a standalone Dart/Flutter package, with lib/, example/, test/ and pubspec.yaml.
- scripts: helpers for spelling, doc setup.
– Core package “packages/flame” implements engine fundamentals (game loop, components, input, rendering, collisions, assets cache).
– Bridge packages depend on core “flame” and each integrate an external library into Flame’s component model.
– Documentation pipeline uses Sphinx + custom Dart domains and GitHub Pages workflow.

##### Key README Insights
– Flame’s feature set: game loop, FCS component system, effects/particles, collisions, input, graphics, utilities.
– Officially supported bridges: audio, bloc, FireAtlas, Forge2D, isolates, Lottie, network assets, oxygen ECS, Rive, SVG, Tiled.
– Melos orchestrates multi-package versioning and publishing to pub.dev.

##### Diagramming the Architecture
1. Core Engine (“packages/flame”)
2. Bridge Packages (flame_audio, flame_forge2d, flame_bloc, …)
3. 3D Extension (“packages/flame_3d”)
4. Documentation System (doc/_sphinx + GitHub Pages)
5. Examples (examples/ + packages/*/example)
6. CI/CD & Release (GitHub Actions workflows)
7. Package Manager & Tooling (Melos, Dart SDK)
8. Scripts (spelling, docs)

– Core Engine exports APIs → consumed by Bridge Packages and Examples
– Bridge Packages depend on both Core Engine and external libraries (e.g., Bloc, Forge2D, Rive)
– Examples import Core Engine and selected bridges to build demo apps
– Melos coordinates versioning/publishing across packages
– Documentation sources pull code comments from each package to generate site
– CI workflows trigger: tests (unit + golden), benchmarks, docs build, release tagging

c. Architectural Patterns & Principles:
– Monorepo with Melos: centralized dependency and version management
– Package-per-feature: each bridge is isolated for modularity and independent release cycles
– Plugin/bridge pattern: wrap external libraries in Flame’s component model
– Sphinx + custom domains: decouple doc source from code, generate multi-package docs
– CI pipeline enforcing quality gates (spellcheck, lint, tests, benchmarks)

d. Key Technologies & Frameworks:
– Dart & Flutter (core language and UI framework)
– Melos (monorepo CLI)
– Sphinx with custom Dart/Flutter extensions
– GitHub Actions (cicd.yml, benchmark.yml, release-*.yml)
– External libs: bloc, audioplayers, Forge2D, Rive, flutter_svg, tiled

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Monorepo Tooling
    subgraph "Monorepo Tooling"
        melos["Melos CLI"]:::tool
    end
    click melos "https://github.com/flame-engine/flame/blob/main/pubspec.yaml"

    %% Scripts
    subgraph "Scripts"
        scripts["Scripts"]:::tool
    end
    click scripts "https://github.com/flame-engine/flame/tree/main/scripts/"

    %% Documentation System
    subgraph "Documentation System"
        sphinx["Sphinx Sources & Extensions"]:::ciDocs
        md["Markdown Sources"]:::ciDocs
        sphinx --> md
    end
    click sphinx "https://github.com/flame-engine/flame/tree/main/doc/_sphinx"
    click md "https://github.com/flame-engine/flame/tree/main/doc/"

    %% CI/CD & Release
    subgraph "CI/CD & Release"
        cicd["GitHub Actions Workflows"]:::ciDocs
    end
    click cicd "https://github.com/flame-engine/flame/blob/main/.github/workflows/*.yml"

    %% Core Engine
    core["Core Engine"]:::core
    click core "https://github.com/flame-engine/flame/tree/main/packages/flame"

    %% Bridge Packages
    subgraph "Bridge Packages"
        brAudio["Bridge: Audio"]:::bridge
        brForge2D["Bridge: Forge2D (Physics)"]:::bridge
        brBloc["Bridge: BLoC"]:::bridge
        brFireAtlas["Bridge: FireAtlas"]:::bridge
        brConsole["Bridge: Console"]:::bridge
        brDevtools["Bridge: DevTools"]:::bridge
        brIsolate["Bridge: Isolate"]:::bridge
        brLottie["Bridge: Lottie"]:::bridge
        brNetwork["Bridge: Network Assets"]:::bridge
        brOxygen["Bridge: Oxygen ECS"]:::bridge
        brRive["Bridge: Rive"]:::bridge
        brRiverpod["Bridge: Riverpod"]:::bridge
        brSpine["Bridge: Spine"]:::bridge
        brSplash["Bridge: Splash Screen"]:::bridge
        brSVG["Bridge: SVG"]:::bridge
        brTiled["Bridge: Tiled Maps"]:::bridge
        br3D["3D Extension"]:::bridge
    end
    click brAudio "https://github.com/flame-engine/flame/tree/main/packages/flame_audio"
    click brForge2D "https://github.com/flame-engine/flame/tree/main/packages/flame_forge2d"
    click brBloc "https://github.com/flame-engine/flame/tree/main/packages/flame_bloc"
    click brFireAtlas "https://github.com/flame-engine/flame/tree/main/packages/flame_fire_atlas"
    click brConsole "https://github.com/flame-engine/flame/tree/main/packages/flame_console"
    click brDevtools "https://github.com/flame-engine/flame/tree/main/packages/flame_devtools"
    click brIsolate "https://github.com/flame-engine/flame/tree/main/packages/flame_isolate"
    click brLottie "https://github.com/flame-engine/flame/tree/main/packages/flame_lottie"
    click brNetwork "https://github.com/flame-engine/flame/tree/main/packages/flame_network_assets"
    click brOxygen "https://github.com/flame-engine/flame/tree/main/packages/flame_oxygen"
    click brRive "https://github.com/flame-engine/flame/tree/main/packages/flame_rive"
    click brRiverpod "https://github.com/flame-engine/flame/tree/main/packages/flame_riverpod"
    click brSpine "https://github.com/flame-engine/flame/tree/main/packages/flame_spine"
    click brSplash "https://github.com/flame-engine/flame/tree/main/packages/flame_splash_screen"
    click brSVG "https://github.com/flame-engine/flame/tree/main/packages/flame_svg"
    click brTiled "https://github.com/flame-engine/flame/tree/main/packages/flame_tiled"
    click br3D "https://github.com/flame-engine/flame/tree/main/packages/flame_3d"

    %% Examples
    subgraph "Examples"
        monoEx["Examples (monorepo-wide)"]:::example
        pkgEx["Package Examples"]:::example
    end
    click monoEx "https://github.com/flame-engine/flame/tree/main/examples/"
    click pkgEx "https://github.com/flame-engine/flame/tree/main/packages/*/example"

    %% Publishing
    publish["pub.dev Releases"]:::ciDocs

    %% Relationships
    melos --> core
    melos --> brAudio
    melos --> brForge2D
    melos --> brBloc
    melos --> brFireAtlas
    melos --> brConsole
    melos --> brDevtools
    melos --> brIsolate
    melos --> brLottie
    melos --> brNetwork
    melos --> brOxygen
    melos --> brRive
    melos --> brRiverpod
    melos --> brSpine
    melos --> brSplash
    melos --> brSVG
    melos --> brTiled
    melos --> br3D

    core --> brAudio
    core --> brForge2D
    core --> brBloc
    core --> brFireAtlas
    core --> brConsole
    core --> brDevtools
    core --> brIsolate
    core --> brLottie
    core --> brNetwork
    core --> brOxygen
    core --> brRive
    core --> brRiverpod
    core --> brSpine
    core --> brSplash
    core --> brSVG
    core --> brTiled
    core --> br3D

    core --> monoEx
    brAudio --> monoEx
    brForge2D --> monoEx
    brBloc --> monoEx
    core --> pkgEx
    brAudio --> pkgEx
    brForge2D --> pkgEx
    brBloc --> pkgEx

    core --> sphinx
    brAudio --> sphinx
    brForge2D --> sphinx
    brBloc --> sphinx
    brFireAtlas --> sphinx
    brConsole --> sphinx
    brDevtools --> sphinx
    brIsolate --> sphinx
    brLottie --> sphinx
    brNetwork --> sphinx
    brOxygen --> sphinx
    brRive --> sphinx
    brRiverpod --> sphinx
    brSpine --> sphinx
    brSplash --> sphinx
    brSVG --> sphinx
    brTiled --> sphinx
    br3D --> sphinx

    cicd --> core
    cicd --> brAudio
    cicd --> brForge2D
    cicd --> brBloc
    cicd --> brFireAtlas
    cicd --> brConsole
    cicd --> brDevtools
    cicd --> brIsolate
    cicd --> brLottie
    cicd --> brNetwork
    cicd --> brOxygen
    cicd --> brRive
    cicd --> brRiverpod
    cicd --> brSpine
    cicd --> brSplash
    cicd --> brSVG
    cicd --> brTiled
    cicd --> br3D
    cicd --> sphinx
    cicd --> md
    cicd --> publish

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#004085;
    classDef bridge fill:#ffe5b4,stroke:#994d00,color:#994d00;
    classDef example fill:#d4edda,stroke:#155724,color:#155724;
    classDef tool fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef ciDocs fill:#f5c6cb,stroke:#721c24,color:#721c24;
```
