Add Stage Surface Color Dialog and Background Ground Functionality

- Implemented StageSurfaceColorDialog for custom color selection with live preview. - Created StageBackgroundGround class for non-walkable scenery behind the set. - Introduced StageRectSurface for shared rectangular geometry and tint preview. - Added StageSurfacePreview for rendering surface previews. - Developed comprehensive tests for surface color selection, rendering, and serialization.
2026-10-17 21:00:03 -04:00
parent a0510e6405
commit 26dd9c64e1
39 changed files with 3118 additions and 142 deletions
@@ -0,0 +1,74 @@
+# Phase 19 — Background Ground and Wall Color
+
+> **Status:** Accepted product design for a focused Phase 19 follow-up. This brief is the Designer handoff to UI/UX and architecture specifications; it does not define runtime APIs or node structure.
+
+## Goal and audience
+
+Help a child make a Stage feel like a coherent place. Wall panels need a working color choice, and broad ground visible behind buildings or furniture needs its own decorative surface. A child should be able to make the grassy town backdrop in the reference scene, or an indoor carpeted backdrop, without changing where stickmen can walk.
+
+The audience is a child arranging scenes in the Sandbox Stage's EDIT mode and then directing or playing them. The distinction remains simple: **Background ground looks like ground; walkable Ground is where stickmen walk.**
+
+## Desired outcome and story value
+
+- Make a town green behind its buildings and trees while the ordinary Ground tiles still define the walking route.
+- Give a room a carpeted background area in a chosen color, or give an outdoor set a concrete backdrop.
+- Change a painted wall's color and choose a brick or wood color that still looks textured.
+- Reuse favorite colors across walls and carpet without reconstructing a color in every scene.
+- Save, reopen, resize, and rearrange these pieces without losing their look or making decorative areas solid.
+
+## Child flow and behavior
+
+### Choose and edit wall color
+
+In **Scenery → Backgrounds → Wall panel**, the child chooses **Paint**, **Brick**, or **Wood**, then chooses a color. Eight recently used colors appear first, newest first, followed by useful preset colors. **More colors…** opens a color dialog with **Use color** and **Cancel**. A confirmed color updates the small finish preview and the Stage placement ghost before the child draws the panel. Cancel restores the prior choice.
+
+Dragging a rectangle places one wall panel with the chosen finish and color. In **Edit Scenery**, selecting a wall panel exposes **Look** and **Color** in its inspector. A change affects only that panel. The existing move, resize, wall-area erase, and erase-piece behaviors continue to apply.
+
+Paint uses the chosen color as its main surface. Brick and Wood use it to shift their material palettes while retaining recognizable mortar, grain, shading, and variation. Their default choices should look like believable brick and wood; custom colors remain available for imaginative sets. Preview and placed panel must agree about the result.
+
+### Draw Background ground
+
+The **Scenery → Backgrounds** chooser gains **Background ground** immediately after **Wall panel**, with large **Grass**, **Concrete**, and **Carpet** cards. The cards and placement prompt say **“Decorative only · Stickmen don’t walk here.”** The choice is separate from the existing **Ground** palette tool. Carpet has the same recent and preset color choices and **More colors…** flow; confirmed color changes the carpet hue while its fabric detail remains visible.
+
+The child chooses a look, sees a patterned ghost, drags a rectangle, and releases to place a finite decorative surface. In **Edit Scenery**, that piece can be selected, moved, resized, restyled, recolored where applicable, or erased using the same child-facing model as a wall panel. Broad surfaces must remain easy to select in Edit Scenery without taking ordinary EDIT clicks intended for Ground, Props, or characters.
+
+Background ground sits above the Sky and behind wall panels, Far and Near scenery artwork, buildings, trees, and walkable Ground. It is fixed scenery in EDIT, DIRECT, and PLAY. It provides no collision, support, navigation, pickup, Use action, or event target. Walkable Ground keeps its existing physics and terrain tools.
+
+Grass has restrained detail throughout the filled area, so a large green panel reads as grass at normal Stage zoom. Concrete has a distinct surface treatment, and Carpet retains a fabric-like look at chosen colors. Motifs use a stable world scale: resizing reveals or hides more pattern rather than stretching it, and adjoining panels of one look align visibly. Their previews should show the same character as the Stage rendering.
+
+### Reuse colors
+
+Wall Paint, Brick, Wood, and Background ground Carpet share one list of **eight recently used colors**, newest first. Choosing a preset or confirming **Use color** puts that color first and removes any duplicate; the list persists in user settings across scenes. Canceling a custom color dialog or its tentative preview does not add a color. The color history is a convenience for choosing future looks; changing it does not recolor existing pieces.
+
+## Success criteria
+
+- A child can color a new Paint wall and recolor one selected wall without changing another wall. Brick and Wood respond visibly to color while their material details remain legible.
+- A child can place a broad Grass backdrop behind a town's buildings, then place ordinary Ground in front. A stickman follows only the walkable Ground during PLAY.
+- Grass texture remains visible inside a large backdrop at common camera views; Concrete and Carpet are distinguishable in chooser cards and on Stage. A colored Carpet still looks like fabric.
+- Background ground remains finite and editable. Moving or resizing a piece preserves its motif scale; adjoining matching pieces have aligned motifs.
+- The eight-color history is shared across the four colorable looks, persists across scenes and restarts, and ignores canceled choices.
+- Chooser and inspector controls remain reachable on smaller displays, and the visual-only role is clear in words as well as appearance. Save and reopen preserve the pieces, finishes, colors, positions, and visual order.
+
+## Scope and exclusions
+
+Included: the missing wall color controls and textured tint behavior; one decorative rectangular Background ground type with Grass, Concrete, and Carpet; Carpet color; shared eight-color history; responsive chooser and selected-piece editing; visual previews; scene persistence and compatibility with existing scenes.
+
+Excluded: new walkable Ground, Ramp, or Step behavior; changes to navigation or collision; parallax or animated scenery; freehand terrain shapes; user-authored repeatable patterns; automatic horizon blending or edge generation; a general color library beyond the recent list; and a new Scenery file/editor format. The separate [backdrop horizon and edge treatment idea](../ideas/feature_backlog.md) can address deliberate transitions later.
+
+## Current project fit and references
+
+The accepted [Phase 19 product plan](phase_19_scenery_backgrounds_surface_finishes.md) and [UI/UX specification](../specs/phase_19_scenery_backgrounds_ui_ux.md) already call for a wall Color choice and for recoloring a selected panel. The present wall data stores a color, but Brick and Wood rendering uses fixed palettes, and the current chooser and selected-wall card do not expose color. This brief closes that visible Phase 19 gap.
+
+Existing walkable Ground is a `TerrainBlock` with collision and finish drawing. Its Grass motif emphasizes the top edge of the block; it is not the broad interior treatment needed for a distant field. The current semantic draw order places Sky, walls, Far and Near scenery, walkable Ground, floor scenery, and action elements in separate bands. Background ground adds a visual band behind those scene pieces while keeping the Stage's established Scenery selection model.
+
+Relevant implementation locations for the spec-pipeline to inspect are `scripts/stage/scenery/stage_wall_panel.gd`, `scripts/stage/scenery/stage_surface_renderer.gd`, `scripts/stage/stage_draw_order.gd`, `scripts/terrain/terrain_block.gd`, `scripts/stage/stage_scene_io.gd`, `scripts/editors/stage/stage_scenery_controller.gd`, `scripts/editors/stage/sandbox_stage.gd`, `scripts/editors/stage/stage_asset_browser.gd`, `scripts/shared/ui/asset_selector.gd`, and the shared Stage panel system in `docs/specs/stage_panel_ui_system.md`.
+
+## Dependencies, risks, and specification questions
+
+- **Material color:** UI/UX and architecture should define a predictable relationship between the selected hue and each finish's multiple tones. Brick mortar and wood grain must keep enough contrast across very light, dark, or saturated custom colors.
+- **Layering and overlap:** The recommended order is Sky → Background ground → wall panels → Far art → Near art → walkable Ground → floor art → action. The spec should confirm how a large decorative surface is selected when other scenery covers it and how it behaves in existing multi-piece scenery edits.
+- **Large areas and zoom:** Repeatable vector detail needs to stay crisp and coherent without becoming visually noisy or costly across a large rectangle. The spec should settle how it previews at card size and at normal and zoomed Stage views.
+- **Persistence:** Architecture should settle saved identifiers, old-scene defaults, and user-setting storage for the recent colors. The visible history is per user, while each placed piece saves its own color.
+- **Copy and terminology:** UI/UX should settle the final short label for **Background ground**, the helper wording in chooser and capture bar, and the selected-piece inspector wording. The role distinction from walkable **Ground** must survive narrow screens and keyboard/touch use.
+
+These are specification questions; the approved child behavior above should remain intact.