Init Homebase

CLAUDE.md

@@ -16,7 +16,7 @@ Multiplayer game on **Unity DOTS (Entities) + Netcode for Entities** — server-
 | `com.unity.burst` | 1.8.29 | (transitive) |
 | `com.unity.mathematics` | 1.3.3 | (transitive) |
 
-> ⚠️ The values above are the **Unity 6.4.7** set being reverted to — **verify against `packages-lock.json` after the editor downgrade re-resolves**, and reconcile `manifest.json` if the brief 6.6 upgrade left explicit version pins.
+> ✅ Reconciled 2026-06-02: `manifest.json` pins aligned to the resolved **Unity 6.4.7** lock (entities/entities.graphics 6.4.0, URP 17.4.0, test-framework 1.6.0, ugui 2.0.0, multiplayer.center 1.0.1) — a no-op re-resolve (lock unchanged, console clean). The values above now match `packages-lock.json`. See [[DR-008_M5_HomeBase_BaseLayer_Storage]].
 
 > **Version history & status (2026-05-30):** built on **6.4.7** (`6000.4.7f1`; Netcode 1.13.2 / Physics 1.4.6 / Entities 6.4.0). Briefly upgraded to **6.6.0a6**, where Netcode→6.6.0, Physics→6.5.0, Entities→6.5.0 all **renumbered** into the editor line — BUT the alpha's **Netcode/Transport runtime is broken** (all in-editor connections fail with "invalid wrapped network interface"; **confirmed engine bug** via a zero-gameplay repro — see `Docs/Vault` DR-002 and `Docs/UnityBugReport-Netcode-Transport-6.6.0a6.md`). **→ Reverting to Unity 6.4.7 for stable netcode runtime.** If returning to 6.6 later, expect the renumber and re-test the runtime. The M1 player slice should port to 6.4 / Netcode 1.13.2 with no or minimal changes — recompile and `read_console` after the downgrade.
 
@@ -71,6 +71,17 @@ Root namespace: **`ProjectM`**. Code lives under `Assets/_Project/Scripts/` in f
 - **Do NOT copy the CC sample's global `LocalTransform → DontSerializeVariant`.** It is project-wide and would break the non-character ghosts here (projectiles/dummies/pickups) that rely on stock `LocalTransform` replication. Our CC character replicates position via the normal owner-predicted `LocalTransform` path; only the `CharacterInterpolation` variant is registered.
 - **Top-down CC config (planar, no gravity):** `AuthoringKinematicCharacterProperties` with `SnapToGround=false`, `InterpolateRotation=false` (rotation owned by `PlayerAimSystem`), `SimulateDynamicBody=false` (players don't physically push each other); gravity is handled in the processor by feeding `float3.zero` to `Update_GroundPushing` and never adding a gravity term. Result: stays on the spawn plane (y≈1) with no planar-pin system.
 
+### Build gotchas (learned — M5 home base + shared storage, 2026-06-02)
+
+- **Ownerless interpolated ghost ≠ owner-predicted for buffer replication.** A server-spawned **ownerless** ghost (e.g. the shared storage chest) replicates a `[GhostField]` `IBufferElementData` to all clients with **no `OwnerSendType` and no `GhostOwner`** — server mutations just propagate. `[GhostComponent(OwnerSendType = SendToOwnerType.All)]` (per `StatModifier`) is **only** for the predicting *owner* to recompute its own state; adding it (or a `GhostOwner`) to an ownerless ghost is wrong.
+- **One-off shared-state actions belong on an `IRpcCommand`, not a predicted `InputEvent`.** RPCs are reliable, so deposit/withdraw landed even while the server tick-batched (the M2 one-shot `Fire` InputEvent drops under batching). RPC payloads are **plain blittable fields — no `[GhostField]`**; store an op as a **byte**, not an enum (cross-assembly enum-Burst hazard, same one that de-Bursted `ProjectileClassificationSystem`). For a **single** shared target, resolve it as a **server singleton** — never put an `Entity` (not stable cross-world) in the command; only reach for a ghost-id+spawn-tick (`SpawnedGhostEntityMap`) when there are many targets (and that lookup may force the handler off Burst).
+- **Apply server-only RPC effects in the server `SimulationSystemGroup`, NOT the predicted loop** — the predicted loop re-runs on rollback and would double-apply. (Mutating a `DynamicBuffer` is not a structural change, so it's safe to do while iterating a *different* entity query, e.g. the RPC requests.)
+- **Build-grid math must be deterministic + integer-stable.** Corner-origin + center-returning + **half-open** cell bounds + `math.floor` (not truncation — negatives). Lock `CellSize`/`PlotSize` as a coordinate space once: M6 placement builds on it; changing them later invalidates placed structures. (`BaseGridMath`, unit-tested in EditMode like `PlayerSpawnMath`.)
+- **Runtime-spawn shared ghosts; don't bake them into the subscene.** A one-shot server spawner (mirrors `UpgradePickup`/`TrainingDummy`) keeps the subscene ghost-free and dodges the prespawn section-ack/CRC handshake. Do **not** add such a ghost to a connection's `LinkedEntityGroup` if it must survive that player's disconnect (the shared base is world-owned).
+- **Build a correctly-configured ghost prefab by duplicating an existing one** (`UpgradePickup.prefab` → `Storage.prefab`, then swap the authoring MonoBehaviour via `manage_prefabs modify_contents`) rather than hand-adding `GhostAuthoringComponent` — its ownerless/interpolated settings (`HasOwner=0`, `DefaultGhostMode=Interpolated`) + `LinkedEntityGroupAuthoring` come along for free.
+- **`execute_code` runs as a method body** — **no `using` directives** (they parse as statements → "Identifier expected"); fully-qualify every type (`Unity.Entities.World`, `ProjectM.Simulation.BaseAnchor`, …). Also: world flags overlap a shared `Game` bit, so identify worlds by `world.Name == "ServerWorld"/"ClientWorld"` rather than `(Flags & GameServer)`.
+- **An unfocused editor throttles Edit mode to near-idle** → MCP pings time out and the bridge looks hung (it still *queues* commands — `telemetry_ping` succeeds). `Application.runInBackground` only helps in **Play** mode. If it wedges, focus or restart the editor; don't pile `refresh_unity` calls onto a blocked main thread. Prefer `refresh_unity scope=scripts` for code-only changes (`scope=all force` is heavy and contributed to a mid-session hang).
+
 ## Bootstrap & worlds
 
 - `ProjectM.Simulation.GameBootstrap : ClientServerBootstrap` → overrides `Initialize`, sets `AutoConnectPort = 7979` (in-editor auto-connect over IPC; set in M1 — was 0), calls `CreateDefaultClientServerWorlds()`. Entering Play Mode creates separate `ServerWorld` (`WorldFlags.GameServer`) and `ClientWorld` (`WorldFlags.GameClient`) — verified.