stickman/docs/specs/phase_11_prop_interactions.md

# Phase 11 — Prop Interactions and Event Triggers

Status: **Approved for implementation (2026-09-24).**

Throw UX amendment: **Approved for implementation (2026-09-25).**

Throw landing-target amendment: **Approved for implementation (2026-09-25).**

Queue-aware throw-preview amendment: **Approved for implementation (2026-09-25).**

Source: `docs/archive/plans/PHASE_11_PROP_INTERACTIONS.md`. This spec keeps the requested
pickup, drop, throw, ragdoll handoff, and “When…” features while adapting them to
the current Sandbox Stage architecture and closing the design gaps identified
during review.

## 1. Approved design decisions

1. A throw action stores a **fixed stage-world target position**. At run time the
   trajectory starts at the actor’s current held-prop transform and aims at
   that saved point. Actor-relative throws are deferred.
2. Phase 11 supports **one prop held in one compatible hand per stickman**.
   Two-handed grips and holding multiple props are deferred.
3. Each placed prop has a **persistent per-instance stage ID**. The ID is
   separate from the asset’s `spawn_id` and from Godot’s session-only instance
   ID. Duplicates of the same library prop therefore remain distinguishable.

## 1.1 Previously approved throw UX amendment (2026-09-25; superseded by §1.2)

This amendment refines the approved throw action and does not add fields to its
saved payload. It supersedes the exact-landing interpretation of decision 1
and §3.3 while keeping `target_position` as a fixed stage-world point.

- **Cursor meaning:** the saved point is an aim-and-power handle. At release,
  the vector from the predicted release point to that handle sets the launch
  bearing; its length sets launch speed. The prop is allowed to land short of
  or beyond the cursor as gravity and collisions dictate.
- **Power curve:** map cursor distance monotonically and smoothly to launch
  speed, clamp at a maximum, and keep the limits in one set of tunable
  constants. Initial tuning recommendation: 300 px/s at minimum input, rising
  to a 1,250 px/s cap at 700 px of cursor distance. Distances beyond that stay
  at the cap. Retain the existing near-zero-distance no-op guard.
- **Prediction:** preview and execution use the same release point, cursor
  vector, power mapping, velocity, gravity, and prop gravity scale. Draw the
  sampled ballistic path and show the cursor separately from the predicted
  impact point. Use the held prop's collision shape to estimate its first
  world collision along the path, ignoring the actor and held prop; if no
  collision occurs within the existing 2.0-second maximum horizon, mark the
  horizon endpoint. This remains an estimate for moving bodies.
- **Overhand motion:** replace the short backward/upward wrist offset with a
  head-relative IK arc. Lift the held prop behind and beside the head, carry
  it above the crown, then sweep forward over the head. Release during the
  forward sweep and finish with a follow-through. Derive points from the live
  rig pose and facing, and clamp them within the selected arm's reachable
  length so the IK solver does not snap or overextend. A small torso lean may
  support the motion; do not reposition the legs.
- **Release origin:** calculate the preview from the prop's predicted
  attachment transform at the release waypoint, not its pre-windup transform.
  Recompute the same origin at the release frame before applying the bounded
  launch velocity. Keep the action payload as `{ type, target_position }`;
  power is derived at runtime, so existing saved queues remain readable.

Acceptance checks for the amendment: launch speed increases monotonically with
cursor distance until the cap; launch bearing follows the cursor vector;
preview points agree with the chosen release pose and solver; the overhand
hand path clears the head and remains within arm reach; release happens during
the forward sweep; the predicted impact marker is distinct from the cursor.

## 1.2 Approved throw landing-target amendment (2026-09-25)

This approved amendment supersedes §1.1's aim-and-power mapping. It keeps the
saved `{ type, target_position }` payload and treats its fixed stage-world point
as the requested landing/aim point.

- **Range cap:** cap the raw cursor point to a 3,600 px radius from the
  stickman's root position at preview time and again when the throw action
  starts. If it is farther away, project it onto that radius along the
  root-to-cursor vector. The root is the intuitive range reference; the actual
  ballistic path still starts at the prop's predicted hand-release transform.
  A cursor within the existing 4 px no-op threshold of the root skips the
  throw and leaves the prop held.
  Keep the raw saved world point unchanged, so queued actions remain readable.
  When a queued actor has moved by the time the throw starts, recompute only
  the effective capped point from its current root position.
- **Target solver:** in unobstructed flight, solve the launch velocity so the
  prop reaches the effective target on the descending part of its arc. Continue
  using project gravity and the prop's `gravity_scale`. Search flight times
  from 0.35 s to the 2.0 s horizon and select the shortest valid time whose
  launch speed does not exceed 2,100 px/s. This favors a fast trajectory while
  preserving the selected endpoint. If no valid candidate exists, show the
  target as unreachable and skip the throw without releasing the prop.
- **Preview and physical collisions:** preview and execution use the same
  effective target, release transform, selected flight time, velocity, gravity,
  and prop gravity scale. Shape-cast the held prop along the path, excluding
  the thrower's collision bodies and the prop itself. A world collision before
  the target ends the guide at its first safe contact point. If no collision
  occurs before the requested endpoint, the guide reaches that endpoint. If
  the point is in open air, the prop continues under normal physics after
  passing it; the guide marks the requested point rather than the rest of that
  continuing flight. Moving-body impacts remain an estimate.
- **Target markers:** show the raw cursor separately from the effective
  capped target. When a collision truncates the guide before that target, show
  the collision point separately as well. Thus a cursor at 1,200 px from the
  root shows an effective target at 3,600 px, while retaining the cursor marker
  at 1,200 px.
- **Prop weight/material:** keep one shared range and speed policy in this
  change. Physical mass does not change gravitational acceleration. A future
  balance pass may add an explicit gameplay throwability factor derived from
  prop weight or material; it must not silently change the physics mass or
  existing `.prop` schema.

The previously approved overhand IK path, its reach clamp, forward-sweep
release, follow-through, and release-origin prediction remain in force.

Acceptance checks for this amendment: a target within 3,600 px remains exact;
farther targets clamp to a 3,600 px radius from the current stickman root; the
cursor and effective target markers remain distinct; the solver chooses the
shortest valid descending arc under the speed cap; earlier collisions truncate
the guide; unreachable targets release no prop; and queued throws preserve the
raw fixed world point while recomputing a bound when necessary.

## 1.3 Approved queue-aware throw-planning preview (2026-09-25)

At queue-edit time, a throw may follow a queued pickup that has not executed yet.
The preview must model that planned held-prop state without mutating the live
rig, prop, queue, reservations, or physics. This is a planning estimate; runtime
continues to solve from the actual held prop and release transform.

- **Queue prefix:** for an edited throw, inspect authored actions before its
  stable action ID. For a newly appended queue or Direct throw, inspect the
  current queue as the prefix. Start from the rig's current held-prop state,
  then fold only pending actions in order: a valid `pick_up_prop` selects its
  stage prop ID and requested hand; `drop_prop` or `throw_prop` clears the
  virtual held prop. Completed actions are already reflected in live state and
  are not replayed. A missing or incompatible prop leaves the preview
  unavailable.
- **Predicted pickup pose:** use the same grip-selection and pickup stand-off
  calculations as runtime. For an out-of-reach pickup, predict the approach
  root position from the selected grip and `APPROACH_GAP`; also account for
  preceding authored `walk_to` targets. This predicts the ordinary queue case
  without starting locomotion or attaching the prop. If an earlier action makes
  the future actor or prop transform indeterminate (for example, an active
  ragdoll or a prior physical throw), do not present the path as exact; show a
  planning/uncertain status and use the best available pose estimate.
- **Pure preview context:** pass the resolved prop, chosen grip/hand, and
  predicted root transform as explicit preview inputs to the existing
  gravity-aware solver and collision shape cast. Do not temporarily set the
  interactor's `_held_prop`, reserve the prop, change the hand target, or move
  either scene object to make the preview work.
- **Feedback:** show a plan-preview hint such as “Assumes Step 2 pickup
  succeeds.” Keep raw cursor, capped target, and collision markers. Reserve red
  for a genuinely unreachable solved target; if no planned or live prop can be
  resolved, show a neutral explanation instead of a misleading straight red
  trajectory. Preview status must update as the queue prefix or target changes.
- **Scope:** queue edit, queue append, and Direct throw captures have a known
  authored prefix and use this model. Rule-authored throws have no fixed action
  prefix, so they use the live held-prop state and report preview unavailable
  when no prop is currently held.

Acceptance checks for this amendment: at `t = 0`, editing a pending throw after
a pending pickup displays a gravity/collision-aware planning guide; the preview
does not change prop ownership, transforms, reservations, the queue, or live
physics; a preceding drop/throw clears the inferred held prop; the predicted
pickup approach moves the guide origin; and actual execution recomputes the
trajectory from the real release transform. A missing, invalid, or ambiguous
prefix never masquerades as a solver-unreachable red trajectory.

## 2. Existing contracts and scope

- `StickmanRig` is the public runtime facade. It already composes separate
  Locomotion, Ragdoll, and ActionRunner components under `RigComponents`.
- `StickmanActionRunner` owns authored queue IDs and emits one start/finish
  pair per authored action. Walking is currently a normal queue action.
  Pickup’s internal approach must not be inserted into the authored queue:
  pickup remains one authored action, with one action ID and one completion.
- `StickmanLocomotion.walk_to()` drives the existing navigation/terrain
  behavior, but its final root displacement is horizontal. Prop approach must
  choose a grounded stand point and verify hand reach; it cannot assume
  arbitrary 2D walking.
- `PropAnchorData` already normalizes grip roles, allowed hands, local
  transforms, and attachment-transform math. `PropFile` already serializes
  anchors, but `PropLibrary` currently drops them and `StageSpawner` does not
  pass them into `PropBlock`. Phase 11 must close that runtime data path.
- `StickmanRig` uses animated IK target markers. A prop hold/throw pose needs a
  single explicit owner for the active hand target after animation updates and
  before the IK solve. Do not let an AnimationPlayer track and the interaction
  code fight over the same target.
- Rule/action templates live in `TriggerRegistry` and `ActionRegistry`.
  `SandboxStage` handles rule matching and event dispatch; there is no current
  `StageEventRegistry`. Extend these existing paths.
- `PropBlock.begin_play_instance_scale()` moves authored instance scale into
  its visuals/collision during PLAY. Grip alignment must use that effective
  scale, not assume the RigidBody root retains the EDIT scale.

In scope: one-hand pickup, drop, and targeted throw; automatic approach;
prop/rig state handoff; stage-scene persistence for prop identity and queue
payloads; Direct and queue/rule authoring; and three edge-triggered prop rules.

Out of scope: two-hand or multiple-prop holding; torso/leg bending to improve
pickup reach; prop-to-prop mounting; melee hitboxes; moving-target tracking;
actor-relative throws; a general-purpose event bus rewrite; and document-wide
undo/redo.

## 3. Runtime ownership and action lifecycle

Add a `StickmanPropInteractor` component under each rig’s `RigComponents`.
It owns the selected hand, held prop reference, chosen grip ID, reservation,
saved collision/freeze settings, active interaction phase, and recent held
transform samples. `StickmanRig` exposes a narrow facade to the ActionRunner
and calls the interactor’s ragdoll/reset hooks. The ActionRunner remains the
owner of authored queue progression; it delegates prop work to the interactor
and waits in a prop-interaction phase until that action succeeds, fails, or is
cancelled.

The interaction state is:

| State | Contract |
| --- | --- |
| Idle | No prop is held and no pickup is reserved. |
| Approaching | The pickup action owns one prop reservation and uses locomotion to reach a grounded stand point. It is still one active authored action. |
| Reaching | The chosen arm target blends to the chosen grip; the prop is not yet reported as held. |
| Held | Exactly one prop is aligned to the solved wrist and cannot be claimed by another rig. |
| Throwing | The arm performs windup/follow-through; release is committed once at the release boundary. |

Cancellation before pickup attachment stops the approach/arm blend and releases
the prop reservation. Cancellation of a throw before its release boundary
leaves the prop held; cancellation after release never pulls it back and only
ends the remaining follow-through.

Action payloads:

| Type | Runtime payload | Behavior |
| --- | --- | --- |
| `pick_up_prop` | `{ type, target_prop_id: String, hand: "auto" | "left" | "right" }` | Resolve and reserve that exact prop, approach if needed, then attach one compatible grip. |
| `drop_prop` | `{ type }` | Release the currently held prop. If none is held, complete as a skipped no-op. |
| `throw_prop` | `{ type, target_position: Vector2 }` | Throw the held prop toward the saved stage-world point. If none is held, complete as a skipped no-op. |

Skipped means the queue item reaches its existing completed state with a
no-op outcome; it does not add a new persistent queue status. The existing
`action_finished` signal continues to mean that a queue item ended. The
dedicated `prop_*` triggers below are the success signals for actual prop
state changes.

### 3.1 Pickup selection and auto-approach

At action start, resolve `target_prop_id` to a live `PropBlock` in this stage.
Reject a missing ID, a placeholder, an already-held/reserved prop, a rig
already holding a prop, or a hand/anchor combination with no compatible grip.
These failures finish the queue item as skipped and emit no pickup event.

Use the prop’s normalized authored anchors. For `hand: "auto"`, consider
compatible grip/hand pairs, prefer `primary_grip`, then choose the reachable
pair with the shortest wrist-to-grip distance. An explicit left/right request
must use that hand; do not silently switch hands when its selected grip forbids
it. If no editable grip exists, use a generated one-hand fallback grip at the
center of the prop’s visual bounds. Built-in props use that fallback unless
their template provides an explicit grip.

Measure reach from the selected solved wrist to the transformed grip, not from
the rig root to the prop origin. If the grip is out of reach, compute a grounded
stand point on a reachable side of the prop and ask existing locomotion to walk
there. The stand point must account for current terrain height and the chosen
hand. After arrival, re-resolve the prop, recompute its grip transform, and
confirm actual reach before starting the arm blend. A moving prop may cause at
most one approach replan; if it is still unreachable, release the reservation
and skip the action. No unbounded “chase the prop” loop is allowed.

Reservations are claimed synchronously when pickup begins so two actors cannot
both approach and attach the same prop. Release the reservation on success,
failure, cancellation, prop deletion, or actor deletion. Do not emit a
`walk_to` completion or waypoint-arrival event for the internal approach.

### 3.2 Attachment and hold

Interpolate the selected hand’s IK target to the grip over a short reach blend.
Once the arm is solved, align the prop with
`PropAnchorData.solve_attachment_transform()`, using the solved wrist
transform, the grip’s local transform, effective PLAY scale, and the
left-facing mirror convention. Apply the anchor’s z-index offset relative to
the rig’s draw order.

Keep the `PropBlock` under the stage World. Do not reparent it to the animated
rig or use reparenting as the attachment mechanism. During hold, use
`RigidBody2D.FREEZE_MODE_KINEMATIC`, update the prop transform from the solved
wrist in the interaction update, and temporarily disable its collision layer
and mask so it cannot snag terrain, its owner’s collision proxies, or generate
ordinary contact events while held. Save and restore all modified physics
settings on release. The hold transform must be updated only after the wrist
pose has been solved for that frame.

Sample the held prop transform each physics frame. Those samples provide
release linear/angular velocity for drops and ragdoll disarm; do not use
`_last_grounded_walk_velocity_x` as full actor momentum. It is a grounded,
horizontal locomotion value and does not describe airborne or wrist motion.

### 3.3 Drop and throw

A manual drop detaches at the current prop transform, restores its collision
settings and dynamic state, and applies the most recent finite sampled
attachment velocity. A throw uses the same release handoff, then overrides
linear velocity with the trajectory solver result and adds a small deterministic
spin. Release and its event are committed exactly once.

The approved baseline uses a bounded ballistic solver and no-op guards. The
approved §1.2 amendment changes its target handling as follows:

1. Keep the saved absolute `target_position`. At preview and throw start,
   compute the effective point by clamping its radial distance from the current
   stickman root to `MAX_THROW_RANGE` (3,600 px). Use the prop's actual predicted
   attachment transform at the release waypoint as the ballistic origin.
2. For a candidate flight time `t`, compute the required initial velocity as
   `(effective_target - release_position - 0.5 * gravity * t * t) / t`. Search
   `[0.35 s, 2.0 s]` and choose the shortest finite candidate that reaches the
   effective point on descent and stays at or under `MAX_THROW_SPEED`
   (2,100 px/s). The time interval is the preferred tuning seam if playtesting
   shows that the default arc needs to be more or less lofted.
3. If no candidate can reach the target within those bounds, mark the preview
   invalid and leave the prop held when the action runs. Never substitute an
   undershot point while presenting it as the requested landing target.

The preview uses the same effective target, release transform, flight time,
velocity, gravity, and prop gravity scale as execution. Shape-cast the prop
along the path up to the effective target, excluding the thrower's collision
bodies and the held prop. An earlier world collision truncates the guide at
first safe contact; otherwise the guide reaches the effective target. In open
air, the target is an aim point and the physical prop continues until a later
collision. Show the raw cursor, effective capped target, and an earlier
collision point as separate markers.

A queue-authored throw may use the queue-aware planning preview in §1.3. Its
inferred prop, grip/hand, and estimated root pose are immutable solver inputs;
the preview must not simulate pickup by changing live ownership or transforms.
Runtime release always recomputes from actual state.

A cursor within the 4 px zero-distance threshold of the stickman root is a
no-op and leaves the prop held. Godot's positive-Y-down gravity vector must be used consistently. Set
`linear_velocity` from the solved velocity; do not pass a velocity vector to
`apply_central_impulse()`. Never pass a NaN or infinite vector into physics.
Prop mass does not change the solver result; prop-specific throwability remains
future tuning work.

The rig faces toward the saved target before throw windup when the horizontal
offset is outside a small dead zone; it retains that direction afterward.
Use a scripted arm IK pose for windup, release, and follow-through. Do not
directly rotate the torso or reposition the legs in this phase.

## 4. Ragdoll and Sandbox lifecycle

Before `StickmanRig.set_ragdoll(true)` resets locomotion or begins the ragdoll
handoff, ask the interactor to detach any held prop. Restore its collision and
physics settings and apply the latest sampled attachment velocity. This path is
idempotent and works for direct ragdoll, collision-triggered ragdoll, and a
queued ragdoll action.

Ragdoll disarm emits one `prop_dropped` event with reason `ragdoll`; it does
not run the manual drop animation. A manual drop emits the same event with
reason `manual`. A scene reset or leaving PLAY detaches silently, clears
reservations/pose overrides, then lets the existing authored-state restore
return props to their starting transforms. It must not create a gameplay rule
event during cleanup.

Pause/resume preserves a held attachment and its sampled transform state.
Reset/restart restores the unheld authored prop state. Prop interaction actions
require an animated rig; if queued while ragdolled, use the existing recovery
barrier behavior before pickup/throw. A no-held drop/throw after recovery
remains a skipped no-op.

## 5. Events and authoring

Add ActionRegistry entries and labels/icons for `pick_up_prop`, `drop_prop`,
and `throw_prop`. Extend ActionEditor/QueuePanel serialization and the Direct
action popup so actions can be added and edited. Direct popup labels should
read **🫴 Pick Up Prop…**, **⬇️ Drop Prop**, and **🏹 Throw Prop…**. Pick Up
captures a prop; Throw captures a stage-world point; Drop queues immediately.
The When/Then action editor must support those same payloads, including the
second stage capture needed to choose the prop or throw point after the acting
stickman is selected.

Add TriggerRegistry entries for:

| Type | Source | Target | Fire condition |
| --- | --- | --- | --- |
| `prop_picked_up` | Acting stickman | Picked-up prop | After grip alignment and held-state ownership commit. |
| `prop_dropped` | Acting stickman | Released prop | After manual or ragdoll release commits; event payload includes the reason. |
| `prop_thrown` | Acting stickman | Thrown prop | At the exact release boundary, after physics velocity is assigned. |

Prop trigger rules select a stickman source and prop target. Use the existing
ordered, all-matching rule evaluation and normal reactive action queues. Emit
events from the interactor’s successful state transitions, not merely because
an ActionRunner item finished. Do not emit while a prop is being continuously
held, after a failed action, or during scene cleanup. Rule actions can target a
different stickman and can refer to their own prop ID/throw point.

User-authored rules may form a real cycle (for example, pick up → drop → pick
up). Do not synthesize rules or dispatch prop events inline from a failed
attempt. Keep transition events edge-triggered and preserve the existing
stage-run/event-dispatch guards.

## 6. Stage identity, anchors, and saved data

Add a non-empty, opaque `stage_object_id` to every spawned `PropBlock`.
Generate it for each placement/instance; never copy it from the asset or from a
duplicated prop. Keep `spawn_id` exclusively as library/template provenance.
The stage owns resolution and uniqueness checks. Missing custom-prop
placeholders preserve the same ID so replacing a missing asset with its real
asset restores queue/rule references.

Bump StageSceneIO to version 1.1. Keep reading 1.0 scenes; migration assigns
each prop’s current unique `file_id` as its initial `stage_object_id`.
Write `stage_object_id` on each prop entry thereafter. Reject duplicate or
empty IDs in a 1.1 file before applying it, preserving the current scene on
load failure. Existing per-save `file_id` mappings continue to serialize
runtime rule references; do not use Godot instance IDs as saved references.

StageSceneIO queue encode/decode and rule-action conversion must preserve
`target_prop_id` as a stable string and `target_position` as finite vector
data. A queued action whose prop ID no longer resolves stays in the queue and
finishes as skipped when run. A missing-prop placeholder is inert and cannot
be picked up. A rule action with a missing prop target is skipped at execution;
it must not crash or silently retarget another prop.

Carry anchors from `PropLibrary.make_custom_entry()` through `StageSpawner`
into `PropBlock`. Built-in props get a generated centered one-hand grip from
their visual bounds unless their template already defines one. Preserve the
existing .prop anchor schema; do not add runtime-only hand state to .prop
assets.

## 7. Implementation sequence

1. **Identity and data path:** persistent stage IDs, 1.0→1.1 scene migration,
   action payload serialization, and custom/built-in grip availability.
2. **Pickup/drop vertical slice:** PropInteractor, one-hand state ownership,
   approach/revalidation, hold pose, drop, action cancellation, and Direct /
   queue editing.
3. **Throw:** fixed world-target capture, root-relative 3,600 px range clamp,
   shortest-valid bounded landing solver, facing/overhand arm arc, release
   velocity, collision-aware trajectory preview, and queue-prefix planning
   context for pending throw targets.
4. **Lifecycle:** ragdoll disarm, PLAY pause/resume/reset, deletion, and
   recovery-barrier integration.
5. **Rules:** three prop triggers, source/target capture, When/Then prop
   actions, persistence, and missing-target behavior.

Each step should be headless-verifiable with pure serialization/solver cases
and followed by editor/runtime verification in the Sandbox Stage.

## 8. Acceptance criteria

- A distant pickup approaches using one active queue item, then attaches one
  compatible grip to one hand without emitting a synthetic walk event.
- Left/right facing, authored anchor position/rotation, prop scale, and
  z-index offset produce stable grip alignment. Built-in props remain pickable.
- Missing, deleted, reserved, incompatible, or unreachable pickup targets fail
  safely, release their reservation, and emit no successful prop event.
- Drop restores physics/collision properties and transfers sampled release
  motion. Drop and throw with no held prop complete as skipped no-ops.
- A throw queued before the actor moves keeps its saved stage-world point; if
  the range cap binds at runtime, the effective point is clamped from the
  actor's then-current root. Preview and runtime use the same gravity and
  target solver.
- A throw within range reaches its selected point on the descending arc when
  unobstructed; targets beyond range show the 3,600 px effective point separately
  from the cursor. Earlier collisions stop the guide at the collision point.
- At `t = 0`, a pending throw after a pending pickup has a non-mutating,
  queue-aware planning guide; no held prop or invalid prefix shows a neutral
  explanation instead of a false red ballistic path.
- Ragdoll releases a held prop before hiding the animated rig, transfers
  sampled motion, and emits exactly one ragdoll-reason drop event.
- Pause/resume preserves the hold; PLAY reset/exit releases silently and
  restores authored state.
- Prop pickup/drop/throw triggers fire exactly once after their respective
  committed transitions and execute matching rules in existing rule order.
- Prop IDs and new queue/rule action payloads survive save/load, missing custom
  prop placeholders, and object reordering without binding to the wrong copy.

Final user sign-off on §1.3 was received 2026-09-25. Implementation and editor
verification are complete (2026-09-25).