macOS

Purpose

platform/macos/ is the macOS platform layer. It ships an OS_MacOS subclass, a Cocoa / AppKit DisplayServer, Metal-aware rendering context creation, audio via CoreAudio, joypads via GameController.framework / IOHIDManager, and the .app bundle exporter with codesigning + notarization support.

Layout

platform/macos/
├── godot_main_macos.mm                 NSApplication entry
├── os_macos.{mm,h}                     OS_MacOS subclass
├── display_server_macos.{mm,h}         Cocoa/AppKit + Metal/Vulkan/GL context creation
├── godot_application.mm                Custom NSApplication subclass (handles Quit / Open Files)
├── godot_application_delegate.mm       Lifecycle + menu/dock events
├── godot_window.mm, godot_window_delegate.mm   NSWindow + delegate
├── godot_view.mm, godot_view_renderer.{mm,h}   Custom NSView (CAMetalLayer host)
├── godot_open_save_delegate.mm         File dialog delegate
├── godot_status_item.{mm,h}            Status bar (menu-bar) icons
├── godot_button_view.mm                Custom title bar button (when needed)
├── crash_handler_macos.{mm,h}          MachException-based crash handler
├── joypad_macos.{mm,h}                 GameController.framework + IOHIDManager joypads
├── tts_macos.{mm,h}                    NSSpeechSynthesizer TTS
├── key_mapping_macos.mm                macOS keycode ↔ Godot keycode mapping
├── dir_access_macos.{mm,h}             Sandboxed file access helpers
├── export/                             .app bundle + codesign + notarize + DMG packaging
└── detect.py

The .mm extension is Objective-C++ so the engine can call AppKit APIs directly from C++.

Display server

DisplayServerMacOS uses Cocoa under the hood:

• Each Window node maps to an NSWindow plus a custom GodotWindow subclass.
• The window's content view is a GodotView (an NSView) hosting a CAMetalLayer — this is the layer the Metal driver renders into.
• Vulkan via MoltenVK uses the same CAMetalLayer (MoltenVK translates Vulkan to Metal).
• OpenGL 3.3 (compatibility renderer on Intel macs) uses an NSOpenGLContext when chosen; modern Apple Silicon defaults to Metal.
• Native menus are exposed via DisplayServer::global_menu_* so games can show macOS-style top-bar menus.
• File and save dialogs use NSSavePanel / NSOpenPanel with sandbox-aware delegates.
• IME composition and emoji/symbol palettes work via NSTextInputClient.
• Drag-and-drop, services menu integration, full-screen mode (with separate Spaces), and Universal Access settings are wired through standard AppKit paths.

OS_MacOS

OS_MacOS integrates with macOS conventions:

• Default user data dir: ~/Library/Application Support/Godot/.
• Config dir: ~/Library/Application Support/Godot/ (Godot follows the macOS convention of grouping config under Application Support).
• Process management via NSTask.
• Locale detection from the user's preferred languages (NSLocale).
• Log routing via os_log for system console visibility.

Rendering and Apple Silicon

• Metal is the primary backend. The driver is under drivers/metal/ and is shared with iOS.
• Vulkan runs via MoltenVK, which is vendored under thirdparty/. It translates Vulkan calls to Metal at runtime, so the same RenderingDevice path can run on macOS.
• OpenGL 3.3 (Compatibility) is supported but deprecated on macOS by Apple; it remains functional for legacy projects.

Apple Silicon vs Intel: builds support arch=x86_64, arch=arm64, or universal binaries (scons platform=macos arch=universal produces a fat binary).

Joypad

joypad_macos.mm uses GameController.framework on macOS 10.15+ for MFi-certified controllers (PlayStation DualSense, Xbox Wireless via Bluetooth, MFi pads). IOHIDManager is the fallback for non-MFi USB pads.

Audio

• CoreAudio (drivers/coreaudio/) — only audio backend on macOS / iOS / visionOS.
• CoreMIDI (drivers/coremidi/) — MIDI input.

Export

export/export_plugin.cpp produces a .app bundle:

• Lays out Contents/MacOS, Contents/Resources, Contents/Info.plist, and the optional Contents/Frameworks for embedded frameworks (e.g., the Mono runtime).
• Generates a per-project Info.plist from project settings (icons, bundle id, minimum OS version, sandbox usage descriptions).
• Optionally codesigns via codesign with an Apple Developer ID certificate.
• Optionally notarizes via notarytool and staples the resulting ticket to the bundle.
• Optionally produces a .dmg distribution image with a custom background image and layout.

The exporter understands both the editor build (signed with the Godot Foundation certificate when distributed officially) and template builds.

Key abstractions

Abstraction	File	Role
OS_MacOS	platform/macos/os_macos.mm	OS subclass
DisplayServerMacOS	platform/macos/display_server_macos.mm	Cocoa backend
GodotWindow / GodotView	platform/macos/godot_window.mm, godot_view.mm	NSWindow / NSView subclasses
JoypadMacOS	platform/macos/joypad_macos.mm	Joypad input
CrashHandlerMacOS	platform/macos/crash_handler_macos.mm	Crash handler
EditorExportPlatformMacOS	platform/macos/export/export_plugin.cpp	macOS exporter

Entry points for modification

• New AppKit feature → wire a method onto DisplayServerMacOS and expose via the DisplayServer interface.
• Codesign / notarize tweaks → export/export_plugin.cpp plus the helper scripts.
• Apple Silicon-specific code paths → use __aarch64__ guards; most cross-architecture work is handled by the Metal driver.