gh-dev-gom-claude-code-marketplace-plugins-auto-release-manager/skills/references/unity-guide.md

Unity Project Version Management

Overview

Unity projects use a dual-file approach for version management:

1. version.json - Single source of truth (easy to read/edit)
2. ProjectSettings/ProjectSettings.asset - Auto-synced (used by Unity builds)

File Structure

MyUnityProject/
├── version.json                          # Primary source
├── ProjectSettings/
│   └── ProjectSettings.asset            # Auto-synced
└── Assets/
    └── ...

version.json (Primary)

Create this file at project root:

{
  "version": "1.2.3",
  "buildNumber": 42,
  "releaseDate": "2025-10-20"
}

Fields:

• version (required): Semantic version (MAJOR.MINOR.PATCH)
• buildNumber (optional): Incremental build number
• releaseDate (optional): Release date in YYYY-MM-DD format

ProjectSettings.asset (Auto-sync)

The bundleVersion field in this file is automatically synced from version.json:

PlayerSettings:
  bundleVersion: 1.2.3
  AndroidBundleVersionCode: 42
  buildNumber:
    iOS: 42

Workflow

Manual Update

1. Edit version.json:

   {
     "version": "1.3.0"
   }
   

2. Run sync script:

   python scripts/sync_unity_version.py
   

3. Commit both files:

   git add version.json ProjectSettings/ProjectSettings.asset
   git commit -m "chore: bump version to 1.3.0"
   

Automatic Update (with auto-release-manager)

The skill handles everything automatically:

1. Update version.json → 1.3.0
2. Sync to ProjectSettings.asset
3. Git commit both files
4. Create tag v1.3.0
5. Push to remote

Benefits of Dual-File Approach

✅ Easy Version Management

• version.json is simple JSON, easy to read/edit
• Clean git diffs

✅ Unity Integration

• ProjectSettings.asset is used by Unity builds
• Version automatically appears in build

✅ Automated Sync

• Scripts ensure consistency
• No manual errors

✅ Extended Metadata

• version.json can store additional info (buildNumber, releaseDate)
• ProjectSettings.asset only has bundleVersion

Common Issues

Q: Why not just use ProjectSettings.asset?

A: ProjectSettings.asset is a YAML file that's hard to read and edit manually. It also contains hundreds of other settings, making git diffs noisy.

Q: Can I use only version.json?

A: No. Unity reads bundleVersion from ProjectSettings.asset for builds. Both files are needed.

Q: What if files get out of sync?

A: Run python scripts/sync_unity_version.py to sync from version.json (source of truth) to ProjectSettings.asset.

Example: Version Update

Before:

// version.json
{
  "version": "1.2.3",
  "buildNumber": 42
}

After:

// version.json
{
  "version": "1.3.0",
  "buildNumber": 43
}

Auto-synced:

# ProjectSettings.asset
PlayerSettings:
  bundleVersion: 1.3.0  # ← Automatically updated