Repository navigation
Configuration Graphics
Open Graphics in the lobby or Settings → Graphics → Display in game. The macOS display options are shared between the two.
Fresh profiles use Low graphics, windowed mode, and Retina text and UI. VSync is forced on; the lobby’s VSync/frame-limiter control is hidden on macOS. Higher presets and optional effects may expose rendering problems or cost more GPU time.
For a rendering or performance problem, first compare the default setup with MetalFX, HDR, GPU resource sharing and DisplayLink disabled. Change one option at a time and keep the same scene. Reporting Bugs lists the settings to include in a report.
Choose Retina / High-DPI in the lobby's Graphics settings, directly below Graphics Driver Selected, or use in-game Settings → Graphics → Display. The setting is shared between the lobby and game.
| Mode | Effect |
|---|---|
| Standard | Standard-resolution world and UI; lowest rendering bandwidth |
| Retina text and UI | Crisp UI and text with the world at standard resolution; the default balance |
| Full Retina | Renders the world at Retina resolution too; costs more GPU time and bandwidth |
Quit Zero-K completely and reopen it after changing Retina mode. Starting another battle is not enough.
Toggle MetalFX spatial upscaling below the Retina setting in the lobby's Graphics settings, or in in-game Settings → Graphics → Display. It applies immediately to the lower-resolution world in Retina text and UI mode on a Retina display; text and UI still draw at native resolution. Standard and Full Retina modes do not use it. If MetalFX is unavailable or fails, the engine logs the reason and uses the existing bilinear scaling.
MetalFX is off by default. The bundled Mesa bridge can share GPU textures with
MetalFX and present the finished frame directly through Metal. This experimental
path is opt-in and still incurs synchronization costs. See
renderer validation and measurements.
To configure it manually, quit Zero-K and set these values in
~/Library/Application Support/Zero-K/springsettings.cfg:
MacRetinaMode = 1
MacMetalFXSpatial = 1Set MacMetalFXSpatial = 0 to disable it. The lobby reads this shared engine
setting, so an older saved lobby selection does not override manual edits.
Toggle GPU resource sharing in the same lobby Graphics or in-game Display
menu. It applies immediately and is off by default. The manual setting is
MacGPUSharing = 1; use 0 for the CPU staging compatibility path. HDR display
output always uses shared textures, even when this switch is off. Older or incompatible Mesa libraries fall back
automatically and log a [MacGPUSharing] warning. That fallback can cost more
bandwidth and GPU/CPU synchronization time.
Toggle Show native FPS counter in the same in-game Display menu, or use
/fps. It displays FPS, average frame interval, and the current Retina mode,
which helps compare UI-only and Full Retina performance.
Enable macOS HDR display output in the lobby's Graphics settings or in-game Settings → Graphics → Display. It applies immediately in all three Retina modes and is off by default. It preserves bright values from the game's existing lighting for an HDR display, without adding color grading, highlight expansion or another bloom effect. Opaque UI white stays at normal brightness.
The game's HDR (experimental) controls belong to its legacy lighting renderer; GL4 lighting replaces that renderer when available. These lighting choices are separate from macOS display output. Enable the game's deferred lighting buffers to use its dynamic lighting; an HDR output switch does not create new lights or recover brightness clipped inside an effect.
The engine adapts to available display headroom and uses SDR if HDR output is
unavailable. To configure manually, set MacHDR = 1 in springsettings.cfg;
use 0 for SDR. HDR requires GPU sharing for its own frames and may cost GPU
time. See HDR internals and validation.
Toggle Experimental DisplayLink frame pacing in the same Graphics/Display menu. It applies immediately and defaults to Off. The manual engine setting is MacDisplayLink = 1; use 0 to disable it.
The feature uses CAMetalDisplayLink to pace presentation around display updates. It works with shared GPU textures, HDR output, and the reusable Metal upload path. Earlier measurements did not establish a general performance improvement and sometimes regressed, so it remains optional. Render-loop FPS alone does not establish smoother displayed frames. See the measurements.
Enable Notchful fullscreen in the lobby's Graphics settings or Settings → Graphics → Display in game. It is off by default. Quit Zero-K completely and reopen it after changing the setting, then select fullscreen.
The resource HUD switches automatically when fullscreen actually covers the notch area. It reads the current display's notch boundaries from macOS and places metal and energy on opposite sides, with a small margin. The compact icons, bars, quantities and flow indicators use the matching top-bar strip. Quantities pass through to the icons' tooltips; Ctrl-click reserve controls remain available.
Windowed mode, fullscreen below the notch, and displays without a notch keep the default Zero-K layout. Other HUD elements retain their normal arrangement. Notchful fullscreen uses the current desktop without creating a separate macOS Space. The native geometry check follows display and scaling changes.
The app declares its game category and opts into macOS Game Mode. To use it, put Zero-K in macOS full-screen mode and keep it in the foreground. The default windowed mode does not activate Game Mode.
On macOS 26, press Command-Esc while in full screen, then open Game Overlay settings to check Game Mode. If you previously turned it off for Zero-K, turn it back on there; macOS remembers that choice across launches. See Apple's Game Mode instructions.
Quit Zero-K before editing ~/Library/Application Support/Zero-K/springsettings.cfg. These are the shipped defaults:
MacRetinaMode = 1
MacMetalFXSpatial = 0
MacHDR = 0
MacGPUSharing = 0
MacDisplayLink = 0
MacNotchFullscreen = 0
ShowFPS = 1
VSync = 1MacRetinaMode uses 0 for Standard, 1 for Retina text and UI, and 2 for Full Retina. Other switches use 0/1. A stale lobby save does not overwrite manual edits to the shared macOS display options. Keep VSync enabled.
ZkMacOS source · Download the DMG · Report a bug · Get help
Unofficial, experimental Zero-K client. These guides describe the current source; older releases may differ.
- Getting Started
- Playing Zero-K
- Development
- Contributing
- Environment Setup
- Build and Release
- Internals and Validation
- Licensing and Credits
- Source · Downloads