Cozypaw-Hospital/docs/superpowers/specs/2026-05-11-sprint-14-garden-party.md

# Sprint 14 — Garden Party Spec

## Goal

Make the GardenParty scene a fully playable sandbox room with three interactive objects
(GiftBox auto-reset, Balloon pop/respawn, Cake cut/reset) and character snap-to-chair
at the party table.

---

## Scope

**In scope:**
- `gift_box.gd`: add `RESETTING` state (auto-reset 3 s after opening)
- `balloon.gd`: new script — tap to pop, auto-respawn after 5 s
- `cake.gd`: new script — tap to cut slice, auto-reset after 3 s
- `GardenParty.tscn`: replace GiftBox3 with Cake, add Cake node structure, add chair
  ColorRects under snap points, attach balloon.gd to existing Balloon nodes
- Tests: extend `test_gift_box.gd`, add `test_balloon.gd`, add `test_cake.gd`

**Out of scope:**
- New SFX keys (reuse `object_tap` for all three objects)
- Navigation changes (HomeButtonToGarden and HomeButtonReturn already wired)
- Additional characters beyond Bunny1 already in Main.tscn

---

## Object Mechanics

### GiftBox — RESETTING state

New state added to the existing `State` enum:

```
CLOSED → OPENING → RESETTING → CLOSED
```

- `_on_lid_opened()`: state → `RESETTING`, gift fades in (existing tween), inline 3 s
  tween interval runs in parallel → `_start_close_lid()`
- `_start_close_lid()`: lid tweens back (fade-in alpha 0→1, slide y back to 0) →
  `_on_reset_complete()`
- `_on_reset_complete()`: state → `CLOSED`
- `OPEN` state removed — `RESETTING` covers "gift visible + waiting"
- New internal methods: `_start_close_lid()`, `_on_reset_complete()`
- Constant: `RESET_DELAY: float = 3.0`

### Balloon

New file: `scripts/objects/balloon.gd`  
New scene attachment: `balloon.gd` attached to existing `Balloon1` / `Balloon2` nodes in
`GardenParty.tscn`.

```
IDLE → POPPING → POPPED → RESPAWNING → IDLE
```

State transitions:
- Touch input on balloon while `IDLE` → `_start_pop()`
- `_start_pop()`: `AudioManager.play_sfx("object_tap")`, state → `POPPING`, scale tween to
  `Vector2.ZERO` (0.15 s, EASE_IN, TRANS_BACK) → `_on_pop_complete()`
- `_on_pop_complete()`: state → `POPPED`, starts 5 s tween interval → `_start_respawn()`
- `_start_respawn()`: state → `RESPAWNING`, scale tween to `Vector2.ONE` (0.3 s, EASE_OUT,
  TRANS_BACK) → `_on_respawn_complete()`
- `_on_respawn_complete()`: state → `IDLE`

Input: `_input(event)` — same touch-rect pattern as GiftBox, half-size 20 px (balloon is
small).

Constants: `POP_DURATION`, `RESPAWN_DURATION`, `RESPAWN_DELAY`.

### Cake

New file: `scripts/objects/cake.gd`  
New node structure in `GardenParty.tscn` (replaces GiftBox3 at x=820, y=464):

```
Cake (Node2D, cake.gd)
├── Base (ColorRect, ~80×40 px, warm brown)
└── Slice (ColorRect, ~30×40 px, slightly offset + rotated, lighter brown)
```

```
WHOLE → CUTTING → CUT → RESETTING → WHOLE
```

State transitions:
- Touch input on Cake while `WHOLE` → `_start_cutting()`
- `_start_cutting()`: `AudioManager.play_sfx("object_tap")`, state → `CUTTING`,
  tween `Slice.modulate.a` 1→0 (0.3 s, EASE_OUT) → `_on_cut_complete()`
- `_on_cut_complete()`: state → `CUT`, 3 s tween interval → `_start_reset()`
- `_start_reset()`: state → `RESETTING`, tween `Slice.modulate.a` 0→1 (0.3 s, EASE_IN)
  → `_on_reset_complete()`
- `_on_reset_complete()`: state → `WHOLE`

Input: touch rect `BUTTON_HALF_WIDTH = 40`, `BUTTON_HALF_HEIGHT = 20`.

Constants: `CUT_DURATION`, `RESET_DELAY = 3.0`, `RESET_DURATION`.

---

## Scene Changes (GardenParty.tscn)

| Change | Detail |
|---|---|
| Remove `GiftBox3` | Was at position Vector2(820, 464) |
| Add `Cake` | Node2D at Vector2(820, 464), `cake.gd`, child nodes Base + Slice |
| Attach `balloon.gd` | To existing `Balloon1` and `Balloon2` ColorRect nodes |
| Add `ChairLeft` | ColorRect ~60×20 px, brown, under `SnapTableLeft` (x=530, y=480) |
| Add `ChairRight` | ColorRect ~60×20 px, brown, under `SnapTableRight` (x=750, y=480) |

Navigation and snap-point logic unchanged.

---

## Tests

### `test_gift_box.gd` (extend existing)

| Test | Assertion |
|---|---|
| `test_state_becomes_resetting_after_lid_opened` | Call `_on_lid_opened()` → state == `State.RESETTING` |
| `test_state_becomes_closed_after_reset_complete` | Call `_on_reset_complete()` → state == `State.CLOSED` |

### `test_balloon.gd` (new, extends GutTest)

| Test | Assertion |
|---|---|
| `test_initial_state_is_idle` | `state == State.IDLE` |
| `test_start_pop_sets_popping` | Call `_start_pop()` → `state == State.POPPING` |
| `test_on_pop_complete_sets_popped` | Call `_on_pop_complete()` → `state == State.POPPED` |
| `test_on_respawn_complete_sets_idle` | Call `_on_respawn_complete()` → `state == State.IDLE` |

### `test_cake.gd` (new, extends GutTest)

| Test | Assertion |
|---|---|
| `test_initial_state_is_whole` | `state == State.WHOLE` |
| `test_start_cutting_sets_cutting` | Call `_start_cutting()` → `state == State.CUTTING` |
| `test_on_cut_complete_sets_cut` | Call `_on_cut_complete()` → `state == State.CUT` |
| `test_on_reset_complete_sets_whole` | Call `_on_reset_complete()` → `state == State.WHOLE` |

---

## Architecture Notes

- All three objects follow the same state-machine pattern as existing objects (`cradle.gd`,
  `gift_box.gd`, etc.) — no new abstractions.
- Tween-based animations are not unit-tested (visual only). State transitions triggered by
  `tween.finished` callbacks are tested by calling the callbacks directly.
- `AudioServer.get_driver_name() == "Dummy"` guard is already in `AudioManager.play_sfx()`
  — no additional guard needed in new scripts.
- `balloon.gd` scales the Node2D itself (no child sprite node needed at placeholder stage).