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.