ryan/stickman
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Implement Phase 16 - Move To: Walk and Run

Browse Source 
- Introduced a new action type `move_to` allowing children to direct a stickman to a destination using either Walk or Run styles.
- Updated the ActionEditor UI to include Walk/Run buttons for selecting movement styles.
- Ensured compatibility with existing `walk_to` actions by converting them to the new `move_to` format during loading.
- Defined clear success criteria for the implementation, including distinct movement animations and behavior for both Walk and Run.
- Established a comprehensive verification contract to ensure functionality across various terrains and scenarios.
This commit is contained in:
ryan
2026-10-05 15:04:09 -04:00
parent 36596b2c28
commit 3f66cc3195
19 changed files with 2088 additions and 194 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/plans/phase_16_running_stickman.md
+104
View File
@@ -0,0 +1,104 @@
# Phase 16 — Running Stickman
> **Status:** Accepted Designer handoff for the spec-pipeline.
> **Audience:** Architect and implementation team.
> **Purpose:** Product/design brief; the final technical specification is a separate architect deliverable.
## Implementation update — DIRECT mode
The DIRECT-mode quick action uses one **Move To** command. The user places the destination first; a compact follow-up panel then offers a **Movement** dropdown and **Add Move To** / **Cancel**. The dropdown currently offers Walk and Run and is populated from the movement-style choices so more styles can be added without expanding the action menu. The first draft defaults to Walk. A stickman remembers its last successfully committed style while its scene is open; canceling a draft does not change that preference.
Cancel, Escape, right-click, dismissing the popup, or leaving DIRECT mode discards the uncommitted destination and style. The approved readability pass uses a 23 pt Movement label, a 25 pt selector (including style emoji), 22 pt buttons, 54 px selector height, 52 px action-button height, and a 380×172 px panel.
## Goal and audience
Give children a clear way to direct a stickman to a destination at different paces, starting with Walk and Run. Make Run read as a believable human gait in the existing stickman style, rather than a shortened or faster Walk cycle.
The action should describe the destination independently from the way the character travels. This leaves a clean product concept for future movement styles such as Fly, without including them in this phase.
## Desired user outcome
A child can make a stickman walk to one place, then run to another, using the same Move To action and waypoint workflow. The selected style affects both travel pace and animation, so a faster movement has a matching gait. Children do not need to tune a numeric speed to get the intended result.
## Core flow and behavior
1. In the Sandbox Stage action editor, the child adds or edits **Move To** and places a destination using the existing stage-click target flow.
2. The action offers **Walk** and **Run** as per-action movement styles. **Walk** is selected by default.
3. Each style uses a predictable default pace paired with its animation. Numeric speed adjustment is out of scope for the first version.
4. The queue and rule displays identify the style, for example **Move To · Run**, so the child can see which movement was chosen.
5. The existing waypoint drawing, re-placement, and path preview continue to represent the destination independently of the style.
6. In DIRECT mode, the child chooses **Move To**, places the destination, then chooses a style from the follow-up **Movement** dropdown and commits with **Add Move To**. **Cancel** discards the draft.
7. The first DIRECT-mode draft for a stickman defaults to Walk; later drafts use that stickman's last successfully committed style for the current open scene. Canceling never updates the remembered style.
## Run animation target
The target is a natural human run expressed through the project's simple stickman figure. The run should have recognizable gait phases: a foot contact and weight-bearing phase, push-off, a brief airborne phase, leg recovery, and the next contact. Arm swing should counter the legs, with a modest forward lean and controlled body bounce that support the motion without distracting from it.
The motion should be visibly different from walking. Its cycle cadence and foot travel should agree with the Run pace so the feet do not skate over level ground or pass through the floor. Entering and leaving the loop should feel smooth, including when the destination is close enough for only part of a cycle. The animation should read correctly while facing either direction.
The project already has a tool script that bakes walk animations from authored IK-target keyframes. This is a suitable starting point for a generated run clip, with visual tuning expected. Here, “generated” means authored pose/keyframe data is baked into an animation by the project tool; the brief does not assume automatic motion capture or an AI-generated gait.
## Story and directing value
Walk supports calm travel, exploration, and approaching something. Run supports urgency, chasing, escaping, and energetic entrances. Keeping both styles on Move To lets children reuse destinations and path editing while changing the performance of the character.
## Compatibility and project fit
The current action is `walk_to`. Existing `.scene` files and rules should load transparently as **Move To · Walk**, preserving targets, queue order, trigger behavior, and waypoint editing. Saving after load may write the new canonical form. Children should not need to repair or re-author existing stories.
Relevant current behavior and references:
- `scripts/stage/action_registry.gd` registers action names, summaries, and rule/queue conversions.
- `scripts/editors/stage/action_editor.gd` edits actions and captures destination clicks.
- `scripts/stage/stage_scene_io.gd` validates and serializes saved stage actions.
- `scripts/editors/stage/sandbox_stage.gd` builds direct/rule actions and converts rule actions for playback.
- `scripts/stage/stage_director_visuals.gd` draws waypoint paths and action markers.
- `scripts/characters/stickman/stickman_action_runner.gd` runs queued actions; `scripts/characters/stickman/stickman_locomotion.gd` currently owns navigation, walking animation, and terrain following.
- `scripts/tools/create_animations.gd` bakes the current walk clips and stand-up reference animation.
- `docs/specs/phase_3a_spec.md`, `docs/specs/phase_3c_editor_spec.md`, `docs/specs/phase_8_rig_modularization.md`, and `docs/specs/phase_12_live_director.md` describe the existing movement, director, and action workflows.
## Success criteria
- A child can add or edit Move To, choose Walk or Run for that action, and set its destination through the familiar click-on-stage flow.
- In DIRECT mode, destination placement comes before movement-style selection; the child can commit or cancel the staged Move To draft without reopening an action menu.
- DIRECT mode defaults to Walk per stickman and remembers the last committed style only for the lifetime of the open scene.
- Walk is the default, and unedited legacy `walk_to` actions keep walking.
- Walk and Run have distinct, understandable movement paces; choosing Run makes the character travel faster and show a recognizable run cycle.
- The run includes visible support, push-off, flight, recovery, and counter-swinging arms; on level ground, foot contact looks stable and the feet do not visibly skate or penetrate the surface.
- Run starts and finishes cleanly at both short and long destinations, and faces correctly in both directions.
- Queue actions, rule actions, summaries, action editing, waypoint re-placement, and saved/loaded scenes agree on the chosen style and destination.
- Existing arrival, action completion, interruption, and queue behavior remains understandable and intact.
## Scope and exclusions
Included:
- Rename the child-facing concept from Walk To to Move To across relevant authoring, queue/rule summaries, and waypoint interactions.
- Add per-action Walk/Run choice with Walk as the default and style-specific fixed paces.
- Add a destination-first DIRECT-mode Move To draft with an extensible Movement dropdown, Add Move To/Cancel controls, and per-stickman last-committed-style memory for the open scene.
- Add a generated, tuned run cycle and connect it to Run movement.
- Preserve compatibility for existing `walk_to` scene and rule data.
- Validate the animation against existing facing and grounded terrain behavior.
Not included in this phase:
- Fly or additional movement styles.
- Numeric speed controls or user-authored speed presets.
- New pathfinding, obstacle avoidance, slope navigation, or physically simulated locomotion.
- Replacing the stickman art/rig with motion capture.
## Dependencies and risks
- The style must survive all current conversions between queue actions, rule actions, runtime execution, and stage-file serialization.
- Old `walk_to` data must be recognized before new action validation rejects unknown types; migration must preserve waypoint identity and action/event semantics.
- The run cycle must be tuned together with its travel pace and current foot/terrain handling. A convincing in-place loop alone may still look slippery when the root travels.
- Arrival snapping and interruption/cancellation can stop a cycle between gait phases; the architect and developer should decide how to settle into the standing pose without visible popping.
- Current waypoints and event rules refer to movement actions. Renaming the action needs a consistent user-facing summary and migration story throughout both systems.
## Open questions for the spec-pipeline
- How should `ActionEditor` present Walk/Run: two large choice buttons, a segmented control, or another clear kid-facing selector? (The separate DIRECT-mode quick action uses the approved destination-first dropdown.)
- How should `walk_to` be canonicalized so old queue actions, rule actions, triggers that refer to action completion, and saved files retain their intended behavior?
- What run-cycle timing and foot-contact strategy best match the existing IK rig, terrain following, and fixed style pace?
- What transition behavior should apply when Run starts, reaches a short destination, or is interrupted by another action?
- Which level surfaces and terrain cases are required for first-pass visual verification?