ryan/stickman
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
ryan
2026-08-08 00:00:50 -04:00
commit b97bc145e4
34 changed files with 6874 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/phase2_spec.md
+241
View File
@@ -0,0 +1,241 @@
# Phase 2 — Architectural Specification
## Overview
Phase 2 adds **interactive vertex editing** (custom shapes), **per-panel zoom**, and an **expanded .stk save format** to the Stickman Studio editor. Phase 1 (shape creation, save/load, whole-stickman assembly) is complete and functional; Phase 2 builds on it without breaking existing behavior.
---
## 1. Data Model Changes
### 1a. Shape Data Dictionary (updated)
```gdscript
# body_part_panel.gd — internal shape_data extends to:
{
"shape_type": String, # "line", "rectangle", "circle", "" (unchanged)
"points": PackedVector2Array, # vertex positions (unchanged)
"color": String, # hex color (unchanged)
"closed": bool, # NEW — true for polygon fill, false for open line
"vertex_flags": PackedInt32Array # NEW — 0=original, 1=user_created; same length as points
}
```
- `closed` replaces the implicit closed-ness that was derived from `shape_type`. A line has `closed=false`; a rectangle and circle have `closed=true`. The rendering logic switches on `closed` instead of `shape_type`.
- `vertex_flags` tracks which vertices are "original" (filled circle handle) vs "user-created via Create Point" (hollow rectangle handle). Default all-zero for starter shapes.
- `shape_type` is retained as a descriptive tag but no longer drives rendering behavior.
### 1b. .stk File Format (version "1.1")
```json
{
"version": "1.1",
"stickman_name": "Bob",
"body_parts": {
"head": {
"shape_type": "circle",
"closed": true,
"points": [{"x": 120, "y": 40}, ...],
"color": "#000000",
"position": {"x": 150, "y": 40},
"vertex_flags": [0, 0, 0, 1, 0, ...]
}
},
"metadata": {
"created_at": "...",
"modified_at": "..."
}
}
```
- **Version bumped to `"1.1"`.** Loading: if version is `"1.0"`, auto-migrate (set `closed` based on `shape_type`, set `vertex_flags` as all-zeros). Save always writes `"1.1"`.
- New per-shape keys: `"closed"` (bool) and `"vertex_flags"` (array of ints, length matching `points`).
- Backward compatibility: loading a 1.0 file infers `closed` from `shape_type` (`"line"`→false, `"rectangle"`/`"circle"`→true, `""`→false). vertex_flags defaults to all zeros for any shape loaded from 1.0.
### 1c. Circle Refactor
- `_create_circle()` generates **12 vertices** (down from 32). The shape_type remains `"circle"`, `closed=true`, `vertex_flags` all zeros.
- Existing 32-vertex circles in saved `.stk` files still load correctly — `set_shape_data()` accepts arbitrary point arrays.
---
## 2. BodyPartPanel — Vertex Editing
### 2a. Selection State
New internal state variables in `body_part_panel.gd`:
```gdscript
var _selected: bool = false # is this panel's shape currently selected?
var _dragging_vertex: int = -1 # index of vertex being dragged, -1 if none
var _drag_offset: Vector2 # offset from vertex to mouse during drag
var _zoom: float = 1.0 # zoom factor clamped to [0.3, 3.0]
```
### 2b. Interaction Model
| Action | Trigger | Behavior |
|---|---|---|
| **Select shape** | Left-click inside shape bounds | Sets `_selected=true`, emits `shape_selected` signal. Deselects all other panels (coordinated by `stickman_editor.gd`). |
| **Deselect** | Left-click outside shape OR clicking another panel | `_selected=false`. Any in-progress drag is cancelled. |
| **Drag vertex** | Left-click press on a vertex handle, then drag | Sets `_dragging_vertex` to that index. On mouse motion, updates vertex position. On release, clears drag state. Emits `shape_changed`. |
| **Open context menu** | Right-click on the outline path of a **selected** shape | Shows a `PopupMenu` with one item: "Create Point". The click position is stored for vertex insertion. |
| **Create initial shape** | Right-click on an **empty** drawing area (no shape OR shape not selected) | Shows the existing 3-item context menu (Line, Rectangle, Circle). *Unchanged from Phase 1.* |
### 2c. Hit Testing
- **Shape selection hit-test**: Point-in-polygon check against the full shape polygon. For open shapes (lines), check if the click is within a threshold distance (12px) of any edge.
- **Vertex hit-test**: For each vertex, check if the mouse position is within `HANDLE_RADIUS_SELECTION` (8px) of the vertex position (in screen space, accounting for zoom).
- **Edge hit-test for Create Point**: Find the nearest edge to the right-click position (in screen space). The new vertex is inserted at the midpoint of that edge.
### 2d. Rendering Changes (in `_on_drawing_area_draw()`)
Rendering order (back to front):
1. **Fill** (if `closed`): `draw_colored_polygon(pts, color)` — same as Phase 1.
2. **Outline**: `_draw_polyline(pts, color, ...)` — same as Phase 1.
3. **Selection highlight** (if `_selected`): Redraw the polyline in white (`Color.WHITE`), 2px wide, on top of the color outline. This makes the selected shape stand out.
4. **Vertex handles**: For each vertex:
- If `vertex_flags[i] == 0` (original): filled circle, radius `HANDLE_RADIUS / zoom` (so it stays constant screen size).
- If `vertex_flags[i] == 1` (user-created): hollow rectangle, size `(6/zoom)×(6/zoom)`, centered on the vertex.
- If `i == _dragging_vertex`: draw in yellow highlight.
### 2e. Context Menu Refactor
The existing `ContextMenu` (ids 0, 1, 2 — Line, Rectangle, Circle) is repurposed for initial shape creation only.
A **second** `PopupMenu` is needed for vertex editing. Two options:
- **Option A (chosen):** Single PopupMenu, dynamically repopulated based on context. When right-clicking on empty area → show "Line", "Rectangle", "Circle". When right-clicking on outline of selected shape → show "Create Point" only. This requires clearing/rebuilding the menu items programmatically.
- **Option B:** Two separate PopupMenu nodes.
**Decision: Option A** — less scene overhead, single menu node reused.
Menu id: 0=Line, 1=Rectangle, 2=Circle, 3=Create Point (only shown in vertex context).
### 2f. Vertex Insertion (Create Point)
1. Right-click on the outline of a selected shape.
2. Find the nearest edge (line segment) to the click position.
3. Insert a new vertex at the **midpoint** of that edge (not at the click position — this matches the user story where the vertex "appear[s] in the outline where the user clicked" at the nearest edge midpoint, not an arbitrary point).
4. Append `1` to `vertex_flags` at the corresponding position.
5. `queue_redraw()` and `emit shape_changed`.
*Note: PROJECT.md says "a small hollow rectangle will appear in the outline where the user clicked — this is not a point(vertex)". I interpret this to mean: the vertex is placed on the outline at the nearest edge midpoint. The "not a point" language means it's a vertex, just drawn differently (hollow rectangle).*
### 2g. Vertex Dragging
1. Left-click press on a vertex handle (within `HANDLE_RADIUS_SELECTION`).
2. Set `_dragging_vertex = index`, `_drag_offset = position - vertex_position`.
3. On mouse motion (`InputEventMouseMotion`):
- Compute new world-space position: `new_pos = mouse_position / zoom` (undo zoom) or keep everything in world space. **Design decision:** Store points in world space (unscaled). Apply `draw_set_transform(Vector2.ZERO, 0, Vector2(zoom, zoom))` in `_draw()`. Mouse positions are divided by zoom to get world coordinates.
- Update `shape_data.points[_dragging_vertex] = world_pos`.
- `queue_redraw()`.
4. On mouse release: clear `_dragging_vertex`, emit `shape_changed`.
---
## 3. Window Zoom
### 3a. BodyPartPanel Zoom
- Add `_zoom: float = 1.0` (range `[0.3, 3.0]`).
- Mouse wheel handling in `_on_drawing_area_gui_input()`:
- `MOUSE_BUTTON_WHEEL_UP`: `_zoom = clamp(_zoom * 1.10, 0.3, 3.0)`
- `MOUSE_BUTTON_WHEEL_DOWN`: `_zoom = clamp(_zoom / 1.10, 0.3, 3.0)`
- In `_on_drawing_area_draw()`, apply: `drawing_area.draw_set_transform(Vector2.ZERO, 0.0, Vector2(_zoom, _zoom))` before all draw calls.
- Mouse-to-world conversion: All input event positions must be divided by `_zoom` before using as world coordinates (hit-testing, vertex creation, dragging).
- Vertex handles drawn with sizes divided by `_zoom` (e.g., `HANDLE_RADIUS / _zoom`), so they appear the same screen size regardless of zoom level.
### 3b. WholeStickmanPreview Zoom
- Add `_zoom: float = 1.0` (same range).
- Same wheel handling, same `draw_set_transform` application.
- No vertex handles drawn here, so the handle-size concern doesn't apply.
- Drag hit-testing (`_try_start_drag`): Divide `at_position` by `_zoom` to convert to world coordinates. The drag offset and part positions remain in world space.
---
## 4. StickmanEditor — Coordination Changes
### 4a. Selection Coordination
When a `BodyPartPanel` is selected, all other panels must be deselected. Add:
```gdscript
signal shape_selected(part_name: String)
# In _on_body_part_shape_selected(part_name):
# for each panel in _body_part_panels where key != part_name:
# panel.deselect()
```
Add a `deselect()` method to `BodyPartPanel` that sets `_selected=false` and `queue_redraw()`.
### 4b. Save Format Updates
- `FILE_VERSION` → `"1.1"`.
- `_build_json_data()` now includes `"closed"` and `"vertex_flags"` in each shape.
- `_collect_all_shape_data()` updated accordingly — `BodyPartPanel.get_shape_data()` returns the updated dictionary with `closed` and `vertex_flags`.
- `_apply_json_data()` handles both `"1.0"` and `"1.1"`:
- 1.0: auto-migrate (infer `closed` from `shape_type`, set `vertex_flags` to all-zeros).
- 1.1: read `closed` and `vertex_flags` directly.
### 4c. New Signal Wiring
- `BodyPartPanel.shape_changed` — existing, now also emitted on vertex drag end and Create Point.
- `BodyPartPanel.shape_selected` — new, for cross-panel deselection coordination.
- Each panel's `shape_selected` connects to `stickman_editor._on_body_part_shape_selected`.
---
## 5. WholeStickmanPreview — Changes
### 5a. Zoom Support
- Add `_zoom` with same wheel handling and range.
- Apply `draw_set_transform` in `_on_preview_draw()`.
- Convert mouse positions in `_try_start_drag()` and `_on_preview_gui_input()`.
### 5b. Closed Shape Rendering
- The preview currently switches on `shape_type` to decide fill+close. Update to check `closed: bool` from the shape data instead.
- Add `_draw_polyline_preview()` helper for clean line drawing (consistent with BodyPartPanel).
---
## 6. Files Modified
| File | Changes |
|---|---|
| `scripts/body_part_panel.gd` | Major: vertex editing state, selection, zoom, context menu refactor, rendering with closed flag & vertex_flags, circle→12 vertices, mouse handling expanded |
| `scripts/stickman_editor.gd` | Version bump to 1.1, save format includes closed/vertex_flags, load handles 1.0+1.1, selection coordination signal |
| `scripts/whole_stickman_preview.gd` | Zoom support, closed-based rendering instead of shape_type-based, input coordinate transform |
| `scenes/body_part_panel.tscn` | Minimal — ContextMenu items may be reduced or left as-is (dynamic repopulation in script). *Consider adding a 4th static item "Create Point" hidden by default.* |
| `README.md` | Document Phase 2 features, updated .stk format, vertex editing, zoom |
| `docs/phase2_spec.md` | This file |
---
## 7. Implementation Order (Recommended)
1. **Data model + circle refactor** (shape_data adds `closed` + `vertex_flags`, circle→12 vertices, rendering uses `closed`)
2. **Zoom** (mouse wheel, draw_set_transform, coordinate conversion, handle-size scaling)
3. **Shape selection** (left-click hit-test, white outline, cross-panel deselection)
4. **Vertex hit-testing & dragging** (left-click on handles, drag motion, release)
5. **Create Point** (right-click context menu on selected outline, edge finding, vertex insertion)
6. **Save/load update** (version 1.1, closed/vertex_flags in JSON, backward compatible loading)
7. **WholeStickmanPreview zoom + closed rendering**
8. **README update**
---
## 8. Edge Cases & Constraints
- **Empty panel**: Right-click shows shape creation menu (unchanged). Left-click does nothing. Zoom still works.
- **Single-vertex shapes**: If a shape somehow has only 1 vertex, skip rendering (guard already exists at `count < 2`).
- **Min zoom (30%)**: Vertex handles drawn at `HANDLE_RADIUS / 0.3 ≈ 10px` — still visible.
- **Max zoom (300%)**: Vertex handles at `HANDLE_RADIUS / 3.0 ≈ 1px` — still visible but small.
- **Zoom state is NOT persisted** in the .stk file. Each panel resets to 1.0 on load/clear (editor-only transient state).
- **Vertex drag performance**: Emit `shape_changed` on drag end (not every frame) to avoid excessive WholeStickmanPreview rebuilds. Redraws during drag only touch the local panel.
- **Multiple selected shapes**: Only one shape can be selected at a time across the entire editor.
- **Right-click on empty area when shape exists but not selected**: Shows shape creation menu (existing behavior), which replaces the current shape.