diff --git a/docs/superpowers/plans/2026-05-08-sprint-17-hand-slots-outfits.md b/docs/superpowers/plans/2026-05-08-sprint-17-hand-slots-outfits.md new file mode 100644 index 0000000..6bd410d --- /dev/null +++ b/docs/superpowers/plans/2026-05-08-sprint-17-hand-slots-outfits.md @@ -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).