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
| Requirement | Notes |
|---|---|
| A Mac with macOS 13.3 or newer | Builds run on macOS 13.3 and later. Apple silicon is the tested configuration. |
| Xcode | Install it from the App Store, open it once and accept the license (sudo xcodebuild -license). |
| git-lfs | The repository stores binary files with Git LFS. |
| LunarG Vulkan SDK | Provides DXC, the shader compiler front end. Install it to ~/VulkanSDK (the newest version there is used) or set VULKAN_SDK. |
| Apple Metal shader converter | Converts 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:
- downloads the pinned .NET SDK (10.0.303, checksum-verified) into
~/.local/share/PlasmaBuild-SDKand keeps it for later rebuilds, - installs PlasmaBuild to
~/.local/share/PlasmaBuildand links~/.local/bin/plasmabuild, - adds
PATHandPLASMA_BUILD_DIRto your shell profiles.
| Option | Description |
|---|---|
--prefix <dir> | Install PlasmaBuild somewhere else. |
--bin-dir <dir> | Put the plasmabuild link somewhere else. |
--no-modify-path | Leave 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
| Problem | What to check |
|---|---|
plasmabuild is not found | Open 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 SDK | Install the LunarG Vulkan SDK to ~/VulkanSDK, or set VULKAN_SDK. |
| The Metal shader compiler fails to build | The Metal shader converter is missing from /usr/local. Install it or set METAL_SHADER_CONVERTER_DIR. |
| Xcode reports a license problem | Run sudo xcodebuild -license and accept it. |
| Binaries are x86_64 on an Apple silicon Mac | The terminal runs under Rosetta. Start the build with arch -arm64, or use a native terminal. |