first commit

AGENTS.md

@@ -0,0 +1,99 @@
+# AGENTS.md — stickman (Godot 4.4)
+
+## Project type
+- **Godot 4.4** 2D/GUI project (Forward Plus renderer)
+- No CLI build/test/lint commands; open in the Godot editor to run
+- **Main scene:** `res://scenes/stickman_editor.tscn` (set as `run/main_scene` in `project.godot`)
+
+## Project overview
+Stickman Studio is an editor tool for drawing and assembling stick figures. It is a
+`Control`-based GUI (not physics/animation) in its current phase. Body-part vector shapes
+are authored per-panel (each panel supports **multiple shapes** with Z-ordering) and
+assembled in a "Whole Stickman" preview that supports translation, rotation, and scale.
+
+## Required addon
+- **Scalable Vector Shapes 2D** (v2.27.7) at `addons/curved_lines_2d/`
+  - Declared dependency for the project. The current editor UI does not instantiate it directly,
+    but keep it present — it is required for the legacy `stick.tscn` rig.
+
+## Architecture
+- `scripts/stickman_editor.gd` — `extends Control`; the main controller. Owns the menu bar,
+  save/load/clear flow, JSON (de)serialization, and populates the 10 body-part panels.
+  Writes `FILE_VERSION "1.2"`; auto-migrates `"1.0"`/`"1.1"` files on load. Coordinates cross-panel
+  selection so only one shape is selected at a time (`shape_selected` → deselect others).
+  Collects per-part `{shapes[], position, rotation, scale}` for save/load.
+- `scripts/body_part_panel.gd` — `class_name BodyPartPanel`, `extends PanelContainer`.
+  Reusable per-part editor. Public API:
+  - `set_shape_data(data: Variant)` — import shape data (Array or single Dictionary; used on Load/Clear)
+  - `get_shape_data() -> Array[Dictionary]` — export array of `{shape_type, points, color, closed, vertex_flags}`
+  - `clear_shape()` — reset panel, clears all shapes (does **not** emit `shape_changed`)
+  - `select()` — mark the panel's topmost shape as selected (white outline highlight)
+  - `deselect()` — clear selection and cancel any in-progress vertex drag
+  - `signal shape_changed(shapes: Array)` — emitted when any shape is created, modified, deleted, or reordered
+  - `signal shape_selected()` — emitted on left-click; the editor deselects all other panels
+  - **Phase 2 vertex editing:** left-click on a shape selects it; drag a vertex handle to
+    reshape in real time; with a shape selected, right-click near an outline edge offers
+    "Create Point" (inserts a vertex flagged `1` at the edge midpoint). Original vertices
+    are filled circles; user-created vertices are hollow rectangles.
+  - **Phase 4 multi-shape:** panels store a `shapes[]` array. Right-click context menu
+    includes "Send Back" (id 7) and "Bring Forward" (id 8) for Z-ordering. "Delete" (id 5)
+    removes the specific shape under the mouse. `_selected_shape_idx` tracks which shape
+    is active for vertex editing.
+  - **Per-panel zoom:** mouse wheel multiplies `_zoom` by 1.10, clamped to `[0.3, 3.0]`;
+    drawing and input hit-testing both run in world space via `draw_set_transform`.
+  - **Drawing approach:** closedness is read from the `closed` flag (Phase 2), not
+    `shape_type`. Closed shapes are filled via `draw_colored_polygon(pts, color)` before a
+    2 px outline is drawn with `_draw_polyline(..., closed=true)`. Open shapes render
+    outline-only (`closed=false`). Shapes draw in array order (z-order).
+- `scripts/whole_stickman_preview.gd` — `class_name WholeStickmanPreview`,
+  `extends PanelContainer`. Assembles all parts and handles drag-to-reposition, rotation, scale.
+  - `set_body_parts(parts_data)`, `set_all_part_positions(pos)`, `get_part_position(name)`
+  - `get_part_rotation(name) -> float`, `set_part_rotation(name, degrees)`
+  - `get_part_scale(name) -> Vector2`, `set_part_scale(name, scale)`
+  - `_selected_part` (String) — part with white bounding box selected
+  - `_interaction` (enum: NONE, TRANSLATE, ROTATE, SCALE) — current gizmo interaction
+  - Rotation gizmo: filled circle centered below bounding box; Ctrl = 15° snap
+  - Scale gizmo: crosses at 4 corners; Ctrl = aspect ratio lock
+  - `signal part_moved(part_name, new_position)`
+  - Per-panel zoom via mouse wheel (×1.10, clamped to `[0.3, 3.0]`); drag hit-tests and
+    rendering run in world space.
+- Scenes:
+  - `scenes/stickman_editor.tscn` — main editor layout; unique-name nodes (`%Prefix`) used
+    for typed `@onready` access: `%MenuBar`, `%StickmanNameEdit`, `%LeftColumn`,
+    `%CenterColumn`, `%WholeStickmanPreview`, `%SaveDialog`, `%LoadDialog`,
+    `%ClearConfirmDialog`, `%ErrorDialog`.
+  - `scenes/body_part_panel.tscn` — instantiated 10× at runtime (5 per column). Each panel
+    sets `size_flags_vertical = SIZE_EXPAND_FILL` so the panels expand to fill the column
+    height in their parent VBoxContainer.
+
+### Body-part data model
+- 10 internal part keys (ordered): `head`, `torso`, `left_upper_arm`, `left_lower_arm`,
+  `right_upper_arm`, `right_lower_arm`, `left_upper_leg`, `left_lower_leg`,
+  `right_upper_leg`, `right_lower_leg`.
+- Shape dictionary: `{ "shape_type": String, "points": Array[{x,y}], "color": "#hex",
+  "closed": bool, "vertex_flags": Array[int] }`.
+- `shape_type` values: `"line"`, `"rectangle"`, `"circle"`, `""` (empty).
+  Descriptive tag in Phase 2 — rendering uses `closed`.
+- `closed`: `true` = filled + closed outline, `false` = open outline-only.
+- `vertex_flags`: same length as `points`; `0` = original vertex (filled circle),
+  `1` = user-created via "Create Point" (hollow rectangle).
+- **Phase 4:** A panel stores a `shapes[]` array of shape dictionaries. Z-order = array
+  position (first = back, last = front). Per-part data includes `{shapes[], position,
+  rotation, scale}`.
+- The JSON `.stk` format is defined in `README.md` (versioned `"1.2"`, extensible;
+  `"1.0"`/`"1.1"` files auto-migrate on load).
+
+### Legacy scene (do not delete)
+- `stick.tscn` — the original rigged/animated figure using `Skeleton2D` + IK targets +
+  `RemoteTransform2D` + `Line2D` limbs, plus an embedded `@tool` script drawing the head
+  circle. Animations: "walk", "walk_to", "RESET". **Not** the current main scene; kept for
+  future animation/rigging phases.
+
+## Editor conventions
+- `.godot/` is gitignored; never edit it manually.
+- Scene files (`*.tscn`) and `.import` files are text-based; use Godot's editor for complex changes.
+- UID references (Godot 4 native) exist in scenes; do not change them by hand.
+- Use standard Godot `Control` nodes where applicable.
+- Use `class_name` for globally referenced scripts (`BodyPartPanel`, `WholeStickmanPreview`).
+- Prefer `%UniqueName` access over exported node paths in `stickman_editor.gd` / `body_part_panel.gd`.
+- Keep the `.stk` JSON format backward compatible — never change the meaning of an existing key.