Add new scene files and implement stage impact resolver

- Created three new scene files: `wobble.scene`, `wobble2.scene`, and `wobble3.scene` with various terrain and prop configurations.
- Introduced `stage_impact_resolver.gd` script to manage impact detection and response between props and stickmen.
- Added unit tests for actor blocking overlap to ensure proper interaction with stationary props.
This commit is contained in:
2026-10-14 13:08:34 -04:00
parent 628c07e70e
commit 5c3b056a13
21 changed files with 1891 additions and 22 deletions
@@ -1,6 +1,6 @@
# 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; Phases 17c–17d remain deferred.
> **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.
@@ -18,7 +18,7 @@ Phase 17 is one product milestone with four ordered parts. Each part should be i
| --- | --- | --- |
| **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 | Deferred |
| **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.
@@ -41,7 +41,7 @@ A successfully completed interaction emits a child-facing **Used prop** event th
### 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.
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
@@ -74,15 +74,14 @@ Deferred: dynamic Y sorting by character and prop ground points; built-in Use ef
- `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](../specs/phase_17b_use_spots.md) and [Use spots: UI/UX](../specs/phase_17b_use_spots_ui.md). New Used prop rules choose one named spot; legacy whole-prop rules remain compatible. In-editor user verification is pending.
- 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.
- 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](../specs/phase_11_prop_interactions.md) and the live [feature backlog](../ideas/feature_backlog.md).
## 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.
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 questions remain for the deferred parts of Phase 17:
The following design question remains for the deferred part of Phase 17:
- **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?