DuskPort

Dusklight auf macOS installieren — Twilight Princess PC-Port

Dusklight auf macOS installieren — Apple Silicon und Intel Mac. Verifizierte Dateipfade, echte Einstellungsmenüs, Gatekeeper-Workaround und bekannte Probleme bei v1.0.0.

Veröffentlicht 2026-05-10 ·Aktualisiert 2026-06-20

Dusklight liefert separate native Builds für Apple Silicon (M-Serie) und Intel Macs. Diese Anleitung deckt beide ab, inklusive der Startprobleme, die einige Apple-Silicon-Nutzer gemeldet haben.

Zeitaufwand: ~10 Minuten Schwierigkeit: Einfach (mit Vorbehalt — siehe „Bekannte Probleme” weiter unten)

⚠️ Status bei v1.4.1 (Apple-Silicon-Nutzer)

Die meisten Apple-Silicon-Probleme vom Launchtag wurden bereits in v1.0.1 behoben und sind auch in der aktuellen v1.4.1 (16. Juni 2026) weiterhin gefixt:

  • ✅ #779 / #805 — ursprünglicher „Dusk quit unexpectedly” / dyld-Symbol-Missing-Crash → behoben (Collaborator tomlube: „Fixed in 1.0.1”)
  • ✅ #830 — macOS-Tastenbelegung kaputt → behoben
  • ✅ macOS-14-Unterstützung — in v1.0.1 hinzugefügt (nicht mehr komplett ununterstützt)
  • ✅ macOS-12-Unterstützung (Monterey) — in v1.4.0 (16. Juni 2026) nach einer zwischenzeitlichen Regression wiederhergestellt
  • ⏳ #826 — noch offen. Dieses Problem wurde früher fälschlicherweise mit dem dyld-Crash gleichgesetzt; es handelt sich tatsächlich um einen separaten WebGPU/Metal-RmlUi Gradient Pipeline-Shader-Cache-Kompilierfehler. Laut Kommentaren: „Known shader cache crash on macOS currently. Investigating.” Wenn du beim Start abstürzt, ist das der Bug, den du im Auge behalten solltest.

Fazit: Die neueste v1.4.1 installieren. Falls du trotzdem noch abstürzt, das Grafik-Backend wechseln (Settings → Prelaunch → Graphics Backend → Metal / Vulkan / OpenGL) und den Crash unter #826 melden.

Bevor du anfängst

1. Architektur deines Macs bestimmen

  • Apple-Menü → Über diesen Mac
  • Die Zeile „Chip” zeigt eines von:
    • Apple M1 / M2 / M3 / M4 / Pro / Max / Ultra → Apple Silicon, arm64-Build verwenden
    • Intel Core … → Intel Mac, x86_64-Build verwenden

2. Dein eigener GameCube-Twilight-Princess-Disc-Dump

Pflicht. Dusklight enthält keine Spieldateien. Siehe So liest du deine TP-Disc legal aus.

Unterstützte Disc-Regionen:

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

3. macOS-Version

Laut Quellcode zielt Dusklight auf aktuelles macOS über das Metal-Grafik-Backend. Die Mindestversion ist nicht offiziell dokumentiert, aber macOS 12 (Monterey) oder neuer ist eine verlässliche Annahme. Für den Build aus dem Quellcode wird Xcode 16.4+ benötigt (laut docs/building.md) — das gilt aber nur, wenn du selbst kompilieren willst, nicht für den vorgefertigten Binary.

Schritt 1 — Dusklight herunterladen

  1. Öffne github.com/TwilitRealm/dusklight/releases
  2. Wähle unter v1.4.1 Assets die Datei für deinen Mac:
MacDateiGröße
Apple SiliconDusklight-v1.4.1-macos-arm64.zip27,3 MB
IntelDusklight-v1.4.1-macos-x86_64.zip29,0 MB

Den Download im Terminal verifizieren (Hash berechnen und mit dem auf der Release-Seite vergleichen):

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

⚠️ Wenn du versehentlich die falsche Architektur lädst, startet Dusklight entweder gar nicht oder läuft über Rosetta 2 mit Leistungseinbußen. Auf die passende Architektur achten.

Schritt 2 — Entpacken und verschieben

  1. Die .zip-Datei im Finder doppelklicken. Sie entpackt sich zu einem Dusklight.app-Bundle.
  2. Dusklight.app in Programme ziehen (oder in einen anderen Ordner deiner Wahl).

⚠️ Den App-Ordner nicht in einem von iCloud Drive oder Dropbox synchronisierten Verzeichnis ablegen — Dateisync-Konflikte können Spielstände beschädigen.

Schritt 3 — Erster Start (Gatekeeper-Workaround)

Dusklight ist nicht von Apple notarisiert. Beim ersten Start blockiert macOS Gatekeeper die App.

macOS 12–14

  1. Programme im Finder öffnen
  2. Rechtsklick auf Dusklight.app → Öffnen
  3. Ein Dialog erscheint: „macOS kann den Entwickler von ‚Dusklight’ nicht verifizieren. Willst du es wirklich öffnen?”
  4. Auf Öffnen klicken

Damit wird Dusklight dauerhaft freigegeben; danach kannst du die App normal starten.

macOS 15 (Sequoia)

Auf Sequoia funktioniert der Rechtsklick → Öffnen-Trick manchmal nicht. Falls er blockiert:

  1. Dusklight normal starten (wird blockiert)
  2. Systemeinstellungen → Datenschutz & Sicherheit → Sicherheit
  3. „Dusklight wurde blockiert” suchen → Trotzdem öffnen klicken
  4. Mit Touch ID oder Passwort bestätigen

Schritt 4 — ROM verifizieren

Bevor du Dusklight auf dein Disc-Image zeigst, SHA-1 im Terminal prüfen:

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

Das Ergebnis muss exakt übereinstimmen:

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

Falls keiner passt, lies weiter unter SHA-1-Mismatch-Fehlerbehebung.

Schritt 5 — Disc laden

  1. Dusklight starten
  2. Im Prelaunch-Menü erscheint der Knopf Select Disc Image
  3. Ein nativer macOS-Dateidialog öffnet sich mit dem Filter „Game Disc Images” (Endungen iso, gcm, ciso, gcz, nfs, rvz, wbfs, wia, tgc)
  4. Deinen Disc-Dump auswählen
  5. Den „Verifying disc image”-Overlay abwarten (ein paar Sekunden für den XXH128-Hash-Check)
  6. Status wechselt zu „Disc ready.”
  7. Knopf wechselt zu Play — klicken zum Starten

Schritt 6 — Controls einrichten

✅ Tastenbelegung ist seit v1.0.1 gefixt. Der frühere macOS-Bug #830 ist geschlossen. Wer noch v1.0.0 hat, auf v1.0.1 updaten.

Der verifizierte Einstellungspfad lautet:

Settings → Input → Controller → Configure Controller

Damit öffnet sich ein Port-Fenster mit den Reitern Port 1, Port 2, … und den Seiten Controller / Buttons / Triggers / Sticks / Rumble, dazu ein Options-Bereich mit Enable Dead Zones und Emulate Triggers.

Empfohlene Mac-Controller:

  • DualShock 4 / DualSense — per Bluetooth koppeln, nativer Gyro-Support
  • Switch Pro Controller — per Bluetooth koppeln
  • Xbox Wireless Controller — per Bluetooth koppeln (Modell 1914+ für natives macOS-Pairing)
  • 8BitDo Pro 2 — per Bluetooth koppeln, nativer Gyro

Gyro-Aim aktivieren:

Settings → Input → Gyro → Gyro Aim (einschalten)

Dann Gyro Input Method → Sensor

Maussteuerung als Alternative (ab v1.0.0-rc.1):

Settings → Input → Gyro → Gyro Input Method → Mouse

Spielstand-Speicherort

Einfachste Methode: In Dusklight Settings → Interface → Open Data Folder klicken — das öffnet den richtigen Ordner im Finder, egal welche Version.

Manueller Pfad (aktuelle v1.4.1):

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

Für die europäische Disc USA durch EUR im Pfad ersetzen. Im Finder dorthin navigieren: Gehe zu → Ordner öffnen… (oder ⇧⌘G), ~/Library/Application Support/TwilitRealm/Dusklight/ einfügen, Enter drücken.

ℹ️ Ordner heißt jetzt Dusklight: Nach dem Rebranding von Dusk zu Dusklight liegen Spielstände unter ~/Library/Application Support/TwilitRealm/Dusklight/. Beim ersten Start migriert Dusklight automatisch alle Daten aus dem alten ~/Library/Application Support/TwilitRealm/Dusk/-Ordner. Der In-App-Knopf Open Data Folder ist die zukunftssichere Methode, den richtigen Pfad zu finden.

Texture Packs liegen in ~/Library/Application Support/TwilitRealm/Dusklight/texture_replacements/ (verifiziert gegen den v1.4.1-Quellcode, nicht geraten). Mit Open Data Folder dorthin navigieren und den GZ2*-Ordner aus dem Texture-Pack-ZIP in texture_replacements/ ablegen.

Von Dolphin migrieren

Dolphin-Spielstände auf dem Mac liegen unter ~/Library/Application Support/Dolphin/GC/USA/Card A/. Die Datei 01-GZ2E01-gczelda2.gci von Dolphins Ordner in Dusklights Ordner kopieren. Dusklight neu starten.

Häufige Probleme unter macOS

Dusklight stürzt beim ersten Start ab (Apple Silicon)

Zuerst prüfen: Nutzt du das neueste Release? Die Issues #779 und #805 wurden in v1.0.1 (11. Mai 2026) behoben. Wer noch v1.0.0 hat: erst auf v1.4.1 updaten.

Wenn du das neueste Release nutzt und trotzdem abstürzt, triffst du wahrscheinlich #826, einen separaten WebGPU/Metal-Shader-Cache-Kompilierfehler. Workarounds:

  • Ein anderes Grafik-Backend ausprobieren: Settings → Prelaunch → Graphics Backend (Metal / Vulkan / OpenGL der Reihe nach)
  • Den verlinkten Issue auf Updates prüfen

„Dusklight ist beschädigt und kann nicht geöffnet werden.”

Das ist eine Gatekeeper-Variante. Im Terminal:

xattr -cr /Applications/Dusklight.app

Dann erneut öffnen. Damit wird das Quarantäne-Attribut entfernt, das Apple beim Download gesetzt hat.

Tastatur funktioniert im Spiel nicht

#830 wurde in v1.0.1 (11. Mai 2026) behoben. Auf v1.0.1 updaten, falls noch v1.0.0 vorhanden.

Falsche Architektur installiert (langsame Performance)

Wahrscheinlich wurde auf einem Apple-Silicon-Mac der x86_64-Build heruntergeladen, der nun über Rosetta 2 läuft. Den arm64-Build neu herunterladen.

Knisternder Ton

Zwischen den Abtastraten in macOS Audio-MIDI-Setup hin und her schalten, oder das Grafik-Backend wechseln (manchmal wird Audio durch den Renderer gebremst).

Häufige Probleme auf macOS

Was als nächstes?

Zuletzt aktualisiert: 20. Juni 2026. Wir aktualisieren diese Anleitung, wenn macOS-spezifische Patches erscheinen.

← Alle Installationsanleitungen · Hauptseite →