Install Dusk on macOS — Twilight Princess PC Port

Install Dusk on macOS — Apple Silicon and Intel Mac. Verified file paths, real settings menus, Gatekeeper workaround, and v1.0.0 launch crash workarounds.

Published 2026-05-10 ·Updated 2026-06-20

Dusklight ships separate native builds for Apple Silicon (M-series) and Intel Macs. This guide covers both, plus the launch issues that some Apple Silicon users have reported.

Time required: ~10 minutes Difficulty: Easy (with caveat — see Known Issues below)

⚠️ Status at v1.4.1 (Apple Silicon Users)

Most launch-day Apple Silicon pain points were resolved back in v1.0.1 and remain fixed in the current v1.4.1 (2026-06-16):

✅ #779 / #805 — original “Dusk quit unexpectedly” / dyld symbol-missing crash → fixed (collaborator tomlube: “Fixed in 1.0.1”)
✅ #830 — macOS keyboard binding broken → fixed
✅ macOS 14 support — added in v1.0.1 (no longer outright unsupported)
✅ macOS 12 (Monterey) support — restored in v1.4.0 (2026-06-16) after an earlier regression
⏳ #826 — Still open. This was previously confused with the dyld crash; it’s actually a separate WebGPU/Metal RmlUi Gradient Pipeline shader-cache compile failure. Labeled “Known shader cache crash on macOS currently. Investigating.” If you hit a crash on launch, this is the issue to watch.

Bottom line: install the latest v1.4.1. If you still crash, try cycling the Graphics Backend (Settings → Prelaunch → Graphics Backend → Metal / Vulkan / OpenGL) and report to #826.

Before You Start

1. Identify your Mac’s architecture

Apple menu → About This Mac
“Chip” line will say one of:
- Apple M1 / M2 / M3 / M4 / Pro / Max / Ultra → Apple Silicon, use the arm64 build
- Intel Core … → Intel Mac, use the x86_64 build

2. Your own GameCube Twilight Princess disc dump

Required. Dusklight does not include game files. See How to legally dump your TP disc.

Supported disc regions:

GameCube USA (GZ2E01) — SHA-1 75edd3ddff41f125d1b4ce1a40378f1b565519e7
GameCube PAL (GZ2P01) — SHA-1 2601822a488eeb86fb89db16ca8f29c2c953e1ca

3. macOS version

Per the source code, Dusklight targets recent macOS via the Metal graphics backend. The minimum macOS version isn’t officially documented, but macOS 12 (Monterey) or newer is a reasonable working assumption. Building from source requires Xcode 16.4+ (per docs/building.md) — but you don’t need this just to run the prebuilt binary.

Step 1 — Download Dusklight

Go to github.com/TwilitRealm/dusklight/releases
Under v1.4.1 Assets, pick the file matching your Mac:

Mac	File	Size
Apple Silicon	`Dusklight-v1.4.1-macos-arm64.zip`	27.3 MB
Intel	`Dusklight-v1.4.1-macos-x86_64.zip`	29.0 MB

Verify the download in Terminal (compute the hash, then compare to whatever is published on the release page):

shasum -a 256 ~/Downloads/Dusklight-v1.4.1-macos-arm64.zip

⚠️ If you accidentally download the wrong arch, Dusklight either won’t launch or will run via Rosetta 2 with a performance hit. Pick the matching arch.

Step 2 — Extract and Move

Double-click the .zip in Finder. It expands to a Dusklight.app bundle.
Drag Dusklight.app to Applications (or any folder you prefer).

⚠️ Avoid placing it inside a folder synced by iCloud Drive or Dropbox — file sync conflicts can corrupt save files.

Step 3 — First Launch (Gatekeeper Workaround)

Dusklight is not notarized by Apple. The first time you run it, macOS Gatekeeper will block it.

macOS 12–14 path

Open Applications in Finder
Right-click Dusklight.app → Open
A dialog appears: “macOS cannot verify the developer of ‘Dusklight’. Are you sure you want to open it?”
Click Open

This whitelists Dusklight going forward; you can launch normally after this.

macOS 15 path

On Sequoia, the right-click → Open trick is gated. If it doesn’t work:

Try to launch Dusklight normally (it will be blocked)
System Settings → Privacy & Security → Security
Scroll to “Dusklight was blocked” → click Open Anyway
Authenticate with Touch ID or password

Step 4 — Verify Your ROM

Before pointing Dusklight at your disc image, verify the SHA-1 in Terminal:

shasum -a 1 ~/path/to/your-dump.iso

Should match exactly:

75edd3ddff41f125d1b4ce1a40378f1b565519e7 (NTSC-U)
2601822a488eeb86fb89db16ca8f29c2c953e1ca (PAL)

If neither matches, see SHA-1 mismatch troubleshooting.

Step 5 — Load Your Disc

Launch Dusklight
The prelaunch menu shows the button Select Disc Image
A native macOS file dialog opens with filter “Game Disc Images” (extensions iso, gcm, ciso, gcz, nfs, rvz, wbfs, wia, tgc)
Select your disc dump
Wait for the “Verifying disc image” overlay (a few seconds for XXH128 hash check)
Status changes to “Disc ready.”
Button changes to Play — click it

Step 6 — Configure Controls

✅ Keyboard binding is fixed in v1.0.1. The earlier #830 macOS bug is closed. If you’re on v1.0.0, update to v1.0.1.

The verified Settings path is:

Settings → Input → Controller → Configure Controller

This opens a per-port window with tabs Port 1, Port 2, … and pages Controller / Buttons / Triggers / Sticks / Rumble, plus an Options section with Enable Dead Zones and Emulate Triggers.

Recommended Mac controllers:

DualShock 4 / DualSense — pair via Bluetooth, native gyro support
Switch Pro Controller — pair via Bluetooth
Xbox Wireless Controller — pair via Bluetooth (model 1914+ for native macOS pairing)
8BitDo Pro 2 — pair via Bluetooth, native gyro

To enable gyro aim:

Settings → Input → Gyro → Gyro Aim (toggle on)

Then Gyro Input Method → Sensor

Mouse aim alternative (added v1.0.0-rc.1):

Settings → Input → Gyro → Gyro Input Method → Mouse

Save File Location

Easiest path: inside Dusklight go to Settings → Interface → Open Data Folder — this opens the right folder in Finder regardless of version.

Manual path (currently shipping v1.4.1):

~/Library/Application Support/TwilitRealm/Dusklight/USA/Card A/01-GZ2E01-gczelda2.gci

For the European disc, replace USA with EUR in the path. To navigate there in Finder: Go → Go to Folder… (or ⇧⌘G), paste ~/Library/Application Support/TwilitRealm/Dusklight/, hit Enter.

ℹ️ Folder renamed to Dusklight: the app rebranded from Dusk to Dusklight, so saves now live under ~/Library/Application Support/TwilitRealm/Dusklight/. On first launch Dusklight auto-migrates your data from the old ~/Library/Application Support/TwilitRealm/Dusk/ folder, so existing saves carry over. Using the in-app Open Data Folder button is the rename-proof way to find the right path.

Texture packs live in ~/Library/Application Support/TwilitRealm/Dusklight/texture_replacements/ (verified against the v1.4.1 source code, not inferred). Use Open Data Folder to get there and drop the GZ2* folder from your texture pack zip into texture_replacements/.

Migrate from Dolphin

Dolphin saves on Mac live at ~/Library/Application Support/Dolphin/GC/USA/Card A/. Copy 01-GZ2E01-gczelda2.gci from Dolphin’s folder to Dusklight’s folder. Restart Dusklight.

Common Issues on macOS

Dusklight crashes on first launch (Apple Silicon)

First check: are you on the latest release? Issues #779 and #805 were fixed in v1.0.1 (2026-05-11). If you’re still on v1.0.0, update to v1.4.1 first.

If you’re on the latest release and still crashing, you may be hitting #826, which is a separate WebGPU/Metal shader-cache compile failure. Workarounds:

Try a different Graphics Backend in Settings → Prelaunch → Graphics Backend (cycle Metal / Vulkan / OpenGL)
Check the linked issue for status

”Dusklight is damaged and can’t be opened”

This is a Gatekeeper variant message. In Terminal:

xattr -cr /Applications/Dusklight.app

Then re-open. This removes the quarantine attribute Apple added on download.

Keyboard not working in-game

#830 was fixed in v1.0.1 (2026-05-11). Update if you’re still on v1.0.0.

Wrong arch installed (slow performance)

You probably grabbed the x86_64 build on an Apple Silicon Mac and it’s running via Rosetta 2. Re-download the arm64 build.

Audio crackling

Try toggling between sample rates in macOS Audio MIDI Setup, or change the Graphics Backend (sometimes audio is bottlenecked by the renderer).

Common Problems on macOS

“Dusklight is damaged and can’t be opened” → Gatekeeper fix
Apple Silicon launch crash (Metal/WebGPU shader-cache, still open at v1.4.1) → #826 fix guide
Hash verification failed → fix guide
Stuck at 30 FPS → checklist
Dolphin save not loading → migration guide
Full hub → all known issues

What to Try Next

🎨 Install the Henriko Magnifico 4K texture pack
🚀 Framerate & 60 FPS, explained
💾 Save file paths & cross-device sync
🏆 See the achievement list
⚡ Turbo Key shortcut — Hold Tab for 4× speed

Last updated: 2026-06-20. We update this guide as macOS-specific patches release.

← All install guides · Pillar guide →