RFC: CLI-driven Docker image builds — build-unity-image (and future engine variants)

[frostebite]

Context

From maintainer discussion on game-ci/unity-builder#771 — users need custom module combinations (e.g. Wwise requiring windows-mono + linux-il2cpp) that we don't pre-build. Currently, Docker images are built from static Dockerfiles with hardcoded module matrices in game-ci/docker. Users who need non-standard combinations must build their own images with limited guidance.

Proposal

Add game-ci build-unity-image — a CLI command that fully codifies the game-ci/docker build pipeline, including all version-specific patches, SDK setups, and platform conditionals.

game-ci build-unity-image ubuntu windows-mono,linux-il2cpp --unity-version 2022.3.20f1

Why Deep Integration Matters

This is not a thin wrapper. The generated Dockerfiles include every patch from game-ci/docker:

• 18 version-specific Ubuntu patches (IL2CPP fixes, WebGL deps, Android SDK setup across 4 generations, server module auto-install, etc.)
• Full Windows Dockerfile (multi-shell build, MSVCP DLLs, Git, PowerShell Android helpers, service config)

A user gets the exact same image our CI publishes. No missing dependencies, no subtle breakage from skipped patches.

Benefits

• Users can build any module combination without waiting for us to add it to the matrix
• No GameCI-hosted infra needed — users self-serve (GHCR is free for public repos)
• More contributors to CLI — image building is a CLI feature, not scattered Dockerfile knowledge
• Single source of truth — one tool defines how images are built
• Eventually our CI dogfoods this — same path for published images and custom ones

Phased Rollout

Phase 1: CLI build-unity-image ✅ (PR #46)

• Full Dockerfile generation with all patches
• Auto changeset resolution
• Custom tags, push support
• Ubuntu + Windows base OS support

Phase 2: Migrate game-ci/docker CI

• Replace workflow matrices with game-ci build-unity-image invocations
• Validate images are byte-identical to current builds
• Same published tags, same registry

Phase 3: User-facing ecosystem

• game-ci init generates image build steps in workflows
• Docs for common combinations (desktop, mobile, desktop+android)
• Consider reducing the hosted matrix once users can self-serve

No deprecation — existing pre-built images continue indefinitely. This adds capability.

Related

• PR: feat: add build-unity-image command for custom Unity Docker images #46
• Add support for specifying unity modules for builder to install unity-builder#771 — Unity modules feature request
• Add WebGL build support for windows to support web projects using wwise unity-builder#773 — WebGL on Windows gap
• docs: combined orchestrator documentation updates documentation#564 — Docs (includes custom images page)

cc @webbertakken @frostebite

[frostebite]

Syntax Direction

From @webbertakken's feedback, the UX should be as simple as:

jobs:
  build-image:
    name: Build linux × linux+windows
    runs-on: ubuntu-latest
    steps:
      - run: game-ci build-image ubuntu windows-mono,linux-il2cpp

Where the positional args are:

game-ci build-image [base-os] [module1,module2,...]

More examples

# Standard single-module (what we publish today)
game-ci build-image ubuntu android

# Desktop combo (Wwise/FMOD use case)
game-ci build-image ubuntu windows-mono,linux-il2cpp,mac-mono

# Desktop + mobile (Meta XR / Quest + PC)
game-ci build-image ubuntu windows-mono,linux-il2cpp,android

# Windows base with WebGL (issue #773)
game-ci build-image windows webgl

# With explicit version and push
game-ci build-image ubuntu windows-mono,linux-il2cpp \
  --unity-version 2022.3.20f1 \
  --tag ghcr.io/my-org/unity-editor:desktop \
  --push

What this replaces

Today in game-ci/docker, the workflow does:

matrix:
  targetPlatform:
    - base
    - linux-il2cpp
    - windows-mono
    - mac-mono
    - ios
    - android
    - webgl

With the CLI, that becomes:

strategy:
  matrix:
    modules: [base, linux-il2cpp, windows-mono, mac-mono, ios, android, webgl]
steps:
  - run: game-ci build-image ubuntu ${{ matrix.modules }}

Same output, but now users can add their own combos without forking the repo.

[frostebite]

Update: Command should be engine-scoped since the CLI supports multiple engines (Unity, Godot, Unreal):

game-ci build-unity-image ubuntu windows-mono,linux-il2cpp --unity-version 2022.3.20f1

This leaves room for future engine-specific image builders (build-godot-image, build-unreal-image) without overloading a generic command.

[frostebite]

Deep Integration Detail

Per @webbertakken's feedback — the generated Dockerfiles must include all platform-specific patches from game-ci/docker, not just the base module install. This means:

Ubuntu patches included:

• Server modules: Auto-install linux-server/windows-server for 2021.2.5+ when relevant modules present
• IL2CPP fixes: IL2CPP_ADDITIONAL_ARGS for 2019.3.x versions
• WebGL: python2 (2018-2021.1), brotli compression (2018-2020.1), GZip fix (2020.1-2020.2.1), ffmpeg
• Build tools: build-essential + clang for WebGL and linux-il2cpp
• Android SDK: Version-specific SDK setup (2018.x legacy, 2019+ modern, 2021+ cmdline tools, 6000+ platform-tools), license acceptance, symlink fixes for 2022.2+
• Mac-mono: x64arm64/x64ARM64 case symlink fix for 2021-2022
• Legacy deps: libnotify4/libunwind-dev/libssl1.0.0 for 2019.x
• IL2CPP: lld for 2021.x

Windows patches included:

• Windows-specific module installation via cmd shell
• Proper path handling for Windows containers

Result

A user running game-ci build-unity-image ubuntu windows-mono,linux-il2cpp --unity-version 2022.3.20f1 gets the exact same image they'd get from the game-ci/docker CI pipeline. No missing patches, no manual Dockerfile work.

Workflow example

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Build custom image with multiple modules
      - name: Build Unity image
        run: |
          game-ci build-unity-image ubuntu windows-mono,linux-il2cpp \
            --unity-version 2022.3.20f1 \
            --tag ghcr.io/${{ github.repository_owner }}/unity-editor:desktop

      # Use it for the build
      - uses: game-ci/unity-builder@v4
        with:
          customImage: ghcr.io/${{ github.repository_owner }}/unity-editor:desktop
          targetPlatform: StandaloneWindows64

PR: #46