Game Framework #

A unified, modular framework for embedding multiple game engines (Unity, Unreal Engine, and potentially others) into Flutter applications.

✨ Features #

• 🎮 Unified API - One interface for all game engines
• 🔌 Modular Architecture - Plug in only the engines you need
• ↔️ Bidirectional Communication - Flutter ↔ Engine messaging
• ♻️ Lifecycle Management - Automatic pause/resume/destroy
• 📱 Multi-Platform - Android & iOS (Web/Desktop coming soon)
• 🛡️ Type-Safe - Full Dart type safety
• 🚀 Production-Ready - Export automation, validation, and tooling
• 📖 Well-Documented - 3,400+ lines of documentation

🚀 Quick Start #

1. Add Dependencies #

dependencies:
  gameframework: ^0.0.2
  gameframework_unity: ^0.0.2
  gameframework_stream: ^0.0.2  # Optional: for asset streaming

Or install from the command line:

flutter pub add gameframework
flutter pub add gameframework_unity

2. Initialize Engine Plugin #

import 'package:flutter/material.dart';
import 'package:gameframework/gameframework.dart';
import 'package:gameframework_unity/gameframework_unity.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  UnityEnginePlugin.initialize();
  runApp(MyApp());
}

3. Embed Engine in Your App #

class GameScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: GameWidget(
        engineType: GameEngineType.unity,
        onEngineCreated: (controller) {
          controller.sendMessage('GameManager', 'Start', 'level1');
        },
        onMessage: (message) {
          print('Message from engine: ${message.data}');
        },
      ),
    );
  }
}

That's it! See QUICK_START.md for detailed instructions.

📦 Supported Engines #

* = Work in Progress

🏗️ Architecture #

┌─────────────────────────────────────────────────┐
│              Flutter Application                 │
│                                                  │
│  ┌────────────────────────────────────────────┐ │
│  │  GameWidget (Unified API)                  │ │
│  └─────────────┬──────────────────────────────┘ │
│                │                                 │
│  ┌─────────────▼──────────────────────────────┐ │
│  │  GameEngineController (Interface)          │ │
│  └─────────────┬──────────────────────────────┘ │
└────────────────┼──────────────────────────────┘
                 │
        ┌────────┴────────┐
        │                 │
┌───────▼──────┐  ┌───────▼──────┐
│Unity Plugin  │  │Unreal Plugin │
│              │  │   (Soon)     │
└───────┬──────┘  └──────────────┘
        │
┌───────▼──────────────────────────┐
│    Native Bridge                 │
│  (Android/iOS)                   │
└───────┬──────────────────────────┘
        │
┌───────▼──────────────────────────┐
│    Game Engine                   │
│  (Unity/Unreal)                  │
└──────────────────────────────────┘

📚 Documentation #

Getting Started #

• Quick Start Guide - Get up and running in 5 minutes
• Implementation Status - Current project status

Unity Integration #

• Unity Plugin Guide - Flutter-side Unity usage
• Unity Bridge Guide - Unity-side integration
• AR Foundation Guide - AR experiences

Architecture & Design #

• Design Documents - 10 detailed design documents
• API Reference - Inline API documentation
• Changelog - Version history

🎯 Use Cases #

Mobile Gaming #

Embed Unity/Unreal games directly in your Flutter app:

GameWidget(
  engineType: GameEngineType.unity,
  config: GameEngineConfig(fullscreen: true),
)

AR Experiences #

Build AR apps with AR Foundation:

GameWidget(
  engineType: GameEngineType.unity,
  onEngineCreated: (controller) {
    controller.sendMessage('ARManager', 'StartAR', '');
  },
)

Interactive Content #

Mix game content with Flutter UI:

Column(
  children: [
    Expanded(child: GameWidget(...)),
    ControlPanel(), // Your Flutter UI
  ],
)

🛠️ Unity Integration #

Export Your Unity Project #

1. Add Flutter scripts to your Unity project
2. In Unity menu: Flutter > Export for Flutter
3. Select Android and/or iOS
4. Export to your Flutter project

Validate Your Project #

1. In Unity menu: Flutter > Validate Project
2. Fix any issues with one-click fixes
3. Ready to export!

See Unity Plugin Guide for details.

💬 Communication #

Flutter → Unity #

// Simple message
await controller.sendMessage('Player', 'Jump', '10.5');

// JSON message
await controller.sendJsonMessage('GameManager', 'UpdateScore', {
  'score': 100,
  'stars': 3,
});

Unity → Flutter #

// Simple message
FlutterBridge.Instance.SendToFlutter("GameManager", "onReady", "true");

// JSON message
var data = new GameData { score = 100, level = 5 };
FlutterBridge.Instance.SendToFlutter("GameManager", "onUpdate", data);

🎓 Example #

Run the included example to see it in action:

cd example
flutter run

The example demonstrates:

• ✅ Engine initialization
• ✅ Lifecycle management
• ✅ Bidirectional communication
• ✅ Event logging
• ✅ UI controls

📊 Project Status & Roadmap #

Current Version: 0.0.2

✅ Production Ready #

• Unity: Android, iOS
• Core Framework: All platforms
• Quality: Type-safe API, comprehensive tests, clean static analysis

🚧 Work in Progress #

• Unity: Web, macOS, Windows, Linux
• Unreal: Android, iOS

📋 Roadmap #

• Near-term:

  • Complete Unity desktop (macOS, Windows, Linux) support
  • Complete Unity Web/WebGL support
  • Complete Unreal Engine mobile (Android, iOS) integration

• Mid-term:

  • Unreal desktop & web support
  • Advanced asset streaming features
  • Performance optimization tools

• Long-term:

  • Additional game engine integrations
  • Cloud services integration
  • v1.0 Production release

🤝 Contributing #

Contributions are welcome! Please read our Contributing Guide first.

Areas We Need Help #

• Testing on various devices
• Additional game engine integrations
• Documentation improvements
• Example projects

📋 Requirements #

Flutter #

• Flutter 3.10.0 or higher
• Dart 3.0.0 or higher

Android #

• minSdkVersion: 21 (Android 5.0)
• targetSdkVersion: 33
• Kotlin 1.8+
• Gradle 8.0+

iOS #

• iOS 12.0 or higher
• Swift 5.0+
• Xcode 14.0+

Unity #

• Unity 2022.3.x or 2023.1.x
• IL2CPP scripting backend recommended

📄 License #

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Support #

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: See docs-files/

🔗 Links #

• Quick Start Guide
• Unity Plugin Guide
• AR Foundation Guide
• API Documentation
• Changelog

Made with 🎮 for Flutter game developers