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 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.
  • 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), _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/* before re-enabling the IK stack so TwoBoneIK solves toward the end-effectors. 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 (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").
• 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 = 0.8, 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. Playing walk_right also sets the rig's facing_profile via its animation track → export setter → the existing _on_facing_profile_changed handling (menu [√] + redraw). 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.
• 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).
• 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". The Stickman entry caches res://stickmen/test.stk once (load_stk in _init) and applies STICKMAN_FOOT_OFFSET (0, -385) so feet land at the cursor. 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).
• 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.
• 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().

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.