Help
Troubleshooting: when the world looks like vanilla
By Ryleigh Newman · Published · Updated
If Rockstar Shaders is not rendering, the settings screen says why before the log does. Press K in a world and read the line under the title. "Rendering with Rockstar Shaders" means the pack is on and the problem is a setting. "The pack is switched off" means the master switch. "The pack is not rendering (see the log)" means the game is still on OpenGL or the pack hit an error, and logs/latest.log has the reason under the word RockstarShaders.
I made Rockstar Shaders, and it is a 1.0 release measured on one machine, so some of what you see will be a bug. Here are the problems I check, in order.
Download free (1.0.0) Modrinth (pending)Minecraft 26.3, Fabric, macOS on Apple silicon. Install guide. Releases and bug reports on GitHub.
Read the header first
The header shows one of four lines. "Rendering with Rockstar Shaders, pipeline generation N." is the good one. "The pack is switched off; vanilla is on screen." means the master switch, the first row under General, is off; turn it on and the next frame is the pack's. "The pack is not rendering (see the log); vanilla is on screen." is the rest of this page. "A restart-only setting changed: it applies at the next launch." is not a fault.
The switched-off state writes no log line. Its signs are that header and an amber "vanilla" on the Show FPS overlay; in a log it is the absence of "RockstarShaders active on".
The game is still on OpenGL
The log says "RockstarShaders requires the Vulkan backend but the active backend is" and the backend's name. Set it in the game: Options > Video Settings > Graphics API > Vulkan, then restart. If you edit options.txt by hand, the working line is preferredGraphicsBackend:"vulkan" with the quotes; the unquoted form the log prints does not parse, and the game stays on OpenGL without saying so.
At the title screen the mod offers to switch for you. If you chose Not now, the prompt returns when the master switch is turned on again. "options ask for Vulkan but the game is running on" another backend means the option did not take; set it in Video Settings.
Disabled after an error
"RockstarShaders disabled:" and a reason, then a stack trace, means the pack hit a failure while rendering, tore its renderer down and latched itself off for the rest of the session; the game keeps running on vanilla. The reasons in the code are "frame setup failed", "post chain threw during rendering" and "could not re-register pipelines after a resource reload". At start-up the equivalent is "RockstarShaders failed to initialize; falling back to vanilla rendering".
The latch clears without a restart. Open the settings, change any tune value and close the page with Done: the log says "RockstarShaders reload: rebuilding pipelines" and the pack tries again. If it fails the same way, the stack trace is what I need in a report.
Reading the log
The file is logs/latest.log in the Minecraft directory. The mod logs as RockstarShaders, one word; the prompt and the header use two words, so search for both. A healthy start reads, in order: "RockstarShaders loading (Nacre shader pack bundled)"; "No VK_KHR_ray_query on this driver", which is normal on a Mac; "Precompiled N pipelines (M failed)"; "RockstarShaders active on" with the device; then the ray tracing lines.
"RockstarShaders is running with N effect(s) DISABLED because their shaders did not compile" means the pack is on with one effect missing, and a "Pipeline" line above it names which.
Ray tracing unavailable
Without the Metal side-car the pack still renders, but the traced sun shadows, sky visibility, bounce light, water reflections and fog occlusion are gone, and enclosed spaces look veiled. Find "Ray tracing: ready", or "Ray tracing unavailable:" with a reason: disabled by -Drockstarshaders.rt=false, the backend is not Vulkan, VK_EXT_metal_objects not enabled, libvrt.dylib unavailable, no MTLDevice exported, the device does not support Metal raytracing, a refusal to share MoltenVK's command queue, or a failed self test. A single trace can also drop on its own, with a "disabled" line naming it. The Ray tracing: row on the settings front page shows the same status.
Water, sky or light looks wrong
Some of what looks wrong is a known limit, not a fault. There is no white water: foam, spray, aeration and splash crowns are compiled out unless the Advanced key waterWhite is 1, so the Shore foam slider does nothing and Spray over falls reads Off on a fresh install. The ripple field restarts from flat whenever Done rebuilds the renderer. A resource pack's custom sky is not reflected in water. Colored block light leaks through thin walls, and dynamic lights cast no shadows. Your own first-person shadow does not appear, even with Player shadow on. The horizon draws only ground that exists, what Generate horizon makes is not saved, and on a server it holds only chunks you have received. Anything else is a bug; reporting a bug says what to send.
It is slow
Every number I have is from one M4 Max with 48 GB, so measure your own machine: turn on Show pass timings on the Performance & Overlays page, close with Done so the renderer rebuilds with its timer, and read which pass is amber. At 1706x1966 the water pass is the largest, 8.7 to 8.9 ms. The setting that helps most is Render scale: 75%, the default, took that frame from 44.98 to 33.95 ms. Target FPS lowers the scale by itself while frames miss the rate. Do not switch the ray tracing off to save time; measured, every fallback costs more than the trace. MetalFX upscaling is present, experimental and off by default. Getting more frames goes through the rest.
The config file, and still stuck
The settings are in config/rockstarshaders.json. A file that does not parse is kept as rockstarshaders.json.bad beside a fresh one, and a grayed setting was pinned on the command line; the Advanced page covers all of it.
If none of this names your problem, send logs/latest.log and a screenshot with the F3 overlay, plus a screenshot of the pass timings overlay for a performance problem, with which Mac and window size, to GitHub issues. Reporting a bug lists exactly what to include.
Download free (1.0.0) Modrinth (pending)Minecraft 26.3, Fabric, macOS on Apple silicon. Install guide. Releases and bug reports on GitHub.
Related
Questions
Why does the world look like plain Minecraft with Rockstar Shaders installed?
Press K and read the header. Either the master switch is off, or the game is still on OpenGL, or the pack disabled itself after an error. The second and third leave a RockstarShaders line in logs/latest.log saying which.
Why does the FPS overlay say vanilla in amber?
The pack is not rendering. The master switch is off, the game is on OpenGL, or the pack latched itself off after an error. The header under K says which, and the log has the reason for the last two.
What does RockstarShaders disabled mean in the log?
A render-time failure. The pack tore its renderer down and stays off for the session while the game runs on vanilla. Change any tune value and close the settings with Done to make it rebuild and try again.
I put preferredGraphicsBackend:vulkan in options.txt and nothing changed.
The value needs quotes: preferredGraphicsBackend:"vulkan". Without them the line fails to parse silently and the game stays on OpenGL. Setting Graphics API in Video Settings writes it correctly.
Why do caves and rooms look gray and veiled?
The Metal side-car is not running, so the fog has no traced sky occlusion. Search the log for Ray tracing unavailable and its reason. Intel Macs are not supported; Apple Silicon is the target.
Does Rockstar Shaders run on Windows or Linux?
No. The ray tracing is a Metal side-car and the release has only been run on one Apple M4 Max. Windows, Linux and Intel Macs are not supported and have not been tried.