MacNativeGames GitHub: Shader Stutter & Warm-up Fixes

Which kind of stutter are you seeing?

Build stuck at “3/4 shaders” instead? That is shader preparation while making the app, before gameplay. Use the build-stage walkthrough and retain the first error if the build exits.

Match the project, game update and source revision

Record three things before applying a fix: the builder you used, the source revision and the game update printed during the build. An app name alone does not identify its renderer or settings.

Choose the matching source in the build wizard. If you use NX2Apple or nxnative, follow that engine’s settings and log locations; TOTK_* options from this page belong to MacNativeGames.

First launch: know which preparation is running

1. Put the app where you intend to keep it

   For a new build, choose the final output path in the build wizard. For example, set the output to /Applications/Tears of the Kingdom.app if that is where you plan to launch it. Keep that location for the comparison.

2. Open one copy and watch the progress

   Let shader import and warm-up finish. Changing totals or progress means work is continuing. Do not repeatedly quit and restart while judging the first launch. There is no fixed countdown that fits every Mac, game version and cache state.

3. If preparation fails, fix the named cause

   Read the failure rather than treating every pause as a graphics setting. A full disk can interrupt the seed import. A shader translation-chain mismatch after a runtime update needs a matching seed; use the runtime-update recovery steps. Keep the work folder so its game data can be reused.

Check the shader stage when building

TERMINAL · BUILD PROGRESSOpen full-size image ↗

On a phone, swipe the image sideways or open it full size.

For a Mac build with full Xcode, install its Metal toolchain before rebuilding. The packager can then include compiled Metal libraries with the app. This is different from repeatedly clearing the runtime cache.

xcodebuild -downloadComponent MetalToolchain

Run the same build with the same input files and work folder after installing the toolchain. See where the shader and packaging stages appear.

Repeat the same scene before changing settings

Use a short route you can reproduce. A familiar save, one camera turn and the same visual effect are more useful than comparing a quiet room with a busy town.

• Pause largely disappears: keep the cache. Continue playing; a new effect can still introduce another shader variant.
• Pause returns in the same place: capture it in a log and follow the repeated-stall steps below.
• Frame rate is low throughout: start with the output settings and memory pressure, rather than rebuilding every shader.

Use the performance page’s frame-time explanation to distinguish a short hitch from a sustained frame-rate limit.

When the warmed-up route still feels uneven

1. Open the Display page in the settings panel. Record the current resolution, render scale and frame mode.
2. Choose one frame mode for your baseline. Frame lock and frame interpolation are different controls; use the frame-pacing setup to change one variable at a time.
3. Repeat the route. If GPU load is high, lower render output before increasing the target FPS. Watch macOS Activity Monitor’s Memory Pressure during the same scene.
4. Restore your original setting if the change makes no useful difference. Keep the run log for pauses that persist.

Display · find the row you want to changeOpen full size ↗

Swipe sideways to read the controls, or open the full-size image.

The English panel preview above shows where to change the controls. Use the version map if your app uses the older shortcut-only controls. For M1 Air 8 GB and 1.4.3, see the specific repeated-stall case.

Keep shaders, pipeline archives and saves separate

Startup seed

Prepared from your game files during the build and bundled in the app. Rebuilding a changed translation chain prepares a matching seed.

Translated shader cache

~/Library/Application Support/MacNativeGames/TOTK/shader-cache/rt-<chain>/. The launcher selects the translation-chain folder. Keep it between normal launches.

Metal pipeline archives

The cache’s pipelines/ data contains work for the GPU. The runtime uses its identity information to rebuild archives when the OS, GPU or translation chain changes.

Game profile and saves

~/Library/Application Support/MacNativeGames/TOTK/profile/. This is your progress. Follow the save-backup steps before changing versions.

Why an app move can cause another long launch

On builds that depend on macOS’s compiled Metal cache, moving the app can lose cache reuse. Building directly at the final location avoids that extra change. The upstream investigation also found path-length effects in Metal’s cache lookup. Treat the final app location as part of your comparison.

Changing game versions does not require deleting your entire user-data folder. Current source filters warm-up to the selected game’s shader identity. Keep the old cache and saves while the app prepares the matching work.

Do not use a general system-cache cleaner as the first fix. It removes the warm state you are trying to measure and can affect other applications.

Capture the repeated stall in a debug log

November builds write the game log only when debug logging is enabled. Quit the game before changing this option, then launch it normally and reproduce the short route once.

defaults write org.macnativegames.totk TOTK_DEBUG_LOG -bool YES

1. Reproduce once, then quit

   Record the game version, source revision, Mac chip and memory, macOS version, app location and Display settings. Note whether this was the first visit or a warmed-up repeat.

2. Copy the log before launching again

   In Finder, press Shift + Command + G and paste the folder below. Copy totk.log to your report folder. The previous run is totk.previous.log; launching again rotates these files.

~/Library/Logs/MacNativeGames/

Look for [shader-seed], preparation counts, compiler errors and the lines around the repeated pause. Some progress messages are written in Chinese by the runtime. Retain their original wording when reporting a failure.

defaults write org.macnativegames.totk TOTK_DEBUG_LOG -bool NO

Copy first: a later launch with logging off removes the earlier game logs. See the no-log case if the folder has no current file. For Breath of the Wild, use its own org.macnativegames.botw preference and botw.log.

Questions that come up during a retry

Technical reference: GitHub shader preparation and cache behavior · Mac launcher and log behavior. Source snapshot: 821ce8c, 4 November 2026.