Viewfinder

Viewfinder

A shader debugging mod for Iris on Fabric that exposes an MCP server and in-game commands for AI agents to inspect, test, and automate shader development workflows.

Features

• Shader reload and error list – trigger shader reloads and capture compilation errors
• On-demand GPU profiles – collect hierarchical per-pass timings over a fixed frame window without permanent query overhead
• Pipeline and program inspection – observe nested Iris passes and reflect linked program uniforms, UBOs, and SSBOs
• Texture dumping – inspect or export main/alternate colortex, depth, shadow, noise, and custom textures
• SSBO buffer dumping – dump shader storage buffer objects to disk for analysis
• Screenshot scheduling – schedule screenshots with configurable frame delay (for PT)
• Patched shader listing – find which patched shader errored programmatically by listing all and searching for “errored”
• Interactive chat output – copy paths, open dumped files, and insert follow-up commands from chat
• Agent diagnostics snapshot – one JSON payload with shaderpack, render, errors, metrics, textures, SSBOs, and suggested next actions
• Bounded inspection probes – inspect texture stats/pixels and SSBO byte previews before dumping large GPU resources
• Pass output capture – export framebuffer attachments at the end of a selected Iris pass
• Shader mutation – edit directory-pack sources or options and reload with structured diagnostics
• Deterministic scenes – position the authoritative singleplayer player, set time/weather, and freeze or step ticks

Installation

1. Install Fabric Loader for Minecraft 26.1 or 26.2
2. Install Fabric API and Iris (which requires Sodium)
3. Drop the Viewfinder .jar matching your Minecraft version into your mods/ folder
4. For MCP installation, check the repo.

Usage

In-game commands

All commands are registered under /viewfinder:

| Command | Description |
|—|—|
| /viewfinder status | Show current shaderpack name, error count, and MCP address |
| /viewfinder snapshot | Summarize the agent diagnostics snapshot |
| /viewfinder reload | Reload shaders and report any compilation errors |
| /viewfinder errors | List all captured shader errors |
| /viewfinder errors all | List the full captured error buffer |
| /viewfinder errors clear | Clear captured shader errors |
| /viewfinder screenshot [frames] | Take a screenshot (optionally delayed by N frames) |
| /viewfinder screenshot result | Show the path of the last screenshot |
| /viewfinder metrics | Display the last captured GPU timings |
| /viewfinder metrics capture [frames] | Profile the next fixed number of frames |
| /viewfinder metrics reset | Clear collected GPU timing samples |
| /viewfinder ssbo list | List active SSBO buffers |
| /viewfinder ssbo inspect <index> [bytes] | Preview SSBO bytes as hex, int, uint, and float values |
| /viewfinder ssbo dump <index> | Dump an SSBO buffer to ssbo_dumps/ |
| /viewfinder texture list | List available colortex and custom textures |
| /viewfinder texture inspect name <name> [samples] | Probe texture metadata, samples, and channel statistics by name |
| /viewfinder texture inspect id <id> [samples] | Probe texture metadata, samples, and channel statistics by GL id |
| /viewfinder texture sample name <name> <x> <y> [z] | Read a specific texture pixel by name |
| /viewfinder texture sample id <id> <x> <y> [z] | Read a specific texture pixel by GL id |
| /viewfinder texture dump name <name> [raw] | Dump a texture by name (PNG or raw) |
| /viewfinder texture dump id <id> [raw] | Dump a texture by GL id (PNG or raw) |
| /viewfinder patched_shaders | List Iris patched shader files |

Chat output uses clickable controls where Minecraft supports them: dumped file paths can be opened or copied, list output includes dump command suggestions, and captured errors include copy buttons for full messages and stack traces.

MCP server

When the Minecraft client starts, Viewfinder automatically starts a stateless Streamable HTTP MCP server at:

http://127.0.0.1:7150/mcp