preview.module
- README.md2.6 KB
- derive.module
- init.luau163 KB
This package holds more than this page lists. See all of its files in its world.
README.md
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— runmakeFnto instantiate entities, frame a camera to their bounds, render one offscreen frame, and return the still PNG.preview.fromRecipe(ref, recipe, opts?) -> PreviewResult— renderrefby a declared recipe:instantiatestands it through its owninstantiate,surfacepaints the material its type'sref.previewMaterialreturns on the recipe's mesh, andimagefits 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.preview.placeholderPng(reason, inputs?) -> string— the placeholder preview, a dark grey frame crossed through, recordingreason.preview.placeholderReason(ref) -> string?— why an asset'spreview.pngis the placeholder, or nil when it pictures the asset.
Staging an asset reserves its preview.png through the type's
<type>.preview derive hook. A preview that cannot be rendered (the asset
raises, its cook fails, the render device is gone) lands the placeholder
recording why, so the commit staging the asset lands; zm status names it as
a placeholder line while it is staged, and zm derived retry renders it
again.
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)