game init

Initialize a new .game.yml configuration file for your Game Framework project.

Usage

game init [options]

The init command creates a new .game.yml configuration file in your current directory with default settings for Unity or Unreal Engine integration. This file defines your project structure, engine paths, export settings, and platform configurations.

Options

Option	Description	Default
`--engine`	Engine type to configure (unity or unreal)	(interactive prompt)
`--project-path`	Path to engine project	(interactive prompt)
`--force`, `-f`	Overwrite existing .game.yml	false
`--minimal`	Create minimal configuration	false

Interactive Mode

When run without options, init enters interactive mode with arrow key navigation:

game init

You'll be prompted for:

Engine Type: Unity or Unreal Engine
Project Path: Path to your engine project
Export Path: Where to export builds (default: project_path/Exports)
Platforms: Which platforms to enable

Interactive mode provides helpful defaults and validates paths as you enter them.

Generated Configuration

Unity Configuration

name: my_game_package
version: 1.0.0
description: A Flutter package with Unity integration

engines:
  unity:
    project_path: ../MyUnityProject
    export_path: ../MyUnityProject/Exports
    
    platforms:
      android:
        enabled: true
        target_path: android/unityLibrary
        min_sdk_version: 22
        target_sdk_version: 33
      
      ios:
        enabled: true
        target_path: ios/UnityFramework.framework
        min_version: "12.0"
      
      macos:
        enabled: false
        target_path: macos/UnityFramework.framework
      
      windows:
        enabled: false
        target_path: windows/unity
      
      linux:
        enabled: false
        target_path: linux/unity

Unreal Configuration

name: my_game_package
version: 1.0.0
description: A Flutter package with Unreal Engine integration

engines:
  unreal:
    project_path: ../MyUnrealProject
    export_path: ../MyUnrealProject/Builds
    project_file: MyProject.uproject
    
    platforms:
      android:
        enabled: true
        target_path: android/app/src/main
        architecture: arm64
      
      ios:
        enabled: true
        target_path: ios/UnrealFramework.framework
      
      macos:
        enabled: false
        target_path: macos/UnrealFramework.framework
      
      windows:
        enabled: false
        target_path: windows/unreal
      
      linux:
        enabled: false
        target_path: linux/unreal

Examples

Basic Initialization

# Interactive mode
game init

Unity Project

# Initialize with Unity
game init --engine unity --project-path ../MyUnityProject

Unreal Project

# Initialize with Unreal Engine
game init --engine unreal --project-path ../MyUnrealProject

Force Overwrite

# Overwrite existing .game.yml
game init --force

Minimal Configuration

# Create minimal config (only Android and iOS)
game init --minimal

Configuration Sections

Project Metadata

name: my_game_package        # Package name
version: 1.0.0               # Semantic version
description: My game package # Package description

Engine Settings

engines:
  unity:                     # or 'unreal'
    project_path: ../path    # Path to engine project
    export_path: ../exports  # Where builds are exported

Platform Configuration

Each platform has:

enabled: Whether to build for this platform
target_path: Where to sync files in Flutter project
Platform-specific settings (SDK versions, architectures, etc.)

Publishing Configuration (Optional)

publishing:
  registry: https://registry.gameframework.dev
  workspace_id: ws_abc123

After Initialization

Once .game.yml is created, you can:

Customize the configuration - Edit platform settings, paths, versions
Add an engine - If you didn't specify one during init
Export your game - Start the export workflow
Validate configuration - Check for errors

Configuration Best Practices

Path Configuration

Use relative paths for portability:

# Good - relative paths
project_path: ../MyUnityProject
export_path: ../MyUnityProject/Exports

# Avoid - absolute paths
project_path: /Users/john/Projects/MyUnityProject

Version Control

Add .game.yml to version control, but exclude sensitive data:

# Keep .game.yml
!.game.yml

# Exclude CLI config with credentials
.game/config.yml

Platform Selection

Enable only platforms you actively develop for:

platforms:
  android:
    enabled: true   # Active development
  ios:
    enabled: true   # Active development
  macos:
    enabled: false  # Not needed yet

Validation

After creating .game.yml, validate it:

# Check for errors
game config validate

# View current config
game config show

If .game.yml already exists, use --force to overwrite. Otherwise, the command will fail to prevent accidental overwrites.

Troubleshooting

File Already Exists

Error: .game.yml already exists

Solution: Use --force to overwrite or manually edit the existing file

game init --force

Invalid Project Path

Error: Project path does not exist

Solution: Verify the path exists or create the directory first

# Check if path exists
ls ../MyUnityProject

# Create directory if needed
mkdir -p ../MyUnityProject

# Try again
game init --engine unity --project-path ../MyUnityProject

Permission Denied

Error: Permission denied writing .game.yml

Solution: Check directory permissions

# Check permissions
ls -la .

# Fix permissions if needed
chmod u+w .

Configuration Schema

The CLI includes JSON Schema validation for .game.yml:

Schema File: Available in game-cli repository
VS Code Extension: Provides autocomplete and validation
Validation: Run game config validate

Install the Game Framework VS Code extension for .game.yml autocomplete and inline validation!

game add - Add engine to existing project
game config show - View configuration
game config validate - Validate configuration
game export - Export game builds

Next Steps

After initializing your configuration:

Validate your setup with game config validate
Export your game with game export unity --platform android
Sync files to Flutter with game sync unity --platform android
Build your app with game build android

On this page