fx_probe

The reader half of the frame probe: the grid fx_frame_probe.renderFeature writes each frame, and the measurements taken off it.

litRegion is the one that answers a size question. It measures the area of the region rising above a baseline and reports the radius of a disc with that area, so a parameter that claims to change how big something is has a reading to move. A whole-frame number cannot tell an effect that grew from one that merely brightened.

local probe = require("@builtin::tests.fixtures.fx_probe")
local feature = renderer.feature.create("@builtin::tests.fixtures.fx_frame_probe")
-- … let a few frames pass …
local baseline = probe.read()
-- … play the effect …
local lit = probe.litRegion(probe.read(), baseline, 6)
renderer.feature.destroy(feature)

tileAt, faceTiles, sphereTiles and skyTiles answer WHERE to read. The grid covers the whole frame whatever shape the frame is, so a tile box written down for one shape reads a different part of the scene at another. These work out the tiles a world point, the middle of a flat face, the inner part of a sphere, or the sky above the horizon is drawn in from the view the frame was drawn under (camera.viewData(id)), and tilesLuminance and tilesColour read a set of them.

local view = camera.viewData(cam.id)
local plate, offFrame = probe.faceTiles(view, { -4, 40.25, -4 }, { 8, 0, 0 }, { 0, 0, 8 })
local sky = probe.skyTiles(view, { 0, 40, 0 })
local grid = probe.read()
local ratio = probe.tilesLuminance(grid, plate) / probe.tilesLuminance(grid, sky)

local ball = probe.sphereTiles(view, { -3.5, 0, 0 }, 1.5)
local red = probe.tilesColour(grid, ball).r

The two halves are separate assets because renderer.feature.create compiles a feature's init.luau as its own chunk rather than requiring it, so the feature records the target here instead of on its own module table.

A probe is trusted only once it has been shown stable — an unchanged view read twice agreeing — and shown to discriminate, by moving on a control known to change the frame. Both checks belong in the suite that uses it.