Add StageBackgroundView and related tests for plain background functionality
- Implemented StageBackgroundView class for managing sky and plain backgrounds in the stage. - Added functionality to set background type and color, bind camera, and apply themes. - Created test_phase19_plain_background.gd to validate plain background behavior and migration. - Developed test_phase19_starter_chooser_layout.gd to ensure proper layout and functionality of the starter chooser. - Included visual capture tests for UI elements and interactions.
This commit is contained in:
@@ -0,0 +1,118 @@
|
||||
# Phase 19 — Plain Background: architecture specification
|
||||
|
||||
> **Status:** Approved design; implementation under way. This specification implements the [accepted product brief](../plans/phase_19_plain_background.md) and [UI/UX specification](phase_19_plain_background_ui_ux.md). The color-choices and custom-picker PNGs reflect the current-color chip as the sole custom-picker entry and the simple **Preview** label; the solid fill and exact labels in the UI/UX specification govern implementation.
|
||||
|
||||
## Scope and decisions
|
||||
|
||||
Plain Background is a scene-wide, opaque backdrop. It is not a Stage object, a wall panel, or Background ground. The initial color is `#F5EFE0`. File → New adds a truly empty Plain Background starter and relabels the existing neutral-Sky starter **Open Sky**. EDIT → Scenery → Backgrounds offers Plain Background beside the four existing Sky cards. A scene remembers its confirmed plain color while a Sky is active.
|
||||
|
||||
The approved design uses a small shared view composed of the existing `StageSkyView` and a full-rect solid `ColorRect`. `SandboxStage` owns the confirmed scene values and the short-lived picker draft. No `Resource`, global signal bus, or extra selectable node is needed for three scalar document values. The Stage inspector kit (`StageInspectorPanel`, `StagePanelChoiceGroup`, `StagePanelToggleRow`) remains for selected objects; this is a modal chooser and uses `AssetSelector`, `AssetCard`, the existing color controls, and their theme tokens.
|
||||
|
||||
When Sandbox Stage launches as the active scene without a requested scene, `SandboxStage` opens the starter chooser once after startup recovery handling. A restored autosave remains the active scene without a chooser; discarding recovery opens the chooser. CLI scene requests and load errors keep their existing flows. Closing the startup chooser leaves the empty EDIT Stage open and does not reopen the chooser for that session.
|
||||
|
||||
## Node hierarchy and rendering
|
||||
|
||||
```text
|
||||
SandboxStage : Node2D
|
||||
├─ StageBackgroundLayer : CanvasLayer (layer -1)
|
||||
│ └─ StageBackgroundView : Control (full viewport; ignores mouse)
|
||||
│ ├─ StageSkyView : Control (camera-bound only on the live Stage)
|
||||
│ └─ PlainFill : ColorRect (full rect, opaque, ignores mouse)
|
||||
├─ StageGrid : Node2D (EDIT overlay)
|
||||
└─ World : Node2D (existing placed objects)
|
||||
|
||||
StageStarterCardPreview : SubViewportContainer
|
||||
└─ PreviewViewport : SubViewport
|
||||
├─ PreviewBackgroundLayer : CanvasLayer (layer -1)
|
||||
│ └─ StageBackgroundView (unbound still)
|
||||
└─ PreviewWorld : Node2D
|
||||
|
||||
AssetSelector scene-wide card
|
||||
└─ StageBackgroundCardPreview : Control
|
||||
└─ StageBackgroundView (unbound still, clipped to card)
|
||||
```
|
||||
|
||||
`StageBackgroundView` toggles its Sky and Plain children exclusively. A Plain view is a single opaque viewport-sized rect, with no gradient, horizon, motif, parallax, or world transform. Its anchors respond to viewport resize. `StageSkyView` continues to own all five existing Sky IDs and camera response; when hidden for Plain it should not spend frames updating Sky motifs. The view and both children ignore mouse input and never enter Stage selection or draw-order lists. The starter preview must use the same background-kind and color interpretation as the live Stage. The gallery card receives the **remembered** plain color even when the active kind is Sky. Card frames and labels are UI overlays outside the fill, not part of its sample.
|
||||
|
||||
## Typed contracts and ownership
|
||||
|
||||
| Target | Contract and change | Owner responsibility |
|
||||
| --- | --- | --- |
|
||||
| `scripts/stage/scenery/stage_background_view.gd`, `class_name StageBackgroundView extends Control` | `func set_background(kind: StringName, sky_id: StringName, plain_color: Color) -> void`; `func bind_camera(camera: Camera2D) -> void`; `func apply_theme(stage_theme: SandboxTheme) -> void` | Only renders a validated Sky or opaque Plain fill. Reuses `StageSkyView`; has no document, history, or picker state. `bind_camera(null)` yields still previews. |
|
||||
| `scripts/editors/stage/sandbox_stage.gd`, `class_name SandboxStage extends Node2D` | Confirmed `_background_kind: StringName`, `_sky_id: StringName`, `_plain_color: Color`; transient `_plain_color_draft_active: bool`, `_plain_color_draft: Color`. Private typed helpers such as `_commit_background_kind(kind: StringName, sky_id: StringName = &"") -> void`, `_commit_plain_color(color: Color) -> void`, `_preview_plain_color(color: Color) -> void`, `_cancel_plain_color_preview() -> void`, `_refresh_background_view() -> void`. | Sole authority for current scene state, dirty state, save snapshot, recent color history, and draft rollback. Switching to Plain changes the kind immediately and opens choices; switching Sky retains `_plain_color`. |
|
||||
| `scripts/stage/stage_scene_io.gd`, `class_name StageSceneIO extends RefCounted` | `FILE_VERSION := "1.7"`; typed validation/migration of `background_kind`, `sky_id`, and `plain_color`. | Reject malformed new backdrop fields before applying a document; migrate older versions without changing their visible Sky. |
|
||||
| `scripts/editors/stage/stage_scene_adapter.gd`, `class_name StageSceneAdapter extends RefCounted` | Pass all three fields through `collect(...) -> Dictionary` and `apply(...) -> Dictionary`. | Keep background data at the top level; no object entry is created. |
|
||||
| `scripts/editors/stage/stage_asset_browser.gd` and `scripts/shared/ui/asset_selector.gd`, `class_name AssetSelector extends PopupPanel` | Supply four starter cards and five scene-wide background cards; pass `{background_kind, sky_id, plain_color}` for active state and previews. Add typed `signal plain_color_preview_requested(color: Color)`, `signal plain_color_commit_requested(color: Color)`, and `signal plain_color_preview_cancel_requested` through the browser facade. | The chooser owns view navigation, focus, current/selected card display, and picker controls; it emits intents. It never marks the scene dirty or writes scene data. Keep existing `surface_color_confirmed` for wall/Ground setup history; do not route Plain through it and double-record a color. |
|
||||
| `scripts/shared/stage_ui/stage_surface_color_controls.gd`, `class_name StageSurfaceColorControls extends VBoxContainer`; `scripts/shared/ui/color_swatch_selector.gd`, `class_name ColorSwatchSelector extends FlowContainer` | Retain `color_selected(color: Color)` and `custom_color_requested`; activating the current-color chip is the sole entry to the full picker. Ensure compact swatches are at least 44 × 44 and stack sections when a horizontal row will clip. | Show current, recent, and preset colors with separate selected and focus treatment. The Stage's existing eight-color recent list is shared. |
|
||||
| `scripts/shared/stage_ui/stage_surface_color_picker_view.gd`, `class_name StageSurfaceColorPickerView extends VBoxContainer` | Extend `configure(...)`, or add a typed background-specific configuration method, so `preview_color_changed(color: Color)` uses an opaque flat sample for Plain. | Native `ColorPicker` supplies controls. The view displays a draft but does not commit it. Surface motif previews keep their current path. |
|
||||
| `scripts/stage/scenery/stage_starter_card_preview.gd` and `scripts/stage/scenery/stage_background_card_preview.gd` | Use `StageBackgroundView` for starter and background card imagery. | Show a true solid fill for Plain and preserve existing Sky rendering in still previews. |
|
||||
| `scripts/stage/stage_grid.gd`, `class_name StageGrid extends Node2D`; `scripts/stage/stage_gizmos.gd`, `class_name StageGizmos extends Node2D`; `scripts/stage/sandbox_theme.gd`, `class_name SandboxTheme extends RefCounted`; `sandbox_theme.json` | Add theme-backed light/dark grid colors and two-tone editor outline colors. Add typed setters on drawing nodes if needed to pass the current backdrop treatment. | Adapt editor overlays to the background while leaving authored art, speech, and physics unchanged. |
|
||||
|
||||
The signal names above are the desired public interface between chooser, browser, and Stage. Keep the existing `item_selected(entry: Dictionary)` path for Sky and Plain card taps. A Plain card tap commits the active kind before the chooser opens its color-choices view. A Sky card tap commits the new Sky immediately and keeps the chooser open. The current-card indicator uses a stable **Current background** badge and selected border; keyboard focus is separate. The Plain color choices and its custom picker keep the Stage at full brightness while the modal input blocker remains active and transparent. Other chooser views retain the usual visual dimming.
|
||||
|
||||
## Saved scene format and migration
|
||||
|
||||
Save top-level fields in `.scene` v1.7:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.7",
|
||||
"background_kind": "plain",
|
||||
"sky_id": "sky_neutral",
|
||||
"plain_color": "#F5EFE0",
|
||||
"camera": {"position": {"x": 0.0, "y": -400.0}, "zoom": 0.5},
|
||||
"objects": [],
|
||||
"event_rules": []
|
||||
}
|
||||
```
|
||||
|
||||
`background_kind` is exactly `"sky"` or `"plain"`. `sky_id` remains one of the existing five IDs even while Plain is active, preserving the last selected Sky for a later switch. `plain_color` is an opaque canonical six-digit `#RRGGBB` string. Runtime color values are clamped to opacity before commit; invalid file values are rejected at the JSON boundary. The plain starter is a separate `.scene` file under `content/stages/starters/` with these values and empty `objects`/`event_rules`; the existing `blank.scene` can remain the Open Sky starter, with its UI label changed. Town Street and Living Room remain authored compositions and acquire migrated Sky-kind fields on their next save if their source version is older.
|
||||
|
||||
`StageSceneIO._migrate_to_current()` must explicitly handle **1.6** as well as 1.0–1.5. Every pre-1.7 file migrates to `background_kind: "sky"` and `plain_color: "#F5EFE0"`; it preserves its migrated `sky_id` (including `sky_neutral`). In particular, adding 1.6 to the old `version != "1.5"` branch would incorrectly overwrite its Sky choice: keep that earlier version-specific rule intact. Current-version normalization still runs for migrated data. Read and validate the complete document before replacing the live scene. Save and autosave both serialize confirmed fields only; a picker draft is never consulted. `ContentPaths.canonicalize()` continues to handle starter paths.
|
||||
|
||||
## Color transaction and navigation
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Backgrounds
|
||||
Backgrounds --> ColorChoices: tap Plain / commit kind
|
||||
Backgrounds --> Backgrounds: tap Sky / commit sky
|
||||
ColorChoices --> ColorChoices: tap swatch / commit color
|
||||
ColorChoices --> CustomPicker: activate current-color chip / snapshot confirmed color
|
||||
CustomPicker --> ColorChoices: Use color / commit once
|
||||
CustomPicker --> ColorChoices: Back or Esc / discard draft
|
||||
ColorChoices --> Backgrounds: Back / keep commits
|
||||
CustomPicker --> [*]: popup hide, mode switch, scene replacement / discard draft
|
||||
```
|
||||
|
||||
`_plain_color` is the confirmed remembered value; `_plain_color_draft` exists only while the custom picker is open. Every native picker movement calls `_preview_plain_color()` to update the live `StageBackgroundView` and its flat chooser sample, without assigning `_plain_color`, changing recent history, or marking dirty. **Use color** clamps to opaque, commits the chosen color once, clears draft state, calls the existing `_record_recent_surface_color()` once, and returns to color choices. A preset/recent swatch uses the same commit method directly. An intentional selection can reorder recent history; mark the scene dirty only if the confirmed scene value actually changes. Opening choices at the untouched default does not add the default to recents.
|
||||
|
||||
Back, Cancel, Esc, popup hide, mode switch, and scene replacement must all clear the draft and restore the confirmed render. A replacement cancels the draft **before** resetting or loading scene state; popup-hide cleanup must be idempotent because a normal close can trigger it after a button callback. Back from color choices returns to Backgrounds without reverting confirmed card/swatches; Close retains confirmed choices. If Save/autosave occurs during a draft, the snapshot reads `_plain_color`, never the displayed draft. Focus returns to the Plain card from color choices and to the custom-picker opener from the picker; the popup keeps its screen anchor while switching views.
|
||||
|
||||
## Chooser layout and contrast
|
||||
|
||||
Use the existing `AssetSelector` responsive grid and `AssetCard` controls. File → New presents Plain Background, Open Sky, Town Street, Living Room in that order, two columns on a normal desktop and one scrollable column when narrow. Keep fixed heading and reachable Close. Backgrounds presents the five scene-wide cards under **Choose the scene background**; Wall panel and Background ground stay in a separate **More backgrounds** row. The color-choices view has a fixed **Choose background color** heading, flat confirmed preview, a focusable current-color chip with readable hex, up to eight shared recents, and presets. Place **‹ Backgrounds** at the left of the fixed footer and **Close** at the right; stack them as full-width actions on narrow layouts. Activating the current-color chip opens the custom picker; do not add a separate **More colors** button. The custom view has a flat draft preview and fixed Back/Use footer. Reuse `popups.asset_selector`, `popups.dialog`, `stage_surface_colors`, `stage_panels.action`, and `mode_colors.edit` tokens; add only narrowly needed flat-preview/backdrop-overlay tokens. Increase `popups.asset_selector.compact_swatch_size` from 42 to at least 44 in both theme sources, and clamp the actual `ColorSwatchSelector` target size to at least 44 even if a custom theme supplies a smaller number. Card, swatch, and action targets also meet 44 × 44. Scroll the content within viewport-safe bounds; do not horizontally clip compact color sections.
|
||||
|
||||
`StageGrid` currently uses translucent white lines. For Plain, choose theme-backed dark minor/major lines on a light fill and light minor/major lines on a dark fill using the displayed color's luminance, including a temporary draft. Minor lines stay subdued; major lines remain legible. On Sky, retain the established grid treatment. `StageGizmos` currently draws white selection and yellow hover outlines, which can disappear against light fills; add a dark backing stroke beneath a bright core for selection, hover, box selection, rotate ring, and scale handles. Keep screen-space widths and hit testing unchanged. This overlay treatment may be applied consistently for Sky and Plain. No authored object, speech bubble, placement material, or pixel color is rewritten. EDIT still owns grid/gizmos, DIRECT keeps its framing cues, and PLAY hides edit-only overlays. Review cursor pills and placement ghosts on light, dark, and saturated fills during rendered verification.
|
||||
|
||||
## Observable acceptance and verification route
|
||||
|
||||
| User path / repeatable scenario | Observable outcome |
|
||||
| --- | --- |
|
||||
| Fresh Sandbox Stage startup without a scene; close the chooser; compare with a CLI scene load and autosave restore/discard | The chooser opens once over an empty EDIT Stage. Close leaves the blank Stage open without reopening the chooser. A CLI-loaded or restored scene suppresses it; discarding autosave recovery opens it only after the recovery dialog closes. |
|
||||
| Dirty scene → File → New → cancel unsaved gate or cancel starter chooser; then choose Plain and Open Sky in separate runs | Gates preserve the prior scene on cancel. Plain opens an unsaved empty scene with a uniform `#F5EFE0` fill and zero placed objects; Open Sky keeps the former neutral gradient, sun, and clouds. Both card previews match. |
|
||||
| EDIT → Scenery → Backgrounds → Plain → swatch → Sky → Plain | Plain taps switch immediately, swatches update Stage and recent ordering, Sky remains selectable, and returning to Plain restores its confirmed color. Selected badge and focus are distinct. Wall/Ground remain separate. |
|
||||
| Plain custom picker → drag RGB/HSV controls → Back; repeat with Esc, Close, mode change, popup dismissal, and scene replacement | Draft appears in Stage/sample while editing; each cancel path restores the prior confirmed fill. Dirty state, recent list, saved file, and autosave content do not change from the draft. Replacement does not carry draft into the next scene. |
|
||||
| Plain color choices → activate current-color chip → change custom picker controls → Use color → Save → reopen; compare color and recent list before/after | The current-color chip opens the picker without a separate button. One confirmation stores an opaque color, records it once in shared history, and marks the scene dirty once. Reopen restores active kind and remembered color. A Sky-active save/reopen also retains the hidden remembered plain color. |
|
||||
| Load representative v1.0–v1.6 files, especially a v1.6 `sky_neutral` scene and a v1.6 non-neutral Sky; save/reopen | They remain visually Sky scenes with the same Sky ID and composition; migration adds default remembered Plain color and writes v1.7 without changing objects, camera, or Sky choice. Invalid v1.7 background data fails before live-scene replacement. |
|
||||
| Plain Stage with no world objects → pan, zoom, viewport resize, EDIT → DIRECT → PLAY → stop; repeat after save/reopen | Every frame stays an opaque edge-free flat fill. No gradient or motifs appear; backdrop never intercepts clicks. Mode transitions retain color; PLAY has no edit-only grid/gizmos. |
|
||||
| Light `#F5EFE0`, dark, and saturated Plain colors with Ground, artwork, Props, character, speech, selection, and placement ghost | Grid major/minor lines, selection/hover/gizmos, cursor pills, and ghosts remain usable. Foreground pixel colors and object behavior remain unchanged. |
|
||||
| Narrow viewport → pointer/touch/keyboard through starters, cards, swatches, picker, Back/Use/Close | Content scrolls without horizontal clipping; actions stay reachable; all targets meet 44 × 44; returning from subviews restores opener focus and popup anchor. |
|
||||
|
||||
Use the real Stage chooser, stage scene load/save path, and render-capable Stage for the scenarios above. Inspect captured frames at the named colors, camera positions, zoom levels, modes, and viewport sizes; a headless parse or a screenshot command alone does not establish visual correctness. Focused automated checks should cover the v1.7 migration/validation boundary and the commit/cancel state transitions where they meaningfully protect behavior. No new graphical or animation asset is required: thumbnails and previews are rendered from existing Sky drawing and the new solid fill.
|
||||
|
||||
## Trade-offs and implementation constraint
|
||||
|
||||
Composing a backdrop view adds one small node and typed facade but keeps Sky drawing focused and lets live Stage and previews share the same kind switch. Three scalar file fields are easier to validate and migrate than a custom `Resource`; the saved `sky_id` is deliberate remembered state while Plain is active. Color history remains a user setting shared with surface colors, while the confirmed plain color belongs to each scene. Theme-backed grid color can account for the flat background, but it cannot account for every placed object beneath a particular grid segment; the two-tone gizmo outline protects selection visibility across mixed art.
|
||||
|
||||
The existing chooser was designed around four Sky cards and a separate surface row. Its grid-row counting, active-card group, footer placement, and compact swatch width need targeted extension for five scene-wide choices and the new color views. Preserve its popup anchor and focus behavior while changing those branches; do not fork a second gallery or color picker.
|
||||
@@ -0,0 +1,99 @@
|
||||
# Phase 19 — Plain Background: UI/UX specification
|
||||
|
||||
> **Status:** UI/UX direction revised per user feedback from the user-approved PNG mockups. The current-color chip is the sole entry to the custom picker; there is no separate **More colors** button. The default color is approved as warm off-white `#F5EFE0`; the color swatches and sample views must show a flat fill.
|
||||
>
|
||||
> **Design references:** [Phase 19 Plain Background brief](../plans/phase_19_plain_background.md), [approved PNG mockups](../plans/assets/phase_19_plain_background/), [Phase 19 Scenery UI/UX specification](phase_19_scenery_backgrounds_ui_ux.md), and [Child-Facing Dialog Design Principles](dialog_design_principles.md).
|
||||
|
||||
## Child promise
|
||||
|
||||
A child can start with an empty stage filled by one color, choose another color in EDIT, and return to that color after trying a Sky. The color fills the whole camera view. It does not create a selectable object or change the colors and behavior of placed pieces.
|
||||
|
||||
## File → New
|
||||
|
||||
- Keep the existing unsaved-work Save/Discard/Cancel gate. Do not replace the current scene until a starter card is chosen.
|
||||
- Use the existing themed `AssetSelector` shell and `AssetCard` presentation with a fixed **Choose a starter scene** heading, a scrollable responsive card body, and a reachable visible **Close** action. The card order and tab order are **Plain Background**, **Open Sky**, **Town Street**, **Living Room**.
|
||||
- At desktop widths, show an equal-sized 2 × 2 card grid. At narrow widths, wrap to one column and scroll the body while keeping the title and Close action available. Preserve the popup's screen anchor when its layout changes.
|
||||
- Make this chooser materially larger than the current roughly 660 × 560 logical-pixel asset selector: target about 1160 logical pixels wide on a roomy desktop, with a natural height that shows both card rows and the Close action. Cap both dimensions to the usable viewport with safe margins; a short display scrolls the card body while the title and Close stay reachable. At the preferred width, each card's preview should be about 500 pixels wide and at least 240 pixels tall, occupying roughly two-thirds of the card height. Scale the preview with its card instead of leaving a small fixed thumbnail inside a large tile. The [larger starter chooser mockup](../plans/assets/phase_19_plain_background/05_large_starter_chooser.png) shows the intended balance; its pixel dimensions are illustrative, not a fixed window size.
|
||||
- Plain Background's thumbnail is a uniform opaque `#F5EFE0` fill with no horizon, gradient, Sky motif, checkerboard, or object. Its copy is: **“An empty stage with one color. Choose a new color whenever you like.”** Starting it creates a new unsaved scene with no Ground or placed objects and no additional setup step.
|
||||
- Open Sky previews the existing neutral gradient, sun, and clouds. Its copy is: **“An empty stage with a soft sky. Sun and clouds, ready for your story.”** This is the existing empty neutral-Sky starter under a clearer name.
|
||||
- Town Street and Living Room retain their authored compositions and existing descriptions.
|
||||
- Activating a card by pointer, touch, Enter, or Space opens that starter. Close or Escape leaves the current scene intact.
|
||||
|
||||
## Fresh Sandbox startup
|
||||
|
||||
- When the Sandbox Stage launches as the active scene without a requested scene, show **Choose a starter scene** once for that Stage session. This gives children the same clear starting point as File → New.
|
||||
- If an autosave is available, resolve its recovery prompt first. Restoring it opens the recovered scene without the starter chooser; discarding it opens the chooser afterward.
|
||||
- A command-line scene load or load error does not open the starter chooser. The chooser must not cover recovery or another modal dialog.
|
||||
- Close or Escape leaves the empty EDIT Stage available. Do not automatically reopen the chooser during that session; File → New remains available when the child wants another starter.
|
||||
|
||||
## EDIT → Scenery → Backgrounds
|
||||
|
||||
- Extend the current `AssetSelector` Backgrounds tab with a **Plain Background** card alongside **Clear Day**, **Cloudy Day**, **Sunset**, and **Starry Night**. Keep **Wall panel** and **Background ground** visually separated under a **More backgrounds** row.
|
||||
- Show the heading **Choose the scene background** above the five scene-wide choices. The Plain Background card preview uses the remembered plain color even while a Sky is active.
|
||||
- Mark the active choice with the existing cyan selected fill/border and a stable **Current background** badge. Keep the keyboard focus outline visually distinct from selection. Do not identify the current choice by color alone.
|
||||
- Sky cards retain their immediate selection behavior and leave the chooser open. Activating Plain Background immediately restores/applies its remembered color and opens the Plain Background color choices. Back or Close from those choices keeps Plain Background active.
|
||||
- Neither a Sky nor Plain Background is Stage-selectable or included in Pieces here. Switching background never starts placement or changes the current cursor mode.
|
||||
|
||||
## Plain Background color choices
|
||||
|
||||
- Reuse the bounded chooser shell, `StageSurfaceColorControls` and shared `ColorSwatchSelector` visual language; the full-stage preview and scene-specific copy are the only feature-specific presentation.
|
||||
- Keep the **Choose background color** heading. Put **‹ Backgrounds** in the fixed footer, left of **Close**, instead of in the title row. Both are large, outlined secondary actions with 12–16 px separation; at narrow widths, stack them vertically as full-width targets. The scrollable body contains:
|
||||
1. Helper text: **“Tap a color to use it on the Stage.”**
|
||||
2. A large, flat, opaque preview of the confirmed color with no text over the color sample.
|
||||
3. The current color swatch and readable hex value.
|
||||
4. **Recently used** colors, using the shared recent color list (up to eight).
|
||||
5. **Colors** preset swatches.
|
||||
- If recents are empty, show **“Colors you use will appear here.”** Opening Plain Background at the untouched default does not add that default to recents.
|
||||
- Tapping a recent or preset swatch immediately confirms it. The full Stage, preview, current swatch, selected outline/check, dirty state, and recent ordering update together. Leaving and reopening the view preserves that confirmed choice.
|
||||
- Give the selected swatch an outline/check that is distinct from keyboard focus. Make all swatches at least 44 × 44 logical pixels, including compact layouts; the current 42-pixel compact swatch default is too small here.
|
||||
- The current-color chip is the sole entry point to the full custom picker. It is a focusable button with clear hover, pressed, and focus states and the tooltip **“Choose a custom color.”** Activating the chip opens the picker; there is no separate **More colors** button.
|
||||
- Keep the Stage at full brightness while Plain Background color choices or its custom picker are open so live color changes can be judged accurately. Keep the modal input-blocking layer active but visually transparent; clicks outside the dialog must not reach the Stage. The dialog keeps its opaque shell, outline, and footer for modal clarity. Other chooser views retain the normal dim backdrop.
|
||||
|
||||
## Full custom picker
|
||||
|
||||
- Reuse/extend `StageSurfaceColorPickerView`, its native `ColorPicker`, large preview, theme, and compact-height behavior. Use a flat, opaque preview matching the Stage with no text overlay.
|
||||
- Use the heading **Choose background color** and a simple **Preview** label above the large color sample. The tentative behavior is communicated by the Stage updating during picker movement and the visible **Use color** / **Back** actions; no explanatory preview message is needed.
|
||||
- On open, snapshot the last confirmed plain color. Moving native color controls updates only the temporary Stage preview and large sample. It does not change history, scene dirty state, or serialized data.
|
||||
- Use a fixed, visible footer with a dark secondary **Back** (or **Cancel**) button and a blue, bold, white **Use color** primary button, separated by 12–16 logical pixels. All actions remain at least 44 × 44 logical pixels.
|
||||
- **Use color** confirms once, updates the remembered color and recent history once, marks the scene dirty once, and returns to the color choices.
|
||||
- Back, Cancel, Escape, or closing the picker restores the confirmed snapshot and returns to color choices with Plain Background still active.
|
||||
- Mode changes, scene replacement, or unexpected popup dismissal also clear a temporary preview and restore the confirmed color. A temporary color must never enter Save or autosave.
|
||||
|
||||
## Focus, layout, and theme
|
||||
|
||||
- Use `SandboxTheme` values from `popups.asset_selector`, `popups.dialog`, `stage_surface_colors`, `stage_panels.action`, and `mode_colors.edit`. Add a small Plain-preview token group only if the existing theme has no suitable values; avoid a parallel swatch or picker system.
|
||||
- Keep cards, swatches, and actions at least 44 × 44 logical pixels. Preserve the existing dialog style: rounded surfaces, visible outlines, readable type, blue primary action, and labeled Close/Back/Use actions.
|
||||
- Tab order: starter cards → Close; Scenery tabs → scene-background cards → surface cards → Close; color choices: Back → current-color chip → recent swatches → preset swatches → footer; custom picker → Back → Use color.
|
||||
- Opening a subview moves focus to its heading or first useful action. Returning from the color choices restores focus to Plain Background; returning from the custom picker restores focus to the current-color chip.
|
||||
- Keep the title and footer actions reachable while the body scrolls. Cap the popup to the safe viewport; do not force clipping or horizontal scrolling to retain compact horizontal swatch columns. Stack the Back/Close footer actions and current/recent/preset sections at narrow widths. Preserve the popup anchor when switching gallery, color, and custom-picker views.
|
||||
- Pointer, touch, and keyboard users get the same selected, hover, focus, and confirmation feedback. Clicking outside must not silently confirm a tentative custom color.
|
||||
|
||||
## Canvas contrast and feedback
|
||||
|
||||
- Review white, black, and saturated Plain Background colors. On light fills such as `#F5EFE0`, the current white EDIT grid and white selection outlines have about 1.15:1 contrast and nearly disappear. Provide a theme-backed contrasting grid treatment for light and dark fills, keeping minor lines subdued and major lines legible.
|
||||
- Give Stage selection, hover, and gizmo outlines a dark backing plus bright core on Plain Backgrounds of any brightness, following the existing two-tone selection-halo practice. Do not recolor authored artwork.
|
||||
- Keep EDIT chrome and mode pill dark-backed with cyan accents, DIRECT framing amber, and PLAY free of edit-only grid and gizmos. Preserve speech styles and their authored colors. Check cursor pills and placement ghosts at light, dark, and saturated backgrounds.
|
||||
- A Plain Background color is a scene-wide visual setting only: it never intercepts Stage selection or changes object ordering, placement, action behavior, or camera movement.
|
||||
|
||||
## Acceptance scenarios
|
||||
|
||||
1. Open Sandbox Stage without a scene and verify the starter chooser appears. Close it and verify the empty EDIT Stage remains available without another automatic prompt in that session. Open a scene through the CLI and verify the chooser does not appear.
|
||||
2. If an autosave is available at startup, restore it and verify the chooser stays closed; discard it and verify the chooser appears afterward without overlapping the recovery prompt.
|
||||
3. In a dirty scene, use File → New and verify the existing unsaved gate appears first. Cancel the starter chooser and confirm the previous scene remains. Choose Plain Background and verify the new unsaved Stage is a single flat `#F5EFE0` with no Sky, Ground, or placed objects. Verify Open Sky reproduces the existing neutral Sky appearance.
|
||||
4. In EDIT, open Scenery → Backgrounds. Verify all five scene-wide choices are visible, the current choice is identified with text and a border, and Wall panel/Background ground remain separate. Choose Plain Background and verify it opens with the remembered color.
|
||||
5. Tap one preset and one recent swatch. For each, verify the Stage and preview update immediately, the color becomes selected, and recent ordering updates. Close and reopen the choices and verify the confirmed value remains.
|
||||
6. Activate the current-color chip to open the custom picker. Move a color control, then choose Back. Verify the Stage and preview return to the last confirmed color and the scene/recent history remain unchanged. Repeat and choose Use color; verify the choice and history update once and remain after Save/reopen.
|
||||
7. Repeat custom-picker cancellation through Escape, visible Cancel/Back, close, mode change, and scene replacement. No temporary preview may leak into the next Stage or saved scene.
|
||||
8. With each of Sky and Plain active, pan, zoom, resize the viewport, enter/stop PLAY, and reopen a saved scene. Verify the solid fill covers the camera view with no edge and that the remembered plain color returns after switching back from Sky.
|
||||
9. On light, dark, and saturated fills, inspect grid, selection, hover, gizmos, cursor pills, placement ghosts, speech, and mode chrome. Confirm the Stage remains readable and placed artwork colors remain unchanged.
|
||||
10. At narrow viewport sizes, navigate each card, swatch, and action by pointer, touch, and keyboard. Verify the content scrolls without clipping; focus and selection remain distinct; Back/Use/Close remain visible; returning from subviews restores the opener focus and popup anchor.
|
||||
|
||||
## Reuse boundary
|
||||
|
||||
| Surface | Reuse direction |
|
||||
| --- | --- |
|
||||
| Starter and Scenery cards | Extend `AssetSelector` and `AssetCard`; use `StageBackgroundCardPreview` for a real solid-color thumbnail and add the Plain-specific label/selection state. Do not create another card gallery. |
|
||||
| Color choices and recents | Reuse `StageSurfaceColorControls` and `ColorSwatchSelector`/shared history. Extend layout for 44-pixel minimum targets and narrow layouts instead of introducing a parallel swatch system. |
|
||||
| Custom picker | Reuse `StageSurfaceColorPickerView` and the native `ColorPicker`; give the scene-wide background its own flat preview and explicit temporary/confirm/cancel lifecycle. |
|
||||
| Stage contrast | Use `SandboxTheme` tokens and the existing two-tone selection halo pattern; do not mutate user-authored object colors or make a second editor theme. |
|
||||
|
||||
@@ -96,6 +96,7 @@ These are relationship examples, not fixed pixel geometry. On a narrow viewport
|
||||
### Stage palette and Scenery chooser
|
||||
|
||||
- Add one illustrated **Scenery** card to the existing vertically scrollable left palette. Keep **Props** and **Ground** as separate cards, with a short helper line in their chooser/tool: “Stays put”, “Can be part of the action”, or “Stickmen walk here.” The palette card opens the Scenery chooser rather than directly arming a tool.
|
||||
- Keep the Scenery card pressed while its chooser and nested views are open. Back navigation keeps it pressed; closing or canceling the full chooser clears it. If a choice starts drawing, show that active state with the existing on-Stage capture bar instead of leaving the chooser card pressed.
|
||||
- The chooser has a fixed title/Close row; **Backgrounds** and **Artwork** tabs; a scrollable body; and a fixed lower **Make artwork…** action when relevant. It is a chooser workflow, not a selected-object inspector. It receives `SandboxTheme.control_theme()` and its own popup tokens, while borrowing the Stage panel system's font, surface, selected, hover, focus, and target-size rules.
|
||||
- **Backgrounds** shows two large category choices, **Sky** and **Wall panel**. **Artwork** shows a single-select filter row with **All artwork**, **Nature**, **Buildings**, **Walls**, **Roads & paths**, **Objects**, and conditional **Unsorted**. One drawing may carry several tags, so it appears under every matching filter. All artwork includes old, untagged drawings. Filters describe appearance, not behavior. Apply the same filters in the Props browser while keeping its title and placement role distinct.
|
||||
- Use a `FlowContainer` for wrapping filter buttons and an adaptive card grid for previews. Each card has a large illustration, a readable name, and a visible keyboard focus ring. No card depends on hover to reveal its action. Changing tabs or tags preserves the chooser and moves focus to the first relevant control; closing returns focus to the Scenery palette card.
|
||||
@@ -285,3 +286,4 @@ Do not expose “entity”, “collision hull”, “z-index”, “physics laye
|
||||
7. In Living Room, use Select several to choose two wall panels, the window frame, and rug. Preview a shared move, cancel with right-click, and verify all four return exactly to their original locations while Wood Ground and furniture remain still. Preview a uniform corner resize, check the opposite anchor stays fixed and wall motifs do not stretch, then Keep changes; save and reopen. The four pieces retain their new positions/sizes and original depth/finish, while the temporary group selection is gone. Repeat the preview with touch or keyboard controls in a narrow viewport, using Esc to cancel.
|
||||
8. Save a scene with two copies of one live `.prop` Scenery drawing, then make the file unavailable and reopen the scene. The friendly missing-art summary appears once; both labeled markers remain at their saved positions/depths through EDIT and PLAY. In ordinary EDIT, select a character in front of a marker without selecting Scenery. Use a marker's Find artwork badge or the Edit Scenery **Needs artwork** list to open its card. Cancel a file choice and verify both markers remain. Choose a replacement for one copy, preview then cancel once, then confirm it; only that copy changes. Confirm the second still has a marker after save/reopen until it too is repaired or deliberately erased. Repeat the repair path with keyboard and on a narrow touch viewport.
|
||||
9. In Prop Editor, open **Size for Stage** on representative tall, wide, and small artwork. Confirm the standard stickman is drawn in front, the floor/contact guide is visible over every fill, the preview frames both together, presets and fine adjustments preserve proportions, **Keep size** applies, and **✕ Cancel** restores the exact prior geometry. Confirm new placement uses the authored size and loading an existing file performs no automatic normalization. Deliberately save revised geometry over a referenced asset and confirm the usual Save flow and live-reference update on reopen, with scene placement transforms retained. In Edit Scenery, resize one placement and confirm it commits on release and saves/reopens; cancel a still-active drag with Escape/right-click and with the touch capture bar; verify other scenery and Props stay unchanged. Compare this with the separate group Keep/Cancel flow. Repeat sizing-guide visibility and Stage handle/button access with keyboard/touch and at a narrow viewport.
|
||||
10. Open Scenery and navigate between Backgrounds, Plain Background color choices, and its custom picker. Back keeps the Scenery card pressed; Close or Escape from the full chooser clears it. Choose an artwork or surface tool and confirm the chooser card is unpressed while the on-Stage capture bar shows the active tool.
|
||||
|
||||
Reference in New Issue
Block a user