WaterImmersionSystem

Remarks

[35 § D11](../../docs/plan/35-water.md#d11-swimming-is-a-fourth-move-mode-and-immersion-is-the-only-new-number)'s only new number, written. CharacterMoveMode.Swimming exists, CharacterMotion implements wading, the swim restoring force, the drag, the speed scale and the two-threshold hysteresis, and CharacterMovement.Default ships tuned numbers for all of it — and CharacterState.Immersion was written by nothing in the tree until this existed. Its own doc comment says "written by whatever knows where the water is"; this is that writer.

It is here for BuoyancySystem's reason and it is the same join. Vixen.Physics may not reference the water stack and the water kernel may not link Jolt — § D1 makes the physics join a separate assembly, and this is that assembly. A swimming character and a floating crate are the same seam with a different force: one turns immersion into a mode, the other turns it into a lift.

⚠ It finds the water through IWaterSurface and never through WaterZoneSystem. The zone fold lives in Vixen.Rendering.Water, and a reference to it from here would drag a graphics device into the path a dedicated server runs — the one line § D1 exists to forbid. WaterZoneSystem implements the kernel interface, so a game passes the fold it already has and a headless build passes its own.

In FixedUpdate, before the character steps. CharacterMovementSystem runs after PhysicsStepSystem and reads this number to decide the mode; written any later it is one step stale, which at a shoreline is a character that swims a step after it should have and wades a step after it should have — the drift § D2's whole seam exists to prevent, arriving through a phase order.

⚠ The clock is the surface's and not the frame's. There is one water time and WaterClockSystem is its only writer; reading GameTime here would be a second definition of "when", and a swimmer bobbing on a different swell from the one drawn under them is exactly the disagreement the one-clock rule is against.

Sampled at the capsule, not at the entity. A character's origin is at its feet and CharacterMovement.ShapeOffset lifts the capsule off it, so the submerged fraction is measured from the entity's Y over the standing capsule's full height — Immersion takes exactly that pair and is the one definition of the answer.

Fields and properties (3)

• public IWaterSurface Surface

  Where the water is, and the clock it is at.

• public SystemAccess Access

  What this system reads and writes.

• public int Swimming

  How many characters were in water deep enough to swim in, last step.

Methods (3)

• public WaterImmersionSystem(IWaterSurface surface)

  Tells a character how much of it is under water, which is the one number swimming is made of.

• public override JobHandle Update(in SystemContext context, JobHandle dependency)

  Runs the system.

• public void Step(World world)

  Measures one step's worth of immersion.

Used by (2)

• ArenaThirdPersonShooter
• WaterImmersionSystemTestsVixen.Water.Physics.Tests