docs: add Sprint 17 implementation plan (Hand-Slots + Outfits, 147 tests)
This commit is contained in:
Steven Wroblewski
@@ -0,0 +1,852 @@
|
||||
# Sprint 17 — Hand-Slots + Outfits Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Enable items to be held in Character hand slots and outfit items to be dragged onto characters to dress them, with tap-to-undress and save persistence.
|
||||
|
||||
**Architecture:** Three new concerns, each self-contained: (1) `HoldableItem` scans the "characters" group on release and attaches itself to the nearest free HandLeft/HandRight. (2) `OutfitItem` extends `HoldableItem` — on release near a character body it applies itself to an outfit layer and hides. (3) `GameState` extended to persist outfit + held-item state per character (save format v2). No new scene files required — all logic is GDScript.
|
||||
|
||||
**Tech Stack:** Godot 4.6.2, GDScript static typing, GUT v9.6.0, headless runner.
|
||||
|
||||
**GDD Reference:** `docs/game-design.md` — Kapitel 5.2 (Hand-Slot System) + 5.3 (Outfit Layer System) + Kapitel 8 (Save Format v2).
|
||||
|
||||
**Headless runner:**
|
||||
```
|
||||
"F:/Development/_tools/Godot_v4.6.2-stable_win64/Godot_v4.6.2-stable_win64.exe" --headless -s res://addons/gut/gut_cmdln.gd -gdir=res://test/ -gexit 2>&1
|
||||
```
|
||||
|
||||
**Existing tests must stay green:** 115 tests passing before this sprint starts.
|
||||
|
||||
---
|
||||
|
||||
## Context: what Sprint 15 already built
|
||||
|
||||
`Character.tscn` already has `HandLeft` (Node2D at (-32,-30)) and `HandRight` (Node2D at (32,-30)) as attachment points. `character.gd` already has `attach_item(hand, item)`, `detach_item(hand)`, `get_held_item(hand)`, `is_hand_free(hand)`, `set_outfit(layer, id, texture)`, `clear_outfit(layer)`, `get_outfit(layer)`. `CharacterData` already has `outfit: Array[String]`.
|
||||
|
||||
What is missing: (1) Characters are not registered in any group, so items cannot find them by scanning. (2) `detach_item` does not preserve `global_position` when reparenting — it will silently teleport items to (0,0). (3) No `HoldableItem` class. (4) No `OutfitItem` class. (5) GameState only saves character positions, not outfit or held items.
|
||||
|
||||
---
|
||||
|
||||
## File Map
|
||||
|
||||
| Action | Path | Purpose |
|
||||
|---|---|---|
|
||||
| Modify | `scripts/characters/character.gd` | group registration, detach fix, tap detection, apply/remove outfit |
|
||||
| Create | `scripts/objects/holdable_item.gd` | base class: attach to hand slot on drag release |
|
||||
| Create | `scripts/objects/outfit_item.gd` | extends HoldableItem: apply outfit on drop near character |
|
||||
| Modify | `scripts/characters/character_data.gd` | add `held_left`, `held_right` String fields |
|
||||
| Modify | `scripts/autoload/GameState.gd` | save/load outfit + held items per character (v2 format) |
|
||||
| Modify | `test/unit/test_character_v2.gd` | add group, detach-position, tap, apply/remove outfit tests |
|
||||
| Create | `test/unit/test_holdable_item.gd` | HoldableItem unit tests |
|
||||
| Create | `test/unit/test_outfit_item.gd` | OutfitItem unit tests |
|
||||
| Modify | `test/unit/test_game_state.gd` | extend with outfit + held-item save tests |
|
||||
|
||||
---
|
||||
|
||||
## Task 1: Character group + HoldableItem + detach fix
|
||||
|
||||
**Files:**
|
||||
- Modify: `scripts/characters/character.gd`
|
||||
- Create: `scripts/objects/holdable_item.gd`
|
||||
- Modify: `test/unit/test_character_v2.gd`
|
||||
- Create: `test/unit/test_holdable_item.gd`
|
||||
|
||||
### Step 1: Write the failing tests
|
||||
|
||||
Add to `test/unit/test_character_v2.gd` (after the last existing test):
|
||||
|
||||
```gdscript
|
||||
func test_character_is_in_characters_group() -> void:
|
||||
assert_true(_char.is_in_group("characters"))
|
||||
|
||||
|
||||
func test_detach_item_preserves_global_position() -> void:
|
||||
var item: Node2D = Node2D.new()
|
||||
add_child_autofree(item)
|
||||
_char.global_position = Vector2(200.0, 300.0)
|
||||
_char.attach_item("left", item)
|
||||
# HandLeft is at offset (-32, -30) relative to character
|
||||
var expected_global: Vector2 = _char.get_node("HandLeft").global_position
|
||||
_char.detach_item("left")
|
||||
assert_eq(item.global_position, expected_global)
|
||||
```
|
||||
|
||||
Create `test/unit/test_holdable_item.gd`:
|
||||
|
||||
```gdscript
|
||||
## Tests for HoldableItem — hand slot attachment on drag release.
|
||||
extends GutTest
|
||||
|
||||
|
||||
func test_holdable_item_id_default_empty() -> void:
|
||||
var item: HoldableItem = HoldableItem.new()
|
||||
add_child_autofree(item)
|
||||
assert_eq(item.item_id, "")
|
||||
|
||||
|
||||
func test_holdable_item_is_not_in_hand_initially() -> void:
|
||||
var item: HoldableItem = HoldableItem.new()
|
||||
add_child_autofree(item)
|
||||
assert_false(item.is_in_hand_slot())
|
||||
|
||||
|
||||
func test_holdable_item_attaches_to_nearest_free_hand() -> void:
|
||||
var character: Character = preload("res://scenes/characters/Character.tscn").instantiate() as Character
|
||||
add_child_autofree(character)
|
||||
var item: HoldableItem = HoldableItem.new()
|
||||
add_child_autofree(item)
|
||||
item.item_id = "test_item"
|
||||
# Place item at HandLeft position
|
||||
item.global_position = character.get_node("HandLeft").global_position
|
||||
item._on_drag_released(item.global_position)
|
||||
assert_true(item.is_in_hand_slot())
|
||||
|
||||
|
||||
func test_holdable_item_does_not_attach_if_no_character_in_range() -> void:
|
||||
var item: HoldableItem = HoldableItem.new()
|
||||
add_child_autofree(item)
|
||||
item.global_position = Vector2(9999.0, 9999.0)
|
||||
item._on_drag_released(item.global_position)
|
||||
assert_false(item.is_in_hand_slot())
|
||||
|
||||
|
||||
func test_holdable_item_does_not_attach_to_occupied_hand() -> void:
|
||||
var character: Character = preload("res://scenes/characters/Character.tscn").instantiate() as Character
|
||||
add_child_autofree(character)
|
||||
var item1: HoldableItem = HoldableItem.new()
|
||||
var item2: HoldableItem = HoldableItem.new()
|
||||
add_child_autofree(item1)
|
||||
add_child_autofree(item2)
|
||||
# Fill left hand manually
|
||||
character.attach_item("left", item1)
|
||||
character.attach_item("right", item1) # fill both
|
||||
# item2 tries to attach but both hands full
|
||||
item2.global_position = character.global_position
|
||||
item2._on_drag_released(item2.global_position)
|
||||
assert_false(item2.is_in_hand_slot())
|
||||
|
||||
|
||||
func test_holdable_item_detaches_on_pickup_when_in_slot() -> void:
|
||||
var character: Character = preload("res://scenes/characters/Character.tscn").instantiate() as Character
|
||||
add_child_autofree(character)
|
||||
var item: HoldableItem = HoldableItem.new()
|
||||
add_child_autofree(item)
|
||||
character.attach_item("left", item)
|
||||
assert_true(item.is_in_hand_slot())
|
||||
item._on_drag_picked_up(item.global_position)
|
||||
assert_false(item.is_in_hand_slot())
|
||||
|
||||
|
||||
func test_holdable_item_detach_preserves_global_position() -> void:
|
||||
var character: Character = preload("res://scenes/characters/Character.tscn").instantiate() as Character
|
||||
add_child_autofree(character)
|
||||
var item: HoldableItem = HoldableItem.new()
|
||||
add_child_autofree(item)
|
||||
character.attach_item("left", item)
|
||||
var hand_pos: Vector2 = character.get_node("HandLeft").global_position
|
||||
item._on_drag_picked_up(hand_pos)
|
||||
assert_eq(item.global_position, hand_pos)
|
||||
```
|
||||
|
||||
### Step 2: Run import + tests — verify new tests FAIL
|
||||
|
||||
```
|
||||
"F:/Development/_tools/Godot_v4.6.2-stable_win64/Godot_v4.6.2-stable_win64.exe" --headless --import 2>&1
|
||||
"F:/Development/_tools/Godot_v4.6.2-stable_win64/Godot_v4.6.2-stable_win64.exe" --headless -s res://addons/gut/gut_cmdln.gd -gdir=res://test/ -gexit 2>&1
|
||||
```
|
||||
|
||||
Expected: 9 new failures. Existing 115 pass.
|
||||
|
||||
### Step 3: Modify `scripts/characters/character.gd`
|
||||
|
||||
**Change 1:** Add group registration in `_ready()` (after the drag connection block):
|
||||
|
||||
```gdscript
|
||||
func _ready() -> void:
|
||||
var drag: DragDropComponent = get_node_or_null("DragDropComponent") as DragDropComponent
|
||||
if drag != null:
|
||||
drag.drag_picked_up.connect(_on_drag_picked_up)
|
||||
drag.drag_released.connect(_on_drag_released)
|
||||
if data != null:
|
||||
_update_visual_state()
|
||||
_refresh_outfit_layers()
|
||||
add_to_group("characters")
|
||||
```
|
||||
|
||||
**Change 2:** Fix `detach_item` to preserve `global_position`:
|
||||
|
||||
```gdscript
|
||||
func detach_item(hand: String) -> Node2D:
|
||||
if hand != "left" and hand != "right":
|
||||
return null
|
||||
var slot: Node2D = get_node_or_null("Hand" + hand.capitalize()) as Node2D
|
||||
if slot == null or slot.get_child_count() == 0:
|
||||
return null
|
||||
var item: Node2D = slot.get_child(0) as Node2D
|
||||
var saved_pos: Vector2 = item.global_position
|
||||
slot.remove_child(item)
|
||||
var scene_parent: Node = get_parent()
|
||||
if scene_parent != null:
|
||||
scene_parent.add_child(item)
|
||||
item.global_position = saved_pos
|
||||
return item
|
||||
```
|
||||
|
||||
### Step 4: Create `scripts/objects/holdable_item.gd`
|
||||
|
||||
```gdscript
|
||||
## HoldableItem — Node2D that can be held in a Character's HandLeft or HandRight slot.
|
||||
## Attach DragDropComponent as a child. On drag_released scans "characters" group for
|
||||
## the nearest free hand slot within HAND_SLOT_RADIUS.
|
||||
class_name HoldableItem extends Node2D
|
||||
|
||||
signal item_picked_up(item: HoldableItem)
|
||||
signal item_placed(item: HoldableItem)
|
||||
|
||||
const HAND_SLOT_RADIUS: float = 60.0
|
||||
|
||||
|
||||
@export var item_id: String = ""
|
||||
|
||||
|
||||
func _ready() -> void:
|
||||
var drag: DragDropComponent = get_node_or_null("DragDropComponent") as DragDropComponent
|
||||
if drag != null:
|
||||
drag.drag_picked_up.connect(_on_drag_picked_up)
|
||||
drag.drag_released.connect(_on_drag_released)
|
||||
|
||||
|
||||
func _on_drag_picked_up(_pos: Vector2) -> void:
|
||||
if is_in_hand_slot():
|
||||
_detach_from_hand_slot()
|
||||
item_picked_up.emit(self)
|
||||
|
||||
|
||||
func _on_drag_released(_pos: Vector2) -> void:
|
||||
var result: Array = _find_nearest_free_hand_slot()
|
||||
if not result.is_empty():
|
||||
var character: Character = result[0] as Character
|
||||
var hand: String = result[1] as String
|
||||
character.attach_item(hand, self)
|
||||
item_placed.emit(self)
|
||||
|
||||
|
||||
func is_in_hand_slot() -> bool:
|
||||
var p: Node = get_parent()
|
||||
if p == null:
|
||||
return false
|
||||
return p.name == "HandLeft" or p.name == "HandRight"
|
||||
|
||||
|
||||
func _detach_from_hand_slot() -> void:
|
||||
var hand_slot: Node = get_parent()
|
||||
var character: Character = hand_slot.get_parent() as Character
|
||||
if character == null:
|
||||
return
|
||||
var hand: String = "left" if hand_slot.name == "HandLeft" else "right"
|
||||
character.detach_item(hand)
|
||||
|
||||
|
||||
func _find_nearest_free_hand_slot() -> Array:
|
||||
var best_dist: float = HAND_SLOT_RADIUS
|
||||
var best_character: Character = null
|
||||
var best_hand: String = ""
|
||||
for node: Node in get_tree().get_nodes_in_group("characters"):
|
||||
var character: Character = node as Character
|
||||
if character == null:
|
||||
continue
|
||||
for hand: String in ["left", "right"]:
|
||||
if not character.is_hand_free(hand):
|
||||
continue
|
||||
var slot: Node2D = character.get_node_or_null("Hand" + hand.capitalize()) as Node2D
|
||||
if slot == null:
|
||||
continue
|
||||
var dist: float = global_position.distance_to(slot.global_position)
|
||||
if dist < best_dist:
|
||||
best_dist = dist
|
||||
best_character = character
|
||||
best_hand = hand
|
||||
if best_character == null:
|
||||
return []
|
||||
return [best_character, best_hand]
|
||||
```
|
||||
|
||||
### Step 5: Run import + tests — verify all pass (124 total)
|
||||
|
||||
```
|
||||
"F:/Development/_tools/Godot_v4.6.2-stable_win64/Godot_v4.6.2-stable_win64.exe" --headless --import 2>&1
|
||||
"F:/Development/_tools/Godot_v4.6.2-stable_win64/Godot_v4.6.2-stable_win64.exe" --headless -s res://addons/gut/gut_cmdln.gd -gdir=res://test/ -gexit 2>&1
|
||||
```
|
||||
|
||||
Expected: 124/124 passed.
|
||||
|
||||
### Step 6: Commit
|
||||
|
||||
```bash
|
||||
cd "F:/Development/_gameDev/Cozypaw-Hospital/.worktrees/sprint-17-hand-slots-outfits"
|
||||
git add scripts/characters/character.gd
|
||||
git add scripts/objects/holdable_item.gd
|
||||
git add test/unit/test_character_v2.gd
|
||||
git add test/unit/test_holdable_item.gd
|
||||
git commit -m "feat(items): add HoldableItem with hand slot detection, fix detach_item position"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 2: OutfitItem + apply-on-drop + tap-to-undress
|
||||
|
||||
**Files:**
|
||||
- Modify: `scripts/characters/character.gd`
|
||||
- Create: `scripts/objects/outfit_item.gd`
|
||||
- Modify: `test/unit/test_character_v2.gd`
|
||||
- Create: `test/unit/test_outfit_item.gd`
|
||||
|
||||
### Step 1: Write the failing tests
|
||||
|
||||
Add to `test/unit/test_character_v2.gd`:
|
||||
|
||||
```gdscript
|
||||
func test_apply_outfit_item_hides_item() -> void:
|
||||
var item: Node2D = Node2D.new()
|
||||
add_child_autofree(item)
|
||||
_char.apply_outfit_item(1, "white_coat", null, item)
|
||||
assert_false(item.visible)
|
||||
|
||||
|
||||
func test_apply_outfit_item_sets_outfit_data() -> void:
|
||||
var item: Node2D = Node2D.new()
|
||||
add_child_autofree(item)
|
||||
_char.apply_outfit_item(1, "white_coat", null, item)
|
||||
assert_eq(_char.get_outfit(1), "white_coat")
|
||||
|
||||
|
||||
func test_remove_outfit_restores_item_visibility() -> void:
|
||||
var item: Node2D = Node2D.new()
|
||||
add_child_autofree(item)
|
||||
_char.apply_outfit_item(2, "cast_arm", null, item)
|
||||
_char.remove_outfit(2)
|
||||
assert_true(item.visible)
|
||||
|
||||
|
||||
func test_remove_outfit_clears_outfit_data() -> void:
|
||||
var item: Node2D = Node2D.new()
|
||||
add_child_autofree(item)
|
||||
_char.apply_outfit_item(2, "cast_arm", null, item)
|
||||
_char.remove_outfit(2)
|
||||
assert_eq(_char.get_outfit(2), "")
|
||||
|
||||
|
||||
func test_apply_outfit_item_replaces_existing() -> void:
|
||||
var item1: Node2D = Node2D.new()
|
||||
var item2: Node2D = Node2D.new()
|
||||
add_child_autofree(item1)
|
||||
add_child_autofree(item2)
|
||||
_char.apply_outfit_item(1, "white_coat", null, item1)
|
||||
_char.apply_outfit_item(1, "doctor_coat", null, item2)
|
||||
assert_true(item1.visible)
|
||||
assert_false(item2.visible)
|
||||
assert_eq(_char.get_outfit(1), "doctor_coat")
|
||||
|
||||
|
||||
func test_tap_removes_topmost_active_outfit_layer() -> void:
|
||||
var item1: Node2D = Node2D.new()
|
||||
var item3: Node2D = Node2D.new()
|
||||
add_child_autofree(item1)
|
||||
add_child_autofree(item3)
|
||||
_char.apply_outfit_item(1, "white_coat", null, item1)
|
||||
_char.apply_outfit_item(3, "stethoscope", null, item3)
|
||||
_char._handle_outfit_tap()
|
||||
# layer 3 is topmost active — it should be removed first
|
||||
assert_eq(_char.get_outfit(3), "")
|
||||
assert_eq(_char.get_outfit(1), "white_coat")
|
||||
|
||||
|
||||
func test_tap_noop_when_no_outfit_active() -> void:
|
||||
_char._handle_outfit_tap()
|
||||
assert_eq(_char.get_outfit(1), "")
|
||||
assert_eq(_char.get_outfit(2), "")
|
||||
assert_eq(_char.get_outfit(3), "")
|
||||
```
|
||||
|
||||
Create `test/unit/test_outfit_item.gd`:
|
||||
|
||||
```gdscript
|
||||
## Tests for OutfitItem — applies outfit layer when dropped near a character.
|
||||
extends GutTest
|
||||
|
||||
|
||||
func test_outfit_item_default_layer_is_one() -> void:
|
||||
var item: OutfitItem = OutfitItem.new()
|
||||
add_child_autofree(item)
|
||||
assert_eq(item.outfit_layer, 1)
|
||||
|
||||
|
||||
func test_outfit_item_applies_to_character_on_release_in_range() -> void:
|
||||
var character: Character = preload("res://scenes/characters/Character.tscn").instantiate() as Character
|
||||
add_child_autofree(character)
|
||||
var data: CharacterData = CharacterData.new()
|
||||
character.data = data
|
||||
var item: OutfitItem = OutfitItem.new()
|
||||
add_child_autofree(item)
|
||||
item.item_id = "white_coat"
|
||||
item.outfit_layer = 1
|
||||
item.outfit_sprite = null
|
||||
# Place item near character
|
||||
item.global_position = character.global_position
|
||||
item._on_drag_released(item.global_position)
|
||||
assert_eq(character.get_outfit(1), "white_coat")
|
||||
|
||||
|
||||
func test_outfit_item_hides_after_applying() -> void:
|
||||
var character: Character = preload("res://scenes/characters/Character.tscn").instantiate() as Character
|
||||
add_child_autofree(character)
|
||||
var data: CharacterData = CharacterData.new()
|
||||
character.data = data
|
||||
var item: OutfitItem = OutfitItem.new()
|
||||
add_child_autofree(item)
|
||||
item.item_id = "white_coat"
|
||||
item.outfit_layer = 1
|
||||
item.global_position = character.global_position
|
||||
item._on_drag_released(item.global_position)
|
||||
assert_false(item.visible)
|
||||
|
||||
|
||||
func test_outfit_item_falls_back_to_hand_slot_if_no_character_in_range() -> void:
|
||||
var character: Character = preload("res://scenes/characters/Character.tscn").instantiate() as Character
|
||||
add_child_autofree(character)
|
||||
var item: OutfitItem = OutfitItem.new()
|
||||
add_child_autofree(item)
|
||||
item.item_id = "white_coat"
|
||||
item.outfit_layer = 1
|
||||
# Place item near hand slot but NOT near character body
|
||||
item.global_position = character.get_node("HandLeft").global_position
|
||||
item._on_drag_released(item.global_position)
|
||||
# Should attach to hand slot, not apply as outfit
|
||||
assert_true(item.is_in_hand_slot())
|
||||
assert_eq(character.get_outfit(1), "")
|
||||
|
||||
|
||||
func test_outfit_item_does_not_apply_if_far_from_character() -> void:
|
||||
var character: Character = preload("res://scenes/characters/Character.tscn").instantiate() as Character
|
||||
add_child_autofree(character)
|
||||
var data: CharacterData = CharacterData.new()
|
||||
character.data = data
|
||||
var item: OutfitItem = OutfitItem.new()
|
||||
add_child_autofree(item)
|
||||
item.item_id = "white_coat"
|
||||
item.outfit_layer = 1
|
||||
item.global_position = Vector2(9999.0, 9999.0)
|
||||
item._on_drag_released(item.global_position)
|
||||
assert_eq(character.get_outfit(1), "")
|
||||
assert_true(item.visible)
|
||||
```
|
||||
|
||||
### Step 2: Run tests — verify new tests FAIL
|
||||
|
||||
Expected: 12 new failures. Existing 124 pass.
|
||||
|
||||
### Step 3: Modify `scripts/characters/character.gd`
|
||||
|
||||
**Add** these new members and methods. Insert the `var` declarations after the existing `var _current_anim: String = "idle"` line:
|
||||
|
||||
```gdscript
|
||||
var _current_anim: String = "idle"
|
||||
var _drag_start_position: Vector2 = Vector2.ZERO
|
||||
var _outfit_item_refs: Array = [null, null, null]
|
||||
|
||||
const _TAP_THRESHOLD: float = 10.0
|
||||
```
|
||||
|
||||
**Replace** `_on_drag_picked_up`:
|
||||
|
||||
```gdscript
|
||||
func _on_drag_picked_up(pos: Vector2) -> void:
|
||||
_is_held = true
|
||||
_drag_start_position = pos
|
||||
set_animation_state("held")
|
||||
character_picked_up.emit(self)
|
||||
```
|
||||
|
||||
**Replace** `_on_drag_released`:
|
||||
|
||||
```gdscript
|
||||
func _on_drag_released(pos: Vector2) -> void:
|
||||
_is_held = false
|
||||
var drag_distance: float = pos.distance_to(_drag_start_position)
|
||||
if drag_distance < _TAP_THRESHOLD:
|
||||
_handle_outfit_tap()
|
||||
return
|
||||
set_animation_state("idle")
|
||||
if data == null or data.id.is_empty():
|
||||
return
|
||||
GameState.set_character_position(character_id, global_position)
|
||||
character_placed.emit(self, global_position)
|
||||
```
|
||||
|
||||
**Add** new public methods (before `_update_visual_state`):
|
||||
|
||||
```gdscript
|
||||
func apply_outfit_item(layer: int, item_id: String, texture: Texture2D, item_node: Node2D) -> void:
|
||||
if layer < 1 or layer > 3:
|
||||
return
|
||||
var i: int = layer - 1
|
||||
var existing: Node2D = _outfit_item_refs[i] as Node2D
|
||||
if existing != null:
|
||||
existing.global_position = global_position + Vector2(0.0, 60.0)
|
||||
existing.visible = true
|
||||
_outfit_item_refs[i] = item_node
|
||||
set_outfit(layer, item_id, texture)
|
||||
if item_node != null:
|
||||
item_node.visible = false
|
||||
|
||||
|
||||
func remove_outfit(layer: int) -> void:
|
||||
if layer < 1 or layer > 3:
|
||||
return
|
||||
var i: int = layer - 1
|
||||
clear_outfit(layer)
|
||||
var item_ref: Node2D = _outfit_item_refs[i] as Node2D
|
||||
if item_ref != null:
|
||||
_outfit_item_refs[i] = null
|
||||
item_ref.global_position = global_position + Vector2(0.0, 60.0)
|
||||
item_ref.visible = true
|
||||
|
||||
|
||||
func _handle_outfit_tap() -> void:
|
||||
for layer: int in range(3, 0, -1):
|
||||
if not get_outfit(layer).is_empty():
|
||||
remove_outfit(layer)
|
||||
return
|
||||
```
|
||||
|
||||
### Step 4: Create `scripts/objects/outfit_item.gd`
|
||||
|
||||
```gdscript
|
||||
## OutfitItem — HoldableItem that applies an outfit layer to a Character when dropped
|
||||
## within OUTFIT_APPLY_RADIUS of the character's center. If no character is in range,
|
||||
## falls back to normal hand-slot attachment.
|
||||
class_name OutfitItem extends HoldableItem
|
||||
|
||||
const OUTFIT_APPLY_RADIUS: float = 80.0
|
||||
|
||||
@export var outfit_layer: int = 1
|
||||
@export var outfit_sprite: Texture2D
|
||||
|
||||
|
||||
func _on_drag_released(_pos: Vector2) -> void:
|
||||
var character: Character = _find_nearest_character()
|
||||
if character != null:
|
||||
character.apply_outfit_item(outfit_layer, item_id, outfit_sprite, self)
|
||||
return
|
||||
super._on_drag_released(_pos)
|
||||
|
||||
|
||||
func _find_nearest_character() -> Character:
|
||||
var best_dist: float = OUTFIT_APPLY_RADIUS
|
||||
var best: Character = null
|
||||
for node: Node in get_tree().get_nodes_in_group("characters"):
|
||||
var character: Character = node as Character
|
||||
if character == null:
|
||||
continue
|
||||
var dist: float = global_position.distance_to(character.global_position)
|
||||
if dist < best_dist:
|
||||
best_dist = dist
|
||||
best = character
|
||||
return best
|
||||
```
|
||||
|
||||
### Step 5: Run import + tests — verify all pass (136 total)
|
||||
|
||||
```
|
||||
"F:/Development/_tools/Godot_v4.6.2-stable_win64/Godot_v4.6.2-stable_win64.exe" --headless --import 2>&1
|
||||
"F:/Development/_tools/Godot_v4.6.2-stable_win64/Godot_v4.6.2-stable_win64.exe" --headless -s res://addons/gut/gut_cmdln.gd -gdir=res://test/ -gexit 2>&1
|
||||
```
|
||||
|
||||
Expected: 136/136 passed.
|
||||
|
||||
### Step 6: Commit
|
||||
|
||||
```bash
|
||||
git add scripts/characters/character.gd
|
||||
git add scripts/objects/outfit_item.gd
|
||||
git add test/unit/test_character_v2.gd
|
||||
git add test/unit/test_outfit_item.gd
|
||||
git commit -m "feat(items): add OutfitItem with apply-on-drop and tap-to-undress on Character"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 3: GameState v2 — outfit + held items persisted
|
||||
|
||||
**Files:**
|
||||
- Modify: `scripts/characters/character_data.gd`
|
||||
- Modify: `scripts/autoload/GameState.gd`
|
||||
- Modify: `test/unit/test_game_state.gd`
|
||||
|
||||
### Step 1: Write the failing tests
|
||||
|
||||
Check if `test/unit/test_game_state.gd` exists. If not, create it. If it exists, append these tests:
|
||||
|
||||
```gdscript
|
||||
## Tests for GameState — character outfit and held-item persistence.
|
||||
extends GutTest
|
||||
|
||||
|
||||
func before_each() -> void:
|
||||
GameState.apply_save_data({})
|
||||
|
||||
|
||||
func test_character_data_has_held_left_field() -> void:
|
||||
var cd: CharacterData = CharacterData.new()
|
||||
assert_eq(cd.held_left, "")
|
||||
|
||||
|
||||
func test_character_data_has_held_right_field() -> void:
|
||||
var cd: CharacterData = CharacterData.new()
|
||||
assert_eq(cd.held_right, "")
|
||||
|
||||
|
||||
func test_set_character_outfit_stores_value() -> void:
|
||||
GameState.set_character_outfit("bunny_f", ["white_coat", "", "stethoscope"])
|
||||
assert_eq(GameState.get_character_outfit("bunny_f"), ["white_coat", "", "stethoscope"])
|
||||
|
||||
|
||||
func test_get_character_outfit_returns_empty_array_for_unknown() -> void:
|
||||
var result: Array = GameState.get_character_outfit("unknown_id")
|
||||
assert_eq(result, ["", "", ""])
|
||||
|
||||
|
||||
func test_set_character_held_item_left() -> void:
|
||||
GameState.set_character_held_item("bunny_f", "left", "medicine_blue")
|
||||
assert_eq(GameState.get_character_held_item("bunny_f", "left"), "medicine_blue")
|
||||
|
||||
|
||||
func test_get_character_held_item_returns_empty_for_unknown() -> void:
|
||||
assert_eq(GameState.get_character_held_item("unknown", "left"), "")
|
||||
|
||||
|
||||
func test_save_data_includes_outfit() -> void:
|
||||
GameState.set_character_outfit("bunny_f", ["white_coat", "", ""])
|
||||
var data: Dictionary = GameState.get_save_data()
|
||||
assert_true(data.has("character_outfits"))
|
||||
assert_eq(data["character_outfits"]["bunny_f"], ["white_coat", "", ""])
|
||||
|
||||
|
||||
func test_save_data_includes_held_items() -> void:
|
||||
GameState.set_character_held_item("bunny_f", "right", "medicine_blue")
|
||||
var data: Dictionary = GameState.get_save_data()
|
||||
assert_true(data.has("character_held_items"))
|
||||
assert_eq(data["character_held_items"]["bunny_f"]["right"], "medicine_blue")
|
||||
|
||||
|
||||
func test_apply_save_data_restores_outfit() -> void:
|
||||
var save: Dictionary = {
|
||||
"character_outfits": {
|
||||
"bunny_f": ["doctor_coat", "", "stethoscope"]
|
||||
}
|
||||
}
|
||||
GameState.apply_save_data(save)
|
||||
assert_eq(GameState.get_character_outfit("bunny_f"), ["doctor_coat", "", "stethoscope"])
|
||||
|
||||
|
||||
func test_apply_save_data_restores_held_items() -> void:
|
||||
var save: Dictionary = {
|
||||
"character_held_items": {
|
||||
"kitten_f": {"left": "gel_tube", "right": ""}
|
||||
}
|
||||
}
|
||||
GameState.apply_save_data(save)
|
||||
assert_eq(GameState.get_character_held_item("kitten_f", "left"), "gel_tube")
|
||||
```
|
||||
|
||||
### Step 2: Run tests — verify new tests FAIL
|
||||
|
||||
Expected: 11 new failures. Existing 136 pass.
|
||||
|
||||
### Step 3: Modify `scripts/characters/character_data.gd`
|
||||
|
||||
Add two new fields after `outfit`:
|
||||
|
||||
```gdscript
|
||||
## CharacterData — Resource holding all persistent state for one character.
|
||||
class_name CharacterData extends Resource
|
||||
|
||||
enum State { HEALTHY, SICK, SLEEPING, TIRED, PREGNANT, BABY }
|
||||
enum Species { BUNNY, KITTEN }
|
||||
|
||||
@export var id: String = ""
|
||||
@export var display_name: String = ""
|
||||
@export var species: Species = Species.BUNNY
|
||||
@export var state: State = State.HEALTHY
|
||||
@export var current_floor: int = 0
|
||||
@export var position: Vector2 = Vector2.ZERO
|
||||
@export var outfit: Array[String] = ["", "", ""]
|
||||
@export var held_left: String = ""
|
||||
@export var held_right: String = ""
|
||||
```
|
||||
|
||||
### Step 4: Modify `scripts/autoload/GameState.gd`
|
||||
|
||||
Full replacement of the file to add outfit + held-item tracking:
|
||||
|
||||
```gdscript
|
||||
## GameState — global game state: character positions, outfit, held items, object states, current room.
|
||||
extends Node
|
||||
|
||||
signal state_changed
|
||||
signal character_moved(character_id: String, position: Vector2)
|
||||
|
||||
var _character_positions: Dictionary = {}
|
||||
var _character_outfits: Dictionary = {}
|
||||
var _character_held_items: Dictionary = {}
|
||||
var _object_states: Dictionary = {}
|
||||
var current_room: String = "reception"
|
||||
var music_volume: float = 0.6
|
||||
var sfx_volume: float = 1.0
|
||||
|
||||
|
||||
func has_character_position(id: String) -> bool:
|
||||
return _character_positions.has(id)
|
||||
|
||||
|
||||
func get_character_position(id: String) -> Vector2:
|
||||
return _character_positions.get(id, Vector2.ZERO)
|
||||
|
||||
|
||||
func set_character_position(id: String, pos: Vector2) -> void:
|
||||
_character_positions[id] = pos
|
||||
character_moved.emit(id, pos)
|
||||
state_changed.emit()
|
||||
|
||||
|
||||
func get_character_outfit(id: String) -> Array:
|
||||
return _character_outfits.get(id, ["", "", ""])
|
||||
|
||||
|
||||
func set_character_outfit(id: String, outfit: Array) -> void:
|
||||
_character_outfits[id] = outfit
|
||||
state_changed.emit()
|
||||
|
||||
|
||||
func get_character_held_item(id: String, hand: String) -> String:
|
||||
if not _character_held_items.has(id):
|
||||
return ""
|
||||
return _character_held_items[id].get(hand, "")
|
||||
|
||||
|
||||
func set_character_held_item(id: String, hand: String, item_id: String) -> void:
|
||||
if not _character_held_items.has(id):
|
||||
_character_held_items[id] = {"left": "", "right": ""}
|
||||
_character_held_items[id][hand] = item_id
|
||||
state_changed.emit()
|
||||
|
||||
|
||||
func get_object_state(id: String) -> String:
|
||||
return _object_states.get(id, "idle")
|
||||
|
||||
|
||||
func set_object_state(id: String, state: String) -> void:
|
||||
_object_states[id] = state
|
||||
state_changed.emit()
|
||||
|
||||
|
||||
func get_save_data() -> Dictionary:
|
||||
var positions: Dictionary = {}
|
||||
for key: String in _character_positions:
|
||||
var pos: Vector2 = _character_positions[key]
|
||||
positions[key] = [pos.x, pos.y]
|
||||
return {
|
||||
"version": 2,
|
||||
"character_positions": positions,
|
||||
"character_outfits": _character_outfits.duplicate(true),
|
||||
"character_held_items": _character_held_items.duplicate(true),
|
||||
"object_states": _object_states,
|
||||
"current_room": current_room,
|
||||
"music_volume": music_volume,
|
||||
"sfx_volume": sfx_volume,
|
||||
}
|
||||
|
||||
|
||||
func apply_save_data(data: Dictionary) -> void:
|
||||
if data.has("character_positions"):
|
||||
_character_positions = {}
|
||||
for key: String in data["character_positions"]:
|
||||
var val: Variant = data["character_positions"][key]
|
||||
if val is Array and val.size() >= 2:
|
||||
_character_positions[key] = Vector2(val[0], val[1])
|
||||
if data.has("character_outfits"):
|
||||
_character_outfits = data["character_outfits"].duplicate(true)
|
||||
else:
|
||||
_character_outfits = {}
|
||||
if data.has("character_held_items"):
|
||||
_character_held_items = data["character_held_items"].duplicate(true)
|
||||
else:
|
||||
_character_held_items = {}
|
||||
if data.has("object_states"):
|
||||
_object_states = data["object_states"]
|
||||
if data.has("current_room"):
|
||||
current_room = data["current_room"]
|
||||
if data.has("music_volume"):
|
||||
music_volume = data["music_volume"]
|
||||
if data.has("sfx_volume"):
|
||||
sfx_volume = data["sfx_volume"]
|
||||
```
|
||||
|
||||
### Step 5: Run import + tests — verify all pass (147 total)
|
||||
|
||||
```
|
||||
"F:/Development/_tools/Godot_v4.6.2-stable_win64/Godot_v4.6.2-stable_win64.exe" --headless --import 2>&1
|
||||
"F:/Development/_tools/Godot_v4.6.2-stable_win64/Godot_v4.6.2-stable_win64.exe" --headless -s res://addons/gut/gut_cmdln.gd -gdir=res://test/ -gexit 2>&1
|
||||
```
|
||||
|
||||
Expected: 147/147 passed.
|
||||
|
||||
### Step 6: Commit
|
||||
|
||||
```bash
|
||||
git add scripts/characters/character_data.gd
|
||||
git add scripts/autoload/GameState.gd
|
||||
git add test/unit/test_game_state.gd
|
||||
git commit -m "feat(save): extend GameState to v2 — outfit and held items persisted per character"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Final Check
|
||||
|
||||
- [ ] **Run full test suite one last time**
|
||||
|
||||
```
|
||||
"F:/Development/_tools/Godot_v4.6.2-stable_win64/Godot_v4.6.2-stable_win64.exe" --headless -s res://addons/gut/gut_cmdln.gd -gdir=res://test/ -gexit 2>&1
|
||||
```
|
||||
|
||||
Expected output:
|
||||
```
|
||||
Scripts 13
|
||||
Tests 147
|
||||
Passing Tests 147
|
||||
---- All tests passed! ----
|
||||
```
|
||||
|
||||
- [ ] **Verify git log shows 3 clean commits**
|
||||
|
||||
```bash
|
||||
git log --oneline -4
|
||||
```
|
||||
|
||||
Expected:
|
||||
```
|
||||
feat(save): extend GameState to v2 — outfit and held items persisted per character
|
||||
feat(items): add OutfitItem with apply-on-drop and tap-to-undress on Character
|
||||
feat(items): add HoldableItem with hand slot detection, fix detach_item position
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notes for implementer
|
||||
|
||||
- **`_outfit_item_refs` typed as `Array` not `Array[Node2D]`** — GDScript typed arrays with null defaults can cause issues in some Godot versions. Use untyped `Array` with explicit `as Node2D` casts.
|
||||
- **`test_outfit_item_falls_back_to_hand_slot_if_no_character_in_range`** — This test places the item near a HandLeft but NOT near the character body. The OUTFIT_APPLY_RADIUS (80px) check on `character.global_position` will fail (HandLeft is only 32px offset), but since the HandLeft is within HAND_SLOT_RADIUS (60px) of HandLeft position, the HoldableItem fallback will attach it to the hand. Verify position arithmetic in your test setup.
|
||||
- **`before_each` in test_game_state.gd calls `GameState.apply_save_data({})`** — this resets state between tests. The autoload singleton persists between GUT test functions, so the reset is mandatory.
|
||||
- **`_handle_outfit_tap` is public** (no underscore would be cleaner, but the existing convention uses underscore for private methods). Keep the underscore — tests call it directly. This is acceptable for unit testing.
|
||||
- **`_TAP_THRESHOLD`** needs to be a constant not a `const` with underscore (underscore prefix = private, which is fine here since it's internal to character.gd).
|
||||
Reference in New Issue
Block a user