cs68614-hash/costage/director-stage-compose

Compose CoStage

Workflow

1. Open the widget with render_director_stage_widget when it is not already visible.
2. Call get_director_stage_state before editing. Use the returned IDs and current schema.
3. Apply focused changes with apply_director_stage_operations.
4. Re-read the state and verify activeSceneId, positions, poses, cameras, and the active camera inside that scene.
5. Create timeline shots only after the scene and camera for that shot are correct.

Storage

Normal scene state is bound to the current Codex task and survives workspace path changes. When the user wants multiple tasks to edit one director project, first obtain the stageDir returned by render_director_stage_widget or get_director_stage_state, then pass that same absolute stageDir to every render, state, operation, selection, and timeline tool call. Never omit the known stageDir and silently create another scene.

Scene Operations

Use apply_director_stage_operations with one or more operations:

• add_scene: add a blank scene or a complete scene supplied in value; it becomes active unless activate is false.
• set_active_scene: switch the widget to id or sceneId.
• update_scene: rename a scene with patch.label.
• duplicate_scene: clone a scene, optionally setting value.id and value.label.
• delete_scene: delete a scene. Deleting the last scene creates a new blank Default scene so the stage remains usable.
• place_relative: place one node in front of, behind, left of, or right of an anchor node. Camera reference also supports explicit foreground and background. reference selects world, target-local, or camera-screen directions. offset is [right, up, forward] in that reference frame.
• arrange_group: arrange two or more nodes as a line, grid, circle, or arc, then apply facing as center, outward, same_direction, next, target, or none.
• arrange_facing_pair: place exactly two characters around center, separated by distance along horizontal axis, and orient both toward each other.
• orient_toward: orient one node toward targetId or targetPosition. Characters default to their real local +x forward axis.

• update_environment: patch sky, ground, grid, panorama, scene transform, or label settings.
• update_node: patch an existing character, prop, or camera by ID.
• add_node: add a complete node matching an existing node schema.
• delete_node: remove an existing node by category and ID.
• set_active_camera: switch the active camera by ID.

Content operations target the active scene by default. Pass sceneId on every content operation when editing a non-active scene. Do not assume node IDs are unique across scenes.

For characters, preserve real modelUrl, modelName, modelScale, and the complete pose object. When adding a character, copy a current character schema and change only intentional fields. Never substitute placeholder geometry or an invented model URL.

Positions, rotations, scales, and camera targets are three-number arrays. Character and prop rotations are radians. Pose fields are degrees. Camera FOV is degrees.

Adaptive insertion scale

Treat a panorama as an infinite background, never as a physical object whose sphere radius determines character or prop scale. When the user has not specified real-world measurements, new editable nodes must be visible and selectable in the current shot instead of defaulting blindly to scale: [1, 1, 1] at the world origin.

Before adding characters or props, read the active scene, environment.sceneScale, and active camera. Place the new node near the camera target on the scene ground and estimate its uniform object scale from the current framing:

• Visible world height at the target is 2 * cameraDistance * tan(FOV / 2).
• Use roughly 20–32% of that height for one primary character, 12–20% per character in a group, and 12–24% for a normal prop.
• Bundled characters are normalized to about 1.75 * modelScaleY scene units before object scale. Divide the desired world height by that model height and by environment.sceneScale to obtain the object scale.
• Preserve intentional non-uniform prop proportions; multiply the complete prop scale vector by the adaptive factor.

If there is no active camera, create a useful camera or use the scale and spacing of nearby editable nodes as the reference. If the user specifies physical dimensions or an exact blocking plan, preserve those dimensions and adjust the camera framing instead of making actors physically enormous. After insertion, select the new node, re-read state, and verify it is near the intended staging center, above the ground, inside the active camera frustum, and large enough to manipulate.

For environment panorama generation or import, use the director-stage-panorama skill and import_director_stage_panorama. Never fabricate panorama metadata inside update_environment; the importer validates and stores the real image before updating the scene.

Spatial Relationships

Treat phrases such as facing each other, looking at, surrounding, lining up, standing beside, screen left, staggered rows, and keeping distance as relationships, not as independent node coordinates.

All bundled official character GLBs face local +x. Never assume character forward is +z, and never guess facing directions with hard-coded ±90° rotations.

Coordinate Frames

Choose the reference frame from the user's wording:

• reference: "world": stable stage coordinates. World forward is +X; world right is +Z.
• reference: "target": the anchor's own front, back, left, and right. Official character front follows its current local +X rotation.
• reference: "camera": shot composition. Left and right mean screen left and screen right for cameraId; use the active camera when cameraId is omitted.

Never interpret “画面左边 / 镜头右侧 / 前景” as world directions. Use camera reference. Never interpret “站在角色 A 左手边 / 跟在 A 后面” as camera directions. Use target reference. With camera reference, foreground moves toward the camera and background moves deeper into the shot. Do not substitute front or behind for these depth terms.

Blocking Workflow

1. Read the active scene and camera.
2. Add all participants with complete real model data before calculating relationships.
3. Place the primary anchor or group center.
4. Use place_relative for semantic pairwise relations and arrange_group for formations. Chain operations when a layout has a lead actor plus subgroups.
5. Apply standing, sitting, crouching, walking, or gesture poses after root placement. Skeleton pose values must not replace root position or root Y rotation.
6. Re-read the scene and numerically verify spacing, facing, and requested camera-side composition.

Use place_relative for arbitrary blocking such as beside, behind, diagonal, or over-the-shoulder placement. relation supplies the principal direction and distance; offset: [right, up, forward] adds a deterministic diagonal or height adjustment in the same reference frame. orient can face the anchor, copy the anchor direction, follow the reference direction, or preserve current orientation.

Use arrange_group for multi-person blocking:

• line: queues, side-by-side casts, front lines, and staggered rows composed from multiple lines.
• grid: classroom, formation, audience, or crowd blocks. Set columns and spacing.
• circle: round-table, huddle, surrounding, or outward defense arrangements. Set radius.
• arc: interview panels, semicircles, audiences, or camera-facing ensembles. Set radius and arcDegrees.

Set axis as a normalized world X/Z direction when an exact formation axis is required. Without axis, line and grid run along reference right, while circle and arc start from reference forward. Use facing: "target" with targetId or targetPosition for a presenter, prop, stage mark, or shared point.

For two characters facing each other:

1. Add both complete character nodes first.
2. In the same MCP call after both add_node operations, call arrange_facing_pair with their IDs, desired center, horizontal axis, and distance.
3. Apply sitting, standing, or gesture poses independently; pose values do not replace root facing rotation.
4. Re-read state and verify both distance and orientation before reporting success.

For larger groups, add every participant before resolving relationships. Prefer one arrange_group operation over independent coordinate guesses. Use place_relative after the group operation for intentional exceptions, then orient_toward for any final individual eyeline.

For verification, official character horizontal forward is [cos(rotationY), -sin(rotationY)] in world X/Z. Normalize the horizontal vector from the character to its target and require the dot product with forward to be at least 0.98. Verify requested distances and spacing within 0.05 scene units. For camera-relative placement, project the node delta onto camera right and confirm the sign matches screen left or right. Check that distinct participants do not occupy the same horizontal point; increase spacing when their model footprints overlap. If a check fails, correct the relationship before answering.

Camera Coverage

Treat each camera as a real shot design:

• Set position, target, fov, and aspect.
• Keep the target near the intended subject, not at an arbitrary origin.
• Use wider FOV values for establishing coverage and narrower values for close shots.
• Set the intended camera active before creating its timeline shot.

Timeline

Call create_director_timeline_shot to snapshot one scene and its selected camera. Set sceneId, a concise shot label, and durationMs.

For a sequential performance, create an action-stage plan before creating shots. Each distinct performance moment must include:

• actionStage.id: a stable ID shared by every camera covering the same moment;
• actionStage.label, phase, timeMs, and a concrete description;
• characterUpdates: real position, root rotation, or pose changes applied atomically before the shot snapshot.

Use phases setup, anticipation, action, impact, reaction, recovery, or transition. For a new non-setup stage, the tool verifies that at least one character actually differs from the previous shot in that scene. It rejects a new label whose character position, rotation, and pose are unchanged.

When two or more cameras cover the same performance moment, pass the existing actionStage.id again and omit characterUpdates. CoStage reuses the exact character performance snapshot while allowing the selected camera plan to change. Never create a new action-stage ID merely because the camera changes.

Apply stages in chronological order. Do not first pose the final scene and then create every timeline camera from that one state. For deterministic skeletal changes, pass the character's complete current pose with intentional changes in characterUpdates.pose.

When the user refines a character after opening an existing timeline shot, the edit changes the live scene but not the frozen shot automatically. Call refresh_director_timeline_shot with that shot ID after the pose and root transform are correct. CoStage refreshes every camera sharing the same actionStage.id, preserves each camera plan, invalidates stale thumbnails, and rejects a non-setup stage that became identical to its previous stage. Do not report the timeline updated until this tool succeeds and the state is re-read.

Use update_director_timeline to:

• update label or duration.
• move a shot to targetIndex.
• delete a shot.

The timeline belongs to the whole director-stage project. Each item stores sceneId plus a complete scene snapshot, so playback can switch scenes without mounting every scene at once. Do not fake a sequence by changing only thumbnail metadata.

Verification