macOS
The editor, the tools and exported games run on macOS, rendering through Apple's Metal. This page covers what is different on a Mac: the editor's window conventions, the renderer, exporting for macOS and Android from a Mac, and packages with macOS binaries. To build the engine on a Mac, see Building for macOS.
The Editor on macOS
The editor follows the Mac conventions:
- The menus (File, Edit, Project and so on) are in the macOS menu bar at the top of the screen, not in the window.
- The window buttons (the "traffic lights" for close, minimize and zoom) are at the left of the editor's title bar.
- Command takes the place of Ctrl in every shortcut. A shortcut written as
Ctrl+Shift+Sin this manual isCommand+Shift+Son a Mac.
The editor's viewports are rendered by the engine process as on Windows and Linux, and show up in the editor windows as native Metal layers. File watching, downloads (for example in the Package Manager) and editor plugins work as on the other desktops.
When you open a project on a Mac that has no macOS asset profile, the editor adds one (target platform OSX), so assets can be transformed for the Mac.
Metal Renderer
On macOS the engine renders with Metal by default. The Metal backend supports bindless resources, multithreaded command recording, MSAA, ray tracing (acceleration structures, inline ray queries and ray tracing pipelines), mesh shaders, async compute and shared textures between processes.
| Where | How to choose the renderer |
|---|---|
| Editor | Preferences > General > Renderer (Restart Required): Default (Metal on macOS), Metal or Vulkan. Restart the editor to apply it. |
| Player and tools | The -renderer command-line option, for example -renderer Metal. It also overrides the editor preference for one session. |
Shaders are compiled for Metal by converting the DirectX shader output with Apple's Metal shader converter. That converter only runs on macOS, so Metal shader caches are built on a Mac.
Exporting from a Mac
Project > Export Project... on a Mac offers only the platforms a Mac can export:
| Platform | From a Mac |
|---|---|
| macOS | Yes. |
| Android | Yes. |
| Windows, Linux | No: export them from a Windows or Linux computer. |
The dialog shows the platform as macOS (asset profiles call it OSX). If a project's active profile targets a platform the Mac cannot export, for example a Windows project opened on a Mac, the dialog starts on the macOS card instead.
macOS export
A macOS export takes its binaries from Binaries/Mac_<Configuration>. Build the Player for the selected configuration first (plasmabuild build Player -p Mac -c Development). The export reads the load commands of the Player, the runtime plugins and the renderers and ships exactly the .dylib libraries and executables they need. Executables on macOS have no file extension, so nothing else from the binaries folder ships unless a ProjectBinaries.plExportFilter entry includes it on purpose. Files included that way bring their own dependencies along.
The result has the same layout as on the other desktops: Bin/Player starts the game. See Project Export.
Android from a Mac
Android export works from a Mac like from Windows. The editor finds:
- the Android SDK in
ANDROID_HOME,ANDROID_SDK_ROOTor Android Studio's default~/Library/Android/sdk, - the JDK in
JAVA_HOME, Android Studio's bundled runtime (/Applications/Android Studio.app/Contents/jbr/Contents/Home) or/usr/libexec/java_home, - the NDK's macOS toolchain.
See Android for the requirements and the workflow.
Packages and C++ Projects on macOS
Packages can ship macOS binaries in a runtime-macos64 component, with libraries in Bin/Mac_x64_<Configuration> (the folder name is used for Apple silicon too). Each platform's components carry their own ABI tag, and on a Mac the engine checks the macOS tag. See Packages.
C++ projects use Clang on macOS, and the project's plugin builds into the project's Bin folder as on the other platforms. See Sharing C++ Projects.
Limitations
- Windows and Linux builds cannot be exported from a Mac.
- macOS builds cannot be exported from Windows or Linux, because Metal shaders compile only on a Mac.