cs68614-hash/costage/director-stage-panorama

CoStage Panorama

Workflow

1. Call get_director_stage_state and identify the active or requested sceneId. Read its characters, props, cameras, current environment, and staging center.
2. Translate the user's location into a panorama brief that supports the existing 3D blocking. Do not duplicate characters or movable foreground props inside the panorama.
3. Generate the image with the available image-generation tool. Request a true 360-degree equirectangular panorama with an exact 2:1 aspect ratio. The final imported file must be at least 4096x2048; use a real image upscaling tool when the generator returns less, and stop with the actual limitation if no upscaler is available.
4. Call import_director_stage_panorama with the generated local sourcePath, or with the returned base64/data URL when no local path exists. Set source: "generated", preserve the complete prompt, and pass the target sceneId.
5. Re-read the director-stage state. Confirm the target scene environment contains the returned panorama asset, its dimensions are 2:1, and its source is generated.
6. Keep the widget open so the user can rotate the panorama, calibrate panoramaPitch against the Y=0 editor ground, and inspect blocking from director and camera views.

Never report success before the import tool accepts the image and the scene state contains the asset. Never substitute a color, stock image, ordinary perspective image, cubemap strip, placeholder, or invented path when generation or import fails.

Generation Prompt

Build one concise production prompt containing all of these constraints:

• 360-degree equirectangular environment panorama, exact 2:1 aspect ratio, seamless left and right boundary.
• A level horizon near the vertical middle, correct spherical projection, continuous floor and ceiling/sky, and no visible panorama seam.
• A readable, mostly walkable staging area around the scene origin and lower-middle hemisphere.
• Environment scale, architecture, entrances, windows, roads, furniture zones, terrain, and depth landmarks relevant to the requested location.
• Lighting direction, time of day, weather, palette, and atmosphere suitable for the intended shots.
• No people, bodies, text, logos, watermarks, UI, borders, fisheye frame, tiny planet, or ordinary single-view perspective.
• No important doorway, face-like object, vertical edge, or hero prop crossing the left/right seam or either pole.

Describe spatial zones in 360 terms instead of one camera composition. For example: main staging area around the forward hemisphere, secondary doorway 90 degrees to the right, distant depth landmark behind, and uncluttered ground around the origin.

Scene-Aware Rules

• Preserve the role of editable 3D characters and props. The panorama supplies the distant environment and large fixed context.
• Treat the panorama as an infinite background. Scene scale, translation, and rotation apply to editable characters, props, and cameras, never to the panorama.
• If the generated image's visual floor does not meet the editor grid, adjust panoramaPitch through update_environment; do not move characters vertically to compensate for a horizon mismatch.
• For interiors, keep room scale believable, maintain a continuous floor plane, and avoid furniture that visually occupies the same staging positions as existing 3D objects.
• For exteriors, keep the near ground usable and move dense vegetation, traffic, crowds, or architecture away from planned actor marks.
• Match visible light direction to the stage lights when known. A panorama is not a replacement for explicit Three.js key, fill, or practical lights.
• Use at least 4096x2048 for generated panoramas and prefer 8192x4096 for close or narrow-FOV camera work. Generated images below 4096x2048 are rejected; manually uploaded panoramas below that size remain usable but are marked as low resolution. Every panorama must retain an exact 2:1 equirectangular ratio.

Revision

When the user requests changes, generate a revised panorama from the original brief plus the requested delta, then import it as a new content-addressed asset. Do not overwrite image bytes in place. The scene reference changes only after validation succeeds, so failed revisions leave the current panorama intact.