Scene, layout, and composition

Mental model

Story composition starts with two root spaces and then layers structure on top. World content is the default authored stage, screen content is the late-drawn overlay stage, layers group ordered child trees in local coordinates, layout actions calculate assignment plans, and arrange turns those plans into actual sprite movement. Non-root layers can optionally flatten their subtree as one planar 3D surface.

Responsibilities and boundaries

• Root create.space decides whether a sprite belongs to world or screen.
• Layers own local child order, clips, and grouping, but not a second action runtime.
• Layout solvers calculate results; arrange applies those stored assignments.
• Camera and world transforms shape world presentation; screen content ignores both and is composited last.
• Layer 3D is a layer-level projection boundary, not a general scene graph.

Stable current behavior

• Root composition is a world branch plus a screen branch with one final host-mapped logical-canvas clip.
• Layer child order is painter order, and LayerSprite keeps top-left x/y positioning rather than an align model.
• row, column, and align store layout results as descriptor-backed target assignments tied to stable sprite identities.
• arrange preflights live targets before writing, so it applies atomically to compatible survivors of morph and destroy.
• Active Layer 3D projects the full captured subtree, preserving child overlap, clips, effects, text, video, and isolated opacity as one plane.

Current limitations

• row and column currently honor gap only. bounds, hAlign, and vAlign are accepted by the schema but are not applied yet.
• Mixed world/screen layout inputs are rejected instead of projected across spaces.
• Root 3D and nested active 3D planes are forbidden.
• Active 3D siblings keep Story painter order; there is no depth sorting, Z-buffer, raw matrix authoring, or near-plane clipping surface.

How the pieces connect

1. Root actions create sprites into world or screen space.
2. Layers and Composites establish local coordinate and naming contexts.
3. Layout actions read current scene geometry and store future assignment plans.
4. arrange applies those plans through the same property assignment path as ordinary set.
5. Playback renders world through camera/world transforms, then overlays screen content, with optional layer-plane projection at non-root child boundaries.

Go deeper

• Learn: Layout and cameras, Composition and reuse
• Examples: Camera, world, and HUD, Layer 3D store window, Path motion and trim
• Reference: Story syntax
• Specs: RUNE-1002, RUNE-1014, RUNE-1017