Log inGet started
Package

preview.module

Newest version

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 — 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.
  • preview.placeholderPng(reason, inputs?) -> string — the placeholder preview, a dark grey frame crossed through, recording reason.
  • preview.placeholderReason(ref) -> string? — why an asset's preview.png is 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)