stickman/docs/plans/phase_19_scenery_backgrounds_surface_finishes.md

Phase 19 — Scenery, Backgrounds, and Vector Surface Finishes

Status: Accepted product/design brief. Technical specifications and implementation remain to be developed through the spec-pipeline. Audience: UI/UX, architecture, implementation, and art contributors. Purpose: Define the child experience and the content required for indoor and outdoor sets. Rendering, file contracts, and GDScript APIs belong in later specifications.

Goal and audience

Give children a quick way to make a Stage feel like a place: a town street, a living room, or their own setting. They should be able to choose an appealing sky, dress a scene with inert vector artwork, paint visual wall and Ground finishes, and then direct characters among ordinary props. The art remains crisp when the Stage camera pans or zooms.

The audience is a child using the Sandbox Stage's EDIT, DIRECT, and PLAY modes. The central distinction should be easy to learn: Scenery looks and stays put; Props can be part of the action; Ground is where stickmen walk. An artwork asset can be used in more than one role; the Stage placement choice gives that copy its behavior.

Desired child outcome and story value

• Start with Blank Scene, Town Street, or Living Room, then change any ordinary part of the starter instead of being locked into one background picture.
• Build a layered outdoor set: cloudy sky, distant skyline, nearer shops and trees, sidewalk, and road. Characters remain readable and can move on the Ground.
• Build an indoor set: painted wall, window, wall decorations, wood floor, rug, and furniture. A child can change the Sky seen through the starter's window without recoloring the room.
• Use Far, Near, and On the floor scenery to express distance and staging without giving scenery collision or interactions. A child may draw a tree once and place it as either Scenery or a Prop in different scenes.
• Save, reopen, revise, and replay the scene without losing the selected finishes, sky, artwork, or depth choices.

The feature helps children establish story mood and place before directing dialogue and action. Sky and set dressing are visual choices. Functional doors, upper floors, and whole-scene color filters remain separate story mechanics.

Child flow and feedback

Start a scene

File → New shows three large illustrated choices: Blank Scene, Town Street, and Living Room. The existing unsaved-work flow protects the current scene before any choice replaces it. Cancel returns to the existing work. A starter opens as a new unsaved scene with an editable suggested name; it does not insert itself into another scene or create a locked template instance.

New Scene choice	Initial composition	Child can change
Blank Scene	Empty Stage with the existing neutral background and no placed Ground.	Sky, Scenery, Ground, characters, and Props from scratch.
Town Street	Cloudy Day Sky; muted skyline in Far; colorful storefront, house, and tree artwork in Near; walkable Sidewalk and Asphalt Ground.	Sky, skyline strip, individual near artwork, Ground pieces and finishes, plus any added cast or Props. A skyline strip is one artwork placement, not independently editable buildings inside it.
Living Room	Clear Day Sky; green painted wall panels around a window opening; Near window frame, fireplace/mantel, clock, shelf/books, picture, and plant; Wood Ground; an On the floor rug; couch, armchair, and coffee-table Props.	Every panel, artwork placement, rug, Ground piece, and furniture Prop. The wall panels leave an intentional gap beneath the window frame, so the selected Sky is actually visible. Moving or resizing the window and wall pieces may require adjusting more than one piece; this phase has no automatic window-cutting tool.

The starters demonstrate what children can make with the normal tools. Furniture in Living Room starts still with sensible blocking/support behavior where appropriate; the starter does not imply that characters can sit. A short cue may point children to Scenery after a starter opens, without covering the Stage.

Open Scenery

The Stage palette gains Scenery. Its chooser has Backgrounds and Artwork:

Scenery
[ Backgrounds ]  [ Artwork ]

Backgrounds: [ Sky ] [ Wall panel ]
Artwork: [ All artwork ] [ Nature ] [ Buildings ] [ Walls ]
         [ Roads & paths ] [ Objects ]

The Artwork choices use large previews. The tag filters describe the drawing, not what it can do. The built-in, optional, multi-select tag IDs are nature, buildings, walls, roads, and objects; the child-facing labels above can be refined without changing the stored meaning. One drawing may appear in several categories. All artwork includes old and untagged work; Unsorted can appear when there is untagged artwork to show. The same tags can filter the Props browser. The Props and Scenery entry points remain visibly distinct so children do not have to turn off interaction settings for every background item.

The existing vector Prop Editor and .prop assets supply user-created artwork. Phase 19 should make that art discoverable from Scenery, including artwork that has no usable collision hull. There is no separate Scenery Editor or .scenery format in this phase. A later child-facing name such as Artwork Editor may better describe its broadened use; the UI/UX specification should decide how much prop-only material and attachment controls are shown during scenery authoring.

Choose a Sky

Backgrounds → Sky shows four designed thumbnail cards: Clear Day, Cloudy Day, Sunset, and Starry Night. One tap changes the scene's Sky, and choosing another card changes it again. A Sky fills every camera view without an exposed edge; its clouds, sun, moon, and stars remain visually stable and crisp during pan and zoom. Each preset should be a considered composition rather than a flat color with an obvious repeated icon. The Sky remains fixed throughout PLAY.

Changing Sky changes only the sky. It never tints or recolors Ground, wall panels, scenery artwork, characters, or Props. Sky is selected through its chooser, not by clicking a giant rectangle on the Stage.

Draw a wall panel

Backgrounds → Wall panel offers Paint, Brick, and Wood finishes with a color choice. The child chooses a finish, drags from one corner to the other, sees a translucent preview of the intended size and pattern, and releases to place a finite rectangular panel. Snap may help edges meet. A selected panel can later be moved, resized, recolored, restyled, or erased; changing one panel does not silently alter others.

The child-facing explanation should make its role clear: “Looks like a wall. Stickmen can pass through.” A wall panel is world-anchored backdrop art. It does not block a stickman, support a prop, move under physics, respond to Use, or trigger rules. A solid wall belongs to terrain or a later structural feature. When a panel grows, bricks or boards retain a sensible world-scale motif rather than stretching a small image.

Place and edit artwork

The child opens Artwork, chooses a tag such as Nature, taps a drawing such as Tree, sees a ghost over the Stage, and taps to place it. Each Scenery placement offers a simple illustrated depth choice: Far, Near (default), or On the floor. Far supports distant silhouettes such as a skyline. Near supports storefronts, trees, window frames, and wall decor. On the floor supports rugs and markings that sit over finished Ground but under action. A child can change the depth later. Artwork placed through Scenery stays fixed and inert even if the same .prop can also be placed through Props as an interactive object.

The authoritative visual order is:

Sky
  → wall panels
  → Far scenery artwork
  → Near scenery artwork
  → walkable Ground
  → On the floor scenery artwork
  → characters and interactive Props (retaining their existing relative depth choices)

Every Scenery tier is visual only. Its depth never grants collision, support, pickup, Use spots, or event participation. An On the floor rug is visible above a wood Ground finish without covering furniture or the character's feet.

Edit Scenery exposes the scenery pieces for selection. A clear outline and large handles let the child move and resize art, change its depth, or erase it; a wall panel also exposes Finish and Color. Broad panels must not steal clicks or box selections from characters, Ground, and Props in ordinary EDIT. Within Edit Scenery, a cutout in front of a panel should be easy to choose, and the panel must still be reachable through its exposed area, edge, or an overlapping-items choice. Sky remains in its own chooser. A visible Cancel closes a placement or sizing gesture before commit, and leaving Edit Scenery returns to ordinary selection. Selection and focus cannot rely on color alone.

Finish Ground and play

The existing Ground palette entry gains a visual finish chooser. Picture swatches include Paint, Brick, Wood, Grass, Dirt, Sidewalk, and Asphalt. Paint, Brick, and Wood share recognizable names/previews with Wall panel where applicable; Ground-only outdoor finishes need not appear in the wall picker. Tap for one Ground piece or use the existing drag-paint gesture for a run. Ghosts show the selected look. A new choice affects new placements only. Selecting an existing Ground piece lets the child deliberately change that piece's finish. Adjacent painted pieces should read as one continuous surface, especially wood floors, sidewalks, and roads.

Ground remains solid and walkable. This phase gives finishes only to Ground; it does not redesign or restyle Ramp and Step. Children can use Sidewalk and Asphalt Ground in Town Street and Wood Ground in Living Room. A Scenery wall panel or road marking never becomes a movement surface.

In PLAY, edit handles and placement ghosts disappear. Sky and Scenery stay still; characters move on Ground; Props follow their own saved behavior settings. Stopping PLAY restores the authored arrangement for another take. Story playback and camera movement should preserve the intended visual layer order and the child's view of the action.

Included scope and exclusions

Included in Phase 19: one fixed scene-wide Sky preset; four initial Sky designs; finite editable wall panels; inert .prop Scenery placements with Far, Near, and On the floor depth; built-in multi-select browse tags; Ground-only visual finishes; editable Blank/Town Street/Living Room New Scene choices; Scenery-safe selection; scene save/reopen and legacy defaults; and the built-in vector content listed below.

Excluded from Phase 19: a new Scenery Editor or .scenery file; child-authored repeatable finish patterns or reusable whole-Sky themes; animated weather, parallax, or directed Sky transitions; whole-scene filters such as sepia or black-and-white; functional doors or scene travel; automatic window cutouts or glass; Ramp/Step finishes or terrain redesign; inserting a starter into an existing scene; user-authored reusable set templates; and functional stairs or multi-level travel. Multi-level walkable scenes and whole-scene visual filters are separate future ideas, not Phase 19 work.

Asset production manifest

This is the authoritative content checklist for the two starters and the shared pickers. The initial status of every row is Needed. Progress through Needed → Concept ready → Art approved → Final vector ready → Integrated → Verified. A raster sketch may reach Concept ready; it is not a final .prop, Sky theme, or repeatable vector finish. Final cutouts must be repo-native vector/.prop artwork, and Sky/finish visuals must remain crisp through Stage zoom. Art contributors may use raster concept images as reference, then produce final assets in coordination with implementation.

In the tables, TBD in Source/rights means the creator, reference provenance, and license or permission still need recording. TBD in Final location and Evidence means those fields must be filled as content is produced. For each row, validation evidence should include a thumbnail or Sky/finish preview, the asset in the Stage at normal and zoomed views, and save/reopen of its starter use where applicable. Stable IDs identify deliverables; they are not prescribed file names or runtime contracts.

Adaptive Sky themes

Stable ID	Class / final format	Tags / default layer	Starter use	Behavior / collision	Status	Source / rights	Visual acceptance	Final location / definition	Validation evidence
sky_clear_day	Adaptive vector Sky theme; not .prop	N/A; Sky	Living Room; picker	Scene-wide, static; none	Needed	TBD	Appealing blue depth and varied light cloud/sun detail; window gap reads clearly; no edge on pan.	TBD	TBD
sky_cloudy_day	Adaptive vector Sky theme; not .prop	N/A; Sky	Town Street; picker	Scene-wide, static; none	Needed	TBD	Layered, varied clouds leave town silhouettes readable; no obvious tile or edge.	TBD	TBD
sky_sunset	Adaptive vector Sky theme; not .prop	N/A; Sky	Picker	Scene-wide, static; none	Needed	TBD	Warm atmospheric color and sun/cloud composition remain distinct from Clear Day without tinting scene objects.	TBD	TBD
sky_starry_night	Adaptive vector Sky theme; not .prop	N/A; Sky	Picker	Scene-wide, static; none	Needed	TBD	Dark graduated sky, varied stars, and moon remain legible while foreground contrast survives.	TBD	TBD

Repeatable vector surface finishes

These are finish definitions and previews, not ordinary Props. Ground finishes change appearance without changing Ground's walkability; wall finishes stay inert.

Stable ID	Class / final format	Tags / default layer	Starter use	Behavior / collision	Status	Source / rights	Visual acceptance	Final location / definition	Validation evidence
finish_wall_paint	Vector wall finish	N/A; wall panel	Living Room; picker	Inert panel; none	Needed	TBD	Smooth green room wall and other chosen colors without seams at panel edges.	TBD	TBD
finish_wall_brick	Repeatable vector wall finish	N/A; wall panel	Picker	Inert panel; none	Needed	TBD	Bricks keep coherent size and joins as panel is resized.	TBD	TBD
finish_wall_wood	Repeatable vector wall finish	N/A; wall panel	Picker	Inert panel; none	Needed	TBD	Boards read as wood at common Stage zoom and do not stretch with the panel.	TBD	TBD
finish_ground_paint	Vector Ground finish	N/A; Ground	Picker	Solid, walkable Ground	Needed	TBD	Plain color is clean and visually distinct from wall-only backdrop.	TBD	TBD
finish_ground_brick	Repeatable vector Ground finish	N/A; Ground	Picker	Solid, walkable Ground	Needed	TBD	Neighboring pieces form a continuous brick surface.	TBD	TBD
finish_ground_wood	Repeatable vector Ground finish	N/A; Ground	Living Room; picker	Solid, walkable Ground	Needed	TBD	Wood plank floor reads continuously beneath rug and furniture.	TBD	TBD
finish_ground_grass	Repeatable vector Ground finish	N/A; Ground	Picker	Solid, walkable Ground	Needed	TBD	Grassy surface is readable and not noisy behind feet.	TBD	TBD
finish_ground_dirt	Repeatable vector Ground finish	N/A; Ground	Picker	Solid, walkable Ground	Needed	TBD	Earthy surface remains distinct from Grass at thumbnail and Stage size.	TBD	TBD
finish_ground_sidewalk	Repeatable vector Ground finish	N/A; Ground	Town Street; picker	Solid, walkable Ground	Needed	TBD	Light concrete sidewalk forms a broad, aligned run beneath shops.	TBD	TBD
finish_ground_asphalt	Repeatable vector Ground finish	N/A; Ground	Town Street; picker	Solid, walkable Ground	Needed	TBD	Darker road contrasts with sidewalk while preserving visible character edges.	TBD	TBD

Reusable Scenery artwork

Each item below is a .prop vector artwork asset offered through Scenery. Its Scenery placement has no collision or interaction even if the artwork is also available through Props. Final visual-only art must not require an invented solid collision shape merely to enter the Scenery catalog.

Stable ID	Class / final format	Tags / default layer	Starter use	Behavior / collision	Status	Source / rights	Visual acceptance	Final location / definition	Validation evidence
art_city_skyline	Vector .prop cutout	Buildings; Far	Town Street ×1	Inert; none	Needed	TBD	Long, muted overlapping building silhouette reads as distant and leaves cloud sky visible.	TBD	TBD
art_storefront	Vector .prop cutout	Buildings; Near	Town Street ×1 or more	Inert; none	Needed	TBD	Colorful, readable shop front contrasts with skyline; repeat use does not look like one flat strip.	TBD	TBD
art_town_house	Vector .prop cutout	Buildings; Near	Town Street ×1 or more	Inert; none	Needed	TBD	House silhouette and palette differ clearly from storefront at normal zoom.	TBD	TBD
art_tree	Vector .prop cutout	Nature; Near	Town Street ×2 or more	Inert; none	Needed	TBD	Friendly, readable crown/trunk; repeated copies tolerate size and position variation.	TBD	TBD
art_window_frame	Vector .prop cutout	Walls, Buildings; Near	Living Room ×1	Inert; none	Needed	TBD	Frame is transparent at its center and aligns over the wall-panel gap to reveal actual Sky.	TBD	TBD
art_fireplace_mantel	Vector .prop cutout	Walls, Objects; Near	Living Room ×1	Inert; none	Needed	TBD	Fireplace and mantel read clearly as decoration without suggesting this asset itself blocks movement.	TBD	TBD
art_wall_clock	Vector .prop cutout	Walls, Objects; Near	Living Room ×1	Inert; none	Needed	TBD	Clock reads at room scale without tiny illegible markings.	TBD	TBD
art_bookshelf	Vector .prop cutout	Objects, Walls; Near	Living Room ×1	Inert; none	Needed	TBD	Shelf, books, and plant details remain legible without dense tracing.	TBD	TBD
art_framed_picture	Vector .prop cutout	Objects, Walls; Near	Living Room ×1 or more	Inert; none	Needed	TBD	Clear frame and image contrast on green paint; reuse can vary size/position.	TBD	TBD
art_potted_plant	Vector .prop cutout	Nature, Objects; Near	Living Room ×1	Inert; none	Needed	TBD	Leaf and pot shapes remain distinct from wall and furniture.	TBD	TBD
art_rug	Vector .prop cutout	Objects; On the floor	Living Room ×1	Inert; none	Needed	TBD	Visible over Wood Ground and below furniture/feet; border survives zoom.	TBD	TBD

Interactive furniture Props

These are .prop assets placed through Props in Living Room. Their authored shape and placement roles must support the stated behavior. The same artwork may still be offered as inert Scenery when deliberately placed through Scenery.

Stable ID	Class / final format	Tags / default layer	Starter use	Behavior / collision	Status	Source / rights	Visual acceptance	Final location / definition	Validation evidence
prop_couch	Vector .prop furniture	Objects; Prop depth per placement	Living Room ×1	Still, appropriately character-blocking; valid collision	Needed	TBD	Comfortable couch silhouette sized for stickman and room; no implied Sit action.	TBD	TBD
prop_armchair	Vector .prop furniture	Objects; Prop depth per placement	Living Room ×1	Still, appropriately character-blocking; valid collision	Needed	TBD	Distinct chair silhouette, matching couch style and character scale.	TBD	TBD
prop_coffee_table	Vector .prop furniture	Objects; Prop depth per placement	Living Room ×1	Still, can support small props; valid collision	Needed	TBD	Tabletop/support reads clearly and leaves rug visible.	TBD	TBD

Existing built-in crate and ball artwork may be used in Town Street if an interactive object benefits that starter; no new interactive town asset is required to achieve its visual reference. The artist should establish a coherent cartoon style and scale against the live stickman. Far art is quieter than Near art; outlines and silhouettes must remain clear at selector-thumbnail size and normal Stage zoom. Avoid excessive vector point counts, hard-to-read microdetail, and busy contrast behind character faces or speech bubbles. The source/rights field must distinguish original art, licensed sources, and generated raster concepts. Reference art is not automatically licensed final content.

Success criteria

1. A child can create Town Street from New Scene, recognize the intended Sky/skyline/shops/trees/sidewalk/road composition at the default view, move or remove any placed piece, save it, reopen it, and keep the same look and behavior.
2. A child can create Living Room from New Scene, see the actual selected Sky through its window gap, change the Sky without tinting the room, restyle the wall or Wood Ground, move the rug and furniture independently, and save/reopen the revised set.
3. A child can place one .prop drawing through Scenery and through Props and understand that the two copies behave differently. The Scenery copy never blocks, supports, moves, is picked up or used, or triggers an event in PLAY.
4. Far skyline, Near buildings/trees, Ground, On the floor rug, and Props preserve their intended order through pan, zoom, PLAY, stop, and reload. Character and speech readability survives the four Sky styles and common finishes.
5. Ordinary EDIT selection still reaches foreground characters, Props, and Ground over broad panels. Edit Scenery makes every cutout and panel discoverable and correctable; placement and resize can be canceled before commit. Labels, icons, outlines, and focus reveal state without depending on color alone.
6. Wall panel and Ground finish choices preview correctly; wall patterns do not stretch as panels resize, and adjacent Ground pieces do not show distracting pattern restarts. Changing a palette finish does not repaint existing pieces; a selected piece can be changed deliberately.
7. Older .scene documents retain their prior neutral background and Ground appearance when opened. Older untagged .prop assets remain visible in All artwork, and a missing referenced Scenery asset yields a visible recovery cue rather than silently removing the child's placement.
8. Every required manifest item reaches Verified, with source/rights and final location recorded. A raster concept alone cannot satisfy a final vector content requirement.

Current project context, risks, and dependencies

• The Stage currently has a World, camera, optional world-space grid, registry-driven palette, Ground/Ramp/Step terrain, Props, and stickmen. Ground is a solid TerrainBlock; its drag painter creates independent blocks. Phase 19 must preserve Ground walkability and avoid treating Scenery panels as terrain.
• The current .scene save boundary is StageSceneIO with mapping in StageSceneAdapter. It stores terrain, Props, stickmen, and areas but no Sky, wall panels, or Scenery placements. The accepted design requires additive saved appearance and placement data with legacy defaults; the architect will decide schema and migration details. Persist artwork references through the project's ContentPaths conventions.
• The .prop format and Prop Editor already author multi-shape vector art. PropLibrary currently rejects custom artwork without valid closed collision geometry. Visual-only Scenery must accept legitimate artwork without fake physics. The architect and UI/UX lead should resolve how the same art catalog serves both placement routes and how old untagged art stays discoverable.
• Stage selection currently uses World-object bounds and an overlapping-object chooser. Large wall panels and floor art can otherwise catch almost every click or box selection. A dedicated, forgiving Scenery edit flow and predictable hit order are product requirements. The approved Stage panel UI system supplies the in-stage inspector visual contract; adapt it for selected Scenery/Ground controls where it fits.
• Finite panels, tiled vector finishes, and detailed Sky motifs must stay crisp and performant across Stage zoom and camera pan. Ground pieces need aligned world-scale patterns. The Town Street and Living Room references should guide composition and mood, not be treated as final licensed assets.
• The two starters require the manifest content as real deliverables. Missing art, inconsistent scale, or raster-only placeholders would leave a child with a visually incomplete feature even if the controls work.

Remaining questions for the spec-pipeline

These are design and architecture tasks for the specification stage, not unresolved user choices about Phase 19's product goal:

1. What exact UI presents Backgrounds, Artwork tags, placement layer, Ground finish, and Edit Scenery without crowding the existing Stage palette? Define keyboard, touch, narrow-viewport, dismissal, and undo/cancel behavior using the established Stage panel patterns.
2. How will an adaptive Sky fill unbounded camera views while keeping motifs stable and detailed, and how will wall and Ground finishes keep repeatable pattern scale and alignment through resizing, drag painting, and zoom?
3. What saved scene and optional .prop tag fields, validation, migration defaults, missing-art recovery, and starter creation flow preserve existing documents and the same artwork's independent Scenery/Prop placements?
4. How will selected panels, cutouts, rugs, Ground, and ordinary objects remain reachable where bounds overlap, including the window gap and a room-sized wall?
5. Which asset production workflow turns concepts into final vector content, records provenance, checks collision only for interactive Props, and advances each manifest row through integration and verification?

The live feature backlog tracks the separate follow-up work, including multi-level walkable scenes and whole-scene visual filters.