stickman/docs/plans/phase_19_starter_scene_composition.md

Phase 19 — Starter Scene Composition

Status: Accepted product design for a focused Phase 19 starter-scene polish. This is a design handoff to the spec-pipeline, not a final technical specification.

Goal and audience

Make Town Street and Living Room look like complete, usable story sets when a child opens them, moves the camera, places a stickman, and presses PLAY. The audience is a child starting from File → New who should see a clear place to stage action and be able to change its individual pieces.

The selected visual direction is the upper-left Everyday Storybook composition from the outdoor and indoor concept boards. It favors friendly shapes, a calm backdrop, a clear floor line, and open space for characters and speech.

Desired child outcome

• Town Street: A child immediately recognizes a neighborhood street. Shops, houses, and trees stand on the same sidewalk line; a subdued skyline gives distance; the center has room for a character to walk or speak. The sidewalk, curb, and road remain visible as a continuous set as the child pans through the intended starter area.
• Living Room: A child immediately recognizes a room with a complete wall and wood floor. The window is the only opening to the Sky. Furniture rests on the floor, and a centered rug gives the room warmth while leaving a clear action lane.
• In either starter, the child can select, move, resize, restyle, or remove ordinary pieces with the existing Stage tools, then save and reopen the revised scene.

Core behavior and composition

Opening and editing. Keep the existing Blank Scene, Town Street, and Living Room choices and the current unsaved-scene flow. The two revised starters should open at a useful camera frame with no setup step. They remain editable scenes assembled from the existing Sky, Scenery, wall/background surfaces, walkable Ground, and Props. Do not flatten a starter into a single picture or merge independently useful objects merely to hide seams.

Outdoor set. Use the current Cloudy Day Sky and a quiet Far skyline. Arrange the existing house, storefront, and tree artwork so their visible bases meet one consistent street datum. Preserve a generous, readable opening near the initial center for a stickman and speech. Carry Sidewalk and Asphalt as left-to-right rows of ordinary-size Ground tiles across the visible frame and agreed pan range. Add an opaque, non-walkable Background ground layer below the skyline datum to cover clouds showing through the lower scene. Buildings and trees may repeat or vary in size and spacing to support a longer street, while remaining individual editable placements.

Indoor set. Carry the painted wall and a left-to-right row of ordinary-size Wood Ground tiles across the initial frame and agreed pan range. Make the wall and floor meet cleanly with a visible baseboard or equivalent visual edge. Keep the intentional opening beneath the window frame as the only place the selected Sky shows through; no Sky should leak at outer wall edges, below the floor, or through unintended seams. Position the couch, armchair, and coffee table so they visually rest on the floor. Center the existing rug in the room, show it above the wood finish and below action, and leave enough uncluttered floor for a character to move and be seen. Wall decoration remains secondary to the window and action area.

Camera envelope. The approved implementation target is a 4,760-world-unit minimum for each walkable span: a 1,280-logical-pixel viewport at saved zoom 0.5, ±1,000 world units of pan from the saved camera, and 100 world units of margin at each end. Twenty-five standard 192-unit tiles span 4,800 units and satisfy the target without oversized scaled blocks. Town Asphalt adds one normal-size tile at each end (27 total) so the lower road is physically reachable beyond the sidewalk ends. Outside the defined starter envelope, finite set edges may appear naturally because the camera remains unrestricted. The architecture spec records the exact formula and accepted trade-offs.

Story and kid-facing feedback

The default shot should communicate where action can happen without explanatory text. A child placing a stickman should see feet on a walkable surface, room in the center for a short walk or conversation, and enough contrast to read the character and a speech bubble. Panning should reveal more of the same coherent set, with no sudden floating building, missing floor, or stray Sky gap. Existing Scenery and Ground editing affordances provide recovery if a child moves a piece; this polish adds no new child-facing controls.

Success criteria

1. At the saved starting camera, both starters read as complete places at normal Stage size, with a clear central action area and understandable walkable surfaces.
2. In Town Street, every near building and tree appears grounded on the sidewalk/curb datum. Sidewalk and road continue across the initial view and the defined horizontal pan envelope without an exposed end or distracting join. A character can step from the sidewalk onto the road at either exposed end. The Far skyline remains subdued behind the action.
3. In Living Room, the wall, baseboard, and wood floor continue across the initial view and pan envelope. The selected Sky appears through the window opening only. Couch, chair, and table visibly contact the floor; the rug remains centered and does not consume the character's main movement lane.
4. At normal framing, a placed stickman and speech remain easy to see in both starters. PLAY preserves the intended walking/support behavior, visual order, and composition; saving and reopening preserves the revised set and camera frame.
5. The important pieces remain separately editable through their established tools. Moving or removing one house, tree, wall panel, Ground piece, rug, or furniture Prop does not require replacing a baked image.

The pre-implementation design review found the outdoor artwork bases roughly 128 screen pixels above Ground, the 700-world-unit Ground run ending inside a roughly 917-pixel viewport, and the indoor couch/chair roughly 24 screen pixels above the floor. Those measurements motivated the composition work; they are not final placement coordinates.

Scope and exclusions

Included: Composition and placement polish for the existing Town Street and Living Room starter scenes; continuity of existing surfaces and backdrops over a defined pan range; alignment of visible artwork and furniture with their shared ground/floor datum; initial camera framing; preservation of scene editability and existing Prop/Scenery roles.

Excluded: New story mechanics, sit behavior, new controls or authoring tools, Stage-wide Undo/Redo, camera restrictions, endless scenery generation, and changes to terrain collision or a general navigation system. The existing navigation bake receives only the tile-seam and exposed 32-unit curb connectors required by these authored surfaces. New art is outside this pass unless the existing library cannot make the selected composition legible; identify any specific missing visual element before proposing an asset request.

Current project behavior and references

The Phase 19 scenery product plan defines the starter choices, editable scenery layers, and the distinction between visual Scenery and walkable Ground. The Background Ground and Wall Color brief defines decorative Background ground and editable wall finishes. The Phase 19 handoff says overall user/editor verification is still pending.

The accepted visual direction is detailed in the starter-scene UI/UX specification. The implementation contract is in the approved starter-scene architecture specification.

Before this composition pass, the Town Street scene used one Far skyline, separate Near trees/buildings, and short Sidewalk/Asphalt Ground runs. The Living Room scene used three wall panels, seven Wood Ground pieces, separate decorations, and three Props. Both saved zoom 0.5. The implementation now promotes these starters to current scene format v1.6, extends required surfaces to the approved envelope, and frames starter previews from the saved camera. See the focused architecture specification for exact placements and verification results. The existing artwork and furniture remain in content/props, with each placement independently editable.

Verification status and remaining checks

• The focused composition suite passes 515 assertions, including tile bounds, seam navigation, a physical PLAY step from sidewalk to road, and Living Room floor support.
• A render-capable capture route is not available in this run: the bounded GUI capture exited 134 without producing an image. Visual checks remain for the opening frames, pan endpoints, tile/background joins, starter cards, narrower viewport, and zoom-in framing.
• The broader scenery suite still exits 1 on nine Sky-preview/gallery and Scenery-edit interaction assertions; Town/Living Room surface assertions pass and those nine failures were also present before the latest tile and curb changes.

Implementation status

The initial focused composition test passed 177 assertions, but user visual review found clouds visible through the Town Street below the skyline and rejected the oversized scaled walkable blocks. The revision adds opaque Grass Background ground, ordinary-size tile rows, and a one-tile Asphalt extension at each end so characters can reach the road. The focused composition suite now passes 515 assertions, including routing across tile seams and a grounded PLAY drop onto Asphalt. Rendered review and user/editor checks remain pending. The architecture specification records the measurements and test limitations.