CC Package and Physics

CLAUDE.md

@@ -11,6 +11,7 @@ Multiplayer game on **Unity DOTS (Entities) + Netcode for Entities** — server-
 | `com.unity.collections` | 6.4.0 | (transitive) |
 | `com.unity.netcode` | **1.13.2** | Netcode **for Entities** (ECS). NOT `com.unity.netcode.gameobjects`. Independent 1.x line on Unity 6.4. |
 | `com.unity.physics` | **1.4.6** | Unity Physics (DOTS). Independent 1.x line on Unity 6.4. |
+| `com.unity.charactercontroller` | **1.4.2** | Unity Character Controller (DOTS, kinematic collide-and-slide). Player movement foundation (M5b). Declares `entities`/`physics` 1.3.15 but resolves on our 6.4.0/1.4.6 via SemVer floor (no downgrade). |
 | `com.unity.transport` | 2.7.2 | (transitive) |
 | `com.unity.burst` | 1.8.29 | (transitive) |
 | `com.unity.mathematics` | 1.3.3 | (transitive) |
@@ -50,6 +51,26 @@ Root namespace: **`ProjectM`**. Code lives under `Assets/_Project/Scripts/` in f
 - **In-editor input injection needs a focused Game view — unless you change two settings.** By default the Input System ignores injected/real device input while the Game view is unfocused, so headless (MCP `execute_code`) keypress simulation won't drive `IInputComponentData`. Fix (both now set in this project): `InputSettings.editorInputBehaviorInPlayMode = AllDeviceInputAlwaysGoesToGameView` + `Application.runInBackground = true`. For deterministic, device-independent validation prefer the editor-only **`DebugInputInjectionSystem`** (`ProjectM.Client`, `#if UNITY_EDITOR`): poke its statics from `execute_code` — `DebugInputInjectionSystem.Fire()` / `.SetMove(x,z)` / `.SetAim(x,z)` / `.Stop()` — to drive the local player's `PlayerInput` through the authentic command→prediction pipeline. (Validated: `SetMove` drives + replicates movement. One-shot `Fire` propagation needs a healthy editor — tick-batching under a degraded/corrupt-Burst editor drops one-shot `InputEvent`s while continuous values survive.)
 - **Prototype presentation glue lives in `ProjectM.Client` as MonoBehaviours.** `PrototypeCameraRig` (on the Main Camera) is a tunable player-following ARPG cam (default mid 3/4 ~45° perspective) that reads the local player ghost's `LocalTransform` each LateUpdate. Bright prototype URP-Lit materials are in `Assets/_Project/Materials/` (player cyan, dummy red, projectile yellow, ground grey). `ProjectM.Client` now references `Unity.Transforms` directly (the rig reads `LocalTransform`).
 
+### Build gotchas (learned — M5 physics-in-prediction, 2026-06-01)
+
+- **Editing Assets `.cs` with the raw `Write` tool does NOT reliably trigger a Unity recompile** on an unfocused editor — `refresh_unity` did a domain reload *without* recompiling, so tests + `execute_code` ran a **stale assembly** (symptom: behaviour that exists in *neither* the old nor new source). **Always edit Assets `.cs` via MCP `apply_text_edits` / `create_script`** (Unity's own scripting pipeline) — never `Write`. (`Write`/`Edit` are fine for non-asset files: vault, asmdef JSON, etc.) See [[2026-06-01_M5_Physics_In_Prediction]].
+- **Predicted physics is implicit — there is no `PredictedPhysics` toggle.** With the netcode-physics package present (`Unity.NetCode.Physics`, `…Physics.Hybrid`) and predicted ghosts carrying physics components, Netcode relocates `PhysicsSystemGroup` into the **`PredictedFixedStepSimulationSystemGroup`** (a child of `PredictedSimulationSystemGroup`, marked **OrderFirst**). `NetCodePhysicsConfig` only tunes lag-comp / run-mode / history. Put one in the gameplay subscene with `PhysicGroupRunMode = LagCompensationEnabledOrAnyPhysicsEntities` so the group runs whenever physics entities exist.
+- **Unity Physics 1.x bakes built-in `UnityEngine` colliders + `Rigidbody`** — the old `PhysicsShapeAuthoring`/`PhysicsBodyAuthoring` (Physics 0.x) are **gone** (`unity_reflect` finds neither). Author a dynamic body with a `CapsuleCollider`/`BoxCollider` + `Rigidbody` (`useGravity=false` → planar/`PhysicsGravityFactor`=0; `isKinematic=false`; `interpolation=Interpolate` → `PhysicsGraphicalSmoothing`). Static colliders = collider, no Rigidbody, baked into the subscene (present identically in server + client worlds, deterministic, no replication).
+- **`PhysicsVelocity` auto-replicates** — Netcode ships `PhysicsVelocityDefaultVariant` + a generated serializer, so a predicted-physics ghost needs **no hand-written `[GhostField]`** for velocity (`LocalTransform` is already replicated). Drive the character by writing `PhysicsVelocity.Linear`, not by teleporting `LocalTransform`.
+- **`Rigidbody.FreezeRotation` is NOT honored by the DOTS baker** (baked `PhysicsMass.InverseInertia` stays non-zero). Hold a top-down character's facing by zeroing angular velocity each tick + writing rotation directly (`PlayerAimSystem`); set `PhysicsMass.InverseInertia = float3.zero` in a baker/system if a hard lock is needed.
+- **Gravity-off bodies accumulate vertical contact impulses permanently** (a capsule rides up a box edge and floats away — looks like tunnelling, isn't). Pin players to the movement plane *after* the physics step: a system in `PredictedSimulationSystemGroup` `[UpdateAfter(PredictedFixedStepSimulationSystemGroup)]` clamping Y to `PlayerSpawner.SpawnPoint.y` + zeroing `Linear.y` (`PlayerPlanarConstraintSystem`).
+- **The predicted physics group is OrderFirst**, so a system in `PredictedSimulationSystemGroup` with `[UpdateBefore(PredictedFixedStepSimulationSystemGroup)]` is **ignored** (OrderFirst/OrderLast wins) → 1-tick velocity offset (consistent across server/client/rollback — prediction stays in sync). For same-tick application, put the system *inside* `PredictedFixedStepSimulationSystemGroup` `[UpdateBefore(Unity.Physics.Systems.PhysicsSystemGroup)]` (verified to sort before the step) — but expect cosmetic "invalid UpdateBefore" warnings from the relocation.
+
+### Build gotchas (learned — M5b Unity Character Controller, 2026-06-01)
+
+- **The player is now a Unity Character Controller kinematic character, NOT a dynamic Rigidbody.** `PlayerMoveSystem` + `PlayerPlanarConstraintSystem` (M5) are **deleted**. Movement: `PlayerControlSystem` maps `PlayerInput.Move` × `EffectiveCharacterStats.MoveSpeed` → `CharacterControl` (via the unit-tested `CharacterControlMath.DesiredMovement`); `CharacterProcessor` (collide-and-slide) consumes it in `CharacterPhysicsUpdateSystem` (`[UpdateInGroup(KinematicCharacterPhysicsUpdateGroup)]`, relocated into the predicted loop). The DR-006 predicted-physics infra (`NetCodePhysicsConfig`, baked static walls) is **kept** — the CC character sweeps against that same PhysicsWorld.
+- **A package declaring an older `com.unity.entities`/`com.unity.physics` dependency can still resolve on our renumbered stack** — Unity treats the dep as a SemVer **floor**, so Entities 6.4.0 satisfies a `1.3.15` requirement and is NOT downgraded. Don't trust a version-string mismatch as "incompatible": **probe** (add the package, confirm `packages-lock.json` kept Entities 6.4.0 / Physics 1.4.6 / Netcode 1.13.2 + a clean compile; rollback if not). CC 1.4.2 verified this way.
+- **CC 1.4.2 API shape = `IKinematicCharacterProcessor<T>` + `KinematicCharacterDataAccess` + static `KinematicCharacterUtilities.Update_*`.** The legacy `KinematicCharacterAspect` (IAspect, instance `Update_*`) also exists but is NOT what the 1.4.x samples use — verify the installed shape with `unity_reflect`, don't assume. (A sub-agent's package-cache read disagreed with reflect; reflect + first-try clean compile won.)
+- **`KinematicCharacterUtilities.BakeCharacter` aborts** (logs an error, adds nothing) **if the GameObject has a `Rigidbody`** and requires uniform (1,1,1) scale. The player prefab keeps its `CapsuleCollider` (baked into `PhysicsCollider`) but the M5 `Rigidbody` was removed. Two bakers on one prefab GameObject (`PlayerAuthoring` + `PlayerCharacterAuthoring`) is fine — both resolve the same entity.
+- **`CharacterInterpolation` must be PredictedClient-only.** `BakeCharacter` adds it to all prefab versions; a `DefaultVariantSystemBase` registers `CharacterInterpolation → [GhostComponent(PrefabType = GhostPrefabType.PredictedClient)]` so it's stripped from server + interpolated-client prefabs (else double-interp on remotes). Verified: server ghost has no `CharacterInterpolation`, client ghost does.
+- **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.
+
 ## 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.