FAQ & troubleshooting
Quick checks for install and first launch. For a static list of recurring quirks, see Known issues. Work through the sections below, then use GitHub Issues when you can reproduce an engine problem.
iOS vs Android / desktop setup
Android and desktop: install the app, then in Dusklight use Select Disc Image and Play — same sequence the project readme lists. iOS spends most effort on sideloading (see Install → iOS); once Dusklight runs, the in-app steps match everyone else.
Won’t start (desktop)
- Re-download the zip for your OS and CPU from Download by system or grab the matching filename on Releases.
- Windows: if SmartScreen appears, use More info → Run anyway only for binaries you fetched from an official release asset.
- Antivirus may quarantine new binaries — restore or allow-list if you trust the release you downloaded.
Disc image rejected or black screen
- Re-check SHA-1 against Setup. A wrong revision or patched rip may fail.
- Use a straight disc dump in a format the project supports; avoid repacking unless release notes say otherwise.
HD textures & texture packs
Dusklight v1.3+ supports native texture replacementsin its own folder layout — not Dolphin's HD pack system. Dolphin packs cannot be dropped in unchanged.
For paths, folder naming (GZ2E01 / GZ2P01), and v1.4.0 regression fixes, see Texture packs. We do not list third-party pack downloads here.
Performance & controls
- 30 FPS cap: check video settings for an unlock framerate option.
- Controller / gyro: review Input settings; v1.4 added broader mouse and mobile touch support.
- AMD on Windows: upgrade to v1.4.1+ if performance dropped on v1.4.0.
Wrong download
Intel Mac vs Apple silicon, Linux x86_64 vs arm64 AppImage, Windows x64 vs arm64, and Steam Deck (x86_64 only) are not interchangeable. Match the filename on Releases.
Linux & Steam Deck
- Use the x86_64 AppImage on most PCs and on Steam Deck — not the ARM64 Linux package.
- If the binary is not executable:
chmod +x Dusklight-*.AppImage. - For SteamOS Desktop Mode, paths, and first-run tips, see Install → Linux — Dusklight on Steam Deck.
Android & iOS
- Android: enable install from your file manager or browser if blocked; see Install → Android.
- iOS: sideloading varies by account and tool; see Install → iOS.
Performance & hardware chatter
Handheld and SBC tips often show up in community threads — for example this Reddit discussion. Treat them as anecdotal; the issue tracker is better for confirmed bugs.
Another version?
The home page lists the latest build per OS. For an older tag, filename patterns, or to-grab a package by hand, read Releases first, then use the button below only when you need the raw Assets list.
Open full download list