Frequently Asked Questions

Common questions about Game Framework.

General

What is Game Framework?

Game Framework is a toolkit for embedding Unity and Unreal Engine experiences into Flutter applications. It provides a CLI for exporting and syncing game engine builds, a Flutter SDK with a unified GameWidget for rendering engine content, and a cloud platform for publishing and distributing versioned game packages.

How is it different from other game engine Flutter plugins?

• Unified API - Single GameWidget interface works with both Unity and Unreal Engine
• Full workflow - CLI handles exports, syncing, builds, and cloud publishing
• Bidirectional communication - Type-safe messaging between Flutter and game engines
• Versioning and distribution - Publish game packages with semantic versioning to Game Framework Cloud
• Multi-platform - Android, iOS, Web (WebGL), and desktop support from a single codebase

Which game engines are supported?

Unity is fully supported today (Unity 2022.3+). Unreal Engine support is coming soon. The SDK architecture is engine-agnostic, so the same GameWidget API will work with both engines.

Which platforms are supported?

What does Game Framework cost?

Game Framework offers multiple plans to fit teams of different sizes. Visit gameframework.dev for current pricing and plan details.

SDK

How does the Flutter SDK work?

The SDK provides a GameWidget that embeds a game engine view directly into your Flutter widget tree. You specify an engine type, receive a GameEngineController when the engine is ready, and use it to send messages and manage the engine lifecycle.

GameWidget(
  engineType: GameEngineType.unity,
  config: GameEngineConfig(runImmediately: true),
  onEngineCreated: (controller) {
    controller.sendMessage('GameManager', 'Start', 'level1');
  },
  onMessage: (message) {
    print('From engine: ${message.data}');
  },
)

How do I communicate between Flutter and Unity?

Use the GameEngineController to send messages and the onMessage callback (or messageStream) to receive them. Messages use a target/method/data format and support both plain strings and JSON:

// Send a message to Unity
await controller.sendMessage('Player', 'Jump', '');

// Send structured JSON data
await controller.sendJsonMessage('GameManager', 'LoadLevel', {
  'levelId': 5,
  'difficulty': 'hard',
});

// Receive messages from Unity
controller.messageStream.listen((message) {
  if (message.method == 'OnScoreUpdate') {
    final data = jsonDecode(message.data);
    print('Score: ${data['score']}');
  }
});

See the Messaging API for the full reference.

What packages do I need to install?

You need the core package and the engine-specific plugin:

dependencies:
  gameframework: ^0.0.1         # Core SDK
  gameframework_unity: ^0.0.1   # Unity plugin

Then initialize the plugin in your main():

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

How do I handle engine lifecycle events (pause, resume, dispose)?

The GameEngineController provides lifecycle methods. Use WidgetsBindingObserver to respond to app lifecycle changes:

@override
void didChangeAppLifecycleState(AppLifecycleState state) {
  switch (state) {
    case AppLifecycleState.paused:
      _controller?.pause();
      break;
    case AppLifecycleState.resumed:
      _controller?.resume();
      break;
    default:
      break;
  }
}

See the Lifecycle API for details.

CLI

What does the CLI do?

The game-cli automates the full development workflow:

• game init - Create a .game.yml configuration file
• game add engine unity - Add a Unity project to your Flutter app
• game export - Export Unity/Unreal builds for target platforms
• game sync - Copy exported builds into your Flutter project
• game build - All-in-one: export + sync + build
• game publish - Publish versioned packages to Game Framework Cloud

See the CLI Overview for the full command reference.

How does versioning work?

Game Framework uses semantic versioning. Your package version is defined in .game.yml:

name: my_game_package
version: 1.0.0

When you run game publish, the CLI validates the version, uploads your package and game artifacts, and registers the version in Game Framework Cloud. Each published version is immutable and can be referenced by consumers.

Can I use Game Framework in CI/CD?

Yes. Set the GAME_API_KEY environment variable for non-interactive authentication:

export GAME_API_KEY=your_api_key_here

# Then run CLI commands without interactive login
game build android --engine unity
game publish

In your CI pipeline, store the API key as a secret:

• GitHub Actions: Settings > Secrets > Actions > GAME_API_KEY
• GitLab CI: Settings > CI/CD > Variables > GAME_API_KEY (masked)

How do I configure my project?

All project configuration lives in .game.yml at the root of your Flutter project:

name: my_game_package
version: 1.0.0

engines:
  unity:
    project_path: ../MyUnityProject
    export_path: ../MyUnityProject/Exports

    platforms:
      android:
        enabled: true
        target_path: android/unityLibrary
      ios:
        enabled: true
        target_path: ios/UnityFramework.framework

Run game config validate to check for errors and game config show to view the resolved configuration.

Cloud and Publishing

Is streaming supported?

Yes, Game Framework supports streaming for cloud-rendered game experiences. This allows users to run game content without downloading the full engine build to their device. See the Unity Overview documentation for details.

What gets published when I run game publish?

The game publish command uploads your Flutter package source along with compiled game artifacts (Unity/Unreal builds) for each enabled platform. The published package is tied to a workspace and can be consumed by other projects.

How do I authenticate with Game Framework Cloud?

You can authenticate in two ways:

1. Interactive login (for local development):

   game login

2. API key (for CI/CD and scripts):

   export GAME_API_KEY=your_api_key_here

After logging in, select a workspace with game workspace select.

Troubleshooting

Where can I get help?

• Common Errors - Solutions to frequent errors
• Debugging Guide - Verbose logging and diagnostic tools
• GitHub Issues - Report bugs
• GitHub Discussions - Ask questions
• Email support@gameframework.dev for direct support

My app crashes when the engine loads. What should I check?

1. Ensure you called UnityEnginePlugin.initialize() in main() before runApp()
2. Verify game sync completed successfully for your target platform
3. Check that the exported build matches the platform you are running on
4. Look at platform-specific logs (Xcode console for iOS, Logcat for Android)

See the Debugging Guide for more detail.