Steven Wroblewski
85 lines
4.2 KiB
Markdown
85 lines
4.2 KiB
Markdown
# Sprint 18 — Room Chests & Item Spawning Design Spec
|
||
|
||
## Goal
|
||
|
||
Implement a `RoomChest` system: tappable storage nodes in every room that spawn `HoldableItem`/`OutfitItem` instances with a fly-out tween. Items persist in the world until manually dragged back to their chest. All 12 existing rooms get populated with placeholder items (string IDs, no textures yet).
|
||
|
||
## Architecture
|
||
|
||
### Data Layer
|
||
|
||
**`ChestItemData`** — `Resource` subclass, one entry per item slot in a chest.
|
||
|
||
| Field | Type | Purpose |
|
||
|---|---|---|
|
||
| `item_id` | `String` | Canonical item identifier, e.g. `"stethoscope"` |
|
||
| `item_type` | `String` | `"holdable"` or `"outfit"` |
|
||
| `outfit_layer` | `int` | 1–3, only relevant when `item_type == "outfit"` |
|
||
| `spawn_offset` | `Vector2` | Relative target position for fly-out tween |
|
||
|
||
**`RoomChest`** — `Node2D` subclass.
|
||
|
||
| Field | Type | Purpose |
|
||
|---|---|---|
|
||
| `chest_id` | `String` | Unique identifier, e.g. `"pharmacy_medicine"` |
|
||
| `items` | `Array[ChestItemData]` | Configured items for this chest |
|
||
| `_spawned_items` | `Array` | Currently live item nodes in the world |
|
||
|
||
### Spawn Behaviour
|
||
|
||
1. Player taps `RoomChest`.
|
||
2. If `_spawned_items` is not empty → no-op (already spawned).
|
||
3. Otherwise: for each `ChestItemData`, instantiate a `HoldableItem` or `OutfitItem` node. Set `item.home_chest = self`. Reparent to the room scene (not the chest). Tween `global_position` from `chest.global_position` to `chest.global_position + item_data.spawn_offset`.
|
||
|
||
### Return Behaviour
|
||
|
||
`HoldableItem._on_drag_released` checks (in priority order):
|
||
|
||
1. **Chest return** — if `home_chest != null` and `global_position.distance_to(home_chest.global_position) < CHEST_RETURN_RADIUS (80.0)`: tween back to chest → `home_chest.receive_item(self)` → `queue_free()`.
|
||
2. **Outfit apply** — existing OutfitItem logic (80 px body proximity).
|
||
3. **Hand slot attach** — existing HoldableItem logic (60 px hand slot proximity).
|
||
|
||
`RoomChest.receive_item(item: HoldableItem)` removes the item from `_spawned_items`.
|
||
|
||
### GameState v3
|
||
|
||
Extend `GameState` with `_chest_states: Dictionary` mapping `chest_id → Array[String]` of currently spawned `item_id`s. Persist in save data as `"version": 3`. Item positions within the room are **not** persisted (deliberate simplification). On load: if a chest has entries in `_chest_states`, re-spawn those items via the normal fly-out tween from the chest — they land at their configured `spawn_offset`, not their last dragged position.
|
||
|
||
## Room Population
|
||
|
||
All 12 existing room `.tscn` files get `RoomChest` nodes. No textures in this sprint — `item_id` strings only.
|
||
|
||
| Room | chest_id | item_ids |
|
||
|---|---|---|
|
||
| Reception | `reception_desk` | `clipboard`, `pen`, `bandage` |
|
||
| GiftShop | `giftshop_shelf` | `gift_box`, `ribbon`, `balloon` |
|
||
| Restaurant | `restaurant_counter` | `teacup`, `plate`, `spoon` |
|
||
| Emergency | `emergency_cabinet` | `bandage_roll`, `syringe`, `ice_pack` |
|
||
| XRay | `xray_cabinet` | `xray_sheet`, `lead_apron`*, `marker` |
|
||
| Pharmacy | `pharmacy_medicine` | `pill_bottle`, `syrup` |
|
||
| Pharmacy | `pharmacy_tools` | `mortar`, `spatula` |
|
||
| Lab | `lab_bench` | `test_tube`, `pipette`, `microscope_slide` |
|
||
| PatientRooms | `patient_cabinet` | `thermometer`, `stethoscope`*, `pillow` |
|
||
| Ultrasound | `ultrasound_cart` | `gel_tube`, `probe`, `towel` |
|
||
| DeliveryRoom | `delivery_cabinet` | `swaddle`*, `scissors`, `cord_clamp` |
|
||
| Nursery | `nursery_shelf` | `bottle`, `rattle`, `blanket`* |
|
||
| GardenParty | `garden_table` | `teapot`, `cake` |
|
||
| GardenParty | `garden_storage` | `confetti`, `party_hat` |
|
||
|
||
`*` = `item_type: "outfit"` (layer: `lead_apron`→1, `stethoscope`→2, `swaddle`→1, `blanket`→1)
|
||
|
||
## Testing
|
||
|
||
- `test/unit/test_room_chest.gd` — unit tests for `RoomChest` and `ChestItemData`
|
||
- `test/unit/test_game_state.gd` — appended tests for GameState v3 chest state
|
||
- `test/unit/test_holdable_item.gd` — appended tests for chest-return priority
|
||
|
||
Tests follow GUT v9.6.0, `extends GutTest`, `add_child_autofree`.
|
||
|
||
## Out of Scope
|
||
|
||
- Item textures / sprites (Sprint 18 uses null textures throughout)
|
||
- Chest open/close sprite animation (visual polish, later sprint)
|
||
- Per-item sounds (AudioManager sprint)
|
||
- Chest state per save-slot (single save file, existing SaveManager)
|