first commit

2026-08-08 00:00:50 -04:00
commit b97bc145e4
34 changed files with 6874 additions and 0 deletions
@@ -0,0 +1,577 @@
+# Phase 3 — Architectural Specification
+
+## Overview
+
+Phase 3 adds a **grid system** (configurable, with snap-to-grid for vertices and whole-stickman assembly), **panning** (middle-mouse-button drag), **global settings persistence** (`settings.json`), **color changing** (ColorPicker integration), **shape delete**, and **vertex delete** to the Stickman Studio editor. Phases 1-2 (shape creation, vertex editing, zoom, save/load) are complete and functional; Phase 3 builds on them without breaking existing behavior.
+
+---
+
+## 1. Data Model Changes
+
+### 1a. Color is already in the model
+
+The shape data dictionary already includes `"color": "#hex"`. The `.stk` format already serializes/deserializes color. Phase 3 adds a **ColorPicker UI** to change it interactively.
+
+### 1b. Global Settings (`user://settings.json`)
+
+New persistent settings file stored in Godot's user data directory:
+
+```json
+{
+  "grid_size": 5,
+  "snap_to_grid": false,
+  "version": "1.0"
+}
+```
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `version` | `string` | `"1.0"` | Settings file version (for future extensibility) |
+| `grid_size` | `int` | `5` | Grid interval in pixels (applied equally to width and height) |
+| `snap_to_grid` | `bool` | `false` | Whether snap-to-grid is active |
+
+- **Load**: On editor startup (`_ready()`), attempt to load `user://settings.json`. If the file doesn't exist or fails to parse, use defaults.
+- **Save**: Whenever the user changes grid size or toggles snap-to-grid, write the updated settings.
+- **Scope**: Global — all panels share the same grid size and snap setting.
+
+### 1c. Pan offset (transient, not persisted)
+
+Both `BodyPartPanel` and `WholeStickmanPreview` gain a `_pan_offset: Vector2` variable, default `(0,0)`. This is **not persisted** in any file — it resets on load/clear and when the user clicks "Reset Views".
+
+---
+
+## 2. BodyPartPanel — Phase 3 Changes
+
+### 2a. New State Variables
+
+```gdscript
+var _pan_offset: Vector2 = Vector2.ZERO  # camera pan, modified by middle-mouse drag
+var _grid_size: int = 5                   # received from editor
+var _snap_enabled: bool = false           # received from editor
+var _is_panning: bool = false             # true while middle mouse is held
+var _pan_start: Vector2 = Vector2.ZERO    # screen position where pan started
+var _restore_color: Color                 # saved color for Cancel support
+```
+
+### 2b. New Public Methods
+
+```gdscript
+func set_grid_size(size: int) -> void:
+    _grid_size = size
+    drawing_area.queue_redraw()
+
+func set_snap_enabled(enabled: bool) -> void:
+    _snap_enabled = enabled
+
+func reset_view() -> void:
+    _zoom = 1.0
+    _pan_offset = Vector2.ZERO
+    drawing_area.queue_redraw()
+```
+
+### 2c. Panning (Middle Mouse Button)
+
+In `_on_drawing_area_gui_input()`:
+
+1. `MOUSE_BUTTON_MIDDLE` pressed: Set `_is_panning = true`, record `_pan_start = mb.position`.
+2. `MOUSE_BUTTON_MIDDLE` released: `_is_panning = false`.
+3. `InputEventMouseMotion` while `_is_panning`: `_pan_offset += (mm.position - _pan_start) / _zoom`. Then `_pan_start = mm.position`. `queue_redraw()`. **Note**: pan offset moves inversely to drag direction (drag right → camera moves right, content appears to move left). The offset is added to the transform, so positive offset shifts drawing right.
+
+Z-order input priority:
+1. Middle mouse button (if press or panning in progress)
+2. Mouse wheel (zoom)
+3. Left mouse button (vertex drag / shape selection)
+4. Right mouse button (context menu)
+
+### 2d. Grid Drawing
+
+In `_on_drawing_area_draw()`, after `draw_set_transform` but before shape rendering, draw the grid:
+
+```gdscript
+func _draw_grid() -> void:
+    var gs := float(_grid_size)
+    if gs <= 0: return
+
+    var area_size := drawing_area.size
+    var world_origin := (-_pan_offset - Vector2(area_size) * 0.5) / _zoom
+    var world_size := area_size / _zoom
+    var world_end := world_origin + world_size
+
+    var start_x := floor(world_origin.x / gs) * gs
+    var start_y := floor(world_origin.y / gs) * gs
+
+    var grid_color := Color(1.0, 1.0, 1.0, 0.15)
+
+    var x := start_x
+    while x <= world_end.x:
+        drawing_area.draw_line(Vector2(x, world_origin.y), Vector2(x, world_end.y), grid_color, 1.0 / _zoom)
+        x += gs
+
+    var y := start_y
+    while y <= world_end.y:
+        drawing_area.draw_line(Vector2(world_origin.x, y), Vector2(world_end.x, y), grid_color, 1.0 / _zoom)
+        y += gs
+```
+
+The grid is drawn **before** the shape fill/outline so it appears behind the shapes.
+
+Rendering order (updated):
+1. Grid lines (thin, low alpha)
+2. Shape fill (if closed)
+3. Shape outline
+4. Selection highlight (if selected)
+5. Vertex handles
+
+**Important**: The grid must account for both zoom AND pan offset. The transform applied is:
+```gdscript
+drawing_area.draw_set_transform(_pan_offset, 0.0, Vector2(_zoom, _zoom))
+```
+This replaces the current `draw_set_transform(Vector2.ZERO, 0.0, Vector2(_zoom, _zoom))`.
+
+### 2e. Snap to Grid (Vertex Drag)
+
+In the `InputEventMouseMotion` handler for vertex dragging, after computing the world position, apply snap:
+
+```gdscript
+var world_pos := _screen_to_world(mm.position)
+if _snap_enabled:
+    world_pos = _snap_to_grid(world_pos)
+shape_data.points[_dragging_vertex] = world_pos - _drag_offset
+```
+
+Snap helper:
+```gdscript
+func _snap_to_grid(pos: Vector2) -> Vector2:
+    var gs := float(_grid_size)
+    return Vector2(
+        round(pos.x / gs) * gs,
+        round(pos.y / gs) * gs
+    )
+```
+
+Snap is applied **before** the drag offset is subtracted, so the user sees the vertex jump to the nearest grid intersection while dragging.
+
+### 2f. Context Menu — Color Entry
+
+The right-click context menu for a selected shape is updated:
+
+```
+[existing: "Create Point"]  (id 3)
+[separator]
+"Color..."                  (id 4)
+[separator]
+"Delete"                    (id 5)
+```
+
+**"Color..." behavior**:
+1. Save the current color: `_restore_color = Color.from_string(shape_data.color, Color.BLACK)`.
+2. Create or show a `ColorPicker` dialog.
+3. When the user changes the color in the picker (preview): update `shape_data.color` to the hex string and `queue_redraw()`. This gives live preview.
+4. On **OK**: commit the color change, emit `shape_changed`.
+5. On **Cancel**: restore `shape_data.color = _restore_color.to_html()`, `queue_redraw()`.
+
+**Implementation via ColorPickerButton**:
+- Add a `ColorPickerButton` node to the `BodyPartPanel` scene (hidden by default, `visible = false`).
+- When "Color..." is clicked: set the picker's color to the current shape color, set `visible = true`, and programmatically trigger `popup()`.
+- Connect the `color_changed` signal: update `shape_data.color` → `queue_redraw()` (live preview).
+- Connect the `popup_closed` signal: this is where we distinguish OK vs Cancel. If the user clicked the "OK" or selected a swatch, the color was already committed through `color_changed`. If they cancelled, restore `_restore_color`.
+
+Actually, `ColorPickerButton` in Godot 4.4 has a `color_changed` signal for preview but no built-in way to detect Cancel. A cleaner approach:
+
+**Implementation via custom dialog**:
+- Add a `ColorPicker` node inside a `Popup` or `AcceptDialog` with OK/Cancel buttons in the `BodyPartPanel` scene.
+- On "Color...": set the picker color, show the popup.
+- On Cancel: restore previous color.
+- On OK: commit.
+
+Since `ColorPickerButton` doesn't provide a clean Cancel detection, use a simple `AcceptDialog`-equivalent with a `ColorPicker`. Actually, the cleanest approach in Godot 4:
+
+Use the built-in `ColorPicker` node (not `ColorPickerButton`) in a new scene or directly in `body_part_panel.tscn`. When "Color..." is clicked, we can also just use `PopupPanel` with a ColorPicker inside, or use `AcceptDialog` with a custom child.
+
+**Simplest reliable approach**: Use `ColorPicker` node, detect color changes for preview, and use the color_picker's own `Popup` behavior. Actually, let me reconsider. The `ColorPicker` extends `VBoxContainer` - it needs to be in a popup.
+
+**Decision**: Add a `PopupPanel` → VBoxContainer → ColorPicker → HBoxContainer (OK, Cancel buttons) to `body_part_panel.tscn`. On "Color...": set the picker's color, show popup. On color_changed: preview. On OK: commit, hide popup, emit shape_changed. On Cancel: restore, hide popup.
+
+### 2g. Context Menu — Delete Entry
+
+**"Delete" behavior** (id 5):
+1. Call `clear_shape()` (which resets shape_data but does NOT emit shape_changed).
+2. Emit `shape_changed` manually so the Whole Stickman preview updates.
+
+### 2h. Context Menu Refactor — Right-Click Logic
+
+The current `_on_drawing_area_gui_input()` right-click logic is:
+
+```
+if _selected AND near outline → show "Create Point"
+else → show "Line", "Rectangle", "Circle"
+```
+
+Phase 3 changes this to:
+
+```
+1. Check if right-click is on a VERTEX (hit-test vertex handles).
+   If YES:
+     → show "Remove Point" context menu (id 6)
+     return
+
+2. If a shape EXISTS (not empty) AND (_selected OR mouse is over the shape):
+   → show context menu with [Create Point / Color... / Delete] entries
+   return
+
+3. Else (no shape or shape not selected):
+   → show [Line / Rectangle / Circle] shape creation menu
+```
+
+**New context menu item IDs**:
+
+| ID | Label | Context |
+|----|-------|---------|
+| 0 | Line | No shape / shape not selected |
+| 1 | Rectangle | No shape / shape not selected |
+| 2 | Circle | No shape / shape not selected |
+| 3 | Create Point | Shape selected, near outline |
+| 4 | Color... | Shape selected |
+| 5 | Delete | Shape selected |
+| 6 | Remove Point | Right-click on vertex handle |
+
+**Rule for "Delete" visibility**: Show Delete only when a shape exists AND (`_selected == true` OR mouse is over the shape). This means:
+- If the shape is selected but the mouse is not over it, Delete still shows.
+- If the shape is not selected but the mouse is over it, Delete still shows.
+
+### 2i. Vertex Delete (Remove Point)
+
+When the user right-clicks on a vertex handle:
+
+1. Show context menu with only "Remove Point" (id 6).
+2. Store the vertex index as metadata on the context menu.
+3. On "Remove Point" selected:
+   a. Remove the point at the stored index from `shape_data.points`.
+   b. Remove the corresponding entry from `shape_data.vertex_flags`.
+   c. If `shape_data.points.size() == 2`:
+      - Set `shape_data.closed = false` (becomes a line).
+   d. If `shape_data.points.size() < 2`:
+      - Call `clear_shape()` (removes the shape entirely).
+   e. `queue_redraw()` and emit `shape_changed`.
+
+### 2j. Updated `_on_context_menu_id_pressed()`
+
+New match cases:
+```gdscript
+4:  # Color...
+    _show_color_picker()
+5:  # Delete
+    _delete_shape()
+6:  # Remove Point
+    _remove_vertex(context_menu.get_meta("vertex_index", -1))
+```
+
+### 2k. Updated `clear_shape()`
+
+`clear_shape()` MUST also reset pan and zoom since we're starting fresh:
+```gdscript
+_pan_offset = Vector2.ZERO
+_zoom = 1.0
+```
+
+### 2l. Updated `set_shape_data()`
+
+Reset pan offset on data load:
+```gdscript
+_pan_offset = Vector2.ZERO
+```
+
+---
+
+## 3. WholeStickmanPreview — Phase 3 Changes
+
+### 3a. New State Variables
+
+```gdscript
+var _pan_offset: Vector2 = Vector2.ZERO
+var _grid_size: int = 5
+var _snap_enabled: bool = false
+var _is_panning: bool = false
+var _pan_start: Vector2 = Vector2.ZERO
+```
+
+### 3b. New Public Methods
+
+```gdscript
+func set_grid_size(size: int) -> void:
+    _grid_size = size
+    preview_area.queue_redraw()
+
+func set_snap_enabled(enabled: bool) -> void:
+    _snap_enabled = enabled
+
+func reset_view() -> void:
+    _zoom = 1.0
+    _pan_offset = Vector2.ZERO
+    preview_area.queue_redraw()
+```
+
+### 3c. Panning
+
+Same pattern as BodyPartPanel: middle-mouse press/release tracks `_is_panning`, mouse motion updates `_pan_offset` inversely.
+
+### 3d. Grid Drawing
+
+Same grid drawing code as BodyPartPanel, adapted for `preview_area`. Uses the same `_grid_size`. The grid is drawn behind the parts.
+
+The draw transform is updated from:
+```gdscript
+preview_area.draw_set_transform(Vector2.ZERO, 0.0, Vector2(_zoom, _zoom))
+```
+to:
+```gdscript
+preview_area.draw_set_transform(_pan_offset, 0.0, Vector2(_zoom, _zoom))
+```
+
+### 3e. Snap to Grid (Part Drag)
+
+In the drag motion handler, after computing the mouse world position, snap it:
+```gdscript
+var world_pos: Vector2 = mm.position / _zoom
+if _snap_enabled:
+    var gs := float(_grid_size)
+    world_pos.x = round(world_pos.x / gs) * gs
+    world_pos.y = round(world_pos.y / gs) * gs
+var new_pos := world_pos - _drag_offset
+_part_positions[_dragging_part] = new_pos
+```
+
+This uses the mouse pointer position as the snap reference, as specified: the mouse position snaps to grid, and the part follows.
+
+### 3f. Updated `clear_all()`
+
+Reset pan offset on clear:
+```gdscript
+_pan_offset = Vector2.ZERO
+_zoom = 1.0
+```
+
+### 3g. Updated `set_body_parts()`
+
+Reset pan offset on body part set (full refresh from editor):
+```gdscript
+_pan_offset = Vector2.ZERO
+```
+
+---
+
+## 4. StickmanEditor — Phase 3 Changes
+
+### 4a. New Menu Bar Structure
+
+```
+┌──────────────────────────────────────────┐
+│ File  │  Edit         │  View  │         │
+│──────────────────────────────────────────│
+│ Save  │  Configure Grid...  │ Reset Views │
+│ Load  │  Snap to Grid    │         │
+│ ───── │                    │         │
+│ Clear │                    │         │
+└──────────────────────────────────────────┘
+```
+
+### 4b. Menu Setup in `_setup_menu_bar()`
+
+After the existing "File" menu, add:
+
+**Edit menu** (PopupMenu):
+- "Configure Grid..." (id 0) — opens a dialog.
+- Separator.
+- "Snap to Grid" (id 1) — **checkable** item; checked = snap enabled.
+
+**View menu** (PopupMenu):
+- "Reset Views" (id 0) — resets zoom + pan on all panels.
+
+### 4c. New State Variables
+
+```gdscript
+var _grid_size: int = 5
+var _snap_enabled: bool = false
+```
+
+### 4d. New On-Ready Nodes
+
+Add to the scene or create programmatically:
+- `%GridConfigDialog` — a `ConfirmationDialog` or `AcceptDialog` with a SpinBox for grid size.
+- `%ColorPickerPopup` — kept in body_part_panel.tscn, not here.
+
+Actually, the grid config dialog should be in the editor scene since it's a top-level dialog. Add it to `stickman_editor.tscn`. The ColorPicker stays in `body_part_panel.tscn` since it's per-panel.
+
+### 4e. Grid Config Dialog
+
+**Option A**: Add a `ConfirmationDialog` with a `SpinBox` child to `stickman_editor.tscn`.
+- Title: "Configure Grid"
+- Label: "Grid Size (pixels):"
+- SpinBox: min 1, max 100, step 1, value = current `_grid_size`.
+- On confirmed: read SpinBox value, set `_grid_size`, broadcast to all panels + WholeStickmanPreview, write `settings.json`.
+
+### 4f. Settings Load/Save
+
+```gdscript
+func _load_settings() -> void:
+    if not FileAccess.file_exists("user://settings.json"):
+        return  # use defaults
+    var file := FileAccess.open("user://settings.json", FileAccess.READ)
+    if file == null:
+        return
+    var json_text := file.get_as_text()
+    file.close()
+    var json: Variant = JSON.parse_string(json_text)
+    if json is Dictionary:
+        var d := json as Dictionary
+        _grid_size = int(d.get("grid_size", 5))
+        _snap_enabled = bool(d.get("snap_to_grid", false))
+        # Clamp to valid range
+        _grid_size = clampi(_grid_size, 1, 100)
+
+func _save_settings() -> void:
+    var data := {
+        "version": "1.0",
+        "grid_size": _grid_size,
+        "snap_to_grid": _snap_enabled,
+    }
+    var file := FileAccess.open("user://settings.json", FileAccess.WRITE)
+    if file:
+        file.store_string(JSON.stringify(data, "\t", false))
+        file.close()
+```
+
+Called in `_ready()`: load settings, then broadcast to panels.
+
+### 4g. Broadcasting Settings to Panels
+
+New helper:
+```gdscript
+func _broadcast_settings() -> void:
+    for panel in _body_part_panels.values():
+        panel.set_grid_size(_grid_size)
+        panel.set_snap_enabled(_snap_enabled)
+    _whole_preview.set_grid_size(_grid_size)
+    _whole_preview.set_snap_enabled(_snap_enabled)
+```
+
+Called after loading settings in `_ready()` and whenever grid/snap changes.
+
+### 4h. Save Flow Update
+
+Color is already included in `_build_json_data()` via `panel.get_shape_data()` which returns `color`. No .stk format changes needed for Phase 3.
+
+### 4i. Reset Views Handler
+
+```gdscript
+func _on_view_menu_id_pressed(id: int) -> void:
+    if id == 0:  # Reset Views
+        for panel in _body_part_panels.values():
+            panel.reset_view()
+        _whole_preview.reset_view()
+```
+
+---
+
+## 5. Scene File Changes
+
+### 5a. `scenes/stickman_editor.tscn`
+
+Add new nodes under the root `StickmanEditor`:
+
+```
+[node name="GridConfigDialog" type="ConfirmationDialog" parent="."]
+unique_name_in_owner = true
+title = "Configure Grid"
+ok_button_text = "OK"
+
+[node name="VBoxContainer" type="VBoxContainer" parent="GridConfigDialog"]
+layout_mode = 2
+
+[node name="GridSizeLabel" type="Label" parent="GridConfigDialog/VBoxContainer"]
+layout_mode = 2
+text = "Grid Size (pixels):"
+
+[node name="GridSizeSpinBox" type="SpinBox" parent="GridConfigDialog/VBoxContainer"]
+unique_name_in_owner = true
+layout_mode = 2
+min_value = 1.0
+max_value = 100.0
+value = 5.0
+step = 1.0
+rounded = true
+```
+
+### 5b. `scenes/body_part_panel.tscn`
+
+Add a ColorPicker popup:
+
+```
+[node name="ColorPickerPopup" type="PopupPanel" parent="."]
+unique_name_in_owner = true
+visible = false
+
+[node name="VBoxContainer" type="VBoxContainer" parent="ColorPickerPopup"]
+layout_mode = 2
+
+[node name="ColorPicker" type="ColorPicker" parent="ColorPickerPopup/VBoxContainer"]
+unique_name_in_owner = true
+layout_mode = 2
+custom_minimum_size = Vector2(300, 300)
+
+[node name="ButtonRow" type="HBoxContainer" parent="ColorPickerPopup/VBoxContainer"]
+layout_mode = 2
+alignment = 2  # END
+
+[node name="CancelButton" type="Button" parent="ColorPickerPopup/VBoxContainer/ButtonRow"]
+layout_mode = 2
+text = "Cancel"
+
+[node name="OKButton" type="Button" parent="ColorPickerPopup/VBoxContainer/ButtonRow"]
+layout_mode = 2
+text = "OK"
+```
+
+---
+
+## 6. Files Modified
+
+| File | Changes |
+|---|---|
+| `scripts/body_part_panel.gd` | Major: panning (middle mouse), grid drawing, snap-to-grid in vertex drag, ColorPicker integration, "Delete" shape, "Remove Point" vertex delete, context menu refactor, reset_view(), set_grid_size(), set_snap_enabled() |
+| `scripts/stickman_editor.gd` | Modular: Edit/View menus, GridConfigDialog, settings.json load/save, broadcast grid/snap settings, Reset Views handler |
+| `scripts/whole_stickman_preview.gd` | Major: panning, grid drawing, snap-to-grid in part drag, reset_view(), set_grid_size(), set_snap_enabled() |
+| `scenes/stickman_editor.tscn` | Add GridConfigDialog + children |
+| `scenes/body_part_panel.tscn` | Add ColorPickerPopup + children |
+| `docs/phase3_spec.md` | This file |
+
+---
+
+## 7. Implementation Order
+
+1. **Menus + Settings** — Add Edit/View menus, settings.json load/save, broadcast infrastructure
+2. **GridConfigDialog** — Dialog + SpinBox in editor scene, wire up to settings
+3. **Panning** — Middle-mouse drag in BodyPartPanel + WholeStickmanPreview
+4. **Grid drawing** — Background grid in both panels, accounting for zoom + pan offset
+5. **Snap to Grid** — Vertex drag snap + Whole Stickman part drag snap
+6. **Reset Views** — View menu item → reset zoom + pan on all panels
+7. **ColorPicker** — Add ColorPickerPopup, context menu "Color..." entry, preview + commit/cancel
+8. **Shape Delete** — Context menu "Delete" entry, conditional visibility
+9. **Vertex Delete** — Right-click on vertex → "Remove Point", edge cases (2→line, <2→clear)
+10. **Scene files** — Update both .tscn files with new nodes
+11. **README update** — Document Phase 3 features
+
+---
+
+## 8. Edge Cases & Constraints
+
+- **Grid size = 1**: Grid lines become very dense. Still functional; performance acceptable for ~50-100 lines per panel at typical panel sizes (~230x160px @ 1px grid = massive density, but max panel size is ~500x300 visible → 500 lines). If performance issues arise, skip drawing when `_grid_size < 3` at high zoom.
+- **Pan + zoom interaction**: Pan offset is in screen space, applied via `draw_set_transform`. The offset is NOT divided by zoom — it's added before the scale, so pan feels natural at any zoom level. At 2x zoom, dragging 100px in screen space moves the view by 100px world units.
+- **Middle mouse + any other button**: If the user presses middle mouse while dragging a vertex, the vertex drag is cancelled and panning takes over. This prevents conflicts.
+- **ColorPicker Cancel**: If the user opens the color picker and clicks Cancel, the shape color MUST revert to the pre-dialog value. The preview during color picker interaction updates `shape_data.color` directly; on cancel we restore from `_restore_color`.
+- **Delete last remaining vertex**: If Remove Point is called on a shape with 2 vertices, it becomes an open line (`closed=false`). If called on a shape with 1 vertex, the shape is cleared entirely.
+- **Delete shape while selected**: When shape is deleted, clear `_selected`, clear `_dragging_vertex`, emit `shape_changed`.
+- **Settings file missing**: Gracefully use defaults (grid_size=5, snap_to_grid=false). No error dialog.
+- **Settings file corrupted**: Gracefully use defaults. No error dialog.
+- **Snap to Grid toggle**: When toggling snap ON, vertices don't immediately snap — they only snap when dragged. This matches user expectation (existing vertex positions aren't retroactively modified).
+- **Context menu positioning**: All context menus use `popup_on_parent(Rect2(mb.global_position, Vector2.ONE))` for proper screen-space positioning.