Ocarina Recomp troubleshooting
Concrete fixes for the common black-screen, opening-crash and shader-installer problems reported in GitHub issues.
- v0.3.4 fixes
- Issue #20
- Issue #188
- Issues #15/#12
Start with the current release
Use v0.3.4 and compare the installer before running it: Ocarina-Setup-0.3.4-windows.zip, 116,061,045 bytes, SHA-256 7e4906c2b9147dd6f974d382dbe1626e27ec9c69caa70f7167df9b31aca9dd72. v0.3.4 is marked as a test release: it fixes a shader-preparation freeze on AMD RDNA 3 (#208) and black Link in sunlit areas on Intel and AMD (#91), and adds jogar\hookshot-preparar-jogo.bat and jogar\hookshot-copiar-save.bat (#216) to migrate your game folder and save to Hookshot, which the project now recommends (#212). v0.3.3 brought the AMD mesh shader output fix (#202), shader translator fixes (#203), GPU exposure synchronization and tree column fixes (#204).
Black screen on AMD RX 9070 XT and white screen fixes
Issue #20 tracks a black screen on some RX 9070 XT systems, while #202 fixes white screens and white foliage caused by extra mesh shader outputs on AMD. Update the AMD driver, install the newest release, remove the old shader cache, and try again after the installer completes. Include ultima-partida-erros.log, the driver number and the release tag when reporting a repeat. A related open report, #188, shows floors, rocks, roots and Link’s hair rendering pure white on an RX 6550M (RDNA 2).
Opening or Great Deku Tree crash
Issues #15 and #12 describe a crash during the opening cutscene or after the Great Deku Tree when shader compilation and RAM usage peak together. v0.3.2/v0.3.3 mitigate both paths. Keep at least 16 GB RAM available, set a 16–32 GB page file, close other heavy apps and let the install step finish before pressing Play.
Other recent Ocarina Recomp and Hookshot fixes
- v0.3.4: shader-preparation freeze on AMD RDNA 3 fixed (#208); Link no longer black in sunlit areas on Intel and AMD (#91); Linux
jogar-ocarina.shkeeps the fullscreen and GPU chosen in the menu (#168). - Extra mesh shader outputs removed on AMD, resolving white picture and white foliage (#202).
- Shader translator fixes for local memory zeroing, bitfields past bit 31, funnel shift by zero, and integer formats (#203).
- GPU exposure meter synchronization eliminates white flashes and fog flicker (#204).
- Foliage culling record writeback fixes flickering or stretched tree columns (#204).
- Linux build issues tracked in #41; four translator fixes ported in v0.3.3.
- Phantom sun-shading flicker on Temple of Time market stairs tracked in #132.
- Hookshot v2.0.10 builder fix resolves update compile/link errors (#1176, #1197); v2.0.9 addresses NVIDIA 621 startup freeze (#1161); legacy GPU fallback tracked in #1001.
- Windows SmartScreen or antivirus flagging
HookshotBuilder.exeor quarantining compiler tools: see Is Hookshot safe? for SHA-256 verification and builder repair steps. - Linux & Steam Deck
BrokenPipeError/signal 9OOM kills, Mesa RADV depth-texture crashes, and 2.5 GB unified-RAM limits: see the Steam Deck & Linux guide, or compare Hookshot vs NX2navi.
What to attach to a report
Include the GPU model, driver, RAM and page-file size, release tag, the last log and the step where the failure occurred. Report Ocarina Recomp issues on GitHub; never attach game files.
Recommended controllers for PC & Deck
All four Ocarina of Time PC ports use SDL3/SDL2 controller input. A gamepad with 6-axis gyro or drift-free TMR sticks gives the best experience for bow/slingshot aiming, Ocarina notes and Z-targeting:
| Controller | Best For | Why It Fits Ocarina on PC | Link |
|---|---|---|---|
| 8BitDo Ultimate 2 Bluetooth | Switch A/B/X/Y layout + charging dock | Matches Nintendo C-button / action layout, TMR sticks, Bluetooth & 2.4 GHz | View on Amazon → |
| Sony DualSense | Bow & slingshot gyro aiming | Native SDL3 6-axis gyro + rumble on Windows & Linux (Hookshot & ReTuned) | View on Amazon → |
| GameSir Cyclone 2 | Zero-drift 60+ fps PC play | TMR electromagnetic sticks, Hall triggers, 1000 Hz wireless dongle + gyro | View on Amazon → |
| Xbox Wireless Controller | Plug-and-play Windows XInput | Works immediately in Ocarina Recomp, Hookshot (`bin\SDL3.dll`) & TriAevum | View on Amazon → |
As an Amazon Associate, this site earns from qualifying purchases. Full button mappings and dead-zone tips: Controller setup guide.
Frequently asked questions
My AMD card shows a black screen or pure white screen. What should I do?
v0.3.3 removed extra mesh shader outputs on AMD, a likely cause of the white picture and foliage (#202), and v0.3.4 fixes a shader-preparation freeze on RDNA 3 cards such as the RX 7800 XT (#208). Issue #20 for RX 9070 XT black screens remains open: install the newest release and the current AMD Adrenalin driver, delete old shader caches, let the installer complete its shader pass, and retry. If it remains black, attach ultima-partida-erros.log, GPU driver and release tag to the GitHub issue, or try Hookshot, which the Ocarina Recomp developers now recommend (#212).
Floors, rocks, roots or Link’s hair render pure white on my AMD laptop GPU. Is it known?
Yes. Issue #188 (Radeon RX 6550M, RDNA 2, 4 GB, AMD driver 26.10.1) reports the same surfaces rendering pure white with a bloom glow on 0.2.8 and 0.2.9, unchanged by default settings, a lower resolution or switching ASTC decoding between GPU and CPU. It is still open. v0.3.3 asked AMD users to retest after the mesh shader output fix (#202): install the newest release, update the driver and add your log and screenshots to the issue.
Why is Link black in sunny areas on Intel or AMD?
Fixed in v0.3.4 (#91); nothing changes on NVIDIA. Install over the previous version in the same folder; on AMD and Intel the first start builds some shaders again.
The game crashes in the opening cutscene or after the Great Deku Tree. Is it fixed?
Issues #15 and #12 describe shader and RAM spikes during transitions. v0.3.2 and v0.3.3 mitigate these paths. Use at least 16 GB RAM, set a 16–32 GB Windows page file, close background applications, and let the installer finish compiling shaders before pressing Play.
Why do trees flicker or stretch into columns, or why does fog flash white?
Fixed in v0.3.3 (#204): the game now waits for the GPU to finish writing before reading exposure sums (preventing white flashes and fog flicker), and foliage culling tables write back only their 64-byte record to prevent tree geometry deformation.
Why does Hookshot freeze or show a black window on NVIDIA?
NVIDIA 621-series drivers could freeze right after start with v2.0.8 changes (#1161). Hookshot v2.0.9 hotfix defaults write-back diffing (RX_VK_WB_DIFF) and dedicated present queues back to safe paths. If your driver works, re-enable the speedup with RX_VK_WB_DIFF=1 and RX_VK_PRESENT_QUEUE=1.
Why did Hookshot update fail with undeclared identifier or undefined symbol?
Updates failing with errors like use of undeclared identifier 'g_module_b' or undefined symbol: f_8... (#1176, #1197) were caused by stale translated game code from earlier builds being reused. Hookshot v2.0.10 clears stale code on retry so running Update again succeeds cleanly.
Can Apple Silicon macOS users play?
Ocarina Recomp ships a Windows package. Apple Silicon users should use PranavDupati/ninboy-hat-for-macos v1.0.1 and follow that project’s own release notes.