- 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.
@@ -69,6 +69,8 @@ This document tracks known technical debt, optimization opportunities, and minor
| 57 | **Speech composition must temporarily own stage input** — normal scene controls can otherwise select or alter characters and props while the user is editing speech. | Medium | Planned | Gate stage object interactions while the composer is open; keep speech bubble selection/drag, explicit speech placement, and camera-only navigation available. A non-bubble stage click clears the token target but must not activate the object underneath. Verify deferred token clicks and drag thresholds. See `docs/specs/speech_style_toolbar_refinements.md`. (2026-09-28) |
| 58 | **Speech-wide Show settings retain per-bubble render copies** — action-level reveal and motion settings are mirrored into every bubble visual for the current renderer and duration calculations. | Low | Planned | `SpeechPayload.normalize()` is the synchronization boundary; scene and rule encoders must retain the new action-level fields. Older mixed bubble settings intentionally migrate from the first bubble when edited, so later distinct motion/reveal choices are no longer expressible in the group model. If a future renderer reads action-level settings directly, the duplicate visual keys can be removed in a versioned payload migration. See `docs/specs/speech_whole_sequence_show.md`. (2026-09-30) |
| 59 | **Stage-only speech edits remain drafts until session completion** — a recoverable draft can differ from its queue/rule target while the child is styling. | Medium | Planned | Done speech is the single validated in-memory commit boundary. A Scene Save request during composition is deferred until the user explicitly completes speech; it never commits implicitly or writes the stale queue/rule target. Cancel speech confirms before discarding an edited draft. This avoids premature persistence of blank bubbles and stale scene data. Recovery remains draft-only. See `docs/specs/speech_stage_only_editor.md`. (2026-09-30) |
| 60 | **Run contact timing and baked IK poses share authored gait facts** — clip duration/contact phases must agree with locomotion's stance weights and fixed travel pace. | Medium | Planned | Phase 16 keeps one locomotion controller and an authored Run clip. Tune the speed, cycle duration, foot travel, and contact windows together; flight windows must release both foot locks. The generator and runtime each need phase data, so a future data-driven gait asset may be useful if more styles are added. See `docs/specs/phase_16_running_stickman.md`. (2026-10-03) |
| 61 | **Move To migration crosses action and trigger identities** — an old `walk_to` completion filter can silently stop matching after an action becomes `move_to`. | High | Planned | Phase 16 canonicalizes old queue/rule movement actions and `action_finished.params.action_type` filters before validation, while preserving actor IDs, waypoint positions, action order, and rule IDs. Verify old scenes at the boundary and retain the `StickmanRig.walk_to` scripting facade. See `docs/specs/phase_16_running_stickman.md`. (2026-10-03) |
---
@@ -145,5 +147,6 @@ This document tracks known technical debt, optimization opportunities, and minor
| 2026-10-01 | Comic Chain speech behavior revised after preview feedback (`docs/specs/speech_comic_chain_layout.md`): Comic chain is the third persistent **Show bubbles** choice and builds cumulatively, while Stack/Same spot remain placement actions. Entering the mode applies measured Stack positions. Later balloon connectors use blunt joins drawn behind predecessor frames; Think uses dots. Older `bubble_layout: comic_chain` payloads migrate to `arrangement: comic_chain`. |
| 2026-10-03 | Speech bubble order badges now use selection-independent positions (`docs/specs/speech_badge_stability.md`). Badge clustering responds to actual proximity; Show Speech and Speech Style panels avoid the stable badge bounds instead of moving badges when selection changes. |
| 2026-10-03 | Speech badge clusters now also form when bubble frames intersect. For overlapping bubbles, the sorted badge row anchors above the largest frame, preventing a smaller bubble's badge from appearing through the larger bubble's text. |
| 2026-10-03 | Phase 16 Move To/Run architecture specification written for user sign-off (`docs/specs/phase_16_running_stickman.md`). Approved canonical `move_to` plus Walk/Run style, migration of old movement and completion-filter types, a short arrival settle, and visual verification across Ground, Ramp, Step, seams, edges, and existing fall/landing behavior. Logged #60 for duplicated gait phase facts and #61 for the migration boundary. No implementation code changed. |
@@ -6,13 +6,13 @@ This is the live list of future Stickman Studio feature ideas. Designer maintain
Priorities are recommendations for discussion, not a committed release schedule. Keep higher-priority items first and explain the reason for each ranking.
No feature ideas have been captured yet.
1. **Move To with selectable movement styles** — **Status:** Verified · **Suggested priority:** High. **Intent:** Give a stickman one destination action with a per-action style choice, starting with Walk (default) and Run; leave room for future styles like Fly. Use a fixed pace for each style initially, matched to its animation. **Rationale:** Children can direct the same route at different paces without choosing duplicate action types. The first run cycle should read as a believable human gait on the existing stickman rig, with clear foot contact and push-off, a flight phase, alternating arm swing, and cadence matched to travel speed. **Connections:** [Phase 16 design brief](../plans/phase_16_running_stickman.md), `scripts/stage/action_registry.gd`, `scripts/editors/stage/action_editor.gd`, `scripts/stage/stage_scene_io.gd`, `scripts/characters/stickman/stickman_locomotion.gd`, `scripts/tools/create_animations.gd`; existing scenes and rules currently store `walk_to` and should continue as Move To · Walk.
## Entry format
For each feature, record:
- **Status:** Idea, Exploring, Planned, or Parked
- **Status:** Idea, Exploring, Planned, Verified, or Parked
- **Suggested priority:** High, Medium, or Low
- **Intent:** The user goal or experience the feature should support
- **Rationale:** Why it may be valuable and how it fits the project
> **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?
> **Status:** Architecture specification; the DIRECT-mode target-first quick action and its readability pass are implemented. Remaining Phase 16 behavior and visual checks are listed in section 6.
> **Inputs:**`docs/plans/phase_16_running_stickman.md`, accepted ActionEditor UI proposal (Walk/Run buttons), approved DIRECT-mode dropdown flow, and the Phase 1a architecture decisions.
> **Target:** Godot 4.7.1 Sandbox Stage and the existing modular stickman rig.
## 1. Goal and decisions
A child chooses Walk or Run on each **Move To** action, places one destination, and sees the style in queue and rule summaries. Run has a faster fixed pace and its own grounded, pushing, airborne, and recovering poses. The destination, waypoint identity, navigation behavior, and arrival trigger remain independent of style.
Approved decisions:
1. The canonical action type is `move_to`, with persisted `style: "walk" | "run"`. New actions use it. Loading old `walk_to` actions and action-completion filters converts them to `move_to`/Walk before validation.
2. Normal arrival has a brief pose settle. The physical arrival event fires when the root reaches the target; action completion fires when the settle ends. Ragdoll and other interruptions can preempt it.
3. Visual verification covers **every existing terrain shape** (Ground, Ramp, Step), their seams and edges, both facing directions, and existing ledge/fall/landing behavior. This does not add pathfinding or slope navigation.
The Walk/Run choice is a string in saved dictionaries because `.scene` is JSON. A new `Resource` hierarchy or a second navigation component would add conversions and scene dependencies to a two-choice field. The existing `ActionRegistry`, `StageSceneIO`, `StickmanActionRunner`, and `StickmanLocomotion` remain the ownership boundaries.
The saved queue entry is `{"type":"move_to","target":{"x":640,"y":385},"style":"run"}`. The saved rule entry has `type: "move_to"`, its existing `target_id` actor reference, and `params.target` as an `{x,y}` object plus `params.style`. `target` remains a feet/ground destination, as in the current walking action. Neither form stores a numeric pace. Existing `.scene``FILE_VERSION` can remain `1.1` because these fields are additive and old types are handled explicitly at decode; no other document shape changes.
Replace the menu template for `walk_to` with one `move_to` template labeled **Move To**, with `target` position and `style` choice (default Walk). Keep `walk_to` out of `types()` so children never add the legacy type. Define statically typed helpers:
`checked_style` accepts exactly the two lowercase strings; missing or null means Walk for legacy data. An explicit unknown or wrong-type style is invalid at the file boundary and must not silently become Walk. `is_move_action()` accepts `move_to` and legacy `walk_to` at raw-input boundaries. `to_rule_action()` and `from_rule_action()` always produce canonical `move_to` with both `target` and `style`. `summarize()` produces `Move To · Walk` or `Move To · Run` for flat and nested rule shapes without exposing coordinates. Completion-filter labels use the same child-facing **Move To** wording.
`_decode_flat_action()` canonicalizes `walk_to`**before**`ActionRegistry.has_type()` rejects unknown action types, validates the target vector, supplies Walk when style is absent, and rejects explicit invalid styles. `_encode_flat_action()` writes only canonical `move_to`; it also accepts an in-memory legacy `walk_to` input and normalizes it. Rule encode/decode must continue using the registry's flat converters so queue and rule payloads cannot diverge. No migration changes action order, rule ID, actor reference, or waypoint coordinates.
The `action_finished` trigger stores its filter in `trigger.params.action_type`. `_decode_trigger()` maps a legacy filter value of `walk_to` to `move_to`; `_encode_trigger()` canonicalizes it on save. `SandboxStage._rule_matches()` also compares canonicalized filter/action types so an in-memory rule supplied by a script retains its behavior. `arrived_at_waypoint` triggers keep matching `waypoint_pos` and fire for either style. The empty action filter continues to mean “any action.”
### 2.3 Runtime and programmatic compatibility
`StickmanActionRunner` should normalize any legacy action it receives from a programmatic queue or reactive rule before execution and emission, so `action_started`/`action_finished` report canonical `move_to` consistently. `StickmanRig.walk_to(target, speed)` stays as the public direct Walk API and may retain its positive speed override for existing scripts. The child-authored `move_to` action never contains `speed`: Walk uses the existing default pace and Run uses its paired fixed pace. Legacy `walk_to` with an explicit positive `speed` supplied programmatically can retain that override for compatibility during execution; `.scene` serialization remains style-only. Do not let that compatibility case create a speed control in the editor.
Keep the existing `committed(action: Dictionary)`, `cancelled()`, and `target_requested()` signals. Its committed Move To dictionary is fully typed by convention: `type: String`, `target: Vector2`, `style: String`. Add a private `_move_style: String = ActionRegistry.WALK`; `open_new()` resets it to Walk, and `open_edit(action)` reads canonical or legacy movement data, selecting Run when appropriate. `set_walk_target(pos: Vector2)` can remain as a compatibility method name, but it changes only the destination and must preserve `_move_style`. Cancel and Escape discard the draft without mutating a queue or rule action.
Layout inside `_params_box` for Move To:
```text
ActionEditor PopupPanel
└─ MarginContainer / VBoxContainer
├─ Type: [Move To ▾]
├─ VBoxContainer (Move To parameters)
│ ├─ Label: How should they move?
│ ├─ HBoxContainer: [🚶 Walk] [🏃 Run]
│ └─ HBoxContainer: Place to go: / Place chosen [🚩 Choose a Place / Change Place]
└─ HBoxContainer: [Cancel] [Done]
```
The Walk and Run buttons are equal-width choices, each at least 44×44 logical pixels. If the available popup width cannot contain both at that size, stack them vertically without shrinking the hit areas. Use `SandboxTheme`'s DIRECT amber accent, a pressed state, and a visible border for the selected option; use the theme surface for the other. Hover and keyboard focus remain visible, and text/icon/pressed state convey selection without color alone. Footer buttons are at least 44 px high. The existing theme font and emoji font pipeline applies to new controls. Keep the popup's current minimum dialog size unless the controls actually require a larger theme-driven size.
The destination row uses **Place to go:** and **🚩 Choose a Place** when unset, then **Place chosen** and **🚩 Change Place** once set. It never shows raw coordinates. Changing Walk/Run retains the destination. **Done** with no destination starts placement. Explicit placement hides the popup, retains the draft style and old target, and restores the popup after a valid stage click. The stage cursor pill says `🚩 Click where they should walk` or `🚩 Click where they should run`; existing line/ghost, green valid/red invalid target feedback, placement cursor, and prominent cancel action remain. Canceling capture reopens the popup with the old target and style. The final **Done** commits once.
All child-facing action menus say **Move To**. In DIRECT mode, the user chooses the single **Move To** command and places the destination first. That click stages the target and opens a compact follow-up panel with a **Movement** dropdown, **Add Move To**, and **Cancel**; no queue action is added until Add is selected. The dropdown is populated from the registered movement-style choices (currently Walk and Run), defaults to Walk for a stickman's first draft, and remembers the last successfully committed style per stickman while the scene is open. Cancel, Escape, right-click, popup dismissal, and leaving DIRECT mode discard the draft; canceled choices do not update the remembered style. The readability-approved panel is 380×172 px, with a 23 pt label, 25 pt selector/style emoji, 22 pt buttons, a 210×54 px selector, and 52 px-high buttons.
Queue Add/Insert opens `ActionEditor` and permits either style. Queue Edit and waypoint **Edit this Move** must open the editor with the existing target and style; the current `_begin_walk_edit()` stage-only shortcut bypasses pace selection and should be replaced or reserved solely for a clearly separate Change Place gesture. Resolve the edited action by existing `action_id` at commit, preserving action identity and consumed-action restrictions. Waypoint **Erase this Move** removes that same action. Marker hit testing, path drawing, and target re-placement work for both styles.
The rule-builder quick path currently creates a `walk_to` consequence and captures a position without opening `ActionEditor`. Route Move To through the shared editor after actor selection (or an equivalent shared draft using that same control), then put the returned target/style into `params` and resume the existing Add another/finish rule flow. Existing rule Edit/Add paths through `ActionRegistry` and `ActionEditor` must preserve the style in both directions. `SandboxStage._action_for_rig()` should delegate Move To conversion to `ActionRegistry.from_rule_action()` so reactive playback does not drop style. Normal direct movement remains Walk.
`StageDirectorVisuals` recognizes canonical `move_to` for every waypoint/path/hit-test branch and uses `ActionRegistry.summarize()` or equivalent for `Move To · Walk/Run` queue and rule descriptions. `WaypointContext` uses **Edit this Move** and **Erase this Move**. The marker itself represents the destination only and has no Walk/Run icon. Rule completion filters present Move To as one action type; both styles match it. Apply the same child-facing words to status hints and the rule builder. DIRECT-mode style choices are remembered only for the current open scene and are not serialized.
ST -->|queue and rule display| DV[StageDirectorVisuals]
```
## 4. Locomotion, gait, and terrain
### 4.1 Ownership and API
`StickmanActionRunner` keeps the existing action queue, `ActionPhase.WALKING`, status, interruption, and `action_started`/`action_finished` signals. It passes the normalized style to `StickmanLocomotion`. `StickmanLocomotion extends Node` keeps the single `NavigationAgent2D`, target/arrival logic, terrain following, and foot contacts. Add a typed movement entry such as:
The existing `walk_to(target: Vector2, speed: float = -1.0) -> bool` delegates to `move_to(..., WALK, speed)` for `StickmanRig` and older callers. Keep `consume_walk_completed()` and `cancel_walk()` compatibility names if changing them would cause unnecessary API churn; their behavior covers both styles. Use an active style field and one style table/typed constants for clip name, default pace, cycle duration, and contact windows. This keeps travel speed, animation cadence, and contact logic paired at one boundary. `NavigationAgent2D.max_speed` and root movement use the same selected pace. Start with Walk at the existing 300 px/s and a Run candidate around 500 px/s, then tune Run pace and cycle together against visible foot travel; the final constants belong in locomotion, not in the saved action or UI theme.
The current `_stance_weight()` assumes a 0.8-second Walk cosine. Retain that behavior for Walk if it remains visually correct. Run uses an explicit repeating contact schedule aligned with its authored clip. As an initial 0.64-second two-step cycle, put right support at approximately 0.00–0.20 s, left support at 0.32–0.52 s, and brief flight at 0.20–0.32 and 0.52–0.64 s. Smooth the edge of each contact window; return zero support for both feet in flight. Tuning may change those numbers, but the clip and contact windows must change together. Reset foot locks when a foot leaves support; the terrain solver must not pin a recovering or airborne foot to the ground. Keep the existing collision guard against foot penetration when a surface is present.
### 4.2 Baked animation and facing
`scripts/tools/create_animations.gd` remains the authored IK keyframe baker. Add a dedicated Run pose sequence and bake looped `run_right` (and `run_left` only if the existing asset convention requires it) into the rig's `AnimationLibrary` in `scenes/characters/stickman/stickman_rig.tscn`. The authored cycle has contact/weight-bearing, push-off, a short flight, leg recovery, opposite contact, counter-swinging arms, modest forward lean, and controlled torso/head bounce. The final keyframe matches the first for seamless looping. It must be an actual distinct gait, not Walk played faster. The generated clip in the committed rig scene is the runtime asset; the tool source and baked scene must agree.
Runtime walking currently uses `walk_right` for both directions after changing `StickmanRig.FacingProfile`; preserve that proven facing policy for Run if it mirrors the authored pose correctly. Avoid a second independent flip of run marker X values, which would invert the gait twice. Check both directions in the Sandbox Stage, including held props and hand-target ownership if a prop is present.
### 4.3 Start, arrival, cancellation, and terrain state
Starting Move To selects the style's clip, sets facing from target X, enables limb modifiers, clears stale foot locks/settle state, and begins the existing nav/direct fallback. For a target already inside `ARRIVE_DISTANCE`, skip gait playback, snap to the target, emit one arrival, and finish without a visible partial stride. For other short targets, allow a partial cycle and settle from its actual final IK pose.
On physical arrival, keep the existing final-X snap and emit `arrived(target)` exactly once. Stop root travel and smoothly interpolate the six IK markers and torso rotation toward the standing pose for roughly 0.12–0.18 seconds, using the current pose as the start; then set the existing completion flag that `StickmanActionRunner` consumes. The settle is part of the action so a following queue item does not fight its marker writes. During a pause, its timer stays paused with the runner. Repeated completion checks must not emit arrival again. If terrain following is in a hard landing, defer movement and settle according to the existing landing barrier rather than writing competing foot targets.
Interruption cancels gait/settle ownership and releases contact locks. A ragdoll takeover preserves the current solved pose for the established instant physical handoff; it must not first force a standing tween. An interruption that leaves the rig animated can blend to idle only while no newer action owns the markers. Interrupted actions keep the existing interrupted status and emit no `action_finished`. The style and target in authored queue data remain unchanged through pause/resume, reorder, reactive insertion, or target edit.
`StickmanLocomotion` continues its ground probing and existing airborne/landing state machine. A gait's brief authored flight on supported terrain is separate from an actual ledge fall: the Run contact schedule releases foot support without entering `TerrainMotion.AIRBORNE`; the existing ledge probe controls real falls and pauses/resumes the active Run clip as it does Walk. Ground, Ramp, and Step must be checked across up/down travel, transitions at seams, and edge departures. Any needed correction should stay in the existing terrain-following component; adding a new path solver is outside Phase 16.
```mermaid
stateDiagram-v2
[*] --> Moving: Move To begins, target beyond arrival radius
[*] --> Arrived: target already reached
Moving --> Moving: nav/direct travel + gait cycle
Moving --> Arrived: final root snap
Arrived --> Settling: emit arrived once
Settling --> Completed: standing pose reached; completion flag
| `scripts/characters/stickman/stickman_rig.gd` — `StickmanRig` | Retain public Walk facade; add a Move facade only if the runner needs it. |
| `scripts/tools/create_animations.gd` and `scenes/characters/stickman/stickman_rig.tscn` | Author and bake the Run clip into the committed rig asset. |
| `sandbox_theme.json` / `scripts/stage/sandbox_theme.gd` | Use existing DIRECT accent and dialog tokens; add only the minimum style overrides needed for large selected/focused buttons. |
No new autoload, global signal bus, node layer, persisted numeric speed, or separate Run action type is required.
## 6. Implementation and verification contract
Implementation order: (1) registry and I/O migration; (2) editor, stage routes, and visuals; (3) authored Run clip and locomotion/contact timing; (4) arrival/interruption settle; (5) focused verification and visual tuning. The developer should run headless syntax verification as required by the spec-pipeline, then fix parse errors immediately. Add focused regression coverage where it checks distinct behaviors rather than repeating implementation internals.
Required behavior checks:
1. Load a legacy scene with queued `walk_to`, rule consequence `walk_to`, and an `action_finished` trigger filtered to `walk_to`. Targets, order, actor IDs, waypoint rules, and completion behavior survive; saving writes canonical `move_to`/Walk throughout.
2. Queue and rule Walk/Run actions round-trip through flat/nested conversions and `.scene` save/load. Invalid explicit styles are rejected at the file boundary. New/direct actions default to Walk.
- In DIRECT mode, verify destination-first staging, dropdown choice, Add and every draft-cancel path (Cancel, Escape, right-click, popup dismissal, and mode exit). Confirm the first choice defaults to Walk, a successfully committed choice is remembered per stickman in the open scene, and a canceled choice is not remembered.
3. Add/edit from queue and waypoint menu, and add/edit from rule builder. The style survives target capture, target change, capture cancel, editor cancel, and final commit. Editing a consumed action remains blocked. Summaries say `Move To · Walk/Run` and waypoint markers remain destination-only.
4. Run visibly exceeds Walk's pace while its foot cycle tracks root travel on a long level path. Verify short (< one cycle) and zero-distance targets, one arrival and one completion, and no skating or penetration at support.
5. Check both facing directions on Ground, Ramp, and Step; travel over joins and on upward/downward surfaces; ledge fall and landing; reactive interruption, ragdoll takeover, queue pause/resume, and a following queued action. Flight frames show both feet released from contact while a true ledge fall still uses terrain airborne behavior.
The Sandbox Stage CLI scene playback in `AGENTS.md` is the visual verification route. Record the final tuned Run speed/cycle/contact windows and any terrain limitation observed during editor review. Phase 3 ends with a user hand-off for Godot Editor verification; documentation updates follow only after the user confirms the feature works.
## 7. Trade-offs and scope
- A canonical `move_to` type requires coordinated migration in serialization, trigger filters, editor branches, and waypoint visuals. It gives future movement styles one destination-oriented action and avoids carrying a misleading `walk_to` identifier indefinitely.
- A fixed style table keeps pace and gait together and avoids exposing a numeric control to children. Existing programmatic `walk_to(speed)` remains a compatibility route.
- Explicit Run contact windows duplicate a small amount of gait timing data between the animation baker and locomotion. This is preferable to pretending Run follows the Walk cosine stance; the values must be tuned and reviewed together.
- A short settle makes partial cycles readable but delays `action_finished` slightly after physical `arrived`. The events retain distinct meanings and each fires once.
- Full Ground/Ramp/Step visual coverage may require tuning terrain foot placement as well as the clip. It does not authorize new slope pathfinding, dynamic avoidance, or physically simulated locomotion.
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
