Emberwild/.claude/CLAUDE.md

# CLAUDE.md

Guidance for working in this Unity project. **These rules are mandatory** — follow them
exactly when reading, writing, or refactoring any C# script.

---

## 1. Project overview

First-person survival/exploration game built in **Unity 6000.3.8f1** with **URP**.
The game is **online co-op multiplayer** (a single-player build is just a host with no
clients — there is no separate offline mode). Core systems already in place: first-person
locomotion, camera, stats (health/hunger/thirst), inventory + hotbar, crafting, cooking,
harvesting/tools, procedural scatter placement, audio (footsteps by surface + music),
seasons, and a full UI/menu/settings stack.

**Networking stack** (see §3):
- **FishNet 4.7.2** (in `Assets/FishNet/`) — the netcode.
- **Steamworks.NET** + **FishySteamworks** transport — Steam relay (SteamNetworkingSockets,
  no port forwarding). Sessions are joined by a shareable code (host SteamID64) or Steam invite.

Context for current work:
- **This is final, production-quality code — not a prototype.** Aim for clean, well-named,
  well-architected code that respects the patterns in this document. No quick hacks,
  no "temporary" shortcuts; if something is worth doing, do it properly.
- **Multiplayer co-op is a hard constraint** — when touching any player, world or shared
  system, assume two+ players exist (see §3).
- **Player body is split by viewpoint** — the **local owner** sees a **first-person arms
  viewmodel** (his own hands/tools); **remote players** are drawn as a **full third-person
  body**. Each client renders its own arms *and* everyone else's full body. The owner's own
  third-person body is hidden from his first-person camera (owner-only vs remote-only gating
  lives in `PlayerNetworkController` — see §3). HUD/audio feedback still applies on top.
- Animations use **DOTween** (tweens, not Animator) wherever possible.
- Shaders are **hand-written HLSL/ShaderLab** — do not propose Shader Graph.

---

## 2. Architecture — the golden rule

**Everything talks through the static event bus `PlayerEvents`**
(`Assets/GAME/Script/Player/Events/PlayerEvents.cs`).

- `PlayerEvents` is the source of truth for the **local** player's cross-system state
  (`IsDead`, `IsGrounded`, `IsInventoryOpen`, `IsPaused`, `InputLocked`, …). Here "shared"
  means shared *between systems on one client* — never *between players* (see §3).
- Producers call a `Raise*` method; the raiser updates the matching `IsX` state, logs
  (under the `PLAYER_EVENT_LOG` define) and invokes the event.
- Consumers subscribe to the `event` in `OnEnable` and **unsubscribe in `OnDisable`**.
- **Never** reach across systems with `FindObjectOfType` or hard references to read state
  that the bus already exposes. Add a new event/state to `PlayerEvents` instead — **except**
  per-player networked state, which belongs on a `NetworkBehaviour` (SyncVar/RPC), not the
  bus (see §3).

**Each script owns one concern — but "concern" means one reason to change, not one tiny
action.** A script reads its own inputs/state from the bus, does its job, and raises events for
others. Do not let a script mutate another system's internal data directly. If two systems need
to coordinate, route it through `PlayerEvents`.

Group by **cohesion, not by a per-action counter.** Splitting a feature into many micro-scripts
is its own anti-pattern (scattered logic, high coupling, inspector-wiring noise) just as much as a
god-object is. Keep together what changes together and is used together; split only at a **real
seam** — a genuinely different reason to change, a different collaborator set, or a file growing
unwieldy. The seam that always matters: **local player UX vs shared networked state** (see §3) —
never fuse across it. Reference: the build system splits into `BuildManager` (all the *local*
build UX — catalog, menu, placement) and `BuildRegistry` (the *networked* side — committed
structures + the ghost NetworkObject), one clean local/network seam, not a script per
sub-responsibility.

Data that is authored in the editor lives in **ScriptableObjects** (`ItemData`,
`CraftingRecipe`, `SurfaceSoundProfile`, `ScatterProfile`, `MusicPlaylist`,
`ToolDropTable`, …). Logic lives in `MonoBehaviour`s. Keep them separate.

Singletons exist where a single instance is genuinely global (`PlayerInventory.Instance`,
`PlayerStats.Instance`, …); guard every access for `null` — they may not exist yet or in
every scene.

**UI is a dumb view — a manager owns the data and populates it.** A UI component (a panel,
a card, a list row, …) must **never** reach for domain data itself: no catalog, no
`ScriptableObject` list, no scanning a database/model to decide *what* to show. It exposes a
`Populate(...)` / `Set(...)` method that takes a lightweight **view payload** (plain
icon / label / number data — never the authored `ScriptableObject`) plus a selection
callback, and renders exactly what it is handed. A dedicated **manager** owns the real data
(the catalog, the model), builds the view payload, pushes it into the UI, and handles the
callback — i.e. it decides what a click *does*. The view reports interactions back by
**index or token**, never by resolving the underlying data. Data flows one way (manager →
view), interactions flow back one way (view → manager via callback), and views stay
swappable and data-agnostic. Reference implementation: `BuildManager` (owns the catalog,
populates + handles picks) + `BuildMenuUI` / `BuildMenuCardUI` (pure views) +
`BuildCardView` (the view payload).

---

## 3. Multiplayer — the second golden rule

The game runs on **FishNet** (co-op, **client-authoritative** — friendly play, *not*
anti-cheat). Networking code lives in `Assets/GAME/Script/Network/`. When you write or
change anything that involves a player, the world, or shared state, obey these rules.

### `PlayerEvents` is the LOCAL player's bus only

The static `PlayerEvents` (state + events) represents **the local owned player**, never
remote players. Only owner-side code may call `Raise*`. Remote player copies must **never**
drive the static bus — they only update their own instance state (e.g. via SyncVar hooks).
Per-player networked state (health, position, …) belongs on the player's `NetworkBehaviour`
(SyncVar / RPC), not in `PlayerEvents`.

### Owner gating

`PlayerNetworkController` (on the player root) disables every owner-only component
(input, locomotion, camera, tools, **stats**, inventory, hotbar, interactor, audio,
lifecycle) and owner-only object (cameras, audio listener, tool holder) on non-owners, then
raises `LocalPlayerSpawned`. **Any new player component that simulates or reads local input
must be added to that `ownerOnlyBehaviours` list.** Scene/UI code must bind to the *local*
player — get it from `PlayerInventory.Instance` / `PlayerStats.Instance` (owner-only
singletons), **never** `FindObjectOfType<PlayerX>()`, which also matches disabled remote
puppets (their root GameObject stays active) and targets the wrong player.

### Keep systems OFF the player — it holds only its own intrinsic state

**Default to a scene object/registry, not the player prefab.** The player carries *only what is
intrinsically the local player itself*: its owner-only local simulation (input, locomotion, camera,
tools, animation driver) and its own per-player networked state (health/stats, inventory, the body).
**Everything that touches the world or shared state — and anything that does not need per-player
networking — lives OUTSIDE the player.** This is logical: a build, a placed structure, a shared
station, even a *per-player preview of a world action* (the build ghost), is world-facing, so it
belongs to a scene `NetworkBehaviour` (a `SyncList<…>` registry, or a NetworkObject it spawns),
**never bolted onto the player**. Do not reflexively put per-player networked state on the player
just because it is "per player" — ask first *"is this the player, or is it the world?"*. If it is
world/shared, it is a scene object. Reference implementations: `WorldObjectRegistry`, `BuildRegistry`
(committed structures + the spawned ghost preview), `CookingStation`. The player-hosted pattern
below is only for state that genuinely *is* the player.

### Visible body — first-person arms (owner) + third-person body (remotes)

Every player is drawn twice, split by viewpoint (see §1):

- **First-person arms** — the owner's own hands/tools, seen *only* by the owner. The arms mesh
  goes in `PlayerNetworkController.ownerOnlyObjects` (hidden on remotes); it is **never**
  networked because no one else renders it.
- **Third-person body** — the full character everyone else sees. It stays active on *all*
  clients so its `Animator` keeps running. `PlayerBodyVisibility` (a `NetworkBehaviour` on the
  player root) relayers the **owner's own** body onto a `LocalBody` layer that the owner's
  first-person camera excludes from its culling mask — so the owner never sees his own body
  clip the view, yet every remote still renders it. **Layers are local and never networked**,
  so hiding your body from yourself does not hide it from anyone else.

**Animation is a bus consumer, replicated by `NetworkAnimator`.** `PlayerAnimatorDriver`
(`Player/Animation/`) drives an `Animator` purely from `PlayerEvents` (`VelocityChanged`,
`GroundedChanged`, `Jumped`, `AttackSwung`, `CrouchChanged`, …). The same component drives both
rigs from that one shared source, so arms and body stay in lockstep. Each instance is owner-only
local simulation → **add every `PlayerAnimatorDriver` to `ownerOnlyBehaviours`**. On the body,
a sibling FishNet **`NetworkAnimator`** replicates the owner's animation to remotes (whose driver
is disabled and whose body is animated by the replicated parameters instead). Need a new
animation cue? Add an event to `PlayerEvents` and have the driver subscribe — never poll another
system's internals.

### Networking a player system — the canonical pattern (mirror `PlayerInventory`/`PlayerStats`)

- Make it a `NetworkBehaviour`. **No destructive `Awake` singleton guard** (it would destroy
  spawned remote players). Set the `Instance` only for the owner, in `OnStartNetwork`
  (`if (base.Owner.IsLocalClient) Instance = this;`), clear it in `OnStopNetwork`.
- Owner simulates locally; replicate a lightweight snapshot via SyncVar (server writes,
  pushed from the owner through a `[ServerRpc]`, throttled + immediate on key events).
- SyncVar `OnChange` updates remote copies' local state only — guard `if (base.IsOwner) return;`
  and never touch `PlayerEvents` there.

### World state

World objects (pickables, harvestables) are **not** NetworkObjects. They use the
`WorldObject` + `WorldObjectRegistry` pattern: one networked registry per type per scene
owns a synced set of inactive ids + server-side authority (health, loot, drops) via RPC.
Add new harvestable/pickable-like world state here, not as per-object NetworkObjects.
`ItemData` cannot cross the wire — map items to ids through `ItemDatabase`
(**Tools ▸ Ashwild ▸ Rebuild Item Database** after adding items).

**Placed structures are the deliberate exception — they ARE NetworkObjects.** `BuildRegistry` spawns
every committed build server-side (`ServerManager.Spawn`) and each one carries its own state on its
own `BuiltStructure`. This used to be a data registry (a `SyncList` of pose records each client
instantiated locally), and it was changed on purpose: the records never saved the GameObjects — those
were instantiated locally anyway, so memory, colliders and draw calls were identical — they only saved
FishNet's per-object bookkeeping, and they forced a **second, incompatible mechanism** for any build
with real state (chests, cooking stations). One mechanism for walls, chests and campfires alike is
worth the bookkeeping at co-op base scale. Buildables still cross the wire as ids through
`BuildableDatabase`.

This "no NetworkObjects" rule targets genuinely **high-count, stateless** world state — the thousands
of scatter objects — where a per-object NetworkObject buys nothing. It is **not** a blanket ban, and
two cases deliberately go the other way:

- **Placed structures** (hundreds, and many of them stateful) — server-spawned NetworkObjects, see above.
- **The build ghost** (transient, one per player, moves every frame) — a NetworkObject with a
  client-authoritative NetworkTransform, spawned by `BuildRegistry`.

Pick by **state and count together**, not by count alone: the moment an object needs its own
replicated state, a data registry means hand-rolling what FishNet already does per object.

### Shared interactables (cooking stations, future chests/benches)

Anything two players can use at once needs server-authoritative state + RPCs — local-only
MonoBehaviour state will let players clobber each other. `CookingStation` is the reference:
the server owns the simulation (fuel burn + cooking timers), replicates a compact view
(`SyncList<SlotView>` + a `SyncVar<int>` log count), and mutates only through
`[ServerRpc(RequireOwnership = false)]` requests that refund the item on failure via
`PlayerInventory.GrantItemFromServer`. Mirror it for chests/benches.

### Not yet networked — do not rely on these in co-op

These still run locally and will desync between clients until migrated:

- **`GrassClearer`** — modifies the terrain detail layer locally, no RPC → others keep the grass.
- **`SeasonManager`** — the global `_Season` shader value is not synced → visual desync.

### Reference implementations

Copy these patterns rather than inventing new ones: `PlayerInventory.cs` and `PlayerStats.cs`
(networked player system), `HarvestableRegistry.cs` / `WorldObjectRegistry.cs` (world state),
`CookingStation.cs` (server-authoritative shared interactable), `PlayerNetworkController.cs`
(owner gating).

---

## 4. Folder map (`Assets/GAME/Script/`)

| Folder | Namespace | Responsibility |
| --- | --- | --- |
| `Player/Events/` | `Ashwild.Player` | `PlayerEvents` — the central bus. Start here to understand the game. |
| `Player/Input/` | `Ashwild.Player` | `PlayerInputRouter` — the **only** Input System receiver. |
| `Player/Locomotion/` | `Ashwild.Player` | Movement, ground/slope checks, jump, slide, crouch. |
| `Player/Camera/` | `Ashwild.Player` | First-person camera, look, head height. |
| `Player/Tools/` | `Ashwild.Player` | Tool equip/swing logic and tool holder. |
| `Player/` (root) | `Ashwild.Player` | `PlayerStats`, `PlayerInteractor`, `PlayerLifecycle`, `PlayerAudio`. |
| `Network/` | `Ashwild.Network` | FishNet layer — session host/join, player spawn, owner gating, `WorldObject`/registry world-state sync. |
| `Inventory/` | `Ashwild.Inventory` | Inventory model, slots, hotbar, pickables, inventory UI. |
| `Crafting/` | `Ashwild.Crafting` | Recipes, ingredients, crafting manager and its UI. |
| `Cooking/` | `Ashwild.Cooking` | Cooking stations (food + fuel → cooked results). |
| `Harvesting/` | `Ashwild.Harvesting` | Harvestables, tools, resource drops, scatter placement. |
| `Audio/` | `Ashwild.Audio` | Music manager/playlist, surface sound profiles. |
| `Environment/` | `Ashwild.Environment` | Season manager. |
| `GrassClearer/` | `Ashwild.GrassClearer` | Detail/grass removal around placed objects. |
| `Interaction/` | `Ashwild.Interaction` | `IInteractable` and interaction contracts. |
| `Settings/` | `Ashwild.Settings` | Settings manager, panels and sub-panels, brightness. |
| `UI/` | `Ashwild.UI` | HUD, panels, notifications, crosshair, death/splash/pause screens. |
| `Integrations/` | `Ashwild.Integrations` | Third-party integrations (e.g. Discord Rich Presence). |
| `Editor/` | `Ashwild.EditorTools` | Custom inspectors, property drawers, tooling (editor-only). |

### Namespaces — one per top-level system folder

Every script lives in a namespace **`Ashwild.<TopLevelFolder>`** — flat, one per
top-level system folder. Sub-folders do **not** get their own namespace: everything under
`Player/` (incl. `Player/Camera/`, `Player/Input/`, `Player/Tools/`, `Player/HeldItems/`)
is `Ashwild.Player`. This flatness is deliberate — it keeps cross-references short and
avoids a sub-namespace shadowing a Unity type (a namespace `Ashwild.Player.Camera` would
mask `UnityEngine.Camera` inside it).

Rules when adding or moving a script:

- New file → wrap it in the namespace of its top-level folder. Add `using Ashwild.X;` for
  every other Ashwild namespace whose types it references.
- **`Editor/` is the one exception to the `Ashwild.<Folder>` rule** — its namespace is
  **`Ashwild.EditorTools`**, *not* `Ashwild.Editor`, because a namespace segment named
  `Editor` shadows the `UnityEditor.Editor` base type that every custom inspector derives
  from (`CS0118`).
- **Never** put `using Ashwild.EditorTools;` in a runtime (non-`Editor/`) script. Editor
  code compiles into the separate `Assembly-CSharp-Editor` assembly, which runtime code
  cannot reference (`CS0234`). Editor scripts may freely `using` runtime namespaces, not
  the reverse.

---

## 5. Code conventions — non-negotiable

### 5.1 XML summaries
Every **class, method, and non-obvious public member** gets a `/// <summary>` written in
**English**, describing intent (the *why*), not restating the signature.

```csharp
/// <summary>
/// Adds an item to the inventory, stacking into existing slots first.
/// Returns false (and logs) when the item is null or no room remains.
/// </summary>
public bool AddItem(ItemData item, int quantity = 1) { ... }
```

**Use the 3-line form** — opening `/// <summary>`, the text, and the closing
`/// </summary>` each on their own line; never collapse a summary onto one line.

Scope (this matches the real codebase — see `PlayerInventory`/`PlayerStats`):
- **Always:** every class, every method (incl. Unity lifecycle and event handlers), and any
  public member whose intent isn't obvious from its name.
- **Not required:** trivial getters / `=>` passthroughs and `[SerializeField]` fields — group
  the latter under `[Header("...")]` and clarify individual ones with `[Tooltip("...")]`
  (or a summary) only when the name alone doesn't convey intent.

### 5.1b No in-body comments — explain in the summary above the method
**Never write explanatory comments *inside* a method body.** All rationale — the *why*, the
gotchas, the edge cases — goes in the `/// <summary>` above the method (extend it with as much
prose as needed). The body stays pure code. If a block feels like it needs an inline comment to
be understood, that's a signal to either name things better or extract it into its own
well-summarized method. The only inline text allowed in a body is a `// TODO:` / `// HACK:`
marker for tracked future work — not an explanation of what the current code does.

```csharp
// ❌ wrong — explanation lives inside the body
private void Step()
{
    // Subtract instead of zeroing so the leftover carries into the next step.
    distanceTravelled -= stepDistance;
}

/// <summary>
/// Fires a footstep and carries the leftover distance into the next step. Subtracting
/// (instead of zeroing) keeps the cadence even at sprint speed, where the per-frame
/// overshoot would otherwise randomly stretch steps and drift out of sync.
/// </summary>
private void Step()
{
    distanceTravelled -= stepDistance;
}
```

### 5.2 Specific `#region`s — never one generic blob
Group members into **named, specific** regions reflecting their role. Do **not** dump
everything under a single `#region Methods`. Typical regions for a MonoBehaviour:

```csharp
#region Serialized Fields
#region State
#region Unity Lifecycle      // Awake / OnEnable / OnDisable / Start / Update
#region Event Handlers       // bus callbacks
#region Public API
#region Internal Helpers
#endregion
```

Pick regions that match what the script actually does (e.g. `#region Ground Check`,
`#region Surface Detection`, `#region Playback`). The goal: a reader scans the region
names and knows the script's shape instantly.

### 5.3 Event subscription lifecycle
Subscribe in `OnEnable`, unsubscribe in `OnDisable` — always paired, same order.
Never subscribe without a matching unsubscribe (leaks + double-fire after reload).

### 5.4 DOTween hygiene
Cache tweeners in fields and `Kill()` them in `OnDestroy` (and before restarting them).
A tween targeting a destroyed object throws — never leave one running on teardown.

### 5.5 Defensive logging instead of crashes
Guard nullable inputs and log a clear, prefixed error with the **context object** so
clicking the console message selects the culprit in the hierarchy:

```csharp
if (itemData == null)
{
    Debug.LogError($"[Pickable] '{name}' has no ItemData assigned — cannot pick up.", this);
    return;
}
```

Prefix logs with `[ClassName]`. Pass `this` as the second arg whenever possible.

### 5.6 Input naming — avoid the `On<Action>` trap
The `PlayerInput` component uses **Send Messages**, so Unity invokes `On<ActionName>`
methods by reflection on the player's GameObject and its components.
**Only `PlayerInputRouter` may declare `On<Action>` methods.** Any other component with a
method named like an input action (e.g. `OnHotbarScroll`) will be invoked by the Input
System and crash on a signature mismatch. Name bus handlers `Handle<Thing>` instead.

### 5.7 General practices
- `private` fields exposed to the inspector use `[SerializeField] private`, grouped under
  `[Header("...")]`. No public fields just to show them in the inspector.
- One class per file; file name matches the type.
- Prefer `OnEnable/OnDisable` over `Start/OnDestroy` for subscription symmetry.
- No magic numbers in logic that designers tune — promote them to serialized fields.
- Don't add `FindObjectOfType` in hot paths (`Update`/`FixedUpdate`); cache references.
- Keep `Update`/`FixedUpdate` cheap; cache expensive lookups (see `PlayerAudio`'s surface
  cache for the pattern).

---

## 6. Canonical script template

```csharp
using UnityEngine;

/// <summary>
/// One-sentence description of this component's single responsibility.
/// </summary>
[DisallowMultipleComponent]
public class ExampleSystem : MonoBehaviour
{
    #region Serialized Fields

    [Header("Tuning")]
    [SerializeField] private float duration = 1f;

    #endregion

    #region State

    private bool isActive;

    #endregion

    #region Unity Lifecycle

    /// <summary>
    /// Subscribes to the bus events this system reacts to.
    /// </summary>
    private void OnEnable()
    {
        PlayerEvents.Died += HandleDied;
    }

    /// <summary>
    /// Unsubscribes — must mirror OnEnable exactly.
    /// </summary>
    private void OnDisable()
    {
        PlayerEvents.Died -= HandleDied;
    }

    #endregion

    #region Event Handlers

    /// <summary>
    /// Resets the system when the player dies.
    /// </summary>
    private void HandleDied() => isActive = false;

    #endregion

    #region Public API

    /// <summary>
    /// Starts the effect; ignored if already running.
    /// </summary>
    public void Activate()
    {
        if (isActive) return;
        isActive = true;
    }

    #endregion
}
```

---

## 7. Before you finish

- New cross-system communication → add an event to `PlayerEvents`, don't bypass the bus.
- Touched a `MonoBehaviour` that subscribes? Verify `OnEnable`/`OnDisable` stay paired.
- Touched a player system? Confirm it's owner-gated (in `ownerOnlyBehaviours`) and that a
  remote copy never drives `PlayerEvents` or simulates itself (see §3).
- New networked prefab? Add a `NetworkObject` and register it in `DefaultPrefabObjects`.
- Added a tween? Verify it's killed on teardown.
- The project must compile with **zero errors**; treat new warnings as something to fix
  or justify.
- Editor-only code stays under `Editor/`.