What is Game Framework?

Game Framework is a unified, modular framework for embedding multiple game engines (Unity, Unreal Engine) into Flutter applications. It provides a consistent API, bidirectional communication, and complete lifecycle management across all supported engines and platforms.

The Problem We Solve

The Challenge of Game Engine Integration

Integrating game engines like Unity or Unreal Engine into Flutter applications is traditionally complex:

Engine-Specific Code - Different APIs for each engine
Platform Complexity - Different integration methods for iOS, Android, desktop
Communication Barriers - No standardized way to communicate between Flutter and engines
Lifecycle Management - Manual handling of pause, resume, and destroy events
Build Complexity - Manual export and sync processes for each platform

The Game Framework Solution

Game Framework solves these challenges by providing:

Unified API - Single interface that works with all game engines
Platform Abstraction - Automatic handling of platform-specific details
Bidirectional Communication - Type-safe messaging with high performance
Lifecycle Management - Automatic pause/resume/destroy handling
Automated Tooling - CLI tools for exports, builds, and deployment

How Game Framework Works

graph TB
    subgraph FlutterApp[Flutter Application]
        GameWidget[GameWidget]
        Controller[GameEngineController]
    end
    
    subgraph SDK[Game Framework SDK]
        CoreAPI[Core API]
        UnityPlugin[Unity Plugin]
        UnrealPlugin[Unreal Plugin]
    end
    
    subgraph NativeBridge[Native Bridge]
        AndroidBridge[Android Bridge]
        iOSBridge[iOS Bridge]
        DesktopBridge[Desktop Bridge]
    end
    
    subgraph GameEngines[Game Engines]
        Unity[Unity Engine]
        Unreal[Unreal Engine]
    end
    
    GameWidget --> Controller
    Controller --> CoreAPI
    CoreAPI --> UnityPlugin
    CoreAPI --> UnrealPlugin
    UnityPlugin --> AndroidBridge
    UnityPlugin --> iOSBridge
    UnrealPlugin --> AndroidBridge
    UnrealPlugin --> iOSBridge
    AndroidBridge --> Unity
    iOSBridge --> Unity
    AndroidBridge --> Unreal
    iOSBridge --> Unreal

Architecture Overview

Game Framework consists of three main layers:

1. Core Framework Layer

The gameframework package provides:

GameWidget - Universal widget for embedding any engine
GameEngineController - Unified controller for engine lifecycle and communication
GameEngineRegistry - Plugin registration system
Platform interfaces for Android, iOS, macOS, Windows, Linux

2. Engine Plugin Layer

Separate packages for each engine:

gameframework_unity - Unity Engine integration
gameframework_unreal - Unreal Engine integration

Each plugin implements:

Engine-specific controller
Platform view integration
Message protocol adapters
Native bridge implementations

3. CLI Tool Layer

The game-cli command-line tool provides:

Automated game exports from Unity/Unreal
File synchronization to Flutter project
Build automation
Cloud publishing
Workspace management

Core Concepts

GameWidget

The GameWidget is the main UI component for displaying game engines in Flutter:

GameWidget(
  engineType: GameEngineType.unity,
  config: GameEngineConfig(
    runImmediately: true,
    fullscreen: false,
  ),
  onEngineCreated: (controller) {
    // Engine is ready
  },
  onMessage: (message) {
    // Received message from engine
  },
)

GameEngineController

The controller manages the engine lifecycle and communication:

// Send messages to the game
controller.sendMessage('GameManager', 'LoadLevel', 'Level1');

// Pause the engine
controller.pause();

// Resume the engine
controller.resume();

// Dispose the engine
controller.dispose();

Communication Protocol

Game Framework supports multiple communication protocols:

String Messages - Simple text-based messaging
JSON Messages - Structured data with automatic serialization
Binary Protocol - High-performance binary messaging for large data

Lifecycle Management

Automatic handling of application lifecycle events:

Created - Engine initialized and ready
Paused - App goes to background
Resumed - App returns to foreground
Disposed - Engine cleaned up and destroyed

Platform Support

Platform	gameframework	Unity	Unreal	Status
Android	✓	✓	✓	Stable
iOS	✓	✓	✓	Stable
macOS	✓	✓	✓	Beta
Windows	✓	✓	✓	Beta
Linux	✓	✓	✓	Beta

Use Cases

Mobile Games with Native UI

Build mobile games that combine game engine 3D content with Flutter's native UI:

Challenge: Game engines provide limited UI capabilities
Solution: Use Flutter for menus, HUD, settings while game engine handles 3D gameplay
Result: Native-looking UI with powerful 3D game content