# Viewfinder A shader debugging mod for [Iris](https://irisshaders.dev/) 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](https://fabricmc.net/) for Minecraft 26.1 or 26.2 2. Install [Fabric API](https://modrinth.com/mod/fabric-api) and [Iris](https://modrinth.com/mod/iris) (which requires [Sodium](https://modrinth.com/mod/sodium)) 3. Drop the Viewfinder `.jar` matching your Minecraft version into your `mods/` folder 4. For MCP installation, [check the repo](https://github.com/xirreal/viewfinder). ## 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 [bytes]` | Preview SSBO bytes as hex, int, uint, and float values | | `/viewfinder ssbo dump ` | Dump an SSBO buffer to `ssbo_dumps/` | | `/viewfinder texture list` | List available colortex and custom textures | | `/viewfinder texture inspect name [samples]` | Probe texture metadata, samples, and channel statistics by name | | `/viewfinder texture inspect id [samples]` | Probe texture metadata, samples, and channel statistics by GL id | | `/viewfinder texture sample name [z]` | Read a specific texture pixel by name | | `/viewfinder texture sample id [z]` | Read a specific texture pixel by GL id | | `/viewfinder texture dump name [raw]` | Dump a texture by name (PNG or raw) | | `/viewfinder texture dump 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: ```text http://127.0.0.1:7150/mcp ```