Vulkan PostFX

Vulkan PostFX, also known as VPFX, is an experimental VPFX shader pack loader and post-processing framework for Minecraft’s modern Vulkan-based rendering path.

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

This project is still experimental, but it already supports ZIP-based VPFX shader packs through Minecraft’s resource pipeline.

---

Start here

For the best first experience, install both:

• Vulkan PostFX — the loader and 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 loading and gradually moving toward a more capable shader runtime.

---

What Vulkan PostFX does

Vulkan PostFX currently focuses on:

• external ZIP-based VPFX shader pack loading
• graph-based post-processing configuration
• runtime resource pack materialization
• runtime resource pack injection
• external post-chain execution
• scene color sampling
• scene depth capture
• experimental shadow depth input
• diagnostics for broken packs
• early native runtime experiments

This means Vulkan PostFX is already executing a real external VPFX pack pipeline, not just parsing ZIP files.

external ZIP shader pack
  -> VPFX manifest / graph validation
  -> runtime resource pack materialization
  -> Minecraft resource system injection
  -> external post-chain execution

---

Current features

External VPFX pack loading

Vulkan PostFX supports ZIP-based VPFX shader packs containing files such as:

pack.json
post_effect/main.json
shaders/<path>.vsh
shaders/<path>.fsh

Shader references use the following format:

<pack_id>:<path>

For example:

vpfx_minimal_showcase:composite/final

which resolves to:

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

Shader paths are not limited to a fixed post/ directory layout.

---

Runtime namespace rewriting

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

This allows VPFX packs to behave more like external visual packages while still being routed through Minecraft’s resource system.

---

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.

This is one of the core parts of the VPFX loading pipeline.

---

External post-chain execution

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

The current stable execution path is still based on Minecraft’s post-chain system.

---

Scene, depth, and shadow inputs

Current VPFX runtime inputs include:

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

These inputs are used for screen-space effects, depth-based experiments, and shadow-depth debugging.

---

Failure diagnostics

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

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

If a pack is broken, the goal is to make the failure understandable instead of silently failing.

---

Experimental native runtime

Vulkan PostFX is gradually moving beyond Minecraft’s default post-chain backend.

Current experimental native runtime progress includes:

• native runtime support checks
• resource mapping dry-runs
• same-target hazard detection
• transient color target planning
• mainTarget -> transientColor copy validation
• builtin native fullscreen passthrough draw
• opt-in diagnostic mode for testing the native passthrough path

The current experimental native path can be summarized as:

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

This is still experimental and opt-in.

User VPFX shaders are not fully executed natively yet.

---

Current sample pack

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 VPFX shader pack

Put the VPFX shader pack ZIP into the shaderpacks folder of your Minecraft instance.

For development runs, this is usually:

run/shaderpacks/

---

2. Select the active pack

Edit the config file:

config/vulkanpostfx.json

For development runs, this is usually:

run/config/vulkanpostfx.json

Example:

{
  "active_pack_id": "vpfx_minimal_showcase"
}

---

3. Launch the game

When the client starts, Vulkan PostFX will:

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

---

4. Toggle effects

By default:

F8

toggles the current VPFX effect.

F9

toggles the experimental shadow depth debug view.

---

Architecture overview

Current external pack path:

[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]

---

What this is

Vulkan PostFX is currently best described as:

• 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

It is designed for Minecraft’s modern Vulkan rendering path and for VPFX-specific shader packs.

---

What this is not

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

Most Iris / OptiFine shader packs cannot be used directly without porting.

Traditional shader pipeline compatibility is not the current focus of the first development stages.

---

Current limitations

Vulkan PostFX is still alpha software.

The following traditional shader pipeline components are not fully supported yet:

• 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

---

Development roadmap

The recommended development direction is:

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

---

Design philosophy

The core idea of Vulkan PostFX is not to force every traditional shader-pack semantic into Vulkan at once.

Instead, the project follows a staged approach:

make external VPFX packs actually run
  -> improve visual fidelity
  -> stabilize the runtime
  -> expand graph execution
  -> gradually bring back advanced visual features

In other words:

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

---

Notes

This is 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 rendering path
• 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

Vulkan PostFX 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.