preview

Render an asset's preview in the preview studio: an isolated camera, lit only by its own three-point rig, over a neutral backdrop, that nothing in the scene reaches. ref:preview() renders any asset by the recipe its type declares under preview: in its type.yaml, and these are the primitives it calls: they spawn temporary entities, frame an offscreen camera over them, render one frame, read it back as a PNG, and tear the entities down.

Surface

• preview.fromEntities(makeFn, opts?) -> PreviewResult — run makeFn to instantiate entities, frame a camera to their bounds, render one offscreen frame, and return the still PNG.
• preview.fromRecipe(ref, recipe, opts?) -> PreviewResult — render ref by a declared recipe: instantiate stands it through its own instantiate, surface paints the material its type's ref.previewMaterial returns on the recipe's mesh, and image fits a file the asset holds to the frame on the studio backdrop without rendering anything.
• preview.backdrop() -> { r, g, b } — the studio backdrop's colour in a finished preview, 0-255.

PreviewResult is { available, imageBase64?, rendered?, width?, height?, bounds?, stats?, reason? } — imageBase64 is the rendered PNG when available is true, and reason explains why when it is false. opts is { size? = { width, height }, angle? = { yaw, pitch } }.

A preview pictures its whole subject, however many entities it composes. While the subject settles, its bounds are measured each frame by walking it in Luau for up to opts.entityBudget entities (default 2000); a subject composing more is measured by the capture framing alone, which reads each root's hierarchy bounds from the engine.

Example

local result = asset.resolve("gold", "material"):preview({ size = { width = 512, height = 512 } })
-- result.imageBase64 holds the rendered PNG (base64)