whitebox-previs-executor

Prompt 3D White-Model Previsualizer

Public experimental package. This package is an explicit test executor, not a stable promise of arbitrary choreography. It contains the twelve runtime files only; the local workbench and Blender binaries are not bundled.

Configurable runtime dependencies

• Normal or articulated previsualization requires an installed Blender. The lookup order is --blender、WHITEBOX_BLENDER environment variable,PATH, and finally _runtime/blender-*-windows-x64/blender.exeunder the current task. If the specified path is invalid, report an error directly; do not silently switch versions.
• The two launchers require an explicit --runtime-dir, and direct the child process's temporary directory and application configuration into it; no runtime cache is created when structure, backend routing, or dependency checks fail.
• The legacy software renderer's FFmpeg lookup order is --ffmpeg、WHITEBOX_FFMPEG、PATH; the probe is --ffprobe、WHITEBOX_FFPROBE、PATH or the corresponding executable in the same directory as FFmpeg. The public package does not search the author's computer's software paths.
• Compared with the local copy, the public package only adds dependency environment variables, removes the local machine FFmpeg fallback, and rejects invalid specs and incorrect fight backends before launch; this is not a new version of action capability. If dependencies are missing or there is no actually playable video, it must still be reported as incomplete.

Execute only when the current request explicitly asks for an actual white-model previsualization; an existing prompt, creative idea, or "let's see how the plan looks" does not by itself constitute rendering authorization. Creative discussion delivers ideas at the current text stage and is not blocked by missing Blender or video platforms.

Once previsualization begins, the user only needs to provide an already-written video prompt or shot. The first delivery layer is a MP4that the user can play directly; do not first make the user operate Blender, view the editor, fill in coordinates, or review JSON.

Output contract

Each execution produces at least:

• A playable 3D white-model MP4；
• previs_compiled.json: an auditable 3D execution interpretation of the prompt;
• previs_validation.json: duration, frame count, resolution, cut points, actual decoding, and viewing checks;
• Optional .blend project, only as an editable background artifact, not a substitute for the video.

Screenshots, editor UI, project files, parameter tables, static keyframes, 2.5D push-pull, software feature descriptions, or in-memory encoding probes cannot replace the MP4.

Execution flow

1. Fully preserve the user's original prompt. The input may be a one-sentence prompt, a single shot, multiple shots, any duration, or no explicit duration.
2. Compile into a references/prompt-to-previs.md contract according to previs-compiler/1.0 . Execute only the shot intent already present in the prompt; defaults must be traceable and must not masquerade as predictions of a formal video model.
3. Run scripts/validate_compiled_previs.py. Time overlaps, shot gaps, missing cameras, character reference errors, or unexecutable critical ambiguities must be rejected before rendering.
4. Normal blocking and camera previsualization use scripts/run_blender_previs.py to call scripts/blender_previs_adapter.py. Fight specs that include qualified previs-action/1.0 action extensions use scripts/run_blender_rigged_fight.py to call scripts/blender_rigged_fight_adapter.pyinstead; that backend solves shoulders, elbows, wrists, hips, knees, ankles, both-hand grips, weapons, and shared contacts frame by frame. When the action backend fails, it must stop; it must not secretly fall back to the normal block path.
5. Use an actual decoder to verify the MP4's frame count, frame rate, resolution, and duration; then check each shot's first frame, midpoint, last frame, and the frames before and after each cut.
6. The first reply directly displays or links the MP4, then explains defaults and boundaries. If no playable video is available, it may only report that the task is incomplete.

Compilation boundaries

• Execute explicitly stated durations as written; when no duration is given, default to 4 seconds for a single shot and 3 seconds per shot for multiple shots, and mark deterministic_default。
• Only shot numbers, timecodes, hard cuts, cuts to, or explicit transitions trigger automatic shot splitting. "Subsequently, then, next" by default only indicate the order of actions within the same shot.
• When no camera movement is specified, keep it static and do not automatically add cinematic drift.
• When no scene is specified, generate only a ground grid and necessary spatial references; do not invent environment art.
• The current public package has implemented humanoid/humanoid mecha and dual-arm floating-type proxies. Quadruped, vehicle, or other unimplemented categories must be reported at the compilation stage as capability gaps; do not promise a corresponding backend exists, and do not substitute a humanoid or sphere for the original subject. Unless the prompt's subject is itself a sphere, do not use a sphere to replace a humanoid subject.
• Characters and scenes may be rough; stick-figure-level precision is acceptable; but when camera movement is requested, the foreground, midground, and background must provide enough reference for parallax and camera movement to be visibly obvious in the video.
• The preview proves the shots, space, blocking, shot changes, and pacing in the current compilation interpretation; it does not prove that the official model will generate the same pixels, performance, materials, or effects.

Action-intensive fight gate

Ordinary blocking and camera previews may use rough proxies; fights cannot merely move character root nodes and switch cameras. Before rendering, action-intensive prompts must prove that the execution layer has:

• Attack, block, and hit-reaction poses with joint pivots or bones;
• Grip constraints between the weapon and both hands; the weapon must not float;
• The attacking weapon and the defending limb share the same actual contact point;
• Wind-up and deceleration before contact, a freeze at contact, and bidirectional reaction after recovery;
• A viewer who has not read the prompt can tell from the video alone "who attacks with what, who blocks how, where contact occurs, and how both sides bounce off."

When any of the above is missing, only a failure diagnosis may be output, and it must not be called a fight preview. Before starting a full fight sequence, first pass a 2–4 second single-action shot as a gate; if the single-action gate does not pass, do not expand it into a long fight scene or a multi-shot full video.

The action specification must follow references/prompt-to-previs.md of previs-action/1.0 and explicitly list the action beats, the two weapon grip points, the attack and defense contact sockets, the single shared contact, the freeze frame, and the reaction segment. The validator must check the actual rendered joint, weapon, and cable geometry; testing only raw control points, action names, or collision markers does not count as passing. New action types not implemented in the current backend must first have execution and a single-action gate added; they must not reuse similar actions merely because the word "fight" appears.

Completion gate

Only when all of the following conditions are met may you write "prompt preview video generated":

• The MP4 exists, is non-empty, and is opened by an actual decoder;
• Duration, frame rate, resolution, and shot boundaries match the compilation contract;
• The requested camera movement comes from real 3D camera translation or rotation, not a 2D pan or zoom masquerading as one;
• The character's start, midpoint, endpoint, and states before and after shot changes are visible;
• Scene references produce perceptible 3D parallax;
• The full video has been watched, or the first frame, midpoint, and last frame have been checked shot by shot;
• All defaults, unresolved items, and boundaries of what is not proven have been clearly stated.
• If the content is a fight, an independent viewer who has not read the prompt can identify the attacker, the weapon, the blocking party, the contact point, and the reaction; merely seeing blocks approach, interpenetrate, or bounce apart does not count as passing.
• If the content involves holding an object, wrapping, or grasping, the grip point and contact point must land on the final rendered geometry and be maintained across the relevant frames; if the control-point coordinates are correct but the final line segment, hand, or weapon visibly detaches in the frame, it is still judged a failure.

The old versions references/previs-spec.md、scripts/validate_spec.py and scripts/render_previs.py are only used to read historical 0.1 contracts and failure regressions, and are no longer the preferred production route for new prompt previews.