my-project/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Unity game project (no CLI build commands — use the Unity Editor). Two major systems:
1. **Character Controller** — first/third-person movement with animations
2. **Inventory System** — hotbar, drag-drop, crafting, world items, save/load

## Controls

| Action | Key |
|---|---|
| Move | WASD |
| Look | Mouse |
| Run | Left Shift |
| Crouch | C |
| Jump | Space |
| Pickup | E |
| Toggle Inventory | Tab |
| Close Inventory | Escape |
| Hotbar Select | 1–9 |
| Drop Item | Q |

## Architecture

### Input Layer — `PlayerInput` (singleton, DontDestroyOnLoad)
All input is centralised in `Assets/charecter-controller/scripts/PlayerInput.cs`. It is backed by the **New Input System** (`Assets/Input/PlayerControls.inputactions`, action maps: `Gameplay` and `UI`) and supports runtime key rebinding persisted via PlayerPrefs. It exposes:
- Continuous properties: `MoveInput`, `LookInput`, `Crouch`, `Run`
- C# events: `OnJumpPressed`, `OnPickupPressed`, `OnToggleInventory`, `OnDropPressed`, `OnHotbarSelect`
- `Enabled` flag — set to `false` when the inventory is open to block gameplay input

Both `charecter.cs` and `InventoryManager.cs` subscribe to `PlayerInput.Instance` events in `Start()`. Never read `Input.*` directly in new code — go through `PlayerInput`.

### Character Controller — `charecter.cs`
- Requires `CharacterController` component
- Head-bone / body separation: body yaw tracks camera yaw when moving; head offset is clamped to `±maxHeadYaw`
- Bone rotations applied in `LateUpdate` via `ApplyRotations()`
- Animator hashes cached as `static readonly int` fields; animator Speed param: 0 = idle, 0.5 = walk, 1 = run; also drives `IsMoving`, `IsCrouching`, `IsGrounded`
- Item pickup radius-cast in `TryPickupNearbyItem()` (2.5 m sphere, closest `WorldItem` wins)

### Hand Equip System — `HandEquipSystem.cs`
- Attaches to the player; requires a `handBone` transform (right-hand bone)
- Listens to `PlayerInput.OnHotbarSelect` and `InventoryEvents.OnSlotChanged` to keep the in-hand 3D model in sync
- Instantiates `ItemData.modelPrefab` as a child of `handBone`; destroys the previous model on slot change

### Inventory System
**Singleton chain** (all DontDestroyOnLoad, all auto-created if missing):
```
PlayerInput → InventoryManager → InventoryItemFactory
                              → InventoryEvents
```

**InventoryManager** (`Assets/Inventory/Scripts/InventoryManager.cs`)
- `slots[]` (36) = main inventory; `hotbarSlots[]` (9, indices 0-8)
- `_itemDict` maps `ItemData.id → ItemData`; rebuilt via `RebuildItemDictionary()` — call this after runtime DB changes
- `AddItem()` fill order: existing main stacks → empty main slots → existing hotbar stacks → empty hotbar slots
- Save/load: JSON to `Application.persistentDataPath/inventory_save.json`; auto-save on `OnApplicationQuit`

**InventoryEvents** (`Assets/Inventory/Scripts/InventoryEvents.cs`) — singleton event bus (DontDestroyOnLoad):
- `OnItemAdded<string, int>`, `OnItemRemoved<string, int>`, `OnItemCountChanged<string, int>`
- `OnSlotChanged<int, string>` (slotIndex, itemId) — fired whenever a slot's contents change
- `OnInventoryOpened`, `OnInventoryClosed`

**ItemData** — ScriptableObject (`Assets > Create > Inventory > Item`). `id` is auto-assigned as GUID on first `OnEnable`. ItemType enum: `Block, Weapon, Armor, Consumable, Tool, Material`. Each `ItemData` can embed a `craftingRecipe` directly.

**InventoryItemFactory** — creates/drops `WorldItem` GameObjects. Needs an `ItemFactoryConfig` ScriptableObject (`Assets > Create > Inventory > Item Factory Config`) assigned in the Inspector for prefab-based spawning; falls back to a primitive cube if no prefab is configured. Config fields: `worldItemPrefab`, `dropForce`, `dropRandomness`, `despawnTime`.

**InventoryDragDrop** — implements `IBeginDragHandler / IDragHandler / IEndDragHandler`:
- Drag between slots performs a `SwapSlots()` via raycast
- Dropping outside the inventory area calls `InventoryItemFactory.DropItem()` to spawn a `WorldItem`

**CraftingManager** — recipe key is sorted comma-joined ingredient IDs (`"id1,id2,id3"`). Recipes can be added at runtime via `AddRecipe()`. UI: 9 input slots, 1 output slot, craft button.

**InventoryUIBuilder** — generates the entire inventory UI programmatically at runtime (Canvas, GridLayoutGroup, Slot components, drag-drop handlers). Assigns `InventoryManager.Instance.slots` and `.hotbarSlots` directly. Do not assign these arrays in the Inspector when using this builder.

**InventorySetup** — convenience MonoBehaviour; add to a "GameManager" object to auto-create all managers and UI on scene start. Has an Editor button in the Inspector. Skips creation if `InventoryManager` already exists.

### Editor Tools (Tools menu)
These tools set up the scene at edit time — prefer them over manual wiring:
- **Tools > Setup Complete Scene** (`InventorySceneSetup.cs`) — creates EventSystem, all manager singletons, Player, InventoryCanvas, and PlayerInput in one click
- **Tools > Player Builder** (`PlayerBuilderTool.cs`) — creates CharacterController, `charecter.cs`, Camera, PlayerInput, HandEquipSystem; auto-detects head/hand bones; option to save as a prefab
- **Tools > Item Builder** (`ItemBuilderTool.cs`) — creates `ItemData` ScriptableObjects, WorldItem prefabs, and optionally places them in the scene; auto-generates placeholder icons

### Scene Setup
`Assets/Scenes/SampleScene.unity` is the only scene. Typical hierarchy:
- `GameManager` with `InventorySetup` (or manually placed `InventoryManager` + `InventoryUIBuilder`)
- Player with `charecter.cs` + `CharacterController` + Animator + head bone reference + `HandEquipSystem` (hand bone reference)

### Meta Files
Unity requires `.meta` files for all assets — always commit them alongside their assets.