Перейти к содержимому
Mineforgian

Vulkan PostFX

Experimental VPFX shader pack loader and post-processing framework for Minecraft’s modern Vulkan-based rendering path.

Загрузки
13K
Подписчики
23
Обновлён
10 июля 2026 г.
Лицензия
Vulkan-PostFX-License-v1.2

Опубликован 11 апреля 2026 г.

Исходный кодСообщить об ошибке

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

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.

Ченджлог

1.15.11+mc26.2-2026-07-10Релиз26.2 · 10 июля 2026 г.

Vulkan PostFX 1.15.11

This release focuses on the native VPFX render target lifecycle, improving performance, resource safety, temporal effect correctness, and backend fallback reliability.

Highlights

  • Native render targets are now reused across frames instead of being recreated every frame.
  • Render target resources are now owned by the active VPFX session.
  • History and persistent targets are isolated between pack activations.
  • History buffers now advance only when their target was actually written during the frame.
  • Native runtime failures continue to fall back safely to Minecraft PostChain.

Added

  • Added a session-scoped native render target resource manager.

  • Added reusable caching for:

    • Scene color snapshots
    • Transient render targets
    • Persistent render targets
    • History targets
    • Cross-frame ping-pong targets

  • Added immutable native target descriptors containing:

    • Target identifier
    • Width and height
    • Texture format
    • Depth usage
    • Target type

  • Added native resource lifecycle statistics:

    • Allocations
    • Reuses
    • Recreations
    • Disposals
    • Allocation failures
    • Active owned resources
    • Active borrowed resources
    • Resource generation

  • Added native target statistics to the VPFX debug HUD.

  • Added lifecycle validation tests for resource reuse, resizing, failures, history state, session isolation, and fallback behavior.

Changed

  • Native render targets now remain allocated for the lifetime of the active VPFX session when their descriptors remain unchanged.

  • The meaning of a transient target has been clarified:

    • Its contents do not persist between sessions.
    • Its GPU allocation may still be reused between frames.

  • Persistent, history, and ping-pong resources are now fully session-scoped instead of being stored globally by runtime namespace.

  • Render target recreation now follows a safer sequence:

Create the replacement resource
→ Replace the cached reference
→ Destroy the previous resource

  • Native fallback now immediately releases native resources owned by the failed session.

  • Re-selecting the same shader pack still creates a new session and retries the native runtime.

  • Frame render target wrappers are now explicitly non-owning.

    • GPU resource destruction is handled exclusively by the session resource manager.

  • Native clear behavior is now more deterministic:

    • Transient targets are cleared on their first write each frame.
    • Subsequent writes during the same frame preserve existing contents.
    • Persistent and history buffers are initialized when created or resized.
    • Depth targets use a default clear depth of 1.0.

  • Clear-color values are now defensively copied to prevent accidental shared-state modification.

Fixed

  • Fixed native render targets being repeatedly created and destroyed every frame.
  • Fixed old sessions potentially interfering with resources created by a new activation of the same pack.
  • Fixed resource leaks when only part of a history or ping-pong target pair could be created.
  • Fixed failed target recreation destroying the previous valid resource too early.
  • Fixed failed allocations leaving incomplete cache entries.
  • Fixed disposed native sessions silently returning to per-frame target allocation.
  • Fixed native resources remaining allocated after the current session fell back to PostChain.
  • Fixed history buffers sampling undefined memory on their first frame.
  • Fixed failed frames incorrectly advancing history state.
  • Fixed history and ping-pong targets being recreated without correctly invalidating previous history.
  • Fixed native target format changes incorrectly reusing an incompatible cached target.
  • Fixed persistent and history targets being reported as externally borrowed resources.
  • Fixed per-frame logging caused by reused persistent targets.
  • Fixed mutable default clear-color arrays being exposed to callers.
  • Fixed history targets advancing even when no pass wrote to them during the frame.

History Buffer Correctness

History and cross-frame ping-pong targets now advance only when both conditions are met:

  1. The native frame completes successfully.
  2. The specific target was actually written during that frame.

Targets that were not written retain their previous:

  • Read buffer
  • Write buffer
  • History validity state

This prevents temporal effects from accidentally sampling cleared, stale, or unwritten buffers.

Resource Ownership

VPFX now distinguishes between resources it owns and resources borrowed from Minecraft or other systems.

VPFX-owned resources

  • Scene color snapshots
  • Transient render targets
  • Persistent render targets
  • History buffer pairs
  • Cross-frame ping-pong buffer pairs
  • Diagnostic native targets

Borrowed resources

  • Minecraft main framebuffer
  • Scene depth
  • Shadow depth
  • External runtime textures

Borrowed resources are never destroyed by VPFX.

Validation

The native target lifecycle validation suite now contains 36 passing checks, covering:

  • Resource reuse
  • Resize recreation
  • Format changes
  • Allocation failure recovery
  • Partial double-buffer creation rollback
  • Session disposal
  • Same-namespace session isolation
  • Delayed old-session fallback
  • History initialization and commit behavior
  • Native fallback cleanup
  • Pack switching
  • Clear-color isolation
  • History commit gating

Notes

  • Ping-pong targets currently use cross-frame double buffering.
  • Same-frame multi-pass ping-pong alternation is not yet supported.
  • This release does not add new built-in visual effects.
  • VPFX continues to prefer the native runtime and falls back to Minecraft PostChain only for the current failed activation.
  • Selecting the pack again will retry the native backend.
1.15.9+mc26.2-2026-07-07Релиз26.2 · 7 июля 2026 г.

Vulkan PostFX 1.15.9

Highlights

This update focuses on loader stability, native-first backend selection, and VPFX pack validation. VPFX is still a post-processing shader loader, not a built-in shader pack.

Added

  • Added an internal Runtime Graph system for VPFX packs.

    • VPFX packs can now be parsed into a backend-neutral runtime structure before execution.
    • This improves validation, debugging, and future backend support.

  • Added support for VPFX uniform bindings.

    • Supported binding types:

      • $param:<id> for user parameters
      • $builtin:<id> for built-in runtime values
      • $target:<id> for render targets

  • Added detailed VPFX pack load results.

    • Pack loading now records clearer failure stages such as:

      • manifest parsing
      • graph parsing
      • graph validation
      • runtime graph building
      • shader preprocessing
      • resource resolving

  • Added additional validation for VPFX pack definitions.

    • Invalid parameter references
    • Unknown built-in uniforms
    • Missing render targets
    • Invalid pass dependencies
    • Unsafe or unsupported graph definitions

Changed

  • VPFX now follows a clearer native-first backend policy.

    • Every time a VPFX pack is selected or refreshed, the loader will try the native runtime first.
    • If the native runtime fails for that activation, VPFX falls back to the Minecraft PostChain backend.
    • The failure is not treated as a permanent blacklist.
    • Selecting the same pack again will retry the native runtime.

  • Improved backend selection behavior.

    • Backend selection is now treated as a per-activation decision.
    • Previous native runtime failures are cleared when refreshing the active pack.

  • Improved PostChain materialization.

    • VPFX-only metadata fields are removed before generating Minecraft PostChain resources.
    • This prevents loader-only fields such as uniform binding metadata from leaking into vanilla PostChain JSON.

Fixed

  • Fixed cases where a previous native runtime failure could affect later activations of the same pack.
  • Fixed unclear fallback behavior between the native runtime and Minecraft PostChain backend.
  • Fixed several pack validation paths where invalid VPFX pack definitions could fail too late.
  • Fixed internal handling for VPFX-specific uniform binding metadata during resource rewriting.

For Pack Authors

This release improves error visibility for VPFX pack development. Broken packs should now fail with clearer diagnostics instead of silently falling back or crashing at a later runtime stage.

Recommended checks for pack authors:

  • Make sure all $param:<id> bindings reference declared parameters.
  • Make sure all $target:<id> bindings reference valid render targets.
  • Avoid relying on undefined built-in uniforms.
  • Test native runtime behavior and PostChain fallback separately.

Notes

This release does not add new built-in visual effects. The main goal of 1.15.9 is to make the VPFX loader core more stable, more debuggable, and safer for future native backend development.

1.15.8+mc26.3-snap1-2026-06-25Релиз26.3-snapshot-1 · 25 июня 2026 г.

Add homepage and issues page. Writing colored lighting.

1.15.7+mc26.3-snap1-2026-06-25Релиз26.3-snapshot-1 · 25 июня 2026 г.

Vulkan PostFX 1.15.7+mc26.3-snapshot1-2026-06-25

Add more language support. Add diagnostion part. Fix some bugs.

1.15.6+mc26.2-2026-06-23Релиз26.2 · 23 июня 2026 г.

Vulkan PostFX 1.15.6 Changelog

Added

  • Added the native-first safe fallback runtime strategy.

    • VPFX now attempts to use the native direct backend first.
    • If the native backend is unsupported, fails preparation, or fails during frame execution, VPFX automatically falls back to the Minecraft PostChain backend.
    • Native backend failures no longer disable the active VPFX pack by default.

  • Added native fallback stage tracking.

    • VPFX can now report where the fallback happened:

      • SUPPORT_CHECK
      • PREPARE
      • FRAME_EXECUTION

    • HUD and diagnostics can now display the native fallback reason.

  • Added initial Pack Validation UI support.

    • Invalid VPFX packs are now shown in the pack list instead of being silently ignored.
    • Invalid packs are marked as Invalid.
    • Clicking an invalid pack copies a validation report for easier debugging and issue reporting.

  • Added scan-stage issue tracking for VPFX packs.

    • Missing pack.json
    • Manifest parse failures
    • Graph parse failures
    • Missing shaders
    • Fatal validation errors
    • ZIP read failures

Changed

  • Changed VPFX backend selection to prefer native direct execution while keeping Minecraft PostChain as the safe fallback backend.

  • Changed native backend failure handling so that native failures fall back to PostChain instead of failing the whole pack.

  • Changed ZIP pack scanning so broken VPFX packs are preserved as invalid UI entries.

  • Changed the shader pack selection screen to use VpfxPackListEntry, allowing packs to be displayed as:

    • VALID
    • WARNING
    • INVALID

  • Improved fallback diagnostics shown in HUD, UI services, and failure reports.

Fixed

  • Fixed native direct backend failures incorrectly disabling the active VPFX pack.
  • Fixed native frame execution failures potentially causing black screens or broken rendering state.
  • Fixed missing native fallback stage information in diagnostics.
  • Fixed invalid VPFX ZIP packs being silently skipped during scanning.
  • Fixed missing shader, missing target, malformed graph, and broken manifest errors not being visible from the UI.
  • Fixed scan-stage exceptions potentially disrupting the whole pack list.

Removed

  • Removed the old behavior where invalid VPFX packs were silently ignored during scanning.
  • Removed the old behavior where native backend failure could immediately mark the active VPFX pack as failed.
  • Removed several log-only error paths by surfacing pack validation issues through the UI instead.

Developer Notes

This release focuses on VPFX v0.2 stabilization. The main goal is not to add new visual effects, but to improve backend reliability, automatic fallback behavior, and pack author debugging.

Recommended test cases:

  • A VPFX pack that works on the native backend.
  • A VPFX pack that cannot use native but works on PostChain.
  • A pack with a missing shader file.
  • A pack with an invalid graph target reference.
  • A ZIP pack with a missing or malformed pack.json.
1.15.5+mc26.2-2026-06-22Релиз26.2 · 22 июня 2026 г.

Vulkan PostFX 1.15.5

Changes

  • Added entity shadow casters for VPFX shadow depth.
  • Disabled vanilla circular entity shadows while VPFX world shadows are active.
  • Fixed shadow-space coordinate handling so shadow rendering no longer depends on player view direction.
  • Improved shadow receiver stability and reduced terrain-side shadow artifacts.
  • Fixed several bugs.
1.15.4+mc26.2-2026-06-21Релиз26.2 · 21 июня 2026 г.

Vulkan PostFX 1.15.4

This update fixes several bugs and improves overall stability.

Fixed

  • Fixed some shader pack selection screen issues.
  • Fixed the VPFX status HUD toggle not following the UI setting.
  • Fixed external shader packs not properly overriding built-in shadow behavior.
  • Fixed several minor UI layout issues.

Changed

  • Improved shader pack loading and UI behavior.
1.15.4+mc26.2-2026-06-19Релиз26.2 · 19 июня 2026 г.

Fixed some known bugs.

Комментарии

Загружаем…