tools.compose_scene module

COMPOSE_SCENE – Star’s VN scene director tool.

Star builds a JSON scene script specifying characters, backgrounds, dialogue, stage directions, sound effects, and transitions. The script is stored in Redis and published as a scene_event for the web client to play back as full VN-style cutscenes.

@fire @skull THE DIRECTOR SPEAKS. THE STAGE OBEYS.

async tools.compose_scene.run(title='Untitled Scene', characters=None, background=None, music=None, script=None, ctx=None)[source]

Build, validate, persist, and broadcast a VN scene script.

Entry point for the compose_scene tool, which lets Star direct fullscreen visual-novel cutscenes on the web client. It validates that every script step has a known type (against the in-function valid_types set), rewrites the asset path shortcuts (sfx:/bgm:/ambience:/bg:) on the sound/track/loop/image fields to their served paths, ensures the script terminates with an end step, and stamps the scene with owner platform/channel/user ids for the web UI’s access control. It then writes the scene to Redis under star:scenes:{scene_id}, marks it pending at star:pending_scene, and publishes it on the star:scene:play channel for immediate pickup. As a bonus, any dialogue step flagged as_ghost for a non-Star character is delivered as a Matrix ghost message via egregore_bridge.get_bridge.

Dispatched by tool_loader.py as the compose_scene handler (located via getattr(module, "run")); not called directly elsewhere. Side effects are the three Redis writes/publish on ctx.redis and the optional Matrix ghost-message sends.

Parameters:

  • title (str) – Scene title shown on the title card before playback.

  • characters (list | None) – Character ids appearing in the scene (required).

  • background (str | None) – Optional background filename or URL.

  • music (str | None) – Optional background-music track URL.

  • script (list | None) – Ordered list of step dicts, each with a type and type-specific fields (required).

  • ctx (ToolContext | None) – Tool execution context supplying redis plus the owner platform/channel_id/user_id.

Returns:

A JSON object with success, the scene_id, the step count, and the ghost-message count on success, or an {"success": false, "error": ...} object on a missing context/Redis, missing required inputs, an invalid step, or a publish failure.

Return type:

str