Moonlight Ember

Getting Started

Build Metrics helps you track Unity build performance and catch regressions before they reach production. Monitor build time, size, and detect issues automatically.

✅ Offline-first by default

Works fully offline with no account required. You can connect an API key later if you want cloud dashboards and alerts.

Features

⏱️

Automatic build time tracking

Track how long your builds take

📊

Build size monitoring

Track size trends over time

🎮

Multi-platform support

Android, iOS, Windows, macOS, Linux, WebGL

🚨

Regression detection

Get alerts when builds slow down or grow

🔄

CI/CD integration

Works with any platform - just add 2 lines to your workflow

🎁

Offline mode

Works without any account or internet

Privacy & Data

What can be sent (cloud mode)

• Build size, build time, platform, Unity version
• File/asset breakdown (Unity 2022.2+)
• Optional Git info (commit, branch)

What is NOT sent

• Source code
• Asset files
• User content

Requirements

🎯

Unity 2020.3 LTS or newer

All LTS and stable versions

💻

Windows, macOS, or Linux

All platforms supported

⚙️

.NET Standard 2.1

Built-in with Unity

🌐

Internet connection (optional)

Only needed for cloud sync

Installation

Choose your preferred installation method. Both options work identically, with the same features and updates.

📋 Prerequisites

• Unity 2020.3 LTS or newer
• Git installed (for Method A only)
• Internet connection

Method A: Git URL (Recommended)

✓ Automatic Updates • ✓ Faster Setup • ✓ No Downloads

Install directly via Unity Package Manager. This method automatically pulls updates when you restart Unity or manually refresh packages.

Open Unity Package Manager
Window → Package Manager
Add package from Git URL
Click + button (top-left) → Add package from git URL...
Paste this URL:
https://github.com/Alexartx/UnityBuildMetricsPlugin.git#upm
💡 The #upm suffix ensures you get the package-manager-compatible version
Click "Add"
Unity will download and install the plugin automatically. This may take a minute.
Verify installation
You should see "Build Metrics" in the Package Manager list. Go to Tools → Build Metrics → Setup Wizard to configure.

Method B: Unity Package File

✓ Offline Install • ✓ No Git Required • ✓ Traditional Method

Download a .unitypackage file and import manually. This method works offline but requires manual updates.

Download the latest release
Download .unitypackage →
This will take you to GitHub Releases. Download the BuildMetrics.unitypackage file.
Import into Unity
Assets → Import Package → Custom Package...
Select the downloaded file
Navigate to your Downloads folder and select BuildMetrics.unitypackage
Import all files
Unity will show an import dialog. Click Import to add all plugin files to your project.
Verify installation
You should see a BuildMetrics folder in your Assets. Go to Tools → Build Metrics → Setup Wizard to configure.

⚠️ Updating the Plugin

Method A (Git URL): Unity checks for updates automatically. You can also right-click the package in Package Manager and select "Update"
Method B (.unitypackage): Download the latest release and import again. Unity will overwrite old files.

📦 What's Included

• Build event hooks (automatic tracking)
• Setup wizard for API key configuration
• Settings editor for customization
• Manual upload tools
• CI/CD environment variable support

Quick Start

⚡ Get up and running in under 5 minutes

Follow these 3 simple steps to start tracking your Unity builds

Offline Quick Start (No Account)

Install the plugin
Build your project once
Open Tools → Build Metrics to view results

Get Your API Key

Sign up at app.buildmetrics.moonlightember.com
Create a project
Click "Copy API Key" button in the dashboard

💡 Pro Tip: Auto-Detection

After copying your API key, the Unity Setup Wizard will automatically detect it from your clipboard!

Configure the Plugin

In Unity, go to: Tools → Build Metrics → Setup Wizard
If prompted, click "Use This Key" (auto-detected from clipboard)
Or manually paste your API key if needed
Click "Complete Setup"

Build Your Project

Build your project as usual. Metrics are sent automatically after each build!

File → Build Settings → Build

File → Build Settings → Build And Run

View your build metrics in the dashboard →

Configuration

Access settings: Tools → Build Metrics → Settings

Available Settings

API Key

Your unique identifier for optional cloud dashboards and alerts

Default: Empty (offline mode only)

Format: bm_xxxxx...

Auto Upload

Automatically upload build metrics to cloud after each successful build

Default: Enabled

Options: Enabled / Disabled

Manual Upload Options

If you disable auto-upload, use these menu options to upload manually:

Upload Last Build

Upload only the most recent build to cloud

Tools → Build Metrics → Upload Last Build

Upload All Pending

Upload all locally stored builds that haven't been synced yet

Tools → Build Metrics → Upload All Pending

What Gets Tracked?

✓ All Builds

Basic Metrics

• Build time (seconds)
• Build size (bytes)
• Platform (Android, iOS, Windows, macOS, Linux, WebGL)
• Unity version
• Build timestamp
• Development build flag
• Scripting backend (Mono, IL2CPP)
• Artifact type (APK, AAB, IPA, EXE, etc.)
• Build configuration

✓ Optional - If Git Available

Git Information

Automatically captured if Git is installed and project is in a Git repository

• Commit SHA (short hash)
• Commit message
• Branch name
• Dirty status (uncommitted changes)

✓ Unity 2022.2+

File Breakdown

Detailed analysis of build content (Unity 2022.2 or newer)

• Category breakdown (Scripts, Resources, Streaming Assets, Plugins, Scenes, Shaders, Other)
• Top 20 largest files with sizes and categories
• File size distribution analysis

Note: Works on all platforms including Android and WebGL on Unity 2022.2+. Earlier versions support iOS and Standalone only.

CI/CD Integration

Build Metrics works seamlessly in CI/CD pipelines. Set your API key via command line arguments or environment variables and metrics upload automatically.

GitHub Actions →

Complete guide with GameCI integration, Unity license setup, and multi-platform builds

Self-Hosted Runners →

Use your own build machines with custom Unity setups and build profiles

Other CI/CD Platforms

📌 Already have a CI/CD workflow?

Just add 2 lines to your existing setup. Here's what to add for popular platforms:

⚠️ First: Add Your API Key as a Secret

Before using these examples, add BUILD_METRICS_API_KEY to your CI platform's secrets/variables:

• GitHub: Settings → Secrets and variables → Actions
• GitLab: Settings → CI/CD → Variables
• Jenkins: Credentials → Add Credentials
• CircleCI: Project Settings → Environment Variables

GitLab CI

yaml

# Add to your existing .gitlab-ci.yml

variables:
  BUILD_METRICS_API_KEY: $BUILD_METRICS_API_KEY  # ← Add this

build:
  script:
    - unity-editor \
        -batchmode \
        -buildTarget Android \
        -BUILD_METRICS_API_KEY $BUILD_METRICS_API_KEY  # ← Add this

Replace unity-editor with your Unity CLI path.

Jenkins

groovy

// Add to your existing Jenkinsfile

environment {
  BUILD_METRICS_API_KEY = credentials('build-metrics-api-key')  // ← Add this
}

stage('Build') {
  sh """
    unity-editor -batchmode \
      -buildTarget Android \
      -BUILD_METRICS_API_KEY ${BUILD_METRICS_API_KEY}  // ← Add this
  """
}

Replace unity-editor with your Unity CLI path.

CircleCI

yaml

# Add to your existing .circleci/config.yml

jobs:
  build:
    environment:
      BUILD_METRICS_API_KEY: ${BUILD_METRICS_API_KEY}  # ← Add this
    steps:
      - run: |
          unity-editor -batchmode \
            -buildTarget Android \
            -BUILD_METRICS_API_KEY $BUILD_METRICS_API_KEY  # ← Add this

Replace unity-editor with your Unity CLI path.

Unity Cloud Build

Add to Build Target settings:

Environment Variable: BUILD_METRICS_API_KEY = your_api_key

Metrics upload automatically after build completes

✓ Works with any CI/CD platform

• Add 2 lines to your existing workflow
• No code changes in Unity required
• Metrics upload automatically

Configuration Variables

BUILD_METRICS_API_KEY

Your API key (required)

BUILD_METRICS_API_URL

Custom API endpoint (optional, for self-hosted)

📚 More Resources

Features

Build Metrics includes powerful features for tracking, analyzing, and getting notified about your Unity builds.

🏠 Offline Mode →

Track builds locally without internet connection

• Stores last 10 builds locally
• View metrics in Unity Editor
• Export to JSON
• Free forever

🔔 Webhooks & Alerts →

Get notified about build regressions in real-time

• Slack integration
• Discord integration
• Custom webhooks
• Configurable thresholds

What Gets Tracked?

Basic Metrics

Build time (seconds)
Build size (bytes)
Platform (Android, iOS, etc.)
Unity version
Development vs Release
Scripting backend
Artifact type

Advanced Features

Git commit tracking
Branch information
File breakdown (Unity 2022.2+)
Top 20 largest files
Category analysis
Trend charts
Regression detection

iOS size note

On iOS, Build Metrics reports Xcode project size by default. To track final IPA size, export an IPA and upload the size in a post-export step.

API Reference

Build Metrics provides a simple REST API for submitting build metrics programmatically. The Unity plugin uses this API automatically, but you can also integrate it with custom build systems.

✓ Auto-integrated in Unity plugin✓ Custom build systems supported

REST API Endpoint

http

POST https://buildmetrics-api.onrender.com/api/builds

Headers

http

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request Body

json

{
  "platform": "Android",
  "buildTimeSeconds": 120,
  "outputSizeBytes": 52428800,
  "unityVersion": "2021.3.0f1",
  "timestamp": "2026-01-04T12:00:00Z",
  "status": "success",
  "developmentBuild": false,
  "scriptingBackend": "IL2CPP"
}

Response

json

{
  "ok": true,
  "buildId": "build_abc123",
  "message": "Build metrics recorded successfully"
}

Error Responses

Status	Meaning
`400`	Invalid request body
`401`	Invalid or missing API key
`402`	Quota exceeded - upgrade plan
`500`	Server error

Troubleshooting

🔧 Common Issues & Solutions

Find quick solutions to the most common Build Metrics issues

❌ "Invalid API key" error

• Check that your API key is correct in settings
• Cloud mode only: verify your API key is valid
• Ensure API key starts with bm_
• Get a new key from dashboard →

📊 Metrics not appearing in dashboard

• Check Unity console for errors
• Verify internet connection
• Check firewall/proxy settings
• Try manual upload: Tools → Build Metrics → Upload Last Build
• Check build succeeded (failed builds are not uploaded)

⚠️ Build fails with Build Metrics installed

• Check Unity console for specific errors
• Disable auto-upload temporarily
• Verify Unity version is 2020.3 or newer
• Check for conflicting plugins

🔄 CI/CD builds not uploading

• Verify BUILD_METRICS_API_KEY environment variable is set
• Check CI logs for Build Metrics errors
• Ensure build machine has internet access
• Verify API key is not expired

💬 Still Need Help?

Can't find a solution? We're here to help you get Build Metrics working:

📧 Email Support

support@moonlightember.com

🐛 GitHub Issues

Report a bug or request a feature

📈 Dashboard

Check service status

Build Metrics Documentation

Getting Started

Features

Automatic build time tracking

Build size monitoring

Multi-platform support

Regression detection

CI/CD integration

Offline mode

Privacy & Data

Requirements

Installation

Method A: Git URL (Recommended)

Method B: Unity Package File

Quick Start

Get Your API Key

Configure the Plugin

Build Your Project

Configuration

Available Settings

Manual Upload Options

What Gets Tracked?

Basic Metrics

Git Information

File Breakdown

CI/CD Integration

GitHub Actions →

Self-Hosted Runners →

Other CI/CD Platforms

GitLab CI

Jenkins

CircleCI

Unity Cloud Build

Configuration Variables

Features

🏠 Offline Mode →

🔔 Webhooks & Alerts →

What Gets Tracked?

Basic Metrics

Advanced Features

API Reference

REST API Endpoint

Headers

Request Body

Response

Error Responses

Troubleshooting

❌ "Invalid API key" error

📊 Metrics not appearing in dashboard

⚠️ Build fails with Build Metrics installed

🔄 CI/CD builds not uploading

💬 Still Need Help?