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.5"; auto-migrates "1.0"–"1.4" 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, pivot, length, guide_offset} for save/load.
  • Phase 8 save export: writes top-level proportions (hardcoded master-rig rest-pose constants 168/200/200/200/391.5 via the PROPORTIONS const) and per-part pivot/length computed from the panel's local shape bounding box (_compute_part_pivot_length()): pivot = bbox center, length = bbox width for the 4 arm parts (X_AXIS_PARTS) and bbox height otherwise. pivot/length/proportions are write-only metadata — never read back on load, recomputed on every save.
  • Phase 9 Round 5 guide-offset export: each part's save dict also gains "guide_offset": {x, y} = (part bbox center in preview space) − (guide joint in preview space), computed in _collect_all_shape_data() as (pos + pivot) - _whole_preview.get_guide_joint_preview(...) — a pure master-space delta (both points are preview-world coordinates, so panel-size terms cancel). The part→joint map is const GUIDE_JOINT_FOR_PART (head→"Neck" — the head bone's rig attachment origin, NOT the circle center — torso→"Hips", upper arms→Shoulders, lower arms→Elbows, upper legs→"Hips", lower legs→Knees). Write-only metadata like pivot/length; the load path (_apply_json_data) ignores it, so v1.0–v1.4 files load unchanged and gain the key on their next save.
  • Phase 6 recent colors: stores _recent_colors: Array[String] (max 8, most-recent-first), loads from settings.json (recent_colors key) in _load_settings(), saves on each color selection via _save_settings(), and broadcasts to all 10 panels via _broadcast_recent_colors().
  • _on_color_selected(color, part_name): deduplicates, inserts the hex string at the front, trims to 8 entries, saves settings, then broadcasts to all panels.
  • _broadcast_recent_colors(): pushes _recent_colors to every panel via BodyPartPanel.set_recent_colors(_recent_colors).
  • Phase 6 status bar (cursor coords): _process() polls get_global_mouse_position() each frame, checks each panel via is_cursor_over_drawing(global_pos) and the preview via is_cursor_over_preview(global_pos), converts to world space via global_to_world(global_pos), and writes "X: ### Y: ###" to _status_cursor_coords.
  • Phase 6 snap status: _status_snap_status displays "SNAP: ON" / "SNAP: OFF", set in _ready() and re-synced when snap is toggled (_on_edit_menu_id_pressed).
  • Phase 7 pose guide toggle: stores _show_guide: bool (default true), persisted to settings.json under the show_pose_guide key (default true) via _load_settings() / _save_settings(). The View menu item (id 1) is a dynamic, text-only label (no checkmark): "Hide Pose Guide" while the guide is visible, "Show Pose Guide" while hidden, set via _guide_menu_label(). _update_guide_menu_item() refreshes only the item text; it is synced on the about_to_popup signal (_on_view_menu_about_to_popup) and again at the end of _load_settings() (so a persisted show_pose_guide: false shows "Show Pose Guide" immediately at startup). _on_view_menu_id_pressed (id 1) toggles the state, saves, and broadcasts. _broadcast_settings() pushes the value to the preview via WholeStickmanPreview.set_show_guide(_show_guide) (called in _ready() after _load_settings()).
• 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
  • signal color_selected(color: Color) — emitted when the color is confirmed (OK button)
  • set_recent_colors(colors_hex: Array) — clears existing ColorPicker presets and populates with the given hex colors
  • is_cursor_over_drawing(global_pos: Vector2) -> bool — true if global_pos is over the drawing surface
  • global_to_world(global_pos: Vector2) -> Vector2 — maps a global position to drawing ("world") space
  • 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.
  • Phase 6 touchpad: _gui_input handles InputEventMagnifyGesture (pinch zoom) and InputEventPanGesture (2-finger drag panning), both checked before InputEventMouseButton. Pan gesture delta is multiplied by 3.0 for speed parity with mouse panning.
  • Phase 6 cursor-centered zoom: both mouse wheel and pinch zoom adjust _pan_offset so the world point under the cursor stays fixed during zoom.
  • Selection gizmos always on top: bounding box, rotation circle, and scale crosses for the selected part are drawn in a second pass after all parts, via _selected_gizmo_bounds, so they always render in front.
• scripts/whole_stickman_preview.gd — class_name WholeStickmanPreview, extends Control; the assembly preview. Owns per-part position/rotation/scale, Z-order (_part_order), selection + gizmos, grid drawing, and pan/zoom. Public API includes set_body_parts(), set_show_guide(enabled: bool), reset_view(), is_cursor_over_preview(global_pos), and (Phase 9 Round 5) get_guide_joint_preview(joint_name) -> Vector2 — returns the preview-space position of a GUIDE_JOINTS entry via _guide_to_preview(), guarded against unknown names (push_warning + Vector2.ZERO).
  • Phase 7 pose silhouette guide: set_show_guide() stores _show_guide: bool (default true) and redraws; _draw_silhouette_guide() is called in _on_preview_draw() after the part loop and before the drag highlight/selection gizmos, so it renders above the grid and in front of user parts (ghosting over them), below the selection gizmos and drag highlight. The guide is centered at the default view and after Reset Views, computed at draw time from the live preview size via _guide_to_preview() = (master_pos - GUIDE_FIGURE_CENTER) * GUIDE_SCALE + preview_area.size * 0.5, so it also re-centers on window resize; it remains a world-space fixture that moves with pan/zoom. Joint positions are hardcoded constants derived from the master_rig.tscn rest pose (GUIDE_JOINTS: 13 anchors Head/Neck/Shoulders/Elbows/Wrists/Hips/Knees/Ankles; GUIDE_SCALE = 1.0, GUIDE_FIGURE_CENTER = (0, -93.75), GUIDE_HEAD_RADIUS = 100.0). Color-coded: left limbs cyan-blue Color(0.35, 0.70, 1.00), right limbs orange-red Color(1.00, 0.50, 0.20), central spine/head white, with lines at alpha 0.45 and joint dots at alpha 0.65. Joint dots use GUIDE_JOINT_RADIUS / _zoom (6 px constant screen size). The guide is pure drawing — no hit-testing is added, so it never intercepts part dragging/selection.
• scripts/stk_rig_adapter.gd — class_name StkRigAdapter, extends RefCounted; a standalone runtime adapter (Phase 8, not referenced by the editor, extended by Phase 9). static func apply(stk_data, rig) fits an instantiated master_rig.tscn to a loaded .stk dictionary, calling three private helpers in order: _fit_bones (re-fits the 8 limb Bone2D lengths + lower-bone origins, and zeroes the Head driver's local position so the chin sits on the neck joint), _recalibrate_ik (repositions the IK_Targets/Left|Right_Hand and Left|Right_Leg targets), and _mount_shapes (mounts .stk shapes onto the Body/* visual nodes — one node per shape: closed → single Polygon2D, open → single Line2D width 2). The RemoteTransform2D drivers keep their defaults (update_rotation = true), so mounted shapes follow their bones in every pose.
  • Phase 2 (Sandbox) single-shape support: _mount_shapes() reads a part's shapes array when present (v1.2+), and otherwise — when the part dict itself carries points — wraps the whole dict as a single shape (shapes = [pd]), so v1.0/v1.1 single-shape .stk files (e.g. stickmen/test.stk) mount as visible geometry instead of being cleared to nothing.
  • Phase 9 extension: also fits the head bone (Skeleton2D/Torso/Head.position.y = -proportions.torso_length, x preserved) and mounts the head as full geometry like every other part — it clears the Body/Head node's inline @tool circle script via set_script(null) and mounts .stk head shapes as Line2D/Polygon2D. Dead helpers _mount_head_circle, _compute_shapes_bbox, and _first_shape_color were removed.
  • Phase 9 Round 2 bugfix (hanging-convention mount): driver rotation neutralization was removed — the RemoteTransform2D drivers keep update_rotation = true, so each mounted part rotates to follow its bone in every pose (IK flexing included). _mount_shapes() no longer reads the file's pivot/length fields — it recomputes a per-part bounding box at mount time via _compute_part_bbox() (empty bbox → the part is skipped) and derives the mount transform via _compute_mount_transform(), which emits {anchor, scale, theta}: geometry is mounted in the rig's hanging convention (joint anchor at the local origin, far end along local +Y). Anchors: head and torso → bottom-center (cx, max_y) (chin / hip end at the origin); left limbs drawn horizontally → (max_x, cy); right limbs drawn horizontally → (min_x, cy); vertically drawn limbs → top-center (cx, min_y). Alignment rotation θ maps the far end onto local +Y: head 0, torso π (driver π cancels it at rest), left horizontal limbs −π/2, right horizontal limbs +π/2, vertical limbs 0. Scaling is anisotropic — only the auto-detected drawn long axis (width >= height) scales to the bone length (bone_length/extent, guard extent <= 0.0001 → 1.0); the cross axis stays 1:1 (so horizontally-drawn legs become ~200×28, not 101-px bars). _bone_length_for() maps each part to its bone length (upper/lower arm/leg, torso). _map_point() applies (P − J) ⋅ S then q.rotated(θ). The head driver's local position (Skeleton2D/Torso/Head/RemoteTransform2D) is zeroed in _fit_bones() so the mounted head's chin lands on the neck joint. DEFAULT_LINE_WIDTH := 2.0 (was 16.0) matches the editor's 2 px outline. _reset_node_transform() still resets each Body/* container's scale to (1, 1) and rotation to 0 before mounting (position untouched, owned by the driver).
  • Phase 9 Round 3 bugfix (part preview transform + one node per shape): the mount pipeline now composes the part's preview transform E(P) = C + R(rot)·S·(P − C) (scale-then-rotate about the raw bbox center — the editor's exact Whole-Stickman-preview transform) before the hanging-convention mount. _mount_shapes() reads the per-part rotation (degrees, default 0.0) and scale ({x,y}, default (1,1)) from the part dict and applies E to the raw joint end J_raw and far point F_pt_raw (J' = E(J_raw), F' = E(F_pt_raw) − J'). The anchor, alignment θ, and bone-fit scale s are then computed on the transformed geometry: rotations near ±180° (|wrapf(rot)| > 0.75π) swap the attachment to the drawn far end (A = F_pt', V = −F') so flips are visible (e.g. the 180° torso shows its drawn neck end at the hip joint and its hip end at the neck); other rotations keep limbs attached along their bones (a 90° forearm hangs from the elbow with its content turned, exactly as assembled). The bone-fit scale s = bone_length / |V| is measured on the transformed extent so user-scaled parts are not double-fitted. The head mounts upright with θ = 0, s = 1 (a bone-fit scale would double-scale the face), but still applies the part scale through E (face ≈160 px) with the chin at the neck joint and the flip anchor rule still applying. _mount_shape() mounts one node per shape: closed → single Polygon2D (fill only, no paired Line2D outline); open → single Line2D (width 2).
  • Phase 9 Round 4 bugfix (head chin drop): adds const HEAD_CHIN_DROP := 28.0, derived from the editor's pose guide — the head circle (radius 100) is centered at the Head joint (0, −463.5), so its bottom is −363.5; the neck (Head bone origin) is at −391.5, so the chin drops 28 px below the neck. The mounted head points get a Vector2(0.0, 28.0) rig-space translation (offset in _compute_mount_transform() / _map_point(), applied after the part transform and the (θ = 0, s = 1) transform; flip-agnostic — only the head branch sets a non-zero offset). Result: the head's chin lands at world ≈ (0, −363.5), overlapping the torso's top (which ends at −391.5) by 28 px — matching the silhouette guide in the editor.
  • Phase 9 Round 5 guide-offset application: _mount_shapes() reads each part's guide_offset ({x, y}, default absent) and, only when the key is present (old files keep the previous offset-0 behavior and the head falls back to the Round 4 HEAD_CHIN_DROP), applies a node-frame translation t = (guide_offset + (A − C)).rotated(−c_node) where A = the mount anchor already computed (the transformed joint end J', or the transformed far end F_pt' when flipped — Round 3), C = the raw bbox center, and c_node = the part's driver RemoteTransform2D.global_rotation at apply time (read via the reintroduced DRIVER_PATHS const; null-guarded, fallback 0.0). This converts the editor's master-space guide offset into a bone-relative placement so the harness reproduces the guide placement 1:1 (and, for the head — mapped to the guide Neck joint — subsumes the HEAD_CHIN_DROP fallback). t is applied in _map_point() as the final rig-space translation, after E/θ/scale/flip and independent of the flip logic. Re-saving a .stk from the editor populates the offsets.
  • Phase 9 Round 6 bugfix (guide-driven anchor selection): when guide_offset is present, the joint anchor in _compute_mount_transform() is now whichever transformed end (j_prime = E(J_raw) or f_pt_prime = E(F_pt_raw)) is nearest the part's stored guide joint (center − guide_offset): if d_far < d_joint (strict) the far end attaches (anchor = f_pt_prime, v = −f_prime), else the family end (anchor = j_prime, v = f_prime). This replaces the per-side family choice and the 180° flip heuristic for the guide_offset case, fixing the lower left leg (knee now at the joint, was the ankle) and lower right arm (elbow now at the joint, was the wrist), both 180° off their bones because the user's drawn-side conventions are inconsistent per part. The nearest-end rule preserves every previously-correct case and naturally reproduces the 180° flip (a flipped part's far end lands nearest the joint — e.g. the flipped right upper arm shoulder and the flipped torso neck end), plus the head chin (nearest the guide Neck). Old files without the key keep the previous family rules + flip heuristic exactly as before. theta, s, the Round 5 offset t, and the HEAD_CHIN_DROP fallback are unchanged — they consume anchor/v generically. Targets master_rig.tscn node paths; every node lookup is null-guarded (missing node → push_warning + skip, never crash). Consumed by a future runtime pipeline.
• scripts/stickman_rig.gd — class_name StickmanRig, extends Node2D; the runtime owner of facing direction, per-joint bone bend, and Body/* z-order for master_rig.tscn (Phase 9 Task 4). Attached to the Master root node of master_rig.tscn. Non-@tool — node resolution, flag writes, and z-order reordering run only at runtime (_ready + setters on a live instance). Enums FacingProfile { LEFT, RIGHT, FORWARD } (values are the harness facing-menu ids), BendDirection { NORMAL, INVERTED }, and RigState { ANIMATED, RAGDOLL, RECOVERING }. Constants (moved from the harness): SKELETON_PATH, BODY_CONTAINER_PATH, BEND_JOINTS (["LeftArm","RightArm","LeftLeg","RightLeg"]), BEND_JOINT_BONE_PATHS (each joint → its lower Bone2D NodePath relative to Skeleton2D), PROFILE_FLAGS (per-profile flip_bend_direction sets), Z_ORDER_BY_PROFILE (per-profile Body/* draw-order tables, back-to-front). Exports: facing_profile: FacingProfile (default FORWARD, a preset whose setter writes the four per-joint vars, reorders Body/*, and applies a whole-rig Y-axis mirror for LEFT — Master.scale.x = -1; RIGHT/FORWARD (1,1)) and an @export_group("Bend Direction") of four @export_enum("Normal","Inverted") vars left_arm_bend/right_arm_bend/left_leg_bend/right_leg_bend (defaults NORMAL/INVERTED/INVERTED/NORMAL = FORWARD). Recovery exports: rest_timeout (2.0 s), auto_recover (true), plus recovery constants STAND_POSE/IK_TARGET_PATHS/REST_LINEAR_THRESHOLD/REST_ANGULAR_THRESHOLD/ STAND_UP_DURATION/STABILIZATION_DELAY/RAGDOLL_TARGET_SOFTNESS. Signals facing_profile_changed(profile) / bend_flag_changed(joint, flipped). Public API: set_facing_profile/get_facing_profile, set_joint_bend_flipped/get_joint_bend_flipped, get_bend_joints(), and get_bend_joint_global_position(joint) (unknown joint → push_warning + no-op/false/ Vector2.ZERO). _ready() resolves Skeleton2D/Body/4 lower Bone2Ds/4 TwoBoneIK modifications (matched by joint_two_bone2d_node NodePath, never stack index), enables the modification stack (stack.enabled = true), applies the current profile once, then sets _nodes_ready; a _nodes_ready guard makes pre-_ready setters store-only (robust against setter timing during PackedScene.instantiate()). Null-guards + push_warning prefixed "StickmanRig: " throughout; never crashes.
  • Whole-rig Y-axis mirror (replaces _apply_head_flip(), 2026 design change): Facing LEFT is applied as a whole-rig Y-axis mirror — Master.scale.x = -1 (RIGHT/FORWARD → (1,1)) — so the head AND body mirror together and face the correct direction. The old _apply_head_flip() and the Body/Head.scale.x mirror are removed (the Head Pivot node's driver transform is untouched). Per-joint flip_bend_direction flags (PROFILE_FLAGS) and Z_ORDER_BY_PROFILE are kept provisionally (unchanged): the mirror reflects the whole skeleton + IK_Targets + mounted Body/* geometry, while z-order (depth) is unaffected by an X-mirror. walk_to() always plays the canonical walk_right clip (X-mirrored by the root for LEFT; walk_left is no longer used at runtime) and sets the facing profile explicitly. Two head-related fixes under the mirror: the master_rig.tscn head RemoteTransform2D (Skeleton2D/Torso/Head/Pivot) no longer sets update_scale = false — it pushes the full transform like every other Body driver, so Body/Head.scale stays identity under the mirrored root (the old partial-channel push re-canonicalized the scale and caused per-frame Y-flips/wrap-jumps). And _apply_head_lookat_mirror_mode() (called from _apply_profile()) disables the head SkeletonModification2DLookAt when facing LEFT and pins the head bone rotation to the FORWARD canonical aim (π); _pin_mirrored_head_rotation() re-asserts that pin each _physics_process frame while ANIMATED/RECOVERING so recovery's stack re-arm can't let LookAt flip the bone. RIGHT/FORWARD re-enable the LookAt. Consequence: interactive head-aiming while facing LEFT is intentionally static.
  • Phase 10 ragdoll state system: StickmanRig owns a reversible ANIMATED ⇄ RAGDOLL physics mode switch plus a RECOVERING stand-up state. enum RigState { ANIMATED, RAGDOLL, RECOVERING }, var state: RigState (default ANIMATED), signal state_changed(new_state: int), and public API set_ragdoll(enabled: bool) / toggle_ragdoll() / is_in_ragdoll() -> bool / request_recovery() / snap_to_standing() (Phase 2 Sandbox: instantly destroys the ragdoll or cancels the recovery tween, sets the 6 IK targets directly to STAND_POSE, re-shows Body/*, re-enables IK, and returns to ANIMATED with no stand-up glide). _physics_process() → _track_momentum(delta) caches the rig root's linear/angular velocity from per-frame global_position/global_rotation deltas, then drives _update_rest_detection() (auto-recovery trigger). _enter_ragdoll() stop(true)s the AnimationPlayer (ANIMATION_PLAYER_PATH const, keep_state — no pose reset), builds the ragdoll from the CURRENT solved bone positions while the IK stack is still enabled (disabling it first would revert the bones to the authored rest pose, popping the figure), then hides Body/* and disables the IK stack immediately — an instant handoff with no crossfade (the ragdoll spawns at exactly the same pose, so a fade would only read as ghosting), sets state = RAGDOLL + emits. _build_ragdoll() creates a Node2D container "RagdollBodyContainer" under the rig's parent (world root; fallback get_tree().current_scene) and populates it from the RAGDOLL_BODIES table (10 RigidBody2D: torso CapsuleShape2D radius 12 mass 8.0, head CircleShape2D radius 100 mass 2.0, limb capsules radius 8 masses 1.0–2.0; collision_layer/collision_mask = 1, bodies spawn fully visible) and the RAGDOLL_JOINTS table (9 PinJoint2D, one per non-root body pinned at the child bone's origin, softness = RAGDOLL_TARGET_SOFTNESS at build). Angular limits via _apply_ragdoll_joint_limits(): elbow_knee folds +CW -5°..+150°, elbow_knee_ccw -150°..+5°, shoulder_hip ±160°, default (neck) free. Cached momentum is applied to the torso body. apply_ragdoll_velocity_boost(velocity) applies the same velocity delta (mass-scaled apply_central_impulse) to every ragdoll body — used by the harness "Knock Up" button. All ragdoll nodes are spawned procedurally — master_rig.tscn is not modified.
  • Phase 11 instant handoff + recovery: _update_rest_detection() (only when state == RAGDOLL) reads _ragdoll_bodies["torso"]: when its linear/angular velocity drops below REST_LINEAR_THRESHOLD/REST_ANGULAR_THRESHOLD it accumulates _rest_timer; after rest_timeout (and a STABILIZATION_DELAY hold) with auto_recover on it calls _start_recovery(). _start_recovery() (also request_recovery(), no-op unless in RAGDOLL) captures the 10 bodies' rig-local {pos, rot, half} into _captured_pose (half = each capsule's half-length from build-time metadata) plus a landing anchor (_captured_landing_center = the ragdoll torso's world center, _captured_ground_y = torso.center.y + RAGDOLL_TORSO_RADIUS), _reanchor_root_to_landing()s (translates the rig root so the standing figure's feet sit on the ground at the landing X — feet = (_captured_landing_center.x, _captured_ground_y), new_root = feet + FOOT_OFFSET — and re-bases the captured rig-local positions by the root shift; the figure stands up in place, on the ground, where the ragdoll landed, since the ragdoll bodies live under a world sibling and the root never moved while it fell), _destroy_ragdoll()s, sets state = RECOVERING + emits, then _snap_skeleton_to_pose() — a marker-driven snap writing IK_Targets/Torso.position/.rotation, IK_Targets/Head.position, and the 4 limb markers (never the slaved Torso Bone2D), re-showing Body/*, then calling _rearm_ik_stack() — a defensive re-setup (re-sets up the SkeletonModificationStack2D when it reports !get_is_setup(), re-asserts enabled = true and Skeleton2D.set_process_internal(true), and re-asserts the Torso marker's RemoteTransform2D update-position/rotation/scale flags) so the stack reliably resumes solving toward the end-effectors after a disable→enable toggle. Runtime diagnosis of the re-arm is gated behind const DEBUG_RECOVERY := false (off by default; _recovery_dbg() traces stack enabled/setup/internal + bone-following state). Snap geometry: the ragdoll capsules span joint origin→tip along their +X, so the hip is derived as torso.pos − spine_dir·half and the wrist/ankle targets as lower_body.pos + dir·half; the Torso marker rotation subtracts the Torso Bone2D's bone_angle (bone world angle = marker rotation + bone_angle — copying the body rotation directly would slam the skeleton −90° and lay it flat). _play_stand_up() then tweens the 6 markers directly from their captured values to STAND_POSE over STAND_UP_DURATION (2.0 s, sine ease-in-out, _tween_markers_to()); the baked "stand_up" animation is not played (a fixed first keyframe can never match an arbitrary ragdoll rest pose, so recovery starts from wherever the snap left the markers). On tween finish _on_stand_up_finished() re-enables IK, re-shows Body/*, sets state = ANIMATED, and emits. Interruptible: set_ragdoll(true) during RECOVERING kills the stand-up tween and rebuilds the ragdoll; set_ragdoll(false) during RAGDOLL routes through _start_recovery(); repeated set_ragdoll calls are idempotent. is_in_ragdoll() stays state == RigState.RAGDOLL (so RECOVERING reads as "Stickman").
  • Phase 3a director functionality: adds navigation/walking, speech, an action queue, and a queue-runner state machine. Enums RunnerState { IDLE, EXECUTING } and ActionPhase { NONE, WALKING, SPEAKING, WAITING, RAGDOLLING, RECOVERING }. Constants FOOT_OFFSET := (0, -385) (feet → root; matches StageSpawner.STICKMAN_FOOT_OFFSET), NAV_AGENT_LOCAL_POS := (0, 385) (== -FOOT_OFFSET), ARRIVE_DISTANCE / NAV_PATH_DESIRED_DISTANCE / NAV_TARGET_DESIRED_DISTANCE / SPEECH_BUBBLE_OFFSET. New signals arrived, action_started(action, index), action_finished(action, index), queue_finished (on completion, not stop), queue_changed (any queue mutation), speech_finished. Exports walk_speed (300.0). Public API: walk_to( target, speed = -1.0) (feet/ground destination; no-op unless state == ANIMATED), is_walking(), speak(text, duration) (lazily creates a SpeechBubble child at SPEECH_BUBBLE_OFFSET, auto-hides
    • emits speech_finished), the queue API queue_action / clear_queue / get_queue / remove_action / insert_action / queue_size (all mutations emit queue_changed), and the runner API start_queue / stop_queue / is_queue_running. _ready() builds a NavigationAgent2D child at NAV_AGENT_LOCAL_POS (feet, on the ground-level nav mesh; avoidance_enabled = false, max_speed = walk_speed, shared default nav map layer 1). A _physics_process ordering of _track_momentum → _update_rest_detection → _update_walking → _update_speech → _update_runner drives the runner state machine per ActionPhase (walk_to → wait for _walk_done; speak → wait for !_speech_active; wait → _phase_timer countdown; ragdoll → set_ragdoll(true) then wait is_ragdoll_at_rest(); recover → request_recovery() then wait state == ANIMATED). is_ragdoll_at_rest() is a new public query exposing the rest result regardless of auto_recover (the runner polls it; auto-recovery logic is unchanged). _enter_ragdoll() additionally calls _cancel_walking() (no stale walk/path state) and resets _ragdoll_at_rest = false. Walk fix (2026-08-29, hybrid policy): _update_walking defers all nav reads until NavigationServer2D.map_get_iteration_id(...) != 0 (map-sync guard), forces the path query via get_next_path_position() before any empty-path / finished check (the read-only get_current_navigation_path() alone never triggers a repath), then branches on is_target_reachable(): an on-mesh target follows the nav path (_walk_mode = "nav"), while an off-mesh/unreachable target switches to direct straight-line steering toward the clicked waypoint (_walk_mode = "direct", root target = waypoint + FOOT_OFFSET) — a supported case with no push_warning (the old "warn + finish in place" policy was replaced; the rig never stands still at a waypoint). There is no _walk_path_grace variable (the map-sync guard + forced path query replace it) and no unreachable warning; the debug trace now carries a mode=nav|direct field. Off-by-default diagnostics: DEBUG_WALK + _walk_dbg() (rig) and DEBUG_STAGE + _stage_dbg() (sandbox_stage). Walking is kinematic (global_position.move_toward); movement composes with the canonical walk_right in-place limb animation, played for every direction — X-mirrored by the rig root for LEFT (facing is set explicitly by walk_to()/set_facing_profile(); walk_left is no longer used at runtime and the animation .:facing_profile tracks are neutralized/removed).
  • Phase 4 triggers: the arrived signal gained a target: Vector2 payload (emits _walk_target_feet) so the stage can match waypoints for arrived_at_waypoint rules; new enqueue_reactive(actions: Array[Dictionary]) -> void appends reactive actions to the action queue and, if the runner is IDLE, resumes at the first newly-appended action (no replay of the already-consumed queue prefix). Sequential Phase 3a queues are untouched.
• scripts/stickman_factory.gd — class_name StickmanFactory, extends RefCounted; a static factory and the runtime entry point (Phase 9, not used by the editor) that turns a .stk file into a live, rigged master_rig.tscn instance:
  • static func load_stk(path: String) -> Dictionary — reads a .stk file (FileAccess + JSON.parse_string); returns {} + push_warning on failure.
  • static func spawn_from_data(stk_data: Dictionary) -> StickmanRig — instantiates res://master_rig.tscn, calls StkRigAdapter.apply(stk_data, rig), returns the rig root (typed as StickmanRig since the rig now carries the StickmanRig root script).
  • static func spawn(path: String) -> StickmanRig — load_stk() then spawn_from_data(); returns null on empty data.
• scripts/create_animations.gd — @tool extends EditorScript; a standalone editor utility (run manually with master_rig.tscn open, not auto-loaded or referenced at runtime). Supersedes the deleted scripts/create_walk.gd. _run() bakes walk_left/walk_right (same keyframes as the old script, via _generate_walk_animation()) and a one-shot stand_up (via _generate_pose_animation(), STAND_UP_DURATION = 2.0, loop_mode = LOOP_NONE) into the open scene's default AnimationLibrary. stand_up keys the 6 IK_Targets/*:position tracks plus a IK_Targets/Torso:rotation track from POSE_DOWN (a generic "lying on back" pose) to POSE_STANDING (matching master_rig.tscn defaults), with POSE_PATHS/POSE_MARKERS consts. The baked stand_up is an authored reference only — runtime recovery does not play it (StickmanRig tweens the IK targets directly from the captured ragdoll pose).
• scripts/test_harness.gd — standalone staging scene (Phase 9, not wired into the editor; run via F6 on res://scenes/test_harness.tscn) for debugging bone scales, vector drawing offsets, and IK limits in isolation. Top UI bar: "Open .stk…" button → FileDialog (*.stk); quick-select buttons for stickmen/break.stk, stickmen/basic.stk, stickmen/test.stk; "Show Bones" / "Show IK Handles" checkboxes; a status label showing the loaded filename. Viewport: SubViewportContainer → SubViewport → world Node2D + enabled Camera2D; middle-mouse pan, mouse-wheel zoom, camera recenters on each spawn. Each load frees the previous rig and spawns a fresh one via StickmanFactory.spawn(). Debug overlay (a world-space Node2D _draw()): true bone segments (a joint dot at each Bone2D origin + a parent→child line to each Bone2D child, color-coded left cyan / right orange / central white) with leaf bones drawn out to their IK targets (LeftLowerArm→Left_Hand, RightLowerArm→Right_Hand, LeftLowerLeg→Left_Leg, RightLowerLeg→Right_Leg) so wrist/ankle joints are visible (Phase 9 Round 2; previously only origin→parent-origin lines were drawn). The Head leaf is the exception (Phase 9 Round 3): its IK target is a SkeletonModification2DLookAt aim point, not a joint, so it is not in LEAF_BONE_IK_PATHS and the no-target fallback draws a ~90 px segment along the bone's own direction (Vector2(length, 0) rotated by bone_angle then global_rotation) instead of a line to the aim point; colored markers at IK_Targets/{Left_Hand,Right_Hand,Left_Leg,Right_Leg} when "Show IK Handles" is on. Interactive IK: click-drag the Marker2D IK targets; the scene's SkeletonModificationStack2D TwoBoneIK flexes limbs live (the rig self-enables its modification stack in _ready()).
  • Phase 9 Round 7 draggable Torso & Head handles: IK_HANDLE_PATHS now has 6 entries — the 4 limb targets plus "Head" (IK_Targets/Head, the SkeletonModification2DLookAt aim point) and "Torso" (IK_Targets/Torso, whose child RemoteTransform2D moves the hip bone). Dragging the Torso handle translates bones only (no target following) — the marker's RemoteTransform2D moves the hip bone and the whole skeleton + Body/* visuals follow rigidly, while the limb/head targets stay put (dragging the figure away from them stretches the limbs toward the stationary targets, per user decision). Dragging the Head handle drives the Head bone's LookAt rotation (clamped at the authored ~55° constraint); Body/Head follows. _handle_color() colors the head marker yellow (HANDLE_COLOR_HEAD) and the torso marker magenta (HANDLE_COLOR_TORSO); hands stay green, feet blue. The IK overlay also draws a null-guarded semi-transparent yellow aim line from the Head bone origin to the head marker (_draw_ik_handles, width 1.5/zoom, alpha 0.5) — a visual aid for the LookAt test.
  • Phase 9 Task 1 skeleton IK bone switches: adds a "Facing" MenuButton (leftmost control in the top-bar HBox) and per-joint bend-direction toggles for the rig's TwoBoneIK "Flip Bend Direction" flags. The facing profile, the per-joint bend flags, and the Body/* z-order tables now live in the StickmanRig script (Phase 9 Task 4) — the harness drives the rig via _rig_script: StickmanRig (typed root from StickmanFactory.spawn(); signals connected before add_child) and keeps _facing_profile (default FORWARD) only as a UI mirror for the [√] menu prefix + respawn re-application; the rig's exported facing_profile is the authority. Menu item ids are StickmanRig.FacingProfile.LEFT/RIGHT/FORWARD (values used directly as menu item ids). State _context_joint, _facing_button/_facing_menu, _context_menu. The Facing popup (Left/Right/Forward) uses dynamic text-only labels with the current profile prefixed [√] , refreshed on about_to_popup and after selection (mirroring the editor's snap-menu pattern); selection calls _rig_script.set_facing_profile(id). Hit-test for the right-click toggle iterates _rig_script.get_bend_joints() with positions from _rig_script.get_bend_joint_global_position(joint). Per-joint toggle: right-click inside the viewport on an elbow/knee (the upper↔lower limb connector, within JOINT_HIT_RADIUS_PX := 14.0 screen px converted to world by _camera.zoom.x, nearest joint wins) pops a one-item context menu labeled "Normal Bend" (when the rig's get_joint_bend_flipped(joint) is true) or "Invert Bend" (when false); selecting calls _rig_script.set_joint_bend_flipped(_context_joint, not _rig_script.get_joint_bend_flipped(_context_joint)). Only the 4 elbows/knees are right-click targets — shoulders/hips/wrists/ankles/head/torso are not. Lifecycle: _free_current_rig() clears _rig_script (and _context_joint); _load_and_spawn() captures the remembered profile before add_child (so the rig's _ready() facing_profile_changed(FORWARD) doesn't clobber the mirror) then re-applies _rig_script.set_facing_profile(remembered_profile) after _resolve_rig_nodes(). The rig enables its own modification stack in _ready(). No persistence to disk.
  • Phase 9 Task 2 body-part z-order: the rig's _apply_profile() reorders the rig's Body/* visual part nodes (tree order = draw order) from the Facing profile; Z_ORDER_BY_PROFILE (now owned by StickmanRig) maps each FacingProfile to the Body/* part node names in back-to-front draw order (Godot 4 Node2D draws siblings in tree order; all parts keep z_index = 0). FORWARD: torso → left/right upper legs → left/right lower legs → left/right upper arms → left/right lower arms → head (all limbs in front of the torso); LEFT: left arm pair then left leg pair behind the torso, right leg pair then right arm pair in front; RIGHT: mirrored. In every profile upper limbs stay behind lower limbs; far-side (behind-torso) arms draw behind the legs while near-side arms draw in front of the legs; the head is always frontmost. The rig's _apply_body_z_order() walks the profile array back-to-front and move_child(part, count - 1)s each existing child (missing parts skipped), which yields the profile order; unknown extra children stay at the back. Safe with the adapter: shapes are children of the part nodes, so moving a part moves its whole shape group. No persistence to disk.
  • Phase 9 Task 3 coordinates display: adds a "Show Coords" CheckBox in the top-bar HBox (after "Show IK Handles", before the status label), default ON, toggled via _on_show_coords_toggled(pressed) (sets _show_coords: bool = true, flips _coords_panel.visible). A code-built right-side readout (_build_coords_panel(), called from _build_ui() after the viewport container so it renders in front): _coords_panel (PanelContainer) + monospace selectable _coords_label (RichTextLabel, selection_enabled + context_menu_enabled + fit_content, autowrap off, scroll off, FOCUS_CLICK; SystemFont: Consolas/Menlo/DejaVu Sans Mono/Courier New via the normal_font/normal_font_size (18) theme overrides), anchored PRESET_TOP_RIGHT, offset_top = 40.0, offset_right = -8.0, offset_left = -COORDS_PANEL_WIDTH (320.0), grow_vertical = GROW_DIRECTION_END + grow_horizontal = GROW_DIRECTION_BEGIN (auto-height/width, grows left so text never runs off-screen), mouse_filter = MOUSE_FILTER_IGNORE on the panel (the label itself stays interactive for selection); StyleBoxFlat bg Color(0,0,0,0.55), border Color(1,1,1,0.12) w1, corner radius 4, content margin 8. Consts COORDS_PANEL_WIDTH := 320.0 and COORD_BONE_PATHS (10 Skeleton2D-relative bone paths: Torso, Torso/Head, both upper/lower arms, both upper/lower legs). State _coord_bones: Dictionary (bone display name → Bone2D, keyed by path.get_file()), _show_coords. _resolve_rig_nodes() calls _resolve_coord_bones() (via _skeleton.get_node_or_null, push_warning on missing); _free_current_rig() clears _coord_bones (toggle persists across respawns). _process(delta) early-outs when hidden or label null, else _update_coords_display() — sections "Skeleton2D" pos + rot deg, "Bones" pos + rot deg, "IK Targets" pos only (reusing IK_HANDLE_PATHS/_ik_handles); "No rig loaded" fallback; every read guarded with is_instance_valid; the label text is only reassigned when the built string changes, so an active text selection survives idle frames. Values are world-space (global_position/global_rotation), rotation in degrees via _fmt_deg(rad) (1 decimal, °), _fmt_vec2(v) for positions. No persistence to disk.
  • Phase 9 Task 5 rig animation: adds top-bar controls immediately after the "Facing" menu — an _anim_dropdown OptionButton populated per spawn from AnimationPlayer.get_animation_list() (preferring walk_right via DEFAULT_ANIMATION), a _play_button whose label swaps "Play"/"Pause"/"Resume" by _playback_state, a _stop_button (Stop), and a _loop_check CheckBox default ON (harness-level, persists across respawns like _show_coords). The harness resolves the rig's AnimationPlayer directly by node path via the ANIMATION_PLAYER_PATH const (_resolve_anim_player(), called at the end of _resolve_rig_nodes()) and drives it directly; the AnimationTree node remains an untouched unconfigured placeholder (out of scope, D1). Loop is implemented by writing Animation.loop_mode (LOOP_LINEAR/LOOP_NONE) on the selected animation before each play (_apply_loop_mode()); playback state is tracked by the enum PlaybackState {STOPPED, PLAYING, PAUSED} via the button handlers + the animation_finished signal (guarded by _loop) — no polling in _process. Changing the dropdown selection stops playback; _free_current_rig() clears _anim_player, the dropdown, _selected_animation, and state. The animation .:facing_profile tracks are neutralized/removed — facing is now set explicitly via set_facing_profile() / walk_to() (which sets LEFT/RIGHT from the walk direction and root-mirrors for LEFT), so playing walk_right no longer flips the rig's profile through an animation track. No persistence to disk. The "Facing" menu and all animation controls are hidden until an .stk is loaded (_set_rig_controls_visible(false) at the end of _build_ui() and in _free_current_rig(); shown on successful spawn in _load_and_spawn()).
• scripts/terrain_block.gd — class_name TerrainBlock, extends StaticBody2D; a reusable vector terrain component (Vector Terrain System, not used by the editor). Builds its three children in code: Polygon2D (interior fill, fill_color), Line2D (crisp vector border, outline_color/outline_width, auto-closed loop by appending the first vertex to the end, LINE_JOINT_ROUND + round caps), and CollisionPolygon2D (BUILD_SOLIDS solid decomposition — supports concave blocks). Exported properties: polygon_points: PackedVector2Array, fill_color, outline_color, outline_width; a unified setter pushes vertex changes to all three children live (no manual rebuilds).
• scripts/terrain_utils.gd — class_name TerrainUtils, extends RefCounted; static utility (not used by the editor):
  • sanitize_points(points: PackedVector2Array, grid_size: float = 16.0) -> PackedVector2Array — sanitization pipeline in order: grid snap → redundancy removal via a local _simplify_polyline() (Godot 4.7 has no Geometry2D.simplify_polyline(); the local version drops consecutive duplicates, a closing duplicate when last == first, and collinear vertices) → clockwise enforcement via Geometry2D.is_polygon_clockwise() (reverses if false, guaranteeing clockwise output).
  • spawn_block(...) — factory that sanitizes raw input vectors (sanitize_points), creates a TerrainBlock, applies the cleaned points, and adds it to the target container.
• scripts/prop_block.gd — class_name PropBlock, extends RigidBody2D; a reusable dynamic vector prop component (Dynamic Vector Props, not used by the editor), @tool. Builds its children in code: Polygon2D (interior fill, fill_color), Line2D (crisp vector outline, outline_color/outline_width, auto-closed loop by appending the first vertex, LINE_JOINT_ROUND + LINE_CAP_ROUND), and a collision node — CollisionPolygon2D (BUILD_SOLIDS) in POLYGON mode, or CollisionShape2D + CircleShape2D (48-segment radial loop, CIRCLE_SEGMENTS = 48) in CIRCLE mode, toggled via shape_type. Exported properties: shape_type (@export_enum("Polygon","Circle")), polygon_points: PackedVector2Array, radius: float, fill_color, outline_color, outline_width, and material_preset (@export_enum("None","Wood","Rubber","Cardboard","Metal")). Presets set mass + physics_material_override via static mass_for()/physics_material()/tint_for() (Wood: mass 3.0, friction 0.6, bounce 0.1; Rubber: mass 0.5, friction 0.9, bounce 0.85; Cardboard: mass 0.4, friction 0.3, bounce 0.05; Metal: mass 8.0, friction 0.9, bounce 0.0; None: mass 1.0, friction 0.5, bounce 0.05) and recolor fill/outline for non-NONE. Unified live-update setters push geometry/color changes to all children (null-guarded for @tool editor safety); _apply_shape() enables exactly one collision node.
  • Phase 4 collision signal: new signal collided(other: Node); _ready() sets contact_monitor = true, max_contacts_reported = 8, and connects the guarded body_entered signal → _on_body_entered → collided.emit(body), so prop-vs-prop collisions are reported by the physics engine (the stage's geometric feet-point test covers stickman-vs-prop separately).
• scripts/trigger_area.gd — class_name TriggerArea, extends Node2D; a placeable sensor (Phase 4, not used by the editor). @export size: Vector2 (default 96×96), get_area_rect() -> Rect2 (centered on the node's global position), and _draw() (translucent green fill + dashed border). No physics and no signals — it is a pure geometric region evaluated by sandbox_stage.gd's event engine (_update_area_entry) for entered_area rules.
• scripts/prop_utils.gd — class_name PropUtils, extends RefCounted; static factory (not used by the editor):
  • create_box(size := Vector2(48,48)) / create_ball(radius := 24.0) / create_plank(length := 160.0, thickness := 16.0) / create_triangle(base := 56.0, height := 48.0) — primitive generators returning shape-payload dictionaries with default dimensions + color themes (wood/rubber/metal/cardboard).
  • spawn_prop(container, position, shape_payload, material_preset := WOOD, initial_velocity := Vector2.ZERO) -> PropBlock — instantiates a PropBlock, applies the payload (shape_type + geometry + colors via _apply_shape_payload(), sanitizing polygon points through TerrainUtils.sanitize_points()), sets linear_velocity after add_child (only when non-zero), and returns the spawned prop.
• scripts/physics_test_harness.gd — class_name PhysicsTestHarness, extends Node2D; standalone staging scene root (Vector Terrain System / Dynamic Vector Props, not wired into the editor; run via F6 on res://scenes/physics_test_harness.tscn). Builds flat ground, angled ramps, and stepped TerrainBlock instances via TerrainUtils, instantiates res://master_rig.tscn standing on the flat ground, and handles camera input. A top-bar UI (_build_ui(), a CanvasLayer + PanelContainer matching test_harness's style) replaces the old key bindings: Spawn Crate / Spawn Ball / Spawn Plank buttons spawn dynamic props above the angled ramp via PropUtils.spawn_prop() (PROP_SPAWN_POSITION = (300, -300): Wood Crate (create_box(), WOOD, velocity (60,0)), Bouncy Ball (create_ball(), RUBBER, (-80,0)), Heavy Plank (create_plank(), METAL, (30,-40)). Adds a best-effort StaticBody2D collision proxy (RigCollisionProxy, _add_rig_collision_proxy()) since the rig has no physics bodies of its own — a 240×1000 px RectangleShape2D centered at (0,-500) ( RIG_PROXY_SIZE/RIG_PROXY_CENTER) matching the standing figure's world bounds, so props bounce/rest against it; the proxy is a code-only stand-in, not part of the rig.
  • Phase 10 ragdoll trigger: the harness stores the spawned rig in _rig: StickmanRig and shows a toggle-mode Button (_ragdoll_toggle) whose text flips "Stickman" ↔ "Ragdoll" (_update_ragdoll_toggle(), set_pressed_no_signal keeps the label in sync without retriggering). Toggling calls _rig.set_ragdoll(pressed), then on entry calls _remove_rig_collision_proxy() (the ragdoll collides directly with the terrain) and on exit _add_rig_collision_proxy(). _add_rig_collision_proxy() is idempotent — it first _find_rig_collision_proxy() (a direct child named "RigCollisionProxy") and returns early if one exists, so rapid toggling leaves no duplicate proxies.
  • Phase 10 external forces: a "Knock Up" button (_knock_up()) tests impulses beyond gravity: when the rig is in RAGDOLL mode it calls StickmanRig.apply_ragdoll_velocity_boost( KNOCK_UP_VELOCITY = (0, -450)) (mass-scaled apply_central_impulse on every ragdoll body, preserving internal structure), and applies the same upward velocity delta to every dynamic prop (RigidBody2D child of _environment) so the whole pile flies up together.
  • Phase 11 recovery UI: a Label("Rest") + SpinBox (_rest_timeout_spinbox, min 0.1 / max 10.0 / step 0.1, initialized to _rig.rest_timeout after _build_ui) and a "Recover Now" button (_recover_now() → _rig.request_recovery()) are added after the "Knock Up" button. _on_rest_timeout_changed(v) writes _rig.rest_timeout = v (runtime-only, no settings.json). _spawn_rig() connects _rig.state_changed → _on_rig_state_changed(), which removes the collision proxy on RAGDOLL, re-adds it on ANIMATED/RECOVERING, and always _update_ragdoll_toggle() (proxy helpers are idempotent, so the toggle handler's own add/remove is harmless). The toggle label reads "Stickman" during RECOVERING (since is_in_ragdoll() is false).
• scripts/sandbox_stage.gd — class_name SandboxStage, extends Node2D; the Sandbox Stage Builder root controller (Phase 2, not wired into the editor; run via F6 on res://scenes/sandbox_stage.tscn). Owns the EDIT/PLAY mode state machine, placement mode, camera pan/zoom, deletion, status bar, and signal fan-out; instantiates StageSpawner / StageSelection / StageGizmos (via preload consts). enum StageMode { EDIT, PLAY } (default EDIT). EDIT freezes RigidBody2D props with freeze = true + freeze_mode = RigidBody2D.FREEZE_MODE_KINEMATIC (script-driven gizmo dragging needs KINEMATIC, not STATIC) and keeps StickmanRigs ANIMATED (set_ragdoll(false) runs first); PLAY unfreezes props and ragdolls stickmen with auto_recover = false. Signals mode_changed(mode), object_placed(node), object_selected(nodes), object_deselected(), object_deleted(nodes). Camera: middle-mouse pan, wheel zoom clamped to @export min_zoom / max_zoom (0.1 / 6.0); mouse→world via _camera.get_global_mouse_position() (no SubViewport). _world_children_selectable() returns direct Node2D children of World excluding RagdollBodyContainer. Authored-state / restart-the-sim: _authored (instance id → {node, position, rotation}) is updated at edit time on every place (_place_at → _save_object_state) and move/rotate (transform_committed → _on_transform_committed), and cleared on delete (_clear_object_state). _enter_edit_mode() stands stickmen, then freezes every prop (freeze_mode = FREEZE_MODE_KINEMATIC before freeze = true, so the body freezes directly as kinematic — never via the static layer, whose transform sync drops a subsequent position set), then _restore_authored_state() teleports via global_position/global_rotation + zeroed velocity. Because the freeze+teleport can take a physics frame or two to settle, _restore_authored_state() is also re-asserted over the next few _physics_process frames (_restore_frames_left) — so every Play session starts from and returns to the same authored state. Placement ghost: while a palette item is active, set_placement_mode(id) spawns a translucent (modulate.a = 0.5), non-colliding (collision_layer/mask = 0, frozen) copy of the object reparented out of World into _ghost_holder; _process() tracks it to the cursor (+ snap) via _update_ghost_position(), and _place_at() re-spawns it after each placement. A ghost stickman has its Skeleton2D modification stack disabled and its AnimationPlayer stopped so it renders as a static standing figure (its limbs don't flex/follow the cursor). Grid/snap: an optional StageGrid overlay (drawn behind World) plus Grid/Snap CheckBox toggles and a Size SpinBox, persisted to user://sandbox_settings.json (grid_size/snap_to_grid/show_grid); snapping rounds the placement cursor and translate drags via _snap_to_grid() / StageGizmos.snap_size. The grid is visible only in EDIT mode (_apply_grid_settings() sets _grid.visible = _show_grid and current_mode == EDIT, re-applied on mode change). Touchpad: _input handles InputEventMagnifyGesture (pinch zoom ×factor) and InputEventPanGesture (two-finger pan, delta × 3 / zoom) alongside the mouse wheel/middle pan. UI built in code (CanvasLayer + PanelContainer top bar): mode toggle, six palette buttons (built from the spawner registry), Grid/Snap/Size controls, status label. The build controls (spawn palette + Grid/Snap/Size) are hidden in PLAY via _set_build_controls_visible(), called from _enter_edit_mode() / _enter_play_mode() (the mode toggle and status label stay visible).
  • Phase 3a director tool: adds a "Direct" palette toggle button (mutually exclusive with placement) and a PopupMenu (_action_popup, items Walk To/Speak/Wait/Ragdoll/Recover, ids ACT_WALK…ACT_RECOVER) opened by clicking a stickman (_handle_direct_click); the popup is positioned at the clicked stickman's world position converted to screen (_world_to_screen(world_pos)) offset 24 px right, not at the mouse cursor (this first menu also records the session popup anchor for the Phase 4 rule-builder child menus); speak/wait AcceptDialogs append speak/wait actions; Walk To enters a pending target-capture mode whose next stage click appends {"type":"walk_to","target":world_pos} and which Esc cancels (Esc priority: pending target → exit direct mode → existing placement clears). Builds a code-built NavigationRegion2D (_build_navigation(), child of the stage not World so it is never hit-tested) carrying a procedural NavigationPolygon from per-TerrainBlock convex decomposition (_rebake_navigation(), Geometry2D.decompose_polygon_in_convex + fan triangulation, world-space via block.transform * p); a _nav_dirty flag re-bakes once per frame (_process) on terrain place / move / rotate (transform_committed) / delete. Instantiates a StageDirectorVisuals overlay (_build_director_visuals()). Play mode change (D3): _enter_play_mode() no longer auto-ragdolls stickmen — it now sets each rig auto_recover = false and calls start_queue(); ragdoll/recover are explicit queue actions; props still unfreeze. _enter_edit_mode() stop_queue()s then snap_to_standing()s stickmen and re-enables the visuals. Wires node.queue_changed → _director_visuals.mark_dirty when a stickman is placed; object_deleted → mark_dirty(). _set_build_controls_visible() also hides the Direct button in PLAY.
  • Phase 4 triggers & event system: adds a When→Then rule system — _event_rules: Array[Dictionary] of {id, trigger, actions} rules (trigger types: arrived_at_waypoint, action_finished, speech_finished, entered_area, collided; action types reuse the Phase 3a set: walk_to/speak/wait/ragdoll/recover). Rules persist across Play/Edit mode toggles but are not saved to disk (Phase 5). A geometric event engine runs in PLAY (_update_area_entry tests a movable's feet/position against each TriggerArea.get_area_rect(); _update_stickman_prop_collision tests a stickman's feet point against prop AABBs and vice-versa), with edge-triggered dicts (already-fired events) reset on mode entry. A rule-builder UI state machine (RuleStep enum: IDLE, SELECT_TRIGGER, TRIGGER_TARGET, SELECT_ACTION, ACTION_TARGET, ACTION_POSITION, PARAMS) is driven from a "⚡ When..." item in the Direct action popup: trigger sub-menu popup → trigger-target click → rule-action popup → target/position → "Add another action / Done" popup. Esc has highest priority; status-bar hints + toast messages guide the flow. Rule label click → consequence-only edit (replaces the rule, same id); ✕ deletes; _cleanup_rules_for_nodes auto-removes rules referencing deleted objects. All rule-builder context popups are session-anchored: the first popup in a session records its screen position (_popup_anchor / _popup_anchor_set; the Direct first menu = right of the clicked stickman, the rule-label edit entry = the click position), and every child popup in the session — "⚡ When…" trigger sub-menu, rule-action popup, "⬅ Back to actions", "Add another action" — reuses that recorded position via _set_popup_anchor(rect) / _popup_anchor_rect(), so cycling the menus never walks down the screen at the live cursor. The anchor is cleared on confirm (_finalize_rule), cancel (_cancel_rule_build), or Direct-mode/flow exit (_clear_director_pending), but not by _reset_rule_builder() (the Back-to-actions path intentionally reuses it).
  • Phase 3b asset-library selector integration: the Stickman and Prop palette buttons no longer place directly — pressing them opens a modal selector grid (_selector: AssetSelector, an instantiated scenes/asset_selector.tscn PopupPanel, added to the UI CanvasLayer in _build_ui() with theme/font overrides applied via AssetSelector.apply_font), backed by a dim backdrop _selector_dim (a black ColorRect at SELECTOR_DIM_ALPHA = 0.5, mouse_filter = MOUSE_FILTER_IGNORE, on the UI CanvasLayer behind the selector, shown only while the selector is open). State _selector_open/_selector_kind, _thumbnail_queue, _thumbnail_busy. _ready() builds _stickman_library/_thumbnail_cache and the two thumbnail renderer Nodes (_stickman_thumb/_prop_thumb, added as children so they can await), plus a Browse _browse_dialog FileDialog (*.stk). _on_palette_toggled routes stickman/prop presses to _open_selector(id) (which forces the palette button pressed, rescans entries, performs the single-item skip for a lone stickman file, and — when the selected path is absent from the scan — reselects the first entry); its un-press branch closes a matching open selector. _on_asset_selected(entry) writes the selection to StageSpawner (selected_stickman_path / selected_prop_id), closes the selector, and calls set_placement_mode(kind); _close_selector() also clears _thumbnail_queue (it flips _selector_open off before hiding the popup). _on_selector_cancelled() closes + exits placement (un-presses the palette button); the selector's popup_hide signal is also routed to _on_selector_cancelled() (idempotency-guarded), so an outside-click close likewise un-presses the palette button. _on_browse_file_selected builds an ad-hoc entry via StickmanLibrary.make_entry(path) (toast on failure); _on_refresh_requested rescans + re-enqueues. Lazy thumbnail drain: _load_or_enqueue_thumbnails seeds the selector from any cached PNG and enqueues the rest; _process → _drain_thumbnail_queue() renders one per frame (awaits the renderer, save_pngs it, hands the texture back via _selector.set_thumbnail while the selector is open). The selector re-centers on window resize (the root AssetSelector re-runs popup_centered() on size_changed while visible). Esc priority inserts the selector before DIRECT/placement in _unhandled_key_input; _handle_world_click / _handle_mouse_motion early-return while _selector_open (belt-and-suspenders over the modal popup). Selection is session-only — persists across EDIT/DIRECT/PLAY toggles, resets on scene reload, no disk save (_save_settings is untouched).
• scripts/stickman_speech_bubble.gd — class_name SpeechBubble, extends Node2D; a world-space speech bubble drawn in _draw() (Phase 3a, not used by the editor). Child of a StickmanRig at SPEECH_BUBBLE_OFFSET (above the head), so it follows the figure and scales with the camera. Consts FONT_SIZE/PADDING/TAIL_HEIGHT/MAX_WIDTH/BG_COLOR/BORDER_COLOR/TEXT_COLOR. Measures text via ThemeDB.fallback_font.get_string_size(...), draws a rounded-rect background + a downward tail triangle centered on the rig-local origin, then draw_string(...); visible = false by default, no hit-testing. Public API: show_text(text) (store, visible = true, queue_redraw()), hide_bubble(). Driven by StickmanRig.speak(); the rig owns hiding + the speech_finished signal.
• scripts/stage_director_visuals.gd — class_name StageDirectorVisuals, extends Node2D; the Edit-mode director overlay (Phase 3a, not used by the editor), mirroring StageGrid/ StageGizmos. State camera/world/enabled/_dirty; public set_enabled(value) / mark_dirty(). _process() redraws on a dirty flag; _draw() reads each rig's queue via _collect_rigs() (direct World children filtered is StickmanRig). Per action in order: walk_to → a blue waypoint dot (WAYPOINT_RADIUS_PX / _zoom()) with white outline + order number at action["target"]; dashed connectors (draw_dashed_line, DASH_* / _zoom()) between consecutive dots (and from the rig's current feet position to the first dot); non-walk actions (speak/wait/ ragdoll/recover) → a badge (speech bubble / clock / X / up-arrow glyph + order number) anchored at the stickman's position at that point in the sequence — derived by simulating the queue (start at rig feet + FOOT_OFFSET; each walk_to advances the anchor; non-walk anchors at the current position), consecutive badges stacking (0, -28)/zoom. All sizes divided by _zoom() so markers stay screen-constant; pure _draw(), no hit-testing; hidden in PLAY via set_enabled(false).
  • Phase 4 rule visualization: _draw() also renders _event_rules (set via set_rules()) — a dashed white connector line from the trigger object to the target, a green ⚡ trigger badge, an orange → action badge, a dark label with rule_summary() text, and a ✕ delete icon (the label + icon are hit-testable via hit_test_rule(), Vector2.INF sentinel from hit_test_waypoint()); click-label → consequence-only edit, click-✕ → delete.
• scripts/stage_spawner.gd — class_name StageSpawner, extends RefCounted; registry-driven spawner (Phase 2). A _registry: Array[Dictionary] maps ids to terrain/prop/stickman templates; adding a type = appending an entry (no hard-coded id match). Reuses TerrainUtils.spawn_block, PropUtils.spawn_prop, StickmanFactory.spawn_from_data via preload consts. Terrain entries store origin-relative point templates (ground/ramp/step); _spawn_terrain centers the template bbox on its local origin then sets block.position to the cursor, so global_rotation = "rotate about center". Also exposes a static get_world_aabb(node) helper (for a stickman it unions the mounted Body/* shape geometry via a recursive _collect_visual_points() so the box is centered head-to-feet).
  • Phase 4 area palette entry: a new "area" registry entry (label "Area") → _spawn_area() instantiates a TriggerArea; get_world_aabb() gains a duck-typed get_area_rect AABB branch (if the node responds to get_area_rect(), use its Rect2 as the world bounds).
  • Phase 3b asset library (selected-asset spawner): the registry entries are now ground/ramp/step (terrain) + prop + stickman + area — the separate crate/ball entries were removed and a single "prop" entry (label "Prop", kind "prop") added, so get_spawnable_ids() == ["ground","ramp","step","prop","stickman","area"]. Session state: selected_stickman_path (default DEFAULT_STICKMAN_PATH = res://stickmen/test.stk) and selected_prop_id (default "crate"), read/written by the sandbox selector (Phase 3b) — they are session-only (no disk save). _stickman_cache: Dictionary (path → parsed data) seeds the default path in _init and lazily loads+parses any newly selected path on first spawn. _spawn_stickman spawns from the selected path (applies STICKMAN_FOOT_OFFSET (0, -385) so feet land at the cursor); _spawn_prop looks the selected prop id up via PropLibrary.get_entry(id) and spawns its payload (PropUtils.spawn_prop) + material preset. New getters get_selected_stickman_path() / get_selected_prop_id() (status + tests).
• scripts/stickman_library.gd — class_name StickmanLibrary, extends RefCounted (Phase 3b, not used by the editor). Scans res://stickmen/*.stk into entry models for the asset selector. const STICKMEN_DIR := "res://stickmen"; var entries: Array[Dictionary]. Public API: scan(dir_path: String = STICKMEN_DIR) -> Array[Dictionary] (via DirAccess + per-file StickmanFactory.load_stk; a corrupt or missing-body_parts file is skipped with a push_warning — never {}-as-entry; the display name = stickman_name (stripped) if non-empty else the filename basename; results sorted by name, then path, cached on self and returned), get_entries() -> Array[Dictionary] (returns the last scan, does not rescan), find_by_path(path) -> Dictionary ({} if absent), and make_entry(path) -> Dictionary (ad-hoc single-file entry for Browse: load_stk + name fallback; {} on load failure or missing body_parts). Entry shape { "path", "name", "data" }; thumbnails are not embedded in entries — resolved via ThumbnailCache at display time by the selector.
• scripts/prop_library.gd — class_name PropLibrary, extends RefCounted (Phase 3b, not used by the editor). A static registry of the 4 built-in prop templates for the asset selector. static var _templates: Array[Dictionary] (lazily built on first access — PropUtils.create_*() are static func and cannot run in a const). Public API: static get_entries() (builds once, returns the 4 templates), static get_ids(), static get_entry(id) -> Dictionary ({} if unknown), static get_default_id() -> String ("crate"). Template dicts carry {id, name, material_preset, material_label, payload} — Crate/Wood (create_box() + WOOD), Ball/Rubber (create_ball() + RUBBER), Plank/Metal (create_plank() + METAL), Triangle/Cardboard (create_triangle() + CARDBOARD) — generator color themes already match the presets.
• scripts/thumbnails/thumbnail_cache.gd — class_name ThumbnailCache, extends RefCounted (Phase 3b, not used by the editor). Disk PNG cache under user://thumbnails/. Consts STICKMEN_DIR := "user://thumbnails/stickmen", PROP_DIR := "user://thumbnails/props", PROP_VERSION := 1. Public API: stickman_key(path) → "<basename>_<FileAccess.get_modified_time(path)>" (an mtime change yields a new key → missing PNG → regenerate); stickman_png(key) / prop_png(id) ("<id>_v<PROP_VERSION>.png" — bump PROP_VERSION to invalidate all prop thumbnails); load_png(png_path) -> Texture2D (Image.load_from_file + ImageTexture, null if missing/unloadable); save_png(tex, png_path) -> Error (creates the parent dir); ensure_dir; clean_stale_stickmen(valid_keys) (deletes basename_* PNGs not in the valid key set).
• scripts/thumbnails/stickman_thumbnail.gd — class_name StickmanThumbnail, extends Node (Phase 3b, not used by the editor). Renders a parsed .stk into a Texture2D for the asset selector by spawning the real rig. const SIZE := Vector2i(200, 200). _ready() builds one persistent offscreen SubViewport (transparent_bg, render_target_update_mode = UPDATE_ALWAYS) with an enabled in-viewport Camera2D (make_current()). render(stk_data) -> Texture2D: frees prior children, StickmanFactory.spawn_from_data(stk_data)s the rig into the viewport at Vector2.ZERO, frames it via StageSpawner.get_world_aabb(rig) (a degenerate/no-area bbox falls back to a fixed (120×500) rect), _frame_camera fits it with a 12 px margin, awaits RenderingServer.frame_post_draw twice (standard offscreen capture recipe), grabs the viewport texture, frees the rig, and returns an ImageTexture — or null (a placeholder) when the capture is blank/empty (the headless degrade; pixel rendering is manual/F6 verification only). Output is identical to the rig actually placed on stage, not a re-implementation of the editor preview.
• scripts/thumbnails/prop_thumbnail.gd — class_name PropThumbnail, extends Node (Phase 3b, not used by the editor). Renders a prop template into a Texture2D. const SIZE := Vector2i(200, 200). _ready() builds the same offscreen SubViewport + Camera2D pattern as StickmanThumbnail. render(payload, material_preset) -> Texture2D mirrors PropBlock's geometry into a plain Node2D with a Polygon2D (fill) + Line2D (closed loop, round joints/caps) — not a RigidBody2D, so nothing falls under gravity inside the viewport; circle payloads are re-expanded via PropBlock.CIRCLE_SEGMENTS; non-NONE presets tint fill via PropBlock.tint_for and darken the outline; then frames + double-frame_post_draw captures and returns an ImageTexture or null (blank → placeholder).
• scripts/asset_selector.gd — class_name AssetSelector, extends PopupPanel (Phase 3b, not used by the editor); root script of scenes/asset_selector.tscn. A grid popup controller. Signals item_selected(entry), cancelled(), browse_requested(), refresh_requested(). const COLUMNS := 4, ROWS := 3, PAGE_SIZE := 12, CELL_MIN_SIZE, THUMB_SIZE. var kind ("stickman" | "prop"). Public API: open(kind, entries) (sets the title "Choose Your Stickman"/"Choose a Prop", shows Browse…/Refresh only for stickmen, then popup_centered()), set_entries(entries) (used by Refresh — resets page + thumbnails), set_thumbnail(entry, tex) (lazy handoff from the stage's drain), close(), and apply_font(ui_font, emoji_font) (walks the authored controls). _ready() sets exclusive = true and wires the footer buttons; _unhandled_input maps KEY_ESCAPE → cancelled.emit() (the Window's built-in Esc close is not relied on). Re-centers on window resize: the root's size_changed signal re-runs popup_centered() while the popup is visible. Cell build: _rebuild() frees the %GridContainer children, toggles the empty-state %EmptyLabel, shows/hides Prev/Next/page label by page count, and slices the current page via the static pure page_bounds(total, page, page_size) -> Dictionary {start, end, total, page_count} helper. _build_cell(entry) returns a Button with a TextureRect (cached/placeholder texture) + a name Label + (prop only) a material-badge Label; cells emit item_selected. No cell is pre-highlighted on open (the previous selection highlight styling was removed). The .tscn is a minimal shell (title bar, empty grid, footer as authored unique-name nodes %TitleLabel/%GridContainer/ %EmptyLabel/%PageLabel/%PrevButton/%NextButton/%BrowseButton/%RefreshButton/ %CloseButton); all dynamic per-cell content is built in code at runtime because the entry set is dynamic.
• scripts/stage_selection.gd — class_name StageSelection, extends RefCounted; hover/click/ box selection via geometric world-space AABB hit-testing (Phase 2). static get_world_aabb unions a Polygon2D child's world points (terrain/props) or, for a stickman rig, recursively unions its mounted Body/* Line2D/Polygon2D geometry (_collect_visual_points()), so the bounding box is centered on the actual figure head-to-feet (not a fixed rect). _frontmost_at = highest World child index wins, smallest area breaks ties. _is_selectable excludes the RagdollBodyContainer subtree. Signals hover_changed(node) / selection_changed(nodes); public API get_selected/get_primary/ clear_selection/select_only/add_to_selection/toggle_selection/is_selected/hit_test/ update_hover/box_select. (Phase 4) get_world_aabb also handles TriggerArea objects via the same duck-typed get_area_rect AABB branch, so trigger areas are selectable/hit-testable.
• scripts/stage_gizmos.gd — class_name StageGizmos, extends Node2D; hover highlight + selection outlines + a rotate ring (Phase 2). No translate handle — objects are dragged directly by the root; set_targets(nodes: Array[Node2D]) holds the current multi-selection, and begin_translate_drag(node, world_pos) starts a TRANSLATE drag that moves all selected nodes together (drag_to drives global_position with optional grid snap via snap_size, snapping the drag anchor and applying the same delta to the rest). The rotate ring is drawn and hit-tested only when exactly one node is selected (hit_test → Handle.ROTATE). The rotate drag is absolute-from-start — drag_to() sets global_rotation to _rotate_start_rotation + (current − start angle), with holding Ctrl snapping to 15° increments via snappedf(new_rotation, deg_to_rad(15.0)). _draw() draws a selection outline for every selected node. Pure _draw() + distance-based hit-testing (no Area2D); enum Handle { NONE, TRANSLATE, ROTATE }. transform_committed(nodes: Array[Node2D]) emitted on drag end. set_enabled(false) hides + disables in PLAY. Also draws the box-select marquee via set_box_rect(rect).
• scripts/stage_grid.gd — class_name StageGrid, extends Node2D; the optional world-space grid overlay (Phase 2). Pure _draw(): grid lines pan/zoom with the camera (camera.get_screen_center_position()
  • viewport extent / zoom), with a heavier major line every 5 cells; grid_size / enabled are set by SandboxStage. Added as the first child of the stage root so it renders behind World; no hit-testing.
• 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, %StatusBar, %CursorCoords, %SnapStatus.
    • Phase 6 status bar: StatusBar is an HBoxContainer bottom-anchored at 28 px height containing CursorCoords (left) and SnapStatus (right); MainLayout offset_bottom is -28.0 to leave room for it.
  • 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.
  • scenes/test_harness.tscn — standalone staging scene (Phase 9, not wired into the editor; run via F6). Backed by scripts/test_harness.gd. Top UI bar with file open / quick-select, "Show Bones" / "Show IK Handles" / "Show Coords" toggles, and a loaded-filename status label; SubViewport world with an enabled Camera2D (middle-mouse pan, wheel zoom, recenter on spawn); interactive limb IK via SkeletonModificationStack2D TwoBoneIK.
  • scenes/physics_test_harness.tscn — standalone staging scene (Vector Terrain System / Dynamic Vector Props, not wired into the editor; run via F6). Backed by scripts/physics_test_harness.gd. Root Node2D + script, Camera2D at position (0, -400) zoom 0.5, empty Environment container. Wheel-zoom scales between 0.25x and 3.0x (resolution independence / vector outline thickness); middle-drag pans. Top-bar buttons Spawn Crate / Spawn Ball / Spawn Plank spawn dynamic props (PropUtils) above the angled ramp; a toggle button flips the rig Stickman ↔ Ragdoll (removing/restoring the best-effort StaticBody2D rig collision proxy); a Knock Up button impulses the ragdoll and all props upward.
  • scenes/sandbox_stage.tscn — standalone staging scene (Sandbox Stage Builder, Phase 2, not wired into the editor; run via F6). Backed by scripts/sandbox_stage.gd. Minimal root Node2D + script, Camera2D at position (0, -400) zoom (0.5, 0.5), and an empty World (Node2D) container; the GridLayer (StageGrid), GizmoLayer (StageGizmos), PlacementGhost holder, and the CanvasLayer top-bar UI (mode toggle + six palette buttons + Grid/Snap/Size controls + status label) are built in code at _ready(). Phase 3b instantiates the AssetSelector grid popup (see below) into the UI CanvasLayer.
  • scenes/asset_selector.tscn — standalone asset-selector grid popup (Phase 3b, not wired into the editor). Rooted at AssetSelector (PopupPanel, scripts/asset_selector.gd); a minimal shell/layout skeleton — authored title bar, empty GridContainer, empty-state Label, and a footer (Prev / page label / Next / Browse… / Refresh / Close), all as unique-name nodes (%TitleLabel, %GridContainer, %EmptyLabel, %PageLabel, %PrevButton, %NextButton, %BrowseButton, %RefreshButton, %CloseButton). All dynamic per-cell content (thumbnail + name + prop material badge) is built in code at runtime because the entry set is dynamic; instantiated by sandbox_stage.gd (_build_ui) for the Stickman / Prop palette-button selector grids.

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}.
• Phase 8: per-part data adds pivot {x, y} (local bounding-box center = rotation origin) and length (float, bbox extent along the segment axis) for format v1.4; the .stk root also gains a top-level proportions object (5 rig bone lengths). All three are write-only metadata recomputed on every save — never read back on load.
• Phase 9 Round 5: per-part data adds guide_offset {x, y} (bbox center − guide joint, preview space; pure master-space delta) for format v1.5. Write-only metadata like pivot/length; the load path ignores it, so v1.0–v1.4 files load unchanged and gain the key on their next save.
• The JSON .stk format is defined in README.md (versioned "1.5", extensible; "1.0"–"1.4" files auto-migrate on load).

settings.json (Phase 6)

• Persisted editor preferences written to settings.json via _save_settings() and loaded in _load_settings().
• Keys: version, grid_size, snap_to_grid, recent_colors, show_pose_guide.
• recent_colors: Array[String] — the last up-to-8 selected hex colors, most-recent-first. Populated on load and flushed on every color selection.
• show_pose_guide: bool — whether the pose silhouette guide is visible in the Whole Stickman preview. Default true. Loaded in _load_settings() and flushed on every toggle via _broadcast_settings().

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.