capture.oneshot

The low-level one-shot capture primitive. Spawns an ephemeral offscreen camera configured from a source — the viewport, an entity (or several), a world-space position, or a UI window — triggers a single render, and returns the camera and render-target handles synchronously so the caller drives the readback and cleanup itself. It does not wait for the render: it returns at once, and the caller reads the target back and cleans up, which makes it the path for a caller that must not yield (the capture MCP tool is built on it).

When framing an entity, omitting the distance auto-fits the camera to the union world-space bounds of the target(s), so the subject is guaranteed fully in frame at any scale — a small prop and a large building both fill the shot. Because the data drives the camera, an empty result is a real signal that the geometry or material is wrong rather than a framing mistake; a distance can be passed to force a fixed orbit radius, and an angle sets only the viewing direction. Further options select the output by pass name (or view, or a raw debugChannel), set which render layers draw with a renderLayers spec such as "all !ui", turn the post-process chain on or off with postProcessing, choose an orthographic projection, and set field of view, clip planes, and output size. The returned camera is left disabled so it can be re-triggered to produce additional frames on the same target, as when stitching a collage.