Smart Unity Tool

Execute Unity Editor commands, asset operations, and project management tasks from the command line.

When to Use This Command

Run this command when you need to:

• Run Unity Editor batch mode operations (builds, asset imports, tests) without opening the GUI
• Execute custom Unity Editor scripts for asset processing, scene management, or project configuration
• Manage Unity project settings, packages, and platform configurations from the terminal

Consider alternatives when:

• You need visual scene editing or layout work that requires the Unity Editor GUI
• Your task involves real-time game debugging that needs the Unity profiler

Quick Start

Configuration

Copy
name: smart-unity-tool
type: command
category: game-development

Example Invocation

Copy
claude command:run smart-unity-tool --action build --target ios --config release

Example Output

Unity Project: MyGame (2023.3.1f1)
Action: Build
Target: iOS (ARM64)
Configuration: Release

Unity Editor Batch Mode:
  [+] Project opened in batch mode
  [+] Script compilation: 0 errors, 2 warnings
  [+] Addressable assets built: 184 bundles
  [+] Player settings validated for iOS
  [+] Xcode project generated

Build Details:
  Output: builds/ios/MyGame.xcodeproj
  Scenes included: 24
  Managed code size: 12.4 MB
  Asset size: 287 MB
  Build time: 6m 15s

Next steps:
  1. Open Xcode project: open builds/ios/MyGame.xcodeproj
  2. Configure signing team in Xcode
  3. Build and archive for TestFlight

Core Concepts

Unity CLI Operations Overview

Aspect	Details
Batch Mode	Run Unity Editor headlessly for builds, tests, and automation
Editor Scripts	Execute custom C# scripts via -executeMethod parameter
Package Manager	Install, update, and remove UPM packages from command line
Asset Operations	Import, process, and validate assets without GUI interaction
Platform Switching	Configure build target and player settings per platform

Unity Command Workflow

  Command Request
       |
       v
  +-------------------+
  | Locate Unity      |---> Find installed Unity version
  +-------------------+
       |
       v
  +-------------------+
  | Open Batch Mode   |---> -batchmode -nographics
  +-------------------+
       |
       v
  +-------------------+
  | Execute Action    |---> Build / Test / Import / Script
  +-------------------+
       |
       v
  +-------------------+
  | Parse Output      |---> Errors, warnings, results
  +-------------------+
       |
       v
  +-------------------+
  | Report Results    |---> Build path, test results, logs
  +-------------------+

Configuration

Parameter	Type	Default	Description
action	string	build	Unity action: build, test, import, run-script, refresh-packages
target	string	current	Build target: ios, android, windows, macos, webgl, linux
config	string	development	Build configuration: debug, development, release
method	string	none	Custom editor method to execute (for run-script action)
unity_version	string	auto-detect	Unity version to use from installed versions

Best Practices

1. Use Batch Mode for CI Builds - Running Unity with -batchmode -nographics skips the GUI and enables automated builds. This is essential for CI/CD pipelines where no display server is available.

2. Pin Unity Version in Project - Store the required Unity version in ProjectSettings/ProjectVersion.txt and enforce it in CI. Version mismatches between developers cause serialization conflicts and hard-to-debug issues.

3. Separate Build Scripts from Game Code - Place Editor scripts in an Editor assembly definition so they are excluded from player builds. Build automation code should never ship in the final game binary.

4. Cache Library Folder in CI - The Library folder contains imported asset caches. Caching it between CI runs avoids reimporting thousands of assets on every build, reducing build times from hours to minutes.

5. Log Build Results Structured - Output build results as structured JSON rather than Unity's default log format. Structured output is easier to parse for CI status reporting and artifact tracking.

Common Issues

1. License Activation Fails in CI - Unity requires an activated license to run in batch mode. Use Unity's serial-based activation for CI environments and store the license file (.ulf) as a CI secret.

2. Build Fails With Missing References - Scripts reference assemblies or assets that exist in the Editor but not in the build. Verify that all referenced assets are included in the build and that Editor-only code is guarded with UNITY_EDITOR preprocessor directives.

3. Batch Mode Hangs Without Output - Unity batch mode can hang on dialogs or import prompts that require user interaction. Add -quit flag and set a timeout in the CI job to prevent indefinite hangs.