Skip to main content
Version: Next (dev)

Building For macOS

This guide builds the engine and editor on a Mac from an engine source checkout. The Mac build uses Apple Clang and the Metal renderer. Run the commands below in Terminal from the engine repository root.

Prerequisites​

RequirementNotes
A Mac with macOS 13.3 or newerBuilds run on macOS 13.3 and later. Apple silicon is the tested configuration.
XcodeInstall it from the App Store, open it once and accept the license (sudo xcodebuild -license).
git-lfsThe repository stores binary files with Git LFS.
LunarG Vulkan SDKProvides DXC, the shader compiler front end. Install it to ~/VulkanSDK (the newest version there is used) or set VULKAN_SDK.
Apple Metal shader converterConverts compiled shaders to Metal. Its installer puts it in /usr/local. Set METAL_SHADER_CONVERTER_DIR (a folder with include/ and lib/) if it is elsewhere.

You don't need to install .NET yourself. The setup script downloads the .NET SDK that PlasmaBuild needs.

Install PlasmaBuild​

./Setup.sh

On macOS, Setup.sh builds PlasmaBuild from Utilities/PlasmaBuild, so it matches the build rules of your checkout. It:

  1. downloads the pinned .NET SDK (10.0.303, checksum-verified) into ~/.local/share/PlasmaBuild-SDK and keeps it for later rebuilds,
  2. installs PlasmaBuild to ~/.local/share/PlasmaBuild and links ~/.local/bin/plasmabuild,
  3. adds PATH and PLASMA_BUILD_DIR to your shell profiles.
OptionDescription
--prefix <dir>Install PlasmaBuild somewhere else.
--bin-dir <dir>Put the plasmabuild link somewhere else.
--no-modify-pathLeave your shell profiles unchanged.

Open a new terminal and check the installation:

plasmabuild --version

Run ./Setup.sh again after pulling changes to PlasmaBuild.

Generating an Xcode Workspace​

./GenerateWorkspace_xcode.sh

The script runs:

plasmabuild generate workspace --workspace PlasmaEngine --ide xcode

and writes PlasmaEngine.xcworkspace to the repository root. The project files live in Intermediate/ProjectFiles/Xcode. Building in Xcode runs PlasmaBuild, so Xcode and the command line produce the same binaries. A single target's project can be generated with plasmabuild generate project --ide xcode.

VS Code, Rider and CMake workspaces are also available on macOS through GenerateWorkspace_vscode.sh, GenerateWorkspace_rider.sh and GenerateWorkspace_cmake.sh.

Building​

Build the editor:

plasmabuild build PlasmaEditor -p Mac -c Development

Binaries are written to Binaries/Mac_<Configuration>, for example Binaries/Mac_Development. Launch the editor from there:

./Binaries/Mac_Development/PlasmaEditor

The Player, ShaderCompiler and the other tools build the same way (plasmabuild build Player -p Mac -c Development). The Mac Player ships with the Metal renderer and the Metal shader compiler.

Troubleshooting​

ProblemWhat to check
plasmabuild is not foundOpen a new terminal after Setup.sh, or run it with --bin-dir pointing at a folder on your PATH. GenerateWorkspace_xcode.sh also looks in PLASMA_BUILD_DIR and ~/.local/bin.
DXC for macOS comes from the Vulkan SDKInstall the LunarG Vulkan SDK to ~/VulkanSDK, or set VULKAN_SDK.
The Metal shader compiler fails to buildThe Metal shader converter is missing from /usr/local. Install it or set METAL_SHADER_CONVERTER_DIR.
Xcode reports a license problemRun sudo xcodebuild -license and accept it.
Binaries are x86_64 on an Apple silicon MacThe terminal runs under Rosetta. Start the build with arch -arm64, or use a native terminal.

See Also​