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).
- **No player arms / viewmodel** — feedback comes from camera, audio and UI only.
- 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.** 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`.

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.

---

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

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

### 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/`.