# Phase 9 Task 5 — Feature: Rig Animation in the Test Harness ## Overview RIGGING.md Task 5: `master_rig.tscn` already ships an `AnimationPlayer` and an `AnimationTree`. The test harness must let the user **select** an animation from a dropdown, **play / pause / resume / stop** it, and **toggle loop vs. play-once**. Concretely: 1. A **dropdown** listing the rig's animations (from `AnimationPlayer.get_animation_list()`). 2. A **play/pause/resume** button (single button whose label reflects playback state) plus a **Stop** button. Per RIGGING.md, **Play always restarts from the beginning**; **Stop resets to the start** so the next Play restarts. 3. A **Loop** checkbox that makes the selected animation loop or play just once. This is a **harness-only** change. `master_rig.tscn` is **not** modified (the two animation nodes already exist and are sufficient). `scripts/stickman_rig.gd` is **not** modified (the harness resolves the `AnimationPlayer` directly by node path, exactly as it already resolves `Skeleton2D` and the IK handles). Only `scripts/test_harness.gd` changes. ## 1. Findings — `master_rig.tscn` animation nodes ### 1a. Node paths (both are direct children of the `Master` rig root) | Node | Path (rig-relative) | Properties | |---|---|---| | `AnimationPlayer` | `AnimationPlayer` | `libraries/ = AnimationLibrary_t75yq`; no `active` override (defaults to `true`). | | `AnimationTree` | `AnimationTree` | `active = false`; `tree_root = AnimationNodeStateMachine_6rw38`; `anim_player = NodePath("../AnimationPlayer")`. | The harness reaches the player via `_rig.get_node_or_null(NodePath("AnimationPlayer"))` — the rig root is the `Master` node (`_rig`, a `StickmanRig`), and `AnimationPlayer` is a direct child (`parent="."`). ### 1b. Animation library — two animations (not one) The `AnimationLibrary_t75yq._data` dictionary holds **two** animations (RIGGING.md says "currently just 'walk_right'", but there is also a pose-reset helper): | Name | Length | `loop_mode` | Tracks | |---|---|---|---| | `RESET` | `0.001` | *(absent → `LOOP_NONE`)* | `.:facing_profile` (discrete, value `2` = `FacingProfile.FORWARD`) | | `walk_right` | `0.8` | `1` (`LOOP_LINEAR`) | 6 IK-target position tracks + `.:facing_profile` (discrete, value `1` = `RIGHT`) | `AnimationPlayer.get_animation_list()` therefore returns `["RESET", "walk_right"]` (library dictionary insertion order). The dropdown lists both; the harness prefers `walk_right` as the initially-selected item (see §5b). ### 1c. What `walk_right` animates `walk_right` does **not** key `Bone2D` rotations directly. It animates the **6 `IK_Targets` `Marker2D` positions** (the `TwoBoneIK`/`LookAt` solvers then flex the bones) plus a discrete `facing_profile` set on the rig root: - `IK_Targets/Torso:position` (5 keys, cubic interp) — bobbing; the Torso marker's child `RemoteTransform2D` (`remote_path = ../../../Skeleton2D/Torso`) translates the whole skeleton. - `IK_Targets/Head:position`, `IK_Targets/Right_Leg:position`, `IK_Targets/Left_Leg:position`, `IK_Targets/Right_Hand:position`, `IK_Targets/Left_Hand:position` (5 keys each, cubic interp). - `.:facing_profile` (discrete, `update = 1`, value `1` = `FacingProfile.RIGHT`). The `.:facing_profile` track writes through the `StickmanRig.facing_profile` export setter (animation tracks write via `Object.set()`, which triggers the setter), so **playing an animation can change the facing profile** and emits `facing_profile_changed` — which the harness already handles via `_on_facing_profile_changed` (updates the `_facing_profile` mirror, the `[√] ` menu prefix, and the debug redraw). No special harness handling is required; it is documented behavior. `RESET` likewise sets `facing_profile = FORWARD`. ### 1d. Is `AnimationTree` configured? — **No (placeholder)** `AnimationTree` has `active = false` and an **empty** `AnimationNodeStateMachine` root (`AnimationNodeStateMachine_6rw38` has no states, no transitions, and no `start_node`). There is **no** `AnimationNodeAnimation`, no `AnimationNodeBlendTree`, and no output node set. It is a placeholder. **Decision (D1): the harness drives `AnimationPlayer` directly; configuring `AnimationTree` is out of scope.** Justification: the task only needs select/play/pause/stop/loop, all of which `AnimationPlayer` provides directly; a state-machine/blend-tree setup adds nothing for a single animation stream and would require editing `master_rig.tscn`. The `AnimationTree` node is left untouched for a future blending phase. ## 2. Godot 4 API notes (verified for 4.7) - `AnimationPlayer.get_animation_list() -> PackedStringArray` — animation names. - `AnimationPlayer.get_animation(name: StringName) -> Animation` — the `Animation` resource. - `AnimationPlayer.play(name: StringName, ...)` — if the player is **stopped**, calling `play(name)` **restarts from position 0**. If the player is **paused** on the same animation, `play(name)` (or `play()` with no args) **resumes**. We rely on the documented distinction: *"the assigned animation will resume playing if it was paused, or restart if it was stopped."* - `AnimationPlayer.pause()` — pauses, keeps position. - `AnimationPlayer.stop()` — default `keep_state = false`: stops and **resets position to 0**. - `Animation.loop_mode` — `Animation.LOOP_NONE` (0) / `Animation.LOOP_LINEAR` (1). Loop is a property of the **`Animation` resource**, not of `play()`, so the toggle writes `anim.loop_mode` on the selected animation before playing. - `AnimationPlayer.animation_finished(anim_name: StringName)` — emitted when an animation reaches its end and stops. **Not** emitted on `pause()`/`stop()`. For **looping** animations the emit-on- wrap behavior varies across 4.x versions, so the handler ignores the signal while `_loop` is true (see §7 D4) — this is safe under either engine behavior. ## 3. UI design New controls in the top-bar `HBox`, inserted **immediately after the "Facing" `MenuButton` and before the "Open .stk…" button** (keeps the two rig-behavior control clusters — Facing + Animation — adjacent at the left edge, and leaves the load / debug-display clusters untouched): ``` [ Facing ][ AnimDropdown ][ Play/Pause ][ Stop ][ ☑ Loop ][ Open .stk… ][ Break ][ Basic ][ Test ][ Show Bones ][ Show IK Handles ][ Show Coords ] …status… ``` | Node | Type | Text / state | Purpose | |---|---|---|---| | `_anim_dropdown` | `OptionButton` | populated per spawn | Select the animation. | | `_play_button` | `Button` | `"Play"` / `"Pause"` / `"Resume"` (label swaps) | Play-from-start / pause / resume. | | `_stop_button` | `Button` | `"Stop"` | Stop and reset to start. | | `_loop_check` | `CheckBox` | `"Loop"`, `button_pressed = true` | Loop vs. play-once. | Controls are **always enabled** (matching the harness's existing "Facing" menu / checkbox style); each handler no-op-guards on a missing `AnimationPlayer` instead of disabling the control. ## 4. Implementation — `scripts/test_harness.gd` ### 4a. Constants ```gdscript ## AnimationPlayer node path (relative to rig root). const ANIMATION_PLAYER_PATH := "AnimationPlayer" ## Initially-selected animation in the dropdown (RIGGING.md default). const DEFAULT_ANIMATION := "walk_right" ``` ### 4b. Enum ```gdscript ## Harness-tracked playback state (the harness is the sole driver of the ## AnimationPlayer, so it tracks state authoritatively via button handlers and ## the animation_finished signal rather than polling is_playing()). enum PlaybackState { STOPPED, PLAYING, PAUSED } ``` ### 4c. Runtime-built node references (added to the existing block) ```gdscript var _anim_dropdown: OptionButton var _play_button: Button var _stop_button: Button var _loop_check: CheckBox ``` ### 4d. State (added to the existing block) ```gdscript var _anim_player: AnimationPlayer = null var _selected_animation: String = "" var _playback_state: int = PlaybackState.STOPPED var _loop: bool = true # harness-level, persists across respawns (like _show_coords) ``` ### 4e. UI construction — insert in `_build_ui()` Insert after `hbox.add_child(_facing_button)` and before `var open_btn := Button.new()`: ```gdscript _anim_dropdown = OptionButton.new() _anim_dropdown.item_selected.connect(_on_anim_dropdown_selected) hbox.add_child(_anim_dropdown) _play_button = Button.new() _play_button.text = "Play" _play_button.pressed.connect(_on_play_pressed) hbox.add_child(_play_button) _stop_button = Button.new() _stop_button.text = "Stop" _stop_button.pressed.connect(_on_stop_pressed) hbox.add_child(_stop_button) _loop_check = CheckBox.new() _loop_check.text = "Loop" _loop_check.button_pressed = true _loop_check.toggled.connect(_on_loop_toggled) hbox.add_child(_loop_check) ``` ### 4f. Resolution — `_resolve_anim_player()` (new) Called from `_resolve_rig_nodes()` (add the call at its end, after `_resolve_coord_bones()`): ```gdscript func _resolve_anim_player() -> void: _anim_player = _rig.get_node_or_null(NodePath(ANIMATION_PLAYER_PATH)) as AnimationPlayer _populate_animation_dropdown() if _anim_player == null: push_warning("TestHarness: missing '%s' node in rig." % ANIMATION_PLAYER_PATH) return _anim_player.animation_finished.connect(_on_animation_finished) ``` ```gdscript func _populate_animation_dropdown() -> void: _anim_dropdown.clear() _selected_animation = "" _playback_state = PlaybackState.STOPPED _update_play_button() if _anim_player == null: return var preferred_idx := 0 var anim_list: PackedStringArray = _anim_player.get_animation_list() for i: int in anim_list.size(): var anim_name: String = anim_list[i] _anim_dropdown.add_item(anim_name) if anim_name == DEFAULT_ANIMATION: preferred_idx = i if _anim_dropdown.item_count > 0: _anim_dropdown.select(preferred_idx) _selected_animation = _anim_dropdown.get_item_text(preferred_idx) ``` ### 4g. Handlers ```gdscript func _on_anim_dropdown_selected(index: int) -> void: _selected_animation = _anim_dropdown.get_item_text(index) # Changing selection stops any in-progress playback (Play restarts it). if _anim_player != null and is_instance_valid(_anim_player): _anim_player.stop() _playback_state = PlaybackState.STOPPED _update_play_button() func _on_play_pressed() -> void: if _anim_player == null or not is_instance_valid(_anim_player): return if _selected_animation.is_empty(): return match _playback_state: PlaybackState.STOPPED: _apply_loop_mode() _anim_player.play(_selected_animation) # restart from position 0 _playback_state = PlaybackState.PLAYING PlaybackState.PLAYING: _anim_player.pause() _playback_state = PlaybackState.PAUSED PlaybackState.PAUSED: _anim_player.play() # resume the assigned (paused) animation _playback_state = PlaybackState.PLAYING _update_play_button() func _on_stop_pressed() -> void: if _anim_player == null or not is_instance_valid(_anim_player): return _anim_player.stop() # resets position to 0 and stops _playback_state = PlaybackState.STOPPED _update_play_button() func _on_loop_toggled(pressed: bool) -> void: _loop = pressed _apply_loop_mode() func _on_animation_finished(_anim_name: StringName) -> void: if _loop: return # looping: never treat a wrap as "finished" _playback_state = PlaybackState.STOPPED _update_play_button() ``` ### 4h. Helpers ```gdscript func _apply_loop_mode() -> void: if _anim_player == null or not is_instance_valid(_anim_player): return if _selected_animation.is_empty(): return var anim: Animation = _anim_player.get_animation(_selected_animation) if anim != null: anim.loop_mode = Animation.LOOP_LINEAR if _loop else Animation.LOOP_NONE func _update_play_button() -> void: if _play_button == null: return match _playback_state: PlaybackState.STOPPED: _play_button.text = "Play" PlaybackState.PLAYING: _play_button.text = "Pause" PlaybackState.PAUSED: _play_button.text = "Resume" ``` ### 4i. Lifecycle - **`_resolve_rig_nodes()`** — add `_resolve_anim_player()` after `_resolve_coord_bones()`. Each spawn re-resolves the player, repopulates the dropdown (fresh `AnimationPlayer` → fresh list), resets `_playback_state` to `STOPPED`, and re-connects `animation_finished`. - **`_free_current_rig()`** — add: ```gdscript _anim_player = null _anim_dropdown.clear() _selected_animation = "" _playback_state = PlaybackState.STOPPED _update_play_button() ``` (The old player is `queue_free`d with the rig; its `animation_finished` connection dies with it. `_loop` is **not** reset — it is harness-level state that persists across respawns, like `_show_coords` / `_facing_profile`.) - **`_process(delta)`** — **unchanged.** The coordinates readout keeps updating during playback (it reads `global_position`/`global_rotation` every frame), and `AnimationPlayer` self-animates independent of the harness `_process`. No playback-state polling is added (state is tracked via handlers + `animation_finished`). ## 5. Files modified | File | Changes | |---|---| | `scripts/test_harness.gd` | `ANIMATION_PLAYER_PATH`, `DEFAULT_ANIMATION`, `PlaybackState`, `_anim_dropdown`/`_play_button`/`_stop_button`/`_loop_check`, `_anim_player`/`_selected_animation`/`_playback_state`/`_loop`, UI block in `_build_ui()`, `_resolve_anim_player()`, `_populate_animation_dropdown()`, `_on_anim_dropdown_selected()`, `_on_play_pressed()`, `_on_stop_pressed()`, `_on_loop_toggled()`, `_on_animation_finished()`, `_apply_loop_mode()`, `_update_play_button()`; lifecycle hooks in `_resolve_rig_nodes()` + `_free_current_rig()`. | | `docs/phase9_task5_animation_spec.md` | This file. | | `AGENTS.md` | Test-harness section: "Phase 9 Task 5 rig animation" bullet (dropdown + play/pause/stop + loop, drives `AnimationPlayer` directly). | | `README.md` | Test-harness bullet: animation select/play/pause/stop/loop controls. | | `RIGGING.md` | Mark Task 5 implemented. | **Not modified:** `master_rig.tscn`, `scripts/stickman_rig.gd`, `scripts/stickman_factory.gd`, `scripts/stk_rig_adapter.gd`. ## 6. Edge cases - **No rig loaded / no `AnimationPlayer`** (foreign rig): `_resolve_anim_player()` warns once; the dropdown is empty; `_on_play_pressed`/`_on_stop_pressed`/`_on_loop_toggled` no-op-guard. - **Re-spawn**: dropdown repopulated, `_playback_state` reset to `STOPPED`, play button label back to `"Play"`; `_loop` toggle persists and is re-applied on the next play (via `_apply_loop_mode()`). - **Changing the dropdown selection mid-play**: the current animation stops and state → `STOPPED` (the newly selected animation is not auto-started). - **Non-looping animation finishes**: `animation_finished` → state → `STOPPED`, button → `"Play"`. - **Looping animation**: `animation_finished` (if emitted on wrap in this engine version) is ignored by the `_loop` guard; the button stays `"Pause"` indefinitely. - **Manual IK dragging during playback**: not blocked; but the animated tracks overwrite the dragged handles' positions on the next frame, so dragging an animated handle while playing has no lasting effect (expected; documented, not "fixed"). - **Animation changes the facing profile**: `walk_right` → `RIGHT`, `RESET` → `FORWARD`; flows through the rig setter and the existing `_on_facing_profile_changed` (menu `[√] ` + redraw). - **Stopping does not restore the rest pose**: `stop()` resets the *playhead* to 0 but leaves properties at their last keyed values. The `RESET` animation is available to restore facing; full rest-pose restoration on stop is out of scope. - **The 0.001s `RESET` animation + loop ON**: selecting it with loop ON makes a harmless tight loop (facing stays FORWARD). Not special-cased. ## 7. Design decisions | # | Decision | Justification | |---|---|---| | D1 | Drive `AnimationPlayer` directly; `AnimationTree` out of scope | `AnimationTree` is an unconfigured placeholder (`active = false`, empty state machine). Select/play/pause/stop/loop are all first-class `AnimationPlayer` APIs; wiring a blend tree would require editing `master_rig.tscn` for no gain here. | | D2 | Single play/pause/resume button + separate Stop button | Matches RIGGING.md "pause/resume" (toggling) vs "stop (restart on play)" as distinct states; the label swap is the harness's existing dynamic-text pattern (cf. the editor's snap/guide menus). | | D3 | Track playback state via `_playback_state` + `animation_finished`, not `is_playing()` polling | The harness is the sole driver, so state is deterministic. `animation_finished` reliably fires for non-looping end-of-play and never fires on `pause()`/`stop()`; the `_loop` guard makes the looping-wrap ambiguity moot. Avoids adding per-frame polling to `_process`. | | D4 | Loop = write `Animation.loop_mode` on the selected `Animation` before playing | Loop is an `Animation`-resource property, not a `play()` argument; this is the only way to override the authored value. Re-applied on every play so the harness `_loop` toggle is authoritative regardless of authored `loop_mode`. | | D5 | Loop default **ON** | Matches the authored `walk_right` (`loop_mode = 1`), and a walk cycle is the natural looping case. | | D6 | Dropdown populated dynamically per spawn from `get_animation_list()` | The list comes from the rig's own library, so future animations appear automatically; no hardcoded list. | | D7 | Prefer `walk_right` as initial selection (`DEFAULT_ANIMATION`) | Matches RIGGING.md's "currently just 'walk_right'" default even though the library also contains `RESET`. | | D8 | No `stickman_rig.gd` change | The harness already resolves rig children by node path (`SKELETON_PATH`, `IK_HANDLE_PATHS`); `ANIMATION_PLAYER_PATH` follows that established pattern. A rig-level accessor is unnecessary. | | D9 | Controls never disabled; handlers no-op-guard | Matches the existing harness style (the "Facing" menu and checkboxes are always enabled). | ## 8. Verification Only `scripts/test_harness.gd` changes, so the syntax checks target that script. 1. **Whole-project parse check** (established form used by every prior phase — the plain `--check-only` form hangs on renderer init in 4.7.x, so use the `--headless --check-only --quit` variant). Run from the project dir `C:\Godot4\stickman`: ``` ..\Godot_v4.7.1-stable_win64_console.exe . --headless --check-only --quit ``` 2. **Single-script check** (user-specified form; run from anywhere): ``` & "C:\Godot4\Godot_v4.7.1-stable_win64_console.exe" --headless --path "C:\Godot4\stickman" --check-only --script "res://scripts/test_harness.gd" ``` 3. **Manual F6 check** (`res://scenes/test_harness.tscn`): - Load `stickmen/basic.stk` → dropdown lists `RESET` and `walk_right`, `walk_right` selected, play button shows `"Play"`, Loop checked. - Press **Play** → button `"Pause"`; the figure walks (IK targets animate, legs/arms swing, facing menu flips to `[√] Right`). Coordinates readout updates live. - Press **Pause** → button `"Resume"`; figure freezes. Press again → resumes. - Press **Stop** → figure stops, button `"Play"`; press **Play** → restarts from the beginning (not from the paused position). - Uncheck **Loop** → press **Play** → animation plays once, then the button returns to `"Play"` by itself. - Select `RESET` → Play → facing returns to `[√] Forward`. - Load a different `.stk` → dropdown repopulated, playback reset, Loop checkbox state kept. ## 9. Implementation order 1. `scripts/test_harness.gd` — constants, enum, node refs, state, `_build_ui()` block, handlers, helpers, lifecycle hooks. 2. Parse checks (§8 items 1–2) + manual F6 (§8 item 3). 3. Docs: `AGENTS.md`, `README.md`, `RIGGING.md`, this spec.