How flame-engine/flame works
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