Vulkan PostFX

Vulkan PostFX is an experimental VPFX shader pack loader and post-processing framework for Minecraft's modern Vulkan renderer.

It allows external VPFX shader packs to add screen-space visual effects such as color grading, vignette, tone mapping, highlight compression, cinematic look adjustments, and depth/shadow-based experiments.

The project is still experimental, but it already supports external ZIP-based VPFX packs through Minecraft's resource pipeline.

---

Start here

For the best first experience, install:

• Vulkan PostFX — the loader/runtime
• VPFX Minimal Showcase — the official minimal example pack

Vulkan PostFX is not a full Iris / OptiFine replacement.
The goal is to build a new VPFX workflow for Minecraft’s Vulkan rendering path, starting from reliable external pack execution and gradually moving toward a more complete shader runtime.

---

Current Progress

Vulkan PostFX already supports:

• scanning external ZIP shader packs under run/shaderpacks/
• reading and parsing pack.json
• selecting the active pack via active_pack_id
• validating VPFX graph structure
• resolving shader references such as <pack_id>:<path>
• supporting non-post/ shader paths
• shader include preprocessing
• materializing external ZIP packs into runtime resource packs
• injecting runtime resource packs into Minecraft’s resource system
• loading external post chains through ShaderManager
• sampling minecraft:scene_color
• capturing scene depth
• providing experimental shadow depth input
• writing VPFX failure diagnostics for broken packs
• running an early experimental native fullscreen passthrough path

This means the project is no longer just “reading ZIP files” or “pretending to load packs.” It already implements:

external ZIP shader pack
  -> VPFX validation
  -> runtime resource pack
  -> external post chain execution

And experimentally:

minecraft:main
  -> transientColor
  -> builtin native fullscreen passthrough
  -> minecraft:main

---

Project Positioning

What this is

Vulkan PostFX is an experimental shader pack loader and visual runtime for the modern Minecraft Vulkan backend.

It currently focuses on:

• screen-space post-processing
• VPFX shader pack loading
• runtime resource pack materialization
• scene color / depth / shadow inputs
• diagnostics for broken packs
• early native runtime experiments

What this is not

Vulkan PostFX is not yet a mature drop-in replacement for Iris or OptiFine.

It does not currently provide full traditional shader pipeline compatibility, and most Iris / OptiFine shader packs cannot be used directly without porting.

A more accurate description of the current state is:

• a working VPFX ZIP shader pack loader
• a post-effect based execution backend
• an experimental Vulkan shader runtime foundation
• an early native runtime research project

---

Implemented Features

1. External VPFX Pack Loading

Supports loading ZIP-based VPFX shader packs containing:

• pack.json
• post_effect/main.json
• shaders/<path>.vsh
• shaders/<path>.fsh
• optional textures and include files

Shader references use:

<pack_id>:<path>

For example:

vpfx_minimal_showcase:composite/final

which resolves to:

shaders/composite/final.vsh
shaders/composite/final.fsh

---

2. Runtime Namespace Rewriting

External packs are rewritten into isolated runtime namespaces to avoid conflicts with built-in resources and other packs.

---

3. Runtime Resource Pack Injection

External ZIP contents are materialized into runtime resource packs during startup / resource reload and injected into Minecraft’s client resource system.

---

4. External Post Chain Execution

Vulkan PostFX can load external post chains through Minecraft’s ShaderManager and execute them through the current minecraft_postchain backend.

---

5. Scene / Depth / Shadow Inputs

Current VPFX runtime inputs include:

minecraft:scene_color
vulkanpostfx:scene_depth
vulkanpostfx:shadow_depth
minecraft:main

These are used for scene-color effects, depth-based experiments, and shadow-depth debugging.

---

6. Failure Diagnostics

When a VPFX pack fails to load or execute, Vulkan PostFX can generate diagnostic information to help identify issues such as:

• missing shader files
• invalid graph targets
• sampler mismatch
• shader path errors
• external target problems
• pipeline creation failures

---

7. Experimental Native Runtime Milestone

Vulkan PostFX is gradually moving beyond Minecraft’s PostChain backend.

Current experimental native runtime progress includes:

• native runtime support checks
• resource mapping dry-run
• same-target hazard detection
• transient color target planning
• mainTarget -> transientColor copy validation
• builtin native fullscreen passthrough draw
• opt-in diagnostic mode that can skip the external PostChain path after a successful native passthrough draw

This is still experimental and opt-in.

User VPFX shaders are not fully executed natively yet.

---

Current Available Sample

VPFX Minimal Showcase

The official minimal example pack demonstrates:

• VPFX pack.json
• graph-based post effect configuration
• non-post/ shader paths
• minecraft:scene_color sampling
• minecraft:main output
• basic screen-space look adjustment

It is the recommended starting point for testing Vulkan PostFX.

---

Usage

1. Place a shader pack

Put the ZIP shader pack into:

run/shaderpacks/

A template/example pack is available on the project page.

---

2. Select the active pack

Edit the config file:

run/config/vulkanpostfx.json

Example:

{
  "active_pack_id": "vpfx_minimal_showcase"
}

---

3. Launch the game

When the client starts, the loader will:

• scan ZIP files
• parse available VPFX packs
• select the active pack
• validate the graph
• materialize runtime resources
• inject runtime resources into the client resource system
• attempt to load the corresponding external post chain

---

4. Toggle the effect

By default, press:

F8

to toggle the current VPFX effect.

Press:

F9

to toggle the experimental shadow depth debug view.

---

Architecture Overview

[shaderpacks/*.zip]
        |
        v
[VPFX Manifest / Graph Parse]
        |
        v
[Active Pack Selection]
        |
        v
[Runtime Materialization]
        |
        v
[Runtime Resource Pack Injection]
        |
        v
[minecraft_postchain backend]
        |
        v
[External VPFX Post Chain Execution]

Experimental native runtime path:

[VPFX Native Runtime]
        |
        v
[mainTarget -> transientColor]
        |
        v
[builtin native fullscreen passthrough]
        |
        v
[minecraft:main]

---

Current Limitations

Vulkan PostFX is still alpha software.

Not fully supported yet

The following traditional shader pipeline components are not fully supported:

• gbuffers_*
• full shadow.* compatibility
• full composite.* compatibility
• screen-space reflections
• volumetric fog
• natural cloud rendering
• material-aware lighting
• dimension-specific shader routing such as world1/ and world-1/
• direct Iris / OptiFine shader pack compatibility

Native Runtime Limitations

The native runtime currently supports only an experimental builtin fullscreen passthrough path.

It does not yet support:

• user shader native execution
• multi-pass native execution
• custom native render targets
• native scene depth input
• native shadow depth input
• compute shaders
• native volumetric lighting
• native cloud rendering
• RT / path tracing

---

Most Suitable Development Direction Right Now

The recommended next steps are:

1. improve VPFX pack authoring workflow
2. continue validating screen-space look layers
3. improve final-pass translation quality
4. implement user shader native execution
5. gradually introduce native multi-pass graphs
6. expand depth and shadow support
7. eventually explore lighting, clouds, and RT-lite experiments

---

Design Philosophy

The core idea of Vulkan PostFX is not to force all traditional shader semantics into Vulkan at once.

Instead:

first establish a truly executable external shader chain, then gradually bring back the visual logic that matters.

In practice, that means:

• first make external VPFX packs actually run
• then improve visual fidelity
• then expand the runtime
• then gradually approach more advanced shader pipeline capabilities

---

Notes

This is still a fast-evolving experimental project.

If you are looking for a ready-made, fully compatible Iris / OptiFine replacement, Vulkan PostFX is not there yet.

But if you care about:

• Minecraft’s Vulkan renderer
• VPFX shader pack experiments
• external ZIP shader pack loading
• modern runtime resource pack injection
• scene/depth/shadow based post effects
• experimental native render graph runtime development

then this project is built exactly for that.

---

Update Policy

This mod is expected to follow Minecraft snapshot updates quickly.

The project may update weekly, or more often when Minecraft snapshots or VPFX runtime milestones require it.