stickman/AGENTS.md

# 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.