renderFeature.assetType
- README.md58.0 KB
- about.yaml783 B
- behavior.luau792 B
- inspector.luau5.2 KB
- shared.module
- template
- type.yaml3.8 KB
This package holds more than this page lists. See all of its files in its world.
README.md
renderFeature
A render feature inserts custom GPU passes into the frame pipeline. The engine provides one generic capability — a per-frame render-pass queue and a set of pipeline-phase insertion points — and a feature is the authored Luau that decides what passes to enqueue, and where, every frame.
Authoring contract
A .renderFeature folder holds an init.luau that returns a feature module:
return {
setup = function(ctx) -- optional; runs once when the feature goes live
-- A "fragment" pass's `shader` names a POST EFFECT, not a `.shader`
-- guid directly — postprocess.add compiles the shader asset under
-- that name once, here. Enqueueing a name never passed to
-- postprocess.add runs the pass as a no-op every frame (the log
-- reads "effect '<name>' not compiled — pass skipped").
postprocess.add("my_effect", asset.resolve("my.shader.guid", "shader"), { enabled = false })
end,
render = function(ctx) -- required; runs every frame
-- enqueue one or more passes. The spec shape depends on `kind` (see
-- "Pass kinds" below): this is a "fragment" pass (full-screen shader over
-- input textures); a mesh effect (outline, x-ray) is a "geometry" pass
-- with `material` + `select` (see "Geometry passes").
ctx.enqueue {
phase = "afterTransparent",
shader = "my_effect",
inputs = { src = "@scene.color" },
output = myRenderTargetGuid,
}
end,
teardown = function(ctx) end, -- optional; runs once when the feature is destroyed
}
Optional materials/ and shaders/ subfolders hold shader source the feature
constructs GPU programs from. A feature constructs its GPU programs (it does not
reference .material surface assets).
ctx
Built fresh each frame and passed to setup / render / teardown:
| Field | Meaning |
|---|---|
ctx.enqueue(spec) | Queue one render pass for the current frame. |
ctx.viewport | { w, h }: the size the main viewport's scene rasterized at, in pixels (renderer.rasterSize(): the viewport taken down by the render scale). |
ctx.time | Seconds since boot. |
ctx.frame | Monotonic frame index. |
ctx.renderPath | "forward" / "deferred" / … — branch passes on the active path. |
ctx.settings | The feature's knobs as they stand this frame — see "Settings". |
Settings
A feature declares the knobs it takes as settings, each a Field descriptor
with a default, the way a component declares its public fields:
local Fields = require("@builtin::modules.field")
local Field, NoSync = Fields.Field, Fields.NoSync
return {
settings = {
intensity = Field.number(1.0, NoSync, "How much of the effect reaches the image."),
quality = Field.enum({ "low", "high" }, "high", NoSync, "How many samples the pass spends."),
},
render = function(ctx)
local s = ctx.settings -- { intensity = 1.0, quality = "high" }, or what a caller set
...
end,
}
The engine holds one settings table per live feature — every declared default,
overridden by what it was handed — and passes it as ctx.settings on every
setup / render / teardown. A feature reads its knobs there and nowhere
else, so any caller tunes any feature by name:
local h = renderer.feature.create(ref, { settings = { intensity = 0.5 } })
renderer.feature.configure(h, { quality = "low" }) -- lays over the rest
renderer.feature.settings(h) -- { intensity = 0.5, quality = "low" }
renderer.feature.find(ref) -- the live handle, or nil
renderer.feature.schema(ref) -- the declared knobs, unrun
A knob the feature does not declare, or a value of the wrong shape, is refused
by name. A scene authors its features on one RenderFeatures entity — a list
of features, each with its settings — which adopts a feature already live
rather than stacking a second, and takes every one down on disable and destroy.
render runs once per frame; the passes it enqueues run once per render
target drawn that frame — the live viewport, every offscreen capture, every
RTT camera — each at its own resolution. So ctx.viewport is the main
viewport's size, not the size of the target a pass ends up drawing into. Size a
full-screen scratch RT with screen = true and let the engine track the drawn
target (see "Screen-sized targets") rather than deriving it from ctx.viewport.
Screen-sized targets
renderer.texture.create { screen = true } marks a feature RT as full-screen:
before each render target's feature passes, the engine resizes it to that
target's resolution. Create it once — the engine owns its size from then on:
myRt = renderer.texture.create {
width = ctx.viewport.w, height = ctx.viewport.h, -- initial size only
screen = true, format = "rgba16f", name = "my_effect",
}
A target that holds a picture of the scene is rgba16f, which is what the scene
target itself carries: linear light with headroom above the display's white and
no 256-step floor under a dark gradient. Omitting format on a screen-sized
target asks for the same thing. format = "rgba8" is for a mask, a weight or an
occlusion term, where 0..1 is the whole range — hand one of those back over
@scene.color and the frame loses every highlight and bands every gradient, and
the engine says so in the log.
screenScale (default 1.0) takes a fraction of the drawn target's resolution,
for a scratch that runs below composite resolution (a half-res blur passes 0.5).
A screen-sized RT is what makes a full-screen effect composite correctly at any
resolution. Deriving the size from ctx.viewport instead pins the RT to the main
viewport, and every differently-sized render target then composites a mismatched
scratch — the scene scaled into a corner with the rest black.
screenSpace names WHICH image a screen-sized RT follows:
| value | what it tracks |
|---|---|
"scene" (default) | the scene render target, at whatever resolution the render scale asked for. Resized before EVERY render target's feature phases — the main frame and each offscreen one — and cleared to transparent before an offscreen render, so one sink never reads what another left behind |
"composite" | the image the post-scene phases draw into. Resized on the presented frame only, and never cleared for an offscreen render, since none of those phases run there |
The two carry the same size until the render scale drops below 1. From there,
while the renderer presents the viewport itself, the scene reaches the display's
resolution through an upscale that runs before afterScenePost — so a
composite-space RT is the display's size while a scene-space one is the smaller
rasterized frame. Under a UI viewport panel the panel draws the scene target at
its own rect, nothing upscales beforehand, and both spaces carry the scene's
size.
A scene-space target is scratch: whatever a pass does not rewrite this render is transparent black. A composite-space target survives an offscreen render untouched, but it follows the presented frame alone.
History targets
An accumulation across frames (temporal antialiasing, a temporal denoiser, any pass that reads what it wrote last time) lives in a history target:
history = renderer.texture.create {
width = ctx.viewport.w, height = ctx.viewport.h, -- initial size only
history = true, format = "rgba16f", name = "my_accum",
}
-- in render(ctx):
ctx.enqueue {
kind = "compute", program = myResolve,
inputs = { scene_color = "@scene.color", accum_previous = history.previous.guid },
buffers = { accum_state = history.state },
storage = { accum_out = history.guid },
phase = "afterLighting",
}
The passes a feature enqueues run once for every view the frame draws (the
viewport, each render-to-texture camera, each capture), so an accumulation has
to be one per view. A history target keeps one pair of images per view, sized to
that view: for the length of a view's render history.guid names the image the
render writes and history.previous.guid the image the same view's previous
render wrote. Another view never resizes, clears or overwrites them, and a
view's images are freed when it stops drawing. It follows screenSpace and
screenScale like any screen-sized target; a composite-space one is kept for
the viewport, the one view that draws the post-scene phases.
Before each render of a view the engine writes history.state, one
vec4<f32> a pass binds through buffers:
| field | holds |
|---|---|
x | 1 when previous holds this view's previous image; 0 on the view's first render, its first after a camera cut or a change of size, or after a render of the view that ran without the target, and previous then reads transparent black |
y | how many renders in a row have carried the history |
zw | this render's sub-pixel projection offset, in pixels (renderer.setProjectionJitter) |
renderer.setProjectionJitter is the matching per-view sample sequence: every
view walks it by its own count of renders, so the sequence a temporal pass
expects is the one each view's renders sampled.
Post stages
A post effect belongs to one of the frame's named post stages, in frame
order, each stating what the picture holds there: the space an effect there
reads and writes (light, the scene's own light ahead of the display
transform's exposure and tone curve, display, code values, or encoded, the
presented surface's own values) and the size
the picture is held at (raster, the size the scene rasterized; output, the
size the frame is composed and shown at):
| Stage | Space | Resolution | Runs |
|---|---|---|---|
lighting | light | raster | screen-space lighting terms and what draws into the lit scene: occlusion, reflections, indirect light, contact shadows, decals, splats, outlines, diagnostic views. It spans every phase up to afterLighting, so a pass of a feature declaring it may name one of those phases |
medium | light | raster | participating media: aerial perspective, fog, volumetric light |
preTemporal | light | raster | effects reading the jittered raster before reconstruction: depth of field |
temporal | light | raster | the one temporal reconstruction of the raster (TAA); the stage holds one feature at a time |
postTemporal | light | raster | effects reading the reconstructed picture: motion blur |
meter | light | reduced | measuring the picture: the exposure histogram, a fraction of the raster |
optics | light | raster, then output | lens light: bloom, flare, streaks. Its render features run on the raster; the frame then carries the picture to the output size, and the post-process chain's scene layer runs there |
display | display | output | the display transform, then on code values the temporal upscale, debanding, edge antialiasing and sharpening; the chain's display layer, the film grain last |
ui | display | output | the UI, drawn over the finished picture, then what grades the picture with the UI on it: afterUI passes, the chain's all layer, then afterPost passes |
output | encoded | output | the renderer's output stage alone: the one write of the presented surface, in the surface's encoding, rounded to its bit depth with a blue-noise dither (renderer.output). It takes no render feature and no chain effect |
A feature declares the stage it belongs to, and each pass it enqueues with no
phase runs in that stage, at the stage's phase and its band of orders plus the
pass's own local order (a whole number from 0 to 99):
return {
stage = "postTemporal",
render = function(ctx)
ctx.enqueue { kind = "fragment", shader = "my_effect", inputs = { src = "@scene.color" }, order = 0 }
end,
}
Passes sharing an order run in the order they were enqueued, so a chain of passes over shared targets can run at one order, in sequence.
render runs once a frame, but each view the frame draws (the viewport, a
capture, a render-to-texture camera, an environment cube face) looks at the
world from its own camera, so an order that depends on where the camera stands
is stated per pass rather than chosen in render. A pass that composites
something standing in the world states the world point it stands at as
sortPoint: { x = .., y = .., z = .. }, { x, y, z } or a vector, so an
entity's position is one. Among the passes of one phase sharing one order
that run together (its fragment, compute and raster passes; its geometry
passes, which run ahead of those), the ones stating a point trade the places
they were enqueued in so that every view runs the one farthest from its own
camera first and the nearest last: composites laid over the frame by each of
them leave the nearest in front from wherever the view looks. Depth is
taken along the view (the distance in front of a perspective camera, the depth
into an orthographic one's box). Passes at the same depth keep the order they
were enqueued in, so the passes of one effect stating one point (a march into a
target and the composite reading it) stay together, and a pass stating no
point keeps its place:
for _, item in ipairs(items) do
ctx.enqueue { kind = "compute", program = march, storage = { out = scratch.guid }, order = 2, sortPoint = item.center }
ctx.enqueue { kind = "fragment", shader = composite, inputs = { src = scratch.guid }, blend = true, order = 2, sortPoint = item.center }
end
A draw or splat pass takes no sortPoint, and a value that is not three finite
numbers is refused by ctx.enqueue.
A pass may name a
stage of its own in place of the feature's, placed the same way: a feature
whose work spans two stages declares one and names the other on those passes,
the way temporal antialiasing declares temporal for its resolve and names
display on its sharpening passes. A pass naming both a stage and a phase is refused. A stage the
frame does not have is refused by renderer.feature.create, naming the stages
there are, and a second feature declaring the temporal stage while one stands
in it is refused naming both; the temporal stage takes the passes of the
feature declaring it alone. A pass that names a phase runs at that phase and
order, as below. renderer.post.stages() reports every stage and what stands
in it: a feature by the stage its passes' position falls in, marked declared
where that is the stage the feature declares or a pass names. Every built-in
render feature declares its stage; postStages's README lists where each
built-in effect runs.
Pass phases
enqueue runs a pass at a named pipeline boundary — a real seam between the
scene's discrete passes — ordered within a phase by order. Each phase is the
point where the scene colour holds a specific, nameable state:
| Phase | Scene colour there |
|---|---|
afterDepthPrepass | the visibility raster written: @scene.depth holds this frame's complete opaque depth, and @scene.motion its opaque motion, before anything shades. Scene colour is not yet drawn; @scene.colorHistory holds the previous frame's lit colour, and the deferred g-buffer the previous frame's surfaces (readsPrevious) |
afterShadows | shadow maps populated; scene colour not yet drawn. @scene.depth and @scene.motion hold what the visibility raster laid at afterDepthPrepass |
afterSky | sky only. @scene.depth holds the frame's opaque depth, so a pass here tells the pixels the geometry pass draws over (depth above 0) from the ones that stay sky (depth 0) |
afterOpaque | opaque drawn, before transparents. @scene.depth (and the deferred G-buffer) are populated. Forward: lit opaque. Deferred: lit opaque too, which the geometry pass shades straight into the scene colour, on a render no pass reads or writes @scene.shaded in; on one that does, the opaque surfaces are in the G-buffer's shaded channel, so the colour is still sky only until the composite (use afterOpaqueLit). Radiance stamped into @scene.emissive reaches the colour at the composite |
afterOpaqueLit | the lit opaque scene, still before transparents, on both paths — the forward opaque draw, or the deferred geometry pass and composite. The background a refractive or transmissive surface samples: the one phase whose colour holds what is behind such a surface without holding the surface itself |
afterTransparent | transparents drawn, before the OIT composite |
afterLighting | deferred-lighting + OIT composite done — fully lit, final geometry on both paths |
afterScenePost | the chain's scene layer and the display transform done: display code values, before the chain's display layer and the UI |
afterUI | scene + UI composited |
afterPost | the chain's all layer done — the finished picture in display code values, before the output stage writes it to the surface. A pass here reads that picture as @scene.color and draws over a copy of it |
The last three are the post-scene phases, and they work on the COMPOSITED image:
@scene.color there is the target the UI lands on, not the scene render target.
@scene.depth and @scene.motion still bind — they are the scene's own buffers
for the frame just drawn, which is what lets a pass at these phases reproject the
composite it is handed — but they keep the SCENE's resolution. Whenever the
render scale is below 1 on the presented frame, that is smaller than
@scene.color, so a pass here maps between the two by uv rather than by texel
index, and takes its own output size from the target it writes.
A texture is a texture. A pass's sampled input names any texture the engine
holds by the handle that made it: a render target or a texture
renderer.texture.create returned (its guid), or a storage texture a compute
shader created (ref:createStorageTexture2D, its key). Which one it is decides
nothing about whether the pass accepts it. A pass sees the contents a texture
holds when the pass runs: a compute shader that wrote the texture in an earlier
pass of the same frame, or in a dispatchEx recorded at the start of the frame,
is read by a pass at any later point of the frame, and a pass that reads a
target an earlier phase of the frame draws sees that draw once the phase has run.
The @scene.* inputs (@scene.color, @scene.depth, …) bind the live frame
buffers; the deferred g-buffer channels (@scene.normal, @scene.shaded, …)
resolve only on the deferred path. Before the pass that shades has drawn — at
afterDepthPrepass — a g-buffer channel holds the previous frame's surfaces,
and a pass reading it there names the slot in readsPrevious
(readsPrevious = { "scene_normal" }); one that does not is held back rather
than handed a stale normal. @scene.colorHistory is the lit colour the target's
previous render ended with, kept by the engine per render target and never
cleared by a frame: what a pass tracing at afterDepthPrepass, against this
frame's depth, takes its light from — reprojected through the previous
view-projection @frame.camera carries. A capture drawn once, or a camera drawn
again after a pause, is drawn lit first when a pass reads the history, so its
first frame holds one.
Every @scene.* channel, what it holds, its format, the phase it is first
valid from, and the other names it answers to:
| Name | Holds | Format | Valid from | Also named |
|---|---|---|---|---|
@scene.color | the scene's lit colour; the display composite at a post-scene phase | the scene target's format at a scene phase, the display composite's at a post one | every phase | — |
@scene.depth | opaque depth, reversed (1.0 near, 0.0 far/empty sky) | Depth32Float — binds through a texture_depth compute slot, not texture2d | afterDepthPrepass on | — |
@scene.motion | screen-space NDC velocity since the previous frame | Rg16Float | afterOpaque on | — |
@scene.normal | world-space normal + the per-pixel surface-flag field | Rgb10a2Unorm | deferred path, afterOpaque on (previous frame's before — declare readsPrevious) | — |
@scene.shaded | what a surface SENT — its shaded colour, linear and scene-referred | Rgba16Float | deferred path, afterOpaque on (previous frame's before) | @scene.albedo |
@scene.material | what a surface IS — base colour (RGB565) + metallic + perceptual roughness | Rgba8Uint | deferred path, afterOpaque on (previous frame's before) | @scene.mr |
@scene.emissive | radiance a pass stamped on the surface, added at the composite | Rgba16Float | deferred path, afterOpaque on (previous frame's before) | — |
@scene.ao | scene occlusion a feature wrote, read back by shading: occlusion in r, the bent normal laid flat on the octahedron in g and b, and in a whether a bent normal was written | Rgba8Unorm | every scene phase (cleared at the top of the scene render) | — |
@scene.sunOcclusion | the share of the sun's direct light a feature found taken on the way to each pixel's surface (.rgb, 0 none to 1 all), read back by the sun's term alone | Rgba8Unorm | every scene phase (cleared at the top of the scene render) | — |
@scene.reflection | traced reflection radiance (.rgb) + confidence (.a) | Rgba16Float | every scene phase (cleared at the top of the scene render) | — |
@scene.indirect | the indirect diffuse light the surfaces closing each pixel's hemisphere send it (.rgb, in the ambient term's units) + the share of the closed hemisphere it answers for (.a), read back by the diffuse term through zero_scene_indirect_here; the second layer of the texture @scene.reflection is the first of | Rgba16Float | every scene phase (cleared at the top of every scene render) | — |
@scene.colorHistory | the lit colour the target's previous render ended with | Rgba16Float | every phase | — |
@scene.lights | the punctual-light storage buffer: 1024 light entries of eleven vec4s each (the light, then its projection, which names the shadow record it casts through), the light grid, then the virtual shadow map's region: a shadow record per casting light and their page tables. A loop runs over the first @frame.camera[4].w entries, the lights in use; the buffer's length counts the regions after the lights too, so arrayLength does not size a light loop | storage buffer | every phase | — |
@scene.shadowPool | the depth pool every shadow-casting light renders its shadow pages into, read beside @scene.lights through @builtin::shaderModules.light_shadows (zero_light_shadow): the shadow a point, spot or area light casts at any world point, the one the surfaces take. A frame with a pass reading it keeps the coarsest page of every map of each casting light whose reach meets the view | Depth24Plus — binds through a texture_depth compute slot | scene phases only | — |
@scene.environment | the reflection-probe cube array | texture cube array | scene phases only | — |
@scene.environmentSampler | the filtering sampler for @scene.environment | sampler | scene phases only | — |
@scene.reflectionProbes | the environment buffer: the probe blend data naming which probe reaches a point, then the irradiance light-probe volumes | storage buffer | scene phases only | — |
The rendering and ray-tracing guides (guides { path = "topics/rendering" },
guides { path = "topics/raytracing" }) point here rather than repeating this
table.
Two g-buffer channels describe the surface, and they answer different
questions. @scene.shaded is what a surface SENT — the colour the geometry
pass shaded it to, linear and scene-referred, so a surface lit above the
display's peak reads above 1 there. @scene.material is what the surface IS:
the base colour it reflects, its metallic and its perceptual roughness, each in
[0, 1] and each independent of how brightly the surface happens to be lit. A
pass that multiplies incoming light by a reflectance — a bounce multiplier, a
Fresnel tint, an ambient floor — reads @scene.material; a pass that filters
the picture reads @scene.shaded.
@scene.material is an Rgba8Uint channel packing all three into 32 bits, so
its slot declares sample: uint and the module unpacks it:
# bindings.yaml
- { name: scene_material, kind: texture2d, sample: uint }
#include "@builtin::shaderModules.gbuffer_material"
let m = zero_gbuffer_material(scene_material, coord);
let bounce = incoming * m.base_color;
@scene.albedo is another name for @scene.shaded (the SHADED lit colour) and
@scene.mr for @scene.material (the material channel). The engine logs the
substitution once per name, naming the canonical one to write.
@scene.motion carries screen-space velocity: the NDC displacement each pixel's
surface underwent since the previous frame, so a still surface under a still
camera reads (0, 0). Opaque geometry contributes it on both render paths:
the visibility raster writes it for every surface it records, and an opaque
surface whose depth state the raster cannot express writes its own where it
draws. A moving entity, a moving camera and an animated pose all reach it in
the viewport; transparents, particles and sky carry none. A surface a
material's vertex() hook displaces carries the displacement's own velocity. A render target's own camera and a
capture keep no view history, so velocity there is the entity's motion with no
camera term.
@frame.camera is a reserved buffer input carrying the camera CURRENTLY
being drawn: 14×vec4<f32> = the inverse view-projection (columns [0..4),
column-major) + camera world position ([4].xyz, with the number of lights
@scene.lights holds in [4].w) + the previous render's view-projection
(columns [5..9)), which projects a point into the picture that render left +
the view-projection itself (columns [9..13)), which projects a world point
onto the view being drawn and is the matrix the scene rasterized with + the
sub-pixel offset that matrix carries ([13].xy, in NDC; zero without a
temporal upscale). A compute pass declares a
buffer binding and binds it via inputs = { name = "@frame.camera" }, then
reconstructs a pixel's world position from @scene.depth:
let inv_vp = mat4x4<f32>(cam[0], cam[1], cam[2], cam[3]);
// ndc.z is the `@scene.depth` sample itself. Scene depth is reversed — 1.0 is
// the near plane, 0.0 the far plane and empty sky — and this matrix inverts
// that same range, so a sample goes in unmodified.
let wh = inv_vp * vec4<f32>(ndc, 1.0);
let world_pos = wh.xyz / wh.w;
Like @scene.*, the engine resolves it per render target — so the same pass
reconstructs against the live viewport's camera on screen and against an
offscreen capture's / RTT camera off screen. (Pack a camera matrix into your own
buffer instead and the offscreen render reconstructs against the wrong camera.)
Render-feature passes run in the main viewport render and in offscreen captures / render-to-texture, each against its own camera. The
capturetool'ssource = "position"/"entity"therefore run the pass queue too; using@frame.camerais what keeps those captures matching the live viewport.
The scene's light
@frame.light is a reserved buffer input carrying the scene's sun and
ambient term as the camera being drawn is shaded by them, the values the lit
passes read in the same frame: 3×vec4<f32> = the direction the sun's light
travels (unit, world space) with its intensity in w, the sun's colour with
w 1 while it casts shadows, and the ambient colour with its intensity in w.
A pass that lights a participating medium (clouds, haze, fog) reads its sun
here rather than carrying one of its own, so a day cycle, a scripted sun and a
sun switched off reach the medium in the frame they reach the surfaces, and a
scene with the sun and every light at zero leaves it black. #include "@builtin::shaderModules.frame_light" reads it, and states the sun's light
either in the units the scene's lights are stated in
(zero_frame_light_sun_irradiance), for a medium that scatters those lights
too, or as the share of a medium's authored brightness the sun lights (its
intensity up to a unit sun, zero_frame_light_sun_tint):
# bindings.yaml
- { name: scene_light, kind: buffer, access: read, element: vec4<f32> }
#include "@builtin::shaderModules.frame_light"
let light = zero_frame_light(scene_light[0], scene_light[1], scene_light[2]);
let toward_sun = zero_frame_light_toward_sun(light);
let sun = zero_frame_light_sun_tint(light) * authored_brightness;
inputs = { scene_light = "@frame.light" }
The environment
A compute pass reads the scene's captured surroundings — the reflection-probe cube array, its sampler and the environment buffer (the probe blend data, then the irradiance light-probe volumes) — through three reserved inputs, bound to bindings of the shapes group(0) binds them in:
bindings:
- { name: environment_map, kind: textureCubeArray }
- { name: environment_sampler, kind: sampler }
- { name: zero_environment, kind: buffer, access: read, element: ZeroEnvironment, array: false }
inputs = {
environment_map = "@scene.environment",
environment_sampler = "@scene.environmentSampler",
zero_environment = "@scene.reflectionProbes",
}
Named like that, #include "zero::environment" in the shader resolves the
environment at a world point along a direction — zpbr_sample_environment(world_pos, dir, lod), the probes whose radius reaches the point blended by rank and
proximity, each through its proxy volume, and the sky under them — exactly as a
material's environment term does, so a reflection a pass draws and one a
material draws agree about the room they are in. A pass that reads several
directions at one point selects the probes once, let probes = zpbr_select_probes(world_pos);, and gathers each direction with
zpbr_gather_environment_with_probes(probes, world_pos, dir, lod), which answers
the radiance in rgb and the share of it the probes and sky claimed in a.
The three bind at the scene phases; a post or UI phase carries none. A textureCubeArray binding takes
@scene.environment alone, and a fragment pass has no slot of that shape.
Pass kinds
enqueue runs one of six kinds (the kind field; default "fragment"):
-
"fragment"— a full-screen shader over input textures. The program is a GPU material (orshader) the feature constructed;inputsbind live textures (@scene.*or RT guids),outputis the target RT (omit = the phase's default scene target). Post-process, blur, edge effects.Writing named G-buffer channels (
outputs). Instead of the singleoutputRT, a fragment pass may declare anoutputsarray — one or more targets, each a named engine channel (@scene.shaded/@scene.normal/@scene.emissive/@scene.color) or an RT guid — each with its own blend mode:ctx.enqueue { kind = "fragment", shader = myShaderKey, outputs = { { target = "@scene.shaded", blend = "under" }, -- premultiplied dst-over-src { target = "@scene.emissive", blend = "additive" }, -- one fullscreen pass, two targets (MRT) }, phase = "afterOpaque", -- deferred: G-buffer filled, before the composite }Blend modes — the keywords every pass's
blendtakes,srcbeing what the pass returns anddstwhat the target holds:Keyword Result "replace"src— overwrites"alpha"src.rgb * src.a + dst.rgb * (1 - src.a)— straight-alpha source-over"premultiplied"src + dst * (1 - src.a)— source-over for a colour already multiplied by its alpha"additive"src + dst— sums"under"src * (1 - dst.a) + dst— premultiplied destination-over-source: what the target holds stays in front, which accumulates coverage-weighted contributionsA keyword outside the table raises from
ctx.enqueue, naming the field. A@scene.*channel resolves only where it exists (the deferred G-buffer at a pre-composite phase); a pass whose targets are all unavailable at its phase is skipped (logged).output+blend = trueremains the shorthand for a single alpha-blended target. The shader's returned colour is written to every target in the set.A fragment shader returns
vec4<f32>, so the channels it can target are the float ones.@scene.material(also named@scene.mr) isRgba8Uint, which binds asuint— naming it as an output is refused by name, with the channel's format and class in the log, and the rest of the frame draws. A fragment pass'sinputsreads through the same fixed float slot, so naming@scene.materialthere is refused the same way; a compute pass reads that channel through asample: uintslot instead.What a pass with no
inputssamples. A fragment pass that declares noinputsreads@scene.color— the shape of an effect that filters the scene image. A pass that names@scene.coloramong its ownoutputssamples a 1x1 transparent texel instead, because the scene colour is that pass's render target and one texture is a colour attachment or a sampled resource in a render pass, never both. Declareinputs = { src = "@scene.color" }and write an RT to read the scene image and write somewhere else in one pass. -
"compute"— a workgroup dispatch (shader,storage,buffers,dispatch; see "Compute passes"). -
"geometry"— draw scene geometry with a constructed pipeline. The program is a material the feature built (renderer.material.create); the engine draws the scene's render-objects with that material's pipeline + uniforms. -
"draw"— rasterize the feature's OWN geometry:geometrynames a buffer created withusage = { "vertex" },storage.indexone created withusage = { "index" }, andselectthe one entity whose transform and material the draw lands through.params[0]is how many indices to submit — or name a buffer understorage.indirect(created withusage = { "indirect" }, holding aDrawIndexedIndirectArgsblock: index count, instance count, first index, base vertex, first instance) and the count comes from the GPU instead, so a compute pass that compacts geometry pays only for what it kept and nothing waits on a read-back.first_instancemust be 0; the engine resolves the entity's per-instance data another way, because a non-zero one needs a device feature WebGPU does not guarantee. -
"splat"— rasterize a compute buffer of particle records as instanced camera-facing billboards into feature RTs (see "Splat passes"). -
"raster"— draw geometry the feature makes itself with a.rasterShaderof its own:vertexCountvertices for each ofinstanceCountinstances, pulled from the buffers the pass binds, into the scene or the feature's targets, depth-tested against the scene (see "Raster passes").
Geometry passes
A geometry pass re-draws the scene's meshes with a material you supply — the generic primitive for mesh-space effects (the engine names none of them):
ctx.enqueue {
kind = "geometry",
material = myMaterial, -- the HANDLE renderer.material.create
-- returned (or its registry-key string)
geometry = "@geometry.opaque", -- which drawables: "@geometry.opaque" |
-- "@geometry.transparent" | "@geometry.all"
select = { entityA, entityC }, -- OPTIONAL: restrict to these entities
-- (entity refs); omit = every matching mesh
phase = "afterLighting", -- afterLighting = lit scene + valid depth
}
select restricts the draw to the given entities — the per-instance signal that
turns a whole-scene pass into a chosen-meshes effect. A pass with no select
also draws the instanced populations (renderer.mesh.drawInstanced) its
geometry set takes, every copy at its own slot, so a whole-scene pass sees an
instanced forest as it sees the entities around it. The material decides how
those meshes are drawn; you control three things:
- Pipeline render-state.
renderer.material.createtakes arenderblock —cull(back/front/none),depthWrite(bool),blend(opaque/alpha/additive) — so the pass can rasterize differently from the surface pass:local myMaterial = renderer.material.create({ shader = myShaderKey, -- a .shader you authored (identity, not guid) render = { cull = "none", depthWrite = false }, properties = { outline_color = { 1, 0.4, 0, 1 } }, -- seed the shader's uniforms }, "my_pass_mat") -- pass `myMaterial` (or "my_pass_mat") as the pass `material` - The shader. A geometry
.shaderis a surface shader: authorfn vertex(v: VertexData) -> VertexDatato move vertices (object-localv.position/v.normal) andfn fragment(input: FragmentData) -> vec4<f32>for the colour. - Its properties. A shader reads ONLY the uniforms IT declares in
properties.yaml, viamaterial.<yourProp>. Referencing a field it didn't declare (e.g. a StandardMaterialmaterial.base_color) fails to compile and the mesh renders magenta — declare the property or use a constant.
What effect those three produce (outline, x-ray, wireframe, highlight, …) is yours to design — the engine just draws the selected geometry with your pipeline.
Compute passes
A compute pass dispatches a .computeShader program over a workgroup grid:
ctx.enqueue {
kind = "compute",
program = myComputeShader,
storage = { outTex = myStorageRtGuid }, -- slot -> storage-texture RT guid
buffers = { particles = "my_particle_buf" },-- slot -> named compute buffer
inputs = { camera = "@frame.camera" }, -- slot -> @frame.*/@scene.* buffer
dispatch = { x = 64, y = 1, z = 1 },
}
dispatch is optional. Omit it and the pass is dispatched over what it
WRITES: a grid covering its first storage texture, at the @workgroup_size the
shader's entry point declares. With a screen-sized storage target that grid
tracks the render target being drawn, so a screen-space effect covers the live
viewport, an offscreen capture and an RTT camera without the feature knowing any
of their resolutions:
ctx.enqueue {
kind = "compute",
program = myComputeShader,
inputs = { scene_color = "@scene.color", cam = "@frame.camera" },
storage = { outTex = myScreenSizedRt.guid }, -- screen = true
phase = "afterLighting",
}
State an explicit dispatch for a grid that is not one thread per output texel
(a reduction, a particle sim), or when the shader's @workgroup_size is an
override/const expression the engine cannot read.
Each WGSL storage-buffer binding in the shader resolves its bound slot in this
order: an explicit buffers mapping (the handle a buffer's owner holds, or a
name), then inputs (@frame.camera / @frame.light / @scene.lights /
@scene.reflectionProbes), then — when a slot has neither — a buffer whose
engine-side name equals the slot's own name. buffers
is the seam a pass binds through: the buffers a shader works over are the ones
handed to it, whatever each is called. storage binds storage TEXTURES (RT
guids) the same way, one map per resource kind.
Raster passes
A raster pass draws geometry the feature makes itself: a .rasterShader's
vs_main runs vertexCount times for each of instanceCount instances, and
pulls whatever it places from the buffers the pass binds. No mesh and no vertex
buffer stand behind it — the shape of an instanced field of grass, kelp,
leaves or debris, one record per instance. This one draws a field of leaves
from a storage buffer, hidden behind the scene's opaque geometry:
local leafShader = asset.resolve("leaves", "rasterShader")
local leaves -- a buffer of vec4 records, one per leaf: xyz position, w size
return {
setup = function(ctx)
leaves = substrate.createBuffer({ name = "leaf_field", type = "vec4", len = 256, kind = "gpu" })
local records = {}
for i = 0, 255 do
local x, z = (i % 16) - 7.5, (i // 16) - 7.5
table.insert(records, x); table.insert(records, 0); table.insert(records, z); table.insert(records, 0.6)
end
leaves:write(records)
end,
render = function(ctx)
ctx.enqueue {
kind = "raster",
shader = leafShader,
phase = "afterLighting",
vertexCount = 4, -- one quad per leaf
instanceCount = 256, -- one leaf per record
topology = "triangle-strip",
cull = "none",
buffers = { quads = leaves }, -- slot -> buffer, as a compute pass binds them
inputs = { cam = "@frame.camera" }, -- the drawn camera, for vs_main
depth = { target = "@scene.depth", test = true, write = true, compare = "less" },
}
end,
}
The fields a raster pass reads:
| Field | Default | Holds |
|---|---|---|
shader | — (required) | the .rasterShader (its reference or guid) whose vs_main and fs_main the pass draws with |
vertexCount | — (required without indirect) | vertices per instance, @builtin(vertex_index) 0 .. n-1 |
instanceCount | 1 | instances, @builtin(instance_index) 0 .. n-1 |
indirect | none | a buffer created with usage = { "indirect" } holding vertex count, instance count, first vertex and first instance as four u32; the counts then come from the GPU, so a compute pass that culls or spawns instances draws exactly what it kept |
topology | "triangle-list" | "triangle-list" or "triangle-strip" |
cull | "none" | "none", "back" or "front"; a triangle wound counter-clockwise on screen faces the camera, as in WebGPU |
depth | none | { target, test, write, compare }, true for { target = "@scene.depth", test = true, write = true, compare = "less" }, or false for no depth buffer |
outputs / output / blend | @scene.color, replaced | where fs_main's colours land and how they blend: @scene.color, @scene.motion or render targets the feature created, each "replace", "alpha", "premultiplied", "additive" or "under" (the blend table under "Pass kinds") |
generateMips | none | render targets (made with mips) whose mip chain the pass fills once it has drawn |
params | the shader's own | values for the shader's params: fields, by name, for this pass |
phase | — (required) | any pass phase (see "When it runs") |
clear | false | clear the render targets the pass draws into (colour and depth) before it draws; the scene's own targets are never cleared |
buffers / inputs / storage | — | the shader's bindings, resolved exactly as a compute pass resolves its own |
Depth. depth.target is "@scene.depth" (the opaque depth the frame laid
down) or a render target the feature created, whose own depth buffer the pass
draws and tests against. compare states the visible order a fragment is kept
in — "less" keeps the fragment nearer to the camera than what the target
holds, "greater" the farther one, and "lessEqual", "greaterEqual",
"equal", "always", "never" likewise — the keywords a material's depth test
takes. Every depth buffer a raster pass draws into is reversed, the scene's and
a render target's alike: 1.0 is the near plane and 0.0 the far plane, and the
engine maps each keyword onto the comparison that order takes, so "less" is
the hardware's greater. clear = true clears a render target's depth to 0.0,
the far plane, so the first fragment "less" meets is always kept. The matrix
in @frame.camera already writes reversed depth. A pass placing vertices with a
projection of its own that maps the near plane to 0 and the far plane to 1 (a
light's orthographic shadow matrix built the conventional way) writes
clip.z = clip.w - clip.z in vs_main to store the reversed value, and states
its compare keywords in visible order as above. test = false keeps every
fragment; write = false leaves the depth as it stood, and lets the same pass
sample @scene.depth through its inputs.
A render target's depth as a texture. inputs = { shadow = "@depth.<guid>" }
binds the depth buffer of the render target <guid> (built with the target
the first time a pass draws into it or reads its depth) to a kind: texture_depth binding, so a later raster or
compute pass reads what a raster pass drew there: a shadow map,
a depth pre-pass of the feature's own. Sample it with textureLoad, or with
textureSampleCompare through a comparison sampler (below).
Winding. A triangle whose vertices run counter-clockwise on screen faces
the camera, as in WebGPU: cull = "back" drops the clockwise ones and
cull = "front" the counter-clockwise ones. A projection that mirrors the
picture (a negative determinant, such as one whose x or y axis is flipped)
mirrors every triangle's winding with it; depth does not enter into it.
Colour targets. outputs (or output) names @scene.color,
@scene.motion or render targets the feature created, each with its blend:
"replace", "alpha", "premultiplied", "additive" or "under", as the
blend table under "Pass kinds" defines them. blend beside a single
output takes the same keywords (true is "alpha"), so
output = rt, blend = "additive" sums into rt. A keyword the pass does not
know raises from ctx.enqueue, naming blend.
Motion vectors. A pass whose geometry moves writes its velocity into
@scene.motion as a second target, outputs = { { target = "@scene.color" }, { target = "@scene.motion" } }, with fs_main returning it at
@location(1) as a vec2 NDC displacement since the previous frame: the
current clip position divided by its w, less the sub-pixel offset this
render's matrix carries (cam[13].xy), less the previous clip position divided
by its w. vs_main projects the previous position through the previous
render's view-projection, cam[5..9). @scene.motion is drawn from
afterDepthPrepass to afterLighting; temporal reconstruction and motion blur
read what the pass wrote there.
Samplers. A sampler binding takes how it samples from bindings.yaml:
filter (linear | nearest), mipmap (linear | nearest), address for
every axis or addressU / addressV / addressW (clamp | repeat |
mirror), and anisotropy (1 to 16, with filter and mipmap linear). A
binding that also states compare (never, less, less-equal, equal,
greater, greater-equal, not-equal, always, compared as WebGPU states
them, reference against stored texel) is a sampler_comparison, for
textureSampleCompare on a texture_depth binding. A binding stating none of
these is the engine's linear, clamped sampler. A compute shader declares its
samplers the same way.
bindings:
- { name: albedo, kind: texture2d }
- { name: smp, kind: sampler, filter: linear, mipmap: linear, address: repeat, anisotropy: 8 }
- { name: shadow, kind: texture_depth }
- { name: shadow_smp, kind: sampler, compare: greater-equal }
Textures the feature made. A texture renderer.texture.create made from
pixels (rgba = ...) binds by its handle (or its guid) in inputs, the way a
render target does. It holds its whole mip chain, each level made from the
pixels it was given, so a sampler declaring mipmap reads it at any level.
Mip chains. renderer.texture.create({ width, height, mips = true })
makes a render target holding its whole mip chain (mips = <n> holds n
levels). A pass draws into the first level; naming the target in
generateMips = { target } fills every level below it, each the 2x2 average
of the level above, once that pass has drawn — a raster, fragment or compute
pass alike. Bound in inputs, the target binds its whole chain, so a sampler
declaring mipmap: linear (and anisotropy) reads it the way it reads a
texture asset's. A screen or history target is resized to each view it
follows and holds one level.
local water = renderer.texture.create({ width = 512, height = 512, format = "rgba16f", mips = true })
ctx.enqueue({ kind = "raster", shader = waterShader, phase = "afterOpaque", vertexCount = 3,
output = water, clear = true, generateMips = { water } })
ctx.enqueue({ kind = "raster", shader = seabedShader, phase = "afterOpaque", vertexCount = 6,
inputs = { water = water }, depth = true })
Per-pass values. params = { exposure = 1.5, layer = 2 } gives the
shader's params: fields values for this one pass, laid over the values the
shader holds; a field the shader does not declare skips the pass, with the
field named in the log. A compute pass takes the same table, and so does a
compute shader's ref:dispatch and ref:dispatchEx.
The camera. @frame.camera bound to a read buffer gives vs_main the view
being drawn: cam[9..13) is its view-projection, the matrix the scene
rasterized with, cam[5..9) the previous render's, cam[13].xy the sub-pixel
offset this render's matrix carries, and cam[4].xyz its position. A raster
pass runs once per view — the viewport, every capture, every render-to-texture
camera — each through its own camera.
When it runs. A raster pass runs at the phase it states, in order with the
fragment and compute passes of that phase (by priority, then the order they
were enqueued), so a later pass reads what it drew. @scene.depth as a depth
target and @scene.motion as an output are this view's from
afterDepthPrepass to afterLighting; at afterScenePost, afterUi and
afterPost a raster pass draws into the composite (@scene.color) and its
own render targets, testing against a render target's depth. A field holding a
value of the wrong shape raises from ctx.enqueue, naming the field; a pass
whose shader failed to compile, or whose targets or bindings do not resolve,
is skipped with the reason in the log, said once until the reason changes.
Another way to draw an instanced field. The guide
topics/rendering-instance-data, section "Instanced foliage built in the
vertex shader — grass, kelp, hair cards, debris", draws the same kind of field
through an engine material: a surface shader's vertex() reads each
instance's record with zero_object_data(v.instance_id, lane) and its
v.vertex_index on a mesh drawn with renderer.mesh.drawInstanced. That field
is lit, casts and receives shadows, writes motion vectors and takes fog and
post-processing as every material does. A raster pass is a hand-written vertex
and fragment program with its own pipeline, depth and blend — the shape a
hand-written renderer ports into.
Splat passes
A splat pass draws every record of an f32 buffer as a camera-facing billboard —
the raster primitive behind screen-space particle surfaces (the fluidSurface
system is built entirely on it):
ctx.enqueue {
kind = "splat",
phase = "afterLighting",
output = depthRt.guid, -- or `outputs` for the thickness+color MRT
splat = {
buffer = "my_particles", -- compute-buffer name
stride = 12, -- floats per record
posOffset = 0, -- float offset of the position
count = 200000, -- records to draw
radius = 0.3, -- world particle radius
channel = "depth", -- "depth" | "thickness" | "sprite" | "gaussian"
velOffset = 4, -- optional: velocity → screen-space stretch
stretch = 0.04, -- seconds of motion elongating the billboard
colorOffset = 8, -- optional (thickness): + per-particle RGB → MRT
weightOffset = 7, -- optional (sprite): per-particle intensity
minY = -60.0, -- records below this y collapse (parked/dead)
maxRadiusPx = 120, -- optional: cap on the projected pixel radius
},
}
The "gaussian" channel draws the engine's packed splat records — what
renderer.splat.components decodes a .spz or .ply capture into — as
elliptical-weighted-average Gaussians, and takes fields of its own:
splat = {
buffer = "cloud_records",
stride = 6, -- the packed record is six u32 words
posOffset = 0,
count = 1200000,
radius = 1.0, -- multiplies each splat's stored scale
channel = "gaussian",
orderBuffer = "cloud_order", -- back-to-front permutation; "over" needs one
shBuffer = "cloud_sh", -- optional: quantized higher-order SH
shStride = 24, -- u32 words of SH per record
shDegree = 3,
transform = model, -- object -> world, column-major, 16 floats
prevTransform = prevModel, -- where `transform` stood last frame
opacityScale = 1.0,
}
transform places the cloud: each Gaussian's covariance is conjugated by its
upper-left 3×3, so a non-uniform scale shears the cloud the way it shears a mesh.
prevTransform plus a second entry in outputs makes the channel write an MRT
pair — the colour into the first target, and the screen-space displacement each
splat underwent between the two placements into the second, premultiplied by the
same alpha the colour composites under. That second target therefore resolves to
(coverage-weighted mean displacement, coverage), which is what folds a moving
cloud into @scene.motion. Naming one target, or leaving prevTransform out,
renders the colour alone.
The other three channels write different fragments: "depth" writes nearest-surface
linear view depth (R32Float, hardware-depth-tested on the target's own depth
buffer), "thickness" accumulates additive optical thickness (with
colorOffset and a two-entry outputs list it also accumulates
thickness-weighted color into the second target), and "sprite" accumulates a
soft additive disc scaled by weightOffset. Every channel discards fragments
behind opaque scene geometry by sampling the scene depth at the fragment's own
NDC. maxRadiusPx scales down billboards whose projected major radius would
exceed that many pixels, so particles crossing the near plane stay
droplet-sized instead of filling the screen. Targets clear at the pass;
blend = true on the spec loads them instead to accumulate over a prior
splat pass.
renderer.feature.create(featureRef) instantiates a feature and returns a live
handle (featureRef may be an AssetRef<renderFeature> or its identity string).
The handle appears under /zero/runtime/generated_features/<guid>/ for exactly
as long as the framework runs the feature's render. Its info names the
feature and its guid, and its setup: line states how setup ended: ok,
none for a feature that declares no setup, or raised: <error>. Re-creating
the SAME feature asset replaces the live one rather than stacking a duplicate.
A write to a live feature's asset (its init.luau, or a module beside it)
starts the feature again on the stored definition from the next frame: its
teardown runs, its setup runs on the new definition, and its guid and
handles stay. The knobs set at create or through configure carry over when
the new definition still declares them and accepts the value; every other knob
takes the new default. A definition that fails to load leaves the running
feature in place, with a warning.
A feature whose render raises is logged ([renderer.feature] '<identity>' render error: ...) and released the way renderer.feature.destroy releases
one: its teardown runs, its passes are withdrawn, it leaves
renderer.feature.list(), its runtime folder and registry row go, and every
handle to it reads released. renderer.feature.find(handle) answers nil for
it, which is how a module holding a handle tells that its feature stopped.
renderer.feature.list()→{ {guid, identity} }for every live feature.renderer.feature.destroy(handleOrGuid)(orrenderer.destroy(handle)) tears one down — by handle OR by guid string, so you can stop a feature even after losing its handle (e.g. across separateexecutecalls).
In the Inspector
Selecting a render feature opens its Feature section: whether the feature runs in this session, an Enable or Disable action, and its settings as typed controls. While it runs, the controls hold its live values and an edit reconfigures the running feature (renderer.feature.configure checks it against the schema first). Those edits are session state: they change the running feature only, they are not undoable (Ctrl+Z never reaches them), and Disable or a restart ends them; the feature's declared defaults are what the next Enable starts from. While it does not run, the controls show the declared defaults, read-only, and a write reaching it then is refused. A feature enabled, disabled or reconfigured from a script shows in the section as it happens. A feature that declares no settings says so.