135 lines
6.4 KiB
Markdown
135 lines
6.4 KiB
Markdown
# High-Level Architectural Plan: Graphical UI & Palette Polish Phase
|
|
|
|
## Objective
|
|
|
|
To overhaul the `SandboxStage` user interface into a polished, kid-friendly graphical experience, while establishing a flexible, schema-driven theme system that seamlessly supports present UI elements and future feature additions (such as dynamic speech bubble styling, sound customization, and extended rule editors).
|
|
|
|
---
|
|
|
|
## 1. Centralized Theme & Resource Infrastructure
|
|
|
|
### 1.1 JSON Theme Schema Expansion (`sandbox_theme.json`)
|
|
|
|
- **Unified Theme Specification**: Expand the `sandbox_theme.json` contract to serve as the single source of truth for typography, spatial grids, mode accent colors, and component-specific visual presets.
|
|
|
|
- **Subsystem Category Blocks**: Structure the schema into modular sub-dictionaries (e.g., `fonts`, `mode_colors`, `grid`, `popups`, `speech_bubbles`).
|
|
|
|
- **Graceful Fallback Pipeline**:
|
|
|
|
1. Specific component override value.
|
|
|
|
2. Subsystem block default (e.g., `speech_bubbles.style_defaults`).
|
|
|
|
3. Global theme default (`fonts.ui_font`).
|
|
|
|
4. System fallback (`ThemeDB.fallback_font`).
|
|
|
|
- **Resource Preloading & Validation**: Ensure the theme loader validates paths, gracefully handles missing assets with non-blocking warnings, and caches loaded `Font` and `StyleBox` objects.
|
|
|
|
---
|
|
|
|
## 2. Graphical Stage Chrome & Mode Navigation
|
|
|
|
### 2.1 Mode Switcher & Viewport Frame
|
|
|
|
- **3-Segment Graphical Switcher**: Replace standard text toggles with a stylized 3-segment mode control (`[✏️ Edit | 🎬 Direct | ▶️ Play]`).
|
|
|
|
- **Viewport Frame Accent**: Render a screen-constant border frame (`_mode_frame`) around the viewport that dynamically tints according to the active mode accent color.
|
|
|
|
- **Mode Badge Pill**: Maintain a rounded, high-contrast status badge in the viewport corner displaying the active state with mode-specific icons and accent backgrounds.
|
|
|
|
### 2.2 Status Bar & Dynamic Cursor System
|
|
|
|
- **Status & Coordinate Bar**: Polish the bottom bar for scannability, hosting contextual operational hints and live spatial coordinates.
|
|
|
|
- **Contextual Cursors & Floating Tooltips**:
|
|
- Swap between arrow/crosshair, placement cursors, and custom action reticles depending on mode and pending operations.
|
|
|
|
- Attach floating, high-contrast tooltip pills offset from the cursor during target selection workflows (e.g., direct mode commands or trigger mapping).
|
|
|
|
---
|
|
|
|
## 3. Icon-Based Palette & Thumbnail Engine
|
|
|
|
### 3.1 Draggable / Clickable Card Palette
|
|
|
|
- **Visual Asset Cards**: Transition spawner controls from text buttons to visual card tiles displaying item icons, labels, and category badges.
|
|
|
|
- **Placement Integration**: Support both click-to-select active placement and direct drag-and-drop actions onto the stage.
|
|
|
|
### 3.2 Modal Asset Selector & Thumbnail Pipeline
|
|
|
|
- **Asset Selector Modal**: Refine the modal popup and its dimming background backdrop for browsing extended stickmen and prop libraries.
|
|
|
|
- **Asynchronous Thumbnail Cache**:
|
|
- Streamline off-screen thumbnail generation for custom props and stickmen.
|
|
|
|
- Cache generated preview textures to prevent UI stuttering during library scans.
|
|
|
|
---
|
|
|
|
## 4. Visual Overlay & Placement Feedback Engine
|
|
|
|
### 4.1 Terrain Drag-Painting & Ghosting Feedback
|
|
|
|
- **Block-Unit Stride Alignment**: Align placement ghosts and Bresenham line painting to the active terrain template's AABB extent.
|
|
|
|
- **3-State Ghost Tinting**:
|
|
- **Green**: Valid, empty space ready for placement.
|
|
|
|
- **Faint / Neutral**: Same-type block (skipped to avoid double-stamping).
|
|
|
|
- **Red**: Conflicting entity or invalid geometry.
|
|
|
|
### 4.2 Guidance & Target Trajectories
|
|
|
|
- **Axis-Aligned Guides**: Render high-contrast dashed lines along cardinal axes during Shift-locked terrain drags.
|
|
|
|
- **Rubber-Band Trajectories**: Draw contextual connection lines and target reticles from character origins to mouse targets during Direct mode actions.
|
|
|
|
---
|
|
|
|
## 5. Reusable Control Widgets & Forward-Compatible Systems
|
|
|
|
### 5.1 Standardized Kid-Friendly UI Components
|
|
|
|
Develop a suite of reusable, theme-aware control widgets that can be embedded across dialogs, action popups, and future parameter editors:
|
|
|
|
- **Color Swatch Selector**: Clickable circle palettes populated from theme swatch arrays or editor history.
|
|
|
|
- **Preset Size Toggles**: Segmented buttons for coarse adjustments (e.g., **Small**, **Medium**, **HUGE**) mapping to backend integer/scale metrics.
|
|
|
|
- **Preset Style / Font Pickers**: Visual icon or text buttons allowing selection between preset fonts (e.g., Standard, Comic, Pixel, Scary).
|
|
|
|
- **Emoji Quick Grid**: A dedicated grid widget for inserting expressive graphics directly into text fields.
|
|
|
|
### 5.2 Context Menus & Action Popups
|
|
|
|
- **Uniform Popup Styling**: Apply standardized theme rules, font sizes, and emoji scaling across action context menus, trigger submenus, and dialogs.
|
|
|
|
- **Clean Action Dialogs**: Align text input (Speak), duration (Wait), and rename popups with dark-mode sandbox styling.
|
|
|
|
### 5.3 Extension Blueprint: Speech Bubble Customization System
|
|
|
|
Architect the theme and component pipeline so that future speech bubble upgrades plug directly into the visual foundation without refactoring:
|
|
|
|
- **Data Contract**: Ensure the `speak` action payload accepts visual parameters (`font_preset`, `size_preset`, `color`, `bubble_style`) alongside text.
|
|
|
|
- **Style Engine Integration**: Speech bubble nodes consume geometry styles (Standard, Yell, Thought, Whisper) and theme font presets directly from `sandbox_theme.json`.
|
|
|
|
- **UI Reusability**: The standard Color Swatch, Size Toggle, Font Picker, and Emoji Grid widgets drop directly into the Direct mode `Speak` parameter dialog.
|
|
|
|
---
|
|
|
|
## Recommended Execution Sequence
|
|
|
|
1. **Phase 1: Theme Engine & Core Schema**: Extend `sandbox_theme.json` schema, build centralized theme loading/fallback pipeline, and integrate theme application hooks across stage UI.
|
|
|
|
2. **Phase 2: Chrome & Mode Navigation Polish**: Implement the 3-segment mode control, viewport frame accents, status badges, and cursor/tooltip overlay controllers.
|
|
|
|
3. **Phase 3: Reusable UI Component Library**: Build the Color Swatch, Size Toggle, Font Picker, and Emoji Grid widgets.
|
|
|
|
4. **Phase 4: Graphical Palette & Modal Overhaul**: Implement icon-based asset cards, refine the `AssetSelector` modal, and optimize asynchronous thumbnail caching.
|
|
|
|
5. **Phase 5: Context Menus & Overlay Polish**: Update action popups with uniform theme sizing and polish drag-painting ghost/guide overlays.
|