voxelcore/doc/en/scripting/builtins/libgfx-posteffects.md
ostermine 89bdadd6aa render the world relative to an origin near the camera
World coordinates were passed to GPU as floats: u_model of a chunk and
of a model had the world translation, vertices of translucent blocks,
particles, precipitation, block wrappers, lines and 3D texts were built
in the world space, and the camera position was subtracted in shaders.
The float step grows with the distance from the world origin (6 cm at
1M blocks, 2 m at 30M): blocks got skewed, then stuck together.

Camera::getOrigin() is an integer point near the camera (X and Z are
rounded to 1024 blocks, Y is 0). Camera::getView() is relative to it,
and every position passed to GPU is "world - origin" calculated on CPU,
so the shaders keep working with small numbers and do not change:
u_cameraPos, a_modelpos, u_inverseView and the shadows matrices are in
the same space as before, shifted by the origin. Matrices of a shadow
map are converted from the origin of its camera to the origin of the
player camera. The clouds shader gets the origin wrapped by the period
of its waves, the waves stay bound to the world.

Vertices of translucent blocks are local to the chunk now, as vertices
of opaque ones, and drawn with u_model of the chunk.
2026-11-12 10:05:06 +03:00

2.1 KiB

gfx.posteffects library

A library for post-processing effects control.

The effect slot is a resource and must be declared in resources.json in the root directory of the pack:

{
    "post-effect-slot": [
        "slot_name"
    ]
}
-- Returns the index of the effect slot by name (pack:slot_name).
-- If the specified slot does not exist, returns -1
gfx.posteffects.index(name: str) --> int

-- Assigns the effect to the slot
gfx.posteffects.set_effect(slot: int, effect: str)

-- Returns the effect intensity (from 0.0 to 1.0)
-- If the slot is empty, returns 0.0
gfx.posteffects.get_intensity(slot: int) --> number

-- Sets the effect intensity (from 0.0 to 1.0)
-- (The correctness of processing the parameter between 0.0 and 1.0 
-- depends on the effect)
gfx.posteffects.set_intensity(slot: int, intensity: number)

-- Returns true if the slot is not empty and the effect intensity is non-zero
gfx.posteffects.is_active(slot: int) --> bool

-- Sets parameters values ('param' directives)
gfx.posteffects.set_params(slot: int, params: table)

-- Sets values to an array
gfx.posteffects.set_array(
    -- effect slot index
    slot: int,
    -- parameter (array) name
    name: str
    -- data
    data: Bytearray
)

-- Example of filling an array `#param vec3 u_arrayName[64]`:
local buffer = Bytearray(0)
for i = 0, 63 do
    local x = math.random() * 2.0 - 1.0
    local y = math.random() * 2.0 - 1.0
    local z = math.random() * 2.0 - 1.0
    Bytearray.append(buffer, byteutil.pack("fff", x, y, z))
end
gfx.posteffects.set_array(slot, "u_arrayName", Bytearray_as_string(buffer))

Coordinates in shaders

World-space values available in shaders (u_cameraPos, u_view, u_inverseView, positions of vertices and models) are relative to the rendering origin, not to the world origin. The rendering origin is an integer point near the camera: its X and Z are multiples of 1024 blocks, Y is 0. This keeps float precise far from the world origin.

Directions, distances and positions relative to the camera do not depend on the rendering origin. Neither does an effect bound to the blocks grid or repeating with a period that divides 1024.