# 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).