stickman/docs/plans/phase_17_props_for_storytelling.md

Phase 17 — Props for Storytelling

Status: Accepted product brief. Phase 17a is user-approved. Phase 17b implementation is present and awaiting in-editor user verification. Phase 17c implementation is present; automated behavior verification and in-editor user verification are pending. Phase 17d remains deferred. Audience: UI/UX, architect, and implementation team. Purpose: Product and design brief; technical contracts belong in later specifications.

Goal and audience

Help children build layered sets and direct clear cause-and-effect stories with props. A table can sit behind a character and hold a flower pot without blocking the character. The character can pick up the pot, set it down deliberately, drop or throw it, press a button on another prop, and make a struck prop wobble. Children can also keep related set pieces together while arranging a scene.

The audience is a child working in the Sandbox Stage's EDIT, DIRECT, and PLAY modes. The controls should describe visible outcomes, show the relevant target on the stage, and let the child correct a misplaced object or action without rebuilding the scene.

Desired user outcome and delivery order

Phase 17 is one product milestone with four ordered parts. Each part should be independently reviewable; later parts build on the placed-prop behavior established in 17a.

| Part | Child-facing outcome | Priority | Status | | --- | --- | --- | | 17a — Prop roles and placement | Arrange props behind or in front of characters; choose independent physical and interaction capabilities; build pass-through support props; select covered props in EDIT; use Set Down to release a held prop at a chosen stage spot. | First and highest | Implemented and user-approved | | 17b — Use spots | Mark a handle, button, or lever on a placed prop, direct a stickman to use it, and respond through a rule. | Next | Implemented; awaiting user verification | | 17c — Impact wobble | Make a prop briefly wobble after a meaningful hit. | Next | Implemented; awaiting automated behavior and in-editor user verification | | 17d — Scene groups | Organize and move several placed props together while editing a scene. | Last; lower priority | Deferred |

17a's role model, saved-scene migration, fixed depth tiers, covered-object chooser, collision handling, Set Down action, and UI are implemented and user-approved. Automated test run: no execution result is documented for tests/test_phase17a_prop_roles.gd. The success criteria below remain regression guidance. Depth is currently a fixed behind/in-front choice; dynamic Y sorting remains deferred.

Core child flow and feedback

17a — Prop roles and placement

The child places a prop, selects it in EDIT, and chooses its visual depth separately from what it does in PLAY. The initial depth choices are Behind characters and In front of characters. Props keep a clear selection outline and a way to select or edit them even when another object covers them. The stage should make the chosen depth and behavior legible without exposing physics terminology as the primary labels.

Behavior is expressed through independent capabilities, because a prop may support other props while characters pass through it, and a pickable prop may be nonblocking at the start of PLAY but collide after release. Newly placed props start still by default. A table can remain fixed, sit behind a stickman, and support a flower pot without blocking that stickman. The pot stays at its authored starting position until picked up. While held, it follows the hand without collisions; after Set Down, Drop, or Throw, it interacts with configured surfaces, stickmen, and other props as appropriate. It remains available for another pickup. Stopping PLAY restores the authored arrangement and behavior for a repeatable replay.

Set Down complements the existing free Drop and Throw actions. The child directs a stickman holding a prop, chooses Set Down, then clicks any stage-world spot, including open air. The stickman approaches from a reachable grounded position and moves the held prop to the requested release point. If that point embeds the prop in a support surface, the stage raises the release point just enough to clear its collision shape. The arm reaches smoothly; low placements bend the torso and knees. At release, the object becomes physical and falls onto the crate, table, terrain, or other surface below. The stage previews the requested point, corrected release origin when needed, actor approach, and reach, and gives a clear, recoverable cue for an unreachable or blocked release point. A support prop uses its collision geometry; the child does not mark a special support surface.

17b — Use spots

In EDIT, the child adds visible Use spots to a placed prop instance and moves each marker onto a handle, button, or lever. A Use spot differs from a pickup grip: the stickman reaches to the spot while the target prop stays in place. In DIRECT, the child chooses Use, selects the prop and intended spot, and sees whether the spot is reachable. If it cannot be reached, the stage explains the problem at the target rather than silently skipping the action.

A successfully completed interaction emits a child-facing Used prop event that identifies the stickman, prop, and spot. New rules target one specific named spot; saved whole-prop (spot_scope = "any") rules remain supported for compatibility. The spot gets a brief, visible completion cue. Built-in results such as opening a door or toggling a light are later work; the rule system supplies story consequences in this phase.

17c — Impact wobble

The child can turn Wobble when bumped on or off for one placed prop. Enabling it in EDIT plays a brief sample; the choice remains available for pass-through props. In PLAY, a qualifying approach-speed hit produces a short tilt and sideways give on the artwork while the physics body and collisions continue normally. Contact and blocking-movement sweep candidates share one resolver with pair rearming and cooldown gates; animated stickmen, ragdoll bodies, other props, and other physics bodies can supply hits when collision policy allows. Two enabled props can both wobble from one qualifying prop-to-prop hit. Scene v1.4 stores the choice per placement, and older scene versions default it to Off. Stopping PLAY cancels the effect and restores the authored state. The current score is based on approach speed, not mass; the resolver keeps scoring centralized for future mass or impulse work.

17d — Scene groups

In EDIT, the child selects related placed props such as a table, cloth, and pot, chooses Group, and gets a visible shared selection that can be moved together. The child can open the group to adjust one item and can ungroup without losing the items. A group organizes this scene; it does not turn its members into one physical object. In PLAY, each member keeps its own depth, collision, pickup, and event behavior. Picking up the pot moves only the pot. Stopping PLAY returns the authored arrangement, with the group still available in EDIT.

Story and directing value

Depth lets children stage a character behind a table or in front of scenery. Independent support and collision roles make an apparently simple set behave as expected. Set Down gives deliberate blocking and placement moments, while Drop and Throw keep playful physical outcomes. Use spots let a character visibly press or handle a story object; rules let that moment trigger dialogue or another action. Wobble adds an immediate, readable response to a bump. Groups reduce repeated arranging as a set becomes more detailed.

Success criteria

• A child can save, reload, and replay a scene in which a fixed table is visually behind a stickman, supports a pot, and lets the stickman pass through. The pot can be picked up, set down onto the table with a smooth reach, released collision-free until that moment, and then fall onto it through physics. It can also be dropped or thrown and picked up again. PLAY reset restores the authored setup.
• Visual depth and physical/interaction capabilities remain independent on placed copies of the same prop asset. A covered prop remains discoverable and editable in EDIT.
• A child can place more than one Use spot on a prop instance, direct a stickman to a chosen spot, and make a newly authored rule fire for that specific spot only after the interaction completes. Failed reach attempts give useful feedback. Legacy whole-prop rules continue to load and match.
• A meaningful collision produces one readable wobble when enabled; resting contact does not produce continuous wobbling, and stopping PLAY clears the effect.
• A saved scene group can be moved together in EDIT, opened to edit a member, and ungrouped. Members behave independently in PLAY and return to their authored arrangement on reset.
• Older scenes and reusable .prop assets continue to open with sensible behavior. A child does not have to re-author a scene to use the new controls.

Scope and exclusions

Included: per-placement depth and independent capabilities; support for props that need not block characters; predictable start, held, and released prop behavior; Set Down by clicking a stage-world release point, followed by a physical fall; EDIT selection of obscured props; instance Use spots and Used prop rules; controlled impact wobble; and persistent scene-only groups. No support-surface authoring control is part of this phase.

Deferred: dynamic Y sorting by character and prop ground points; built-in Use effects; topple and break reactions; reusable set-piece assets; group physics or jointed assemblies; door opening/closing, functional doorways, and scene travel. Large vector background walls belong to the stage backgrounds work, while fixed actor-blocking walls are structure/terrain concerns. Loose bricks or planks remain movable props.

As-built touchpoints and remaining risks

• scripts/props/prop_block.gd and scripts/props/prop_stage_roles.gd now hold per-placement role settings and EDIT, start-still, start-physics, held, and released profiles. scripts/stage/stage_scene_io.gd writes version 1.2 and migrates older scenes; the .prop asset schema is unchanged. Keep save/load compatibility and PLAY reset in the regression checklist.
• scripts/characters/stickman/stickman_prop_interactor.gd handles pickup, Drop, Throw, and Set Down. It clears collisions while a prop is held and applies its authored release profile afterward. Set Down previews and runtime checks share the target solver; complex queued/rule sequences and changed runtime conditions remain useful regression cases.
• scripts/characters/stickman/stickman_locomotion.gd and scripts/stage/stage_physics_policy.gd include actor-blocking prop collision bits and movement sweeps. Props set to block stickmen are not walkable platforms; terrain remains the movement surface. Keep obstruction, pause/reset, and ragdoll interactions in the regression checklist.
• scripts/stage/stage_selection.gd provides hit_test_all() and the stage shows an Objects here chooser for overlapping candidates. The current hit test uses world-space AABBs rather than exact vector-shape containment, so the chooser may include an object when the pointer is inside its bounds but outside its artwork.
• Props use fixed behind/in-front draw tiers. Dynamic ground-point Y sorting remains deferred. scripts/props/prop_anchor_data.gd continues to describe reusable grip anchors; 17b Use spots are placed-instance data and remain distinct from those grips.
• Phase 17b implementation is present. The architecture and UI contracts are documented in Use spots: architecture and Use spots: UI/UX. New Used prop rules choose one named spot; legacy whole-prop rules remain compatible. In-editor user verification is pending.
• Phase 17c implementation is present in scripts/props/prop_block.gd, scripts/stage/stage_impact_resolver.gd, scripts/editors/stage/sandbox_stage.gd, scripts/editors/stage/stage_prop_settings_view.gd, scripts/editors/stage/stage_run_session.gd, scripts/editors/stage/stage_scene_adapter.gd, and scripts/stage/stage_scene_io.gd. The prop card provides the per-placement switch and EDIT sample, including for pass-through props. PLAY applies a visual-only wobble to artwork; root physics motion and collision geometry remain under normal simulation. Body contacts and identified blocking-stickman sweeps use relative approach speed, with pair tracking and cooldown to suppress repeated resting/push contact. Ragdoll and prop-prop contacts are routed through the resolver. Scene v1.4 persists the boolean and migrates older scenes to Off. Material preset mass is not part of the score; the shared resolver is the extension seam for a future editable-mass or impulse model. Automated behavior verification and in-editor user verification are pending; do not treat the implementation as verified yet.
• Stage multiselection can move several objects together in one edit, but it does not save persistent group membership. Phase 17d must preserve independent member identities and prop-targeted actions when adding saved groups.
• Relevant prior context: Phase 11 prop interactions and the live feature backlog.

Regression checks and future design questions

17a's settings controls, overlap chooser, Set Down release-point behavior, legacy scene defaults, implementation, and UI are user-approved. Keep the table/pot support and pass-through case, blocking movement, open-air and corrected Set Down targets, invalid-target recovery, covered-object selection, repeat PLAY reset, and old-scene replay as regression guidance. For 17c, regression checks should cover EDIT preview and cancellation; pass-through availability; fixed and moving props; a walking/running stickman contact and blocked movement sweep; a falling ragdoll; prop-to-prop hits with both enabled and one disabled; slow/resting contacts and sustained pushes; pause/resume and STOP/replay; per-instance save/reload; and v1.0–v1.3 migration to Off. These are pending checks, not reported results.

The following design question remains for the deferred part of Phase 17:

• 17d — Scene groups: What EDIT gesture makes it clear whether the child is selecting a whole group or one member? How should group membership be shown without covering the set artwork?