SuperAPI AI Directory

ue5-macos-apple-silicon

Coding & development

View repository

Updated 10-22 20:40

About this skill

UE5 on macOS and Apple Silicon

UE5 material defaults to Windows. Validation scripts are PowerShell, build commands are Build.bat, and performance advice assumes tooling that does not exist here. On a Mac, following it produces confident, wrong instructions.

The engine's macOS support is real and has improved substantially — but "supported" and "identical to Windows" are different claims, and the gap is where a week disappears.

Discover before you build

  1. Never assume the engine path or version. Launcher installs, source builds, and multiple side-by-side versions all coexist on Macs. Run the discovery sequence in references/environment-audit.md and write the results into the project context file (ue5-project-context).
  2. Establish the Xcode situation. Xcode version, whether command line tools are selected, and whether the license has been accepted. A failed build here reports as a compiler error with no mention of licensing, which is why it costs so much time.
  3. Decide the architecture target early: arm64 only, or a universal binary. This changes build time, package size, and the flags in every command afterward. See references/build-and-package.md.
  4. Establish what Metal will actually give you on this chip and this macOS version, before designing around a rendering feature. See references/metal-feature-reality.md. Feature availability depends on both the chip generation and the OS version, and the failure mode is silent fallback, not an error.
  5. Fix the profiling toolchain now, not at optimization time. Several Windows-standard tools have no macOS equivalent; know which ones you have before you need them. See references/profiling-on-mac.md.
  6. Translate Windows instructions rather than following them. Keep the translation table in references/windows-to-mac.md at hand when reading any other skill pack.
  7. Record every command that succeeded, with its absolute path and date. On macOS the paths contain spaces and version numbers; a remembered command is a broken command.

Load only what applies:

Required answer format

Return:

  1. Machine facts — chip, memory, macOS version, disk free, each with the command that produced it.
  2. Toolchain facts — engine version and path, Xcode version, CLT selection, license status, with commands.
  3. Architecture decision — arm64 or universal, with the reason.
  4. Verified commands — build editor, build game, cook, package, run tests. Absolute paths, with the date each last succeeded.
  5. Metal feature findings — for each rendering feature the project depends on: available, unavailable, or unverified, with how you checked.
  6. Profiling plan — which tools you have, and what evidence you will collect.
  7. Gaps — anything that needs a human (license acceptance, an install, a signing identity), stated as the shortest possible action list.

Hard rules

  • Never write a Build.bat, .sln, Visual Studio, DirectX, or PIX instruction into a macOS project's documentation. If a source skill says that, translate it and note the translation.
  • Never claim a Windows build exists unless it was built on a Windows machine. "Source-level compatible" and "builds" are different claims; write not built and mean it.
  • Quote every path. Engine paths on macOS routinely contain spaces (/Users/Shared/Epic Games/UE_5.x/), and an unquoted path fails in a way that looks like a missing file.
  • Do not design around a rendering feature that has not been verified in a packaged build on the target hardware. Editor behavior is not proof; the editor can run a different feature level than a shipped build.
  • Silent fallback is the dominant macOS failure mode. A feature that is unavailable often produces a plausible, lower-quality image rather than an error. Verify by looking at actual output and reported feature level, not by absence of errors.
  • Do not run performance comparisons in the editor. Editor overhead on macOS is significant and varies with what panels are open; package and measure, or the numbers mean nothing.
  • Do not add a signing or notarization step to a development build. It is a separate, credential-bearing workflow and belongs to a shipping phase, not to a vertical slice.

Verification

  • Clean build. Delete Intermediate/, Binaries/, and DerivedDataCache/ for the project, then build the editor target from the command line. A build that only works incrementally is not a build.
  • Packaged launch. Package a Development build, launch it from Finder and from the command line, and record the app bundle path, size, and SHA-256.
  • Architecture check. Run lipo -archs (or file) on the packaged binary and confirm it contains exactly the architectures you intended.
  • Feature-level receipt. In the packaged build, capture the log lines reporting RHI and feature level. This is the artifact that settles later arguments about what was actually running.
  • Frame-rate baseline. Packaged build, fixed resolution and quality, fixed camera path, recorded median and 1% low. Repeat after every significant rendering change.

Scope

Not covered: iOS/tvOS/visionOS targets, code signing, notarization, App Store submission, Windows cross-compilation (it does not work — you need a Windows machine), and Rosetta workflows for Intel-only dependencies.