Log inGet started
Package

renderFeature.assetType

Newest version

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:

FieldMeaning
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.timeSeconds since boot.
ctx.frameMonotonic frame index.
ctx.renderPath"forward" / "deferred" / … — branch passes on the active path.
ctx.settingsThe 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:

valuewhat 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:

fieldholds
x1 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
yhow many renders in a row have carried the history
zwthis 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):

StageSpaceResolutionRuns
lightinglightrasterscreen-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
mediumlightrasterparticipating media: aerial perspective, fog, volumetric light
preTemporallightrastereffects reading the jittered raster before reconstruction: depth of field
temporallightrasterthe one temporal reconstruction of the raster (TAA); the stage holds one feature at a time
postTemporallightrastereffects reading the reconstructed picture: motion blur
meterlightreducedmeasuring the picture: the exposure histogram, a fraction of the raster
opticslightraster, then outputlens 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
displaydisplayoutputthe display transform, then on code values the temporal upscale, debanding, edge antialiasing and sharpening; the chain's display layer, the film grain last
uidisplayoutputthe 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
outputencodedoutputthe 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:

PhaseScene colour there
afterDepthPrepassthe 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)
afterShadowsshadow maps populated; scene colour not yet drawn. @scene.depth and @scene.motion hold what the visibility raster laid at afterDepthPrepass
afterSkysky 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)
afterOpaqueopaque 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
afterOpaqueLitthe 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
afterTransparenttransparents drawn, before the OIT composite
afterLightingdeferred-lighting + OIT composite done — fully lit, final geometry on both paths
afterScenePostthe chain's scene layer and the display transform done: display code values, before the chain's display layer and the UI
afterUIscene + UI composited
afterPostthe 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:

NameHoldsFormatValid fromAlso named
@scene.colorthe scene's lit colour; the display composite at a post-scene phasethe scene target's format at a scene phase, the display composite's at a post oneevery phase—
@scene.depthopaque depth, reversed (1.0 near, 0.0 far/empty sky)Depth32Float — binds through a texture_depth compute slot, not texture2dafterDepthPrepass on—
@scene.motionscreen-space NDC velocity since the previous frameRg16FloatafterOpaque on—
@scene.normalworld-space normal + the per-pixel surface-flag fieldRgb10a2Unormdeferred path, afterOpaque on (previous frame's before — declare readsPrevious)—
@scene.shadedwhat a surface SENT — its shaded colour, linear and scene-referredRgba16Floatdeferred path, afterOpaque on (previous frame's before)@scene.albedo
@scene.materialwhat a surface IS — base colour (RGB565) + metallic + perceptual roughnessRgba8Uintdeferred path, afterOpaque on (previous frame's before)@scene.mr
@scene.emissiveradiance a pass stamped on the surface, added at the compositeRgba16Floatdeferred path, afterOpaque on (previous frame's before)—
@scene.aoscene 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 writtenRgba8Unormevery scene phase (cleared at the top of the scene render)—
@scene.sunOcclusionthe 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 aloneRgba8Unormevery scene phase (cleared at the top of the scene render)—
@scene.reflectiontraced reflection radiance (.rgb) + confidence (.a)Rgba16Floatevery scene phase (cleared at the top of the scene render)—
@scene.indirectthe 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 ofRgba16Floatevery scene phase (cleared at the top of every scene render)—
@scene.colorHistorythe lit colour the target's previous render ended withRgba16Floatevery phase—
@scene.lightsthe 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 loopstorage bufferevery phase—
@scene.shadowPoolthe 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 viewDepth24Plus — binds through a texture_depth compute slotscene phases only—
@scene.environmentthe reflection-probe cube arraytexture cube arrayscene phases only—
@scene.environmentSamplerthe filtering sampler for @scene.environmentsamplerscene phases only—
@scene.reflectionProbesthe environment buffer: the probe blend data naming which probe reaches a point, then the irradiance light-probe volumesstorage bufferscene 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 capture tool's source = "position" / "entity" therefore run the pass queue too; using @frame.camera is 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 (or shader) the feature constructed; inputs bind live textures (@scene.* or RT guids), output is the target RT (omit = the phase's default scene target). Post-process, blur, edge effects.

    Writing named G-buffer channels (outputs). Instead of the single output RT, a fragment pass may declare an outputs array — 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 blend takes, src being what the pass returns and dst what the target holds:

    KeywordResult
    "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 contributions

    A 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 = true remains 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) is Rgba8Uint, which binds as uint — 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's inputs reads through the same fixed float slot, so naming @scene.material there is refused the same way; a compute pass reads that channel through a sample: uint slot instead.

    What a pass with no inputs samples. A fragment pass that declares no inputs reads @scene.color — the shape of an effect that filters the scene image. A pass that names @scene.color among its own outputs samples 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. Declare inputs = { 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: geometry names a buffer created with usage = { "vertex" }, storage.index one created with usage = { "index" }, and select the one entity whose transform and material the draw lands through. params[0] is how many indices to submit — or name a buffer under storage.indirect (created with usage = { "indirect" }, holding a DrawIndexedIndirectArgs block: 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_instance must 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 .rasterShader of its own: vertexCount vertices for each of instanceCount instances, 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.create takes a render block — 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 .shader is a surface shader: author fn vertex(v: VertexData) -> VertexData to move vertices (object-local v.position / v.normal) and fn fragment(input: FragmentData) -> vec4<f32> for the colour.
  • Its properties. A shader reads ONLY the uniforms IT declares in properties.yaml, via material.<yourProp>. Referencing a field it didn't declare (e.g. a StandardMaterial material.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:

FieldDefaultHolds
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
instanceCount1instances, @builtin(instance_index) 0 .. n-1
indirectnonea 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
depthnone{ 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, replacedwhere 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")
generateMipsnonerender targets (made with mips) whose mip chain the pass fills once it has drawn
paramsthe shader's ownvalues for the shader's params: fields, by name, for this pass
phase— (required)any pass phase (see "When it runs")
clearfalseclear 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) (or renderer.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 separate execute calls).

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.