stickman/docs/plans/phase_17_props_for_storytelling.md

Phase 17 — Props for Storytelling

Status: Accepted product brief. User approval: Phase 17a implementation and UI accepted. Phases 17b–17d remain 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 | Deferred | | 17c — Impact wobble | Make a prop briefly wobble after a meaningful hit. | Next | Deferred | | 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 where the stickman will approach and reach. If the spot 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. A rule can respond to use of the whole prop or only one specific spot. 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 choose a simple impact response for a placed prop: None or Wobble. A noticeable physical hit produces one short, controlled wobble that settles cleanly. Ordinary resting contact should not make a prop shake repeatedly. The stage's existing collision rules remain available for more elaborate consequences. Stopping PLAY cancels any active wobble and restores the authored prop appearance and placement.

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 rule fire for either the whole prop or that specific spot only after the interaction completes. Failed reach attempts give useful feedback.
• 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 will be placed-instance data and must remain distinct from those grips.
• Stage collision events remain contact based. Phase 17c still needs a dependable hit-strength rule for a moving stickman striking a stationary prop without causing resting-contact jitter or requiring a child-facing force slider.
• 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.

The following design questions remain for the deferred parts of Phase 17:

• 17b — Use spots: How should EDIT show and target multiple instance spots without confusing them with reusable grip anchors, and how should DIRECT explain an unreachable spot?
• 17c — Impact wobble: What impact measure and visual treatment make a wobble consistent across stationary props, moving props, and stickmen without repeated jitter?
• 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?