{
"name": "cinematic.render",
"summary": "Render a Theatre-driven cinematic sequence to a video or frame-sequence artifact.",
"description": "WRAPS packages/vgai-sdk/src/render/render-cinematic.ts’s renderCinematic (I0/I2-I8) as a background job: validates + resolves the request synchronously (failing BEFORE any browser launches, I1 AC), then fires the real pipeline WITHOUT awaiting it and returns a jobId immediately — poll cinematic.render.status for progress/current-frame/elapsed-time/output-paths, or cinematic.render.cancel to abort. Preview (cinematic.preview) and this op drive the exact same window.__vgaiRender render-control harness / AnimationClock seam — the SAME canonical clock implementation (§8 B5 AC).",
"errors": [
"RENDER_REQUEST_INVALID",
"RENDER_CAPABILITY_UNAVAILABLE"
],
"host": "node",
"mutates": true,
"supportsDryRun": false,
"longRunning": true,
"id": "schema-record:d6146e50777459f9ce1d",
"anchor": "record-d6146e50777459f9",
"version": "0.3"
}Cinematic render and capture formats
VGAI Reference 0.3
Planned versioned generated-schema truth covering Deterministic animation/cinematic clock and cues, Deterministic cinematic simulation and rendering.
planned · generated · immutable Reference 0.3
Lifecycle and constraints
Detailed constraints will publish with the generated or reviewed entry.
Runnable Learn material
- Technical Artist
- Animation, blending, masks, retargeting, IK, and attachments
- Build, deployment, diagnostics, and profiling
- Game Animation Sample
- Rendering and Scale Sample
Generated format inventory
Inventory only — AC-REF-002 is not passed. Valid parser-verified examples, narrative guidance, complete cross-field/runtime constraints, and version history remain deferred. This page must not be treated as a complete format contract.
Source: packages/vgai-sdk/src/cinematic/render-operations.ts ·
49 branch-sensitive field records ·
14 source-described.
cinematic.render.input · operation-input · 20 fields
| Field / branch | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
# $ | object | yes | none | {"additionalProperties":false} | Missing source description |
# $.entry | string | yes | none | none | Either an http(s) URL to an already-serving render-mode page, or a filesystem path to a Vite config to spawn. |
# $.out | string | yes | none | none | Output file path (mp4/webm) or output directory (png format). |
# $.format | enum (3) | no | none | {"enum":["mp4","webm","png"]} | Missing source description |
# $.fps | number | no | none | {"exclusiveMinimum":0} | Missing source description |
# $.start | number | no | none | {"minimum":0} | Range start, seconds. Default 0. |
# $.end | number | no | none | none | Range end, seconds. Supply exactly one of end/frameCount. |
# $.frameCount | integer | no | none | {"maximum":9007199254740991,"exclusiveMinimum":0} | Missing source description |
# $.width | integer | no | none | {"maximum":9007199254740991,"exclusiveMinimum":0} | Missing source description |
# $.height | integer | no | none | {"maximum":9007199254740991,"exclusiveMinimum":0} | Missing source description |
# $.dpr | number | no | none | {"exclusiveMinimum":0} | Missing source description |
# $.seed | integer | no | none | {"minimum":-9007199254740991,"maximum":9007199254740991} | Missing source description |
# $.background | enum (2) | no | none | {"enum":["opaque","transparent"]} | Missing source description |
# $.audio | enum (3) | no | none | {"enum":["auto","on","off"]} | Missing source description |
# $.overwrite | boolean | no | none | none | Missing source description |
# $.keepFrames | boolean | no | none | none | Retain the temporary per-frame PNG directory after the render finishes OR is cancelled. |
# $.port | integer | no | none | {"maximum":9007199254740991,"exclusiveMinimum":0} | Missing source description |
# $.simulate | boolean | no | none | none | I5: advance the FULL fixed-step gameplay loop (physics/gameplay phases/AI/particles/participating audio) between captured frames via window.__vgaiRender.simulateSubsteps, instead of the default sequence-controlled (Theatre/GSAP time-seek only) render. |
# $.simulateSubsteps | integer | no | none | {"maximum":9007199254740991,"exclusiveMinimum":0} | Fixed gameplay substeps advanced per captured frame under --simulate. Default 4. |
# $.simulateWarmupSubsteps | integer | no | none | {"minimum":0,"maximum":9007199254740991} | Fixed gameplay substeps advanced ONCE, before frame 0, under --simulate. Default 0 (no warmup). |
cinematic.render.result · operation-result · 5 fields
| Field / branch | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
# $ | object | yes | none | {"additionalProperties":false} | Missing source description |
# $.jobId | string | yes | none | none | Opaque render job handle — poll with cinematic.render.status. |
# $.outPath | string | yes | none | none | Destination path the job will write to. |
# $.resolvedFrameCount | integer | yes | none | {"minimum":-9007199254740991,"maximum":9007199254740991} | Frame count resolved from start/end/frameCount/fps. |
# $.resolvedFps | number | yes | none | none | Missing source description |
cinematic.render.status.input · operation-input · 2 fields
cinematic.render.status.result · operation-result · 16 fields
| Field / branch | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
# $ | object | yes | none | {"additionalProperties":false} | Missing source description |
# $.jobId | string | yes | none | none | Missing source description |
# $.status | enum (4) | yes | none | {"enum":["running","completed","failed","cancelled"]} | Missing source description |
# $.currentFrame | number | yes | none | none | Missing source description |
# $.frameCount | number | no | none | none | Missing source description |
# $.elapsedMs | number | yes | none | none | Time since the job started (or, once settled, its total run time). |
# $.outputPath | string | no | none | none | Missing source description |
# $.manifestPath | string | no | none | none | Missing source description |
# $.durationSeconds | number | no | none | none | Missing source description |
# $.warnings | array | yes | none | none | Missing source description |
# $.warnings[] | string | yes | none | none | Missing source description |
# $.error | object | no | none | {"additionalProperties":false} | Missing source description |
# $.error.message | string | yes | none | none | Missing source description |
# $.error.subsystem | string | yes | none | none | Missing source description |
# $.error.frame | number | no | none | none | Missing source description |
# $.error.time | number | no | none | none | Missing source description |
cinematic.render.cancel.input · operation-input · 3 fields
| Field / branch | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
# $ | object | yes | none | {"additionalProperties":false} | Missing source description |
# $.jobId | string | yes | none | none | Missing source description |
# $.keepFrames | boolean | no | none | none | Cancel-time retention override — when given, wins over the original request’s own keepFrames for the purpose of this cancellation’s temp-frame cleanup decision. |
cinematic.render.cancel.result · operation-result · 3 fields
| Field / branch | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
# $ | object | yes | none | {"additionalProperties":false} | Missing source description |
# $.jobId | string | yes | none | none | Missing source description |
# $.status | enum (4) | yes | none | {"enum":["running","completed","failed","cancelled"]} | The job’s status after cancellation was requested and awaited (bounded). Usually "cancelled", but a job that finished/failed the instant before the abort signal was observed reports its real terminal status rather than a fabricated "cancelled" — and a job whose browser/ffmpeg teardown takes longer than the 15000ms bound still reports "running" (abort WAS signalled; it just has not been confirmed yet — poll cinematic.render.status), never a fabricated terminal state. |
Generated records
{
"name": "cinematic.render.status",
"summary": "Poll a cinematic.render job’s progress, current frame, elapsed time, and output paths.",
"description": "Reads the SAME in-memory job the dispatching cinematic.render call created — see ./render-transport.ts. Errors (when status is \"failed\") include the failing frame/time and originating subsystem (§8 B5 AC).",
"errors": [
"RENDER_JOB_NOT_FOUND"
],
"host": "node",
"mutates": false,
"supportsDryRun": false,
"longRunning": false,
"id": "schema-record:4bc2e99155616f575506",
"anchor": "record-4bc2e99155616f57",
"version": "0.3"
}{
"name": "cinematic.render.cancel",
"summary": "Cancel a running cinematic.render job.",
"description": "Aborts the job’s render-cinematic.ts pipeline via its (B5-additive) AbortSignal seam, then waits (bounded, 15000ms) for it to actually settle before returning the real terminal status. Unless retention is requested (this call’s own keepFrames, or — absent that override — the original request’s), incomplete temporary frames are removed (§8 B5 AC).",
"errors": [
"RENDER_JOB_NOT_FOUND",
"RENDER_JOB_NOT_RUNNING"
],
"host": "node",
"mutates": true,
"supportsDryRun": false,
"longRunning": false,
"id": "schema-record:fe3c99dd9439cf1a8562",
"anchor": "record-fe3c99dd9439cf1a",
"version": "0.3"
}