Floating things on water

The join between Vixen.Water's arithmetic and a physics world. Put a BuoyancyBody on an entity that already has a Collider and a RigidBody, add a BuoyancySystem, and it floats.

It is its own assembly. docs/plan/35 § D1: the water kernel is what a dedicated server runs, so nothing in it may link a physics engine — and a game with water and no rigid bodies must not link Jolt to draw a lake.

A crate in a river, a raft a player stands on, a buoy that bobs. Anything whose interaction with water is displacement rather than a movement mode — a swimming character is swimming's CharacterMoveMode.Swimming and does not come through here, though it is written by the other system in this same assembly and for the same § D1 reason.

Vixen.App.Hosting links Vixen.Rendering.Water — so a zone and a body reach a game the moment it has a compositor with a !WaterSurface node in it. It deliberately does not link this one. § D1's sentence is that a game with water and no rigid bodies must not link Jolt to draw a lake, and a reference from the host is exactly that. Vixen.Audio.Physics is the same shape and is opted into the same way.

What that costs is a failure mode worth stating plainly:

A [ModuleInitializer] cannot run in a process that never loads the assembly.

BuoyancyBody and BuoyancyState are declared to SceneComponentRegistry from an initializer this assembly emits. In a game that has not referenced the package, that initializer never runs, and a scene naming !BuoyancyBody fails to load with *"This build has no component called 'BuoyancyBody'"* — which is loud, and is the right failure, and does not say what to add. Add the package:

⚠ And referencing it is not on its own enough, which is a second failure with the identical message. The CLR runs a module initializer at the first touch of a type in that module — so a game that references the package but only constructs its systems after loading its level has not touched it yet when the scene is deserialized, and gets the same "this build has no component called 'BuoyancyBody'" about an assembly that is right there in its output directory. One statement before the load fixes it, and Samples/13-ThirdPersonShooter's Arena.Load is where to see it:

⚠ The editor is the exception and links it unconditionally, for a reason that has nothing to do with running physics: a component whose assembly is not loaded is missing from Add ▸ and takes a scene naming it down on load, so a boat could not be authored before it could be opted into. See EditorApplication.BuiltInSubsystems, which is the list that touches such an assembly early enough for a scene file to be read against it.

BuoyancyBody.Sphere is a crate or a barrel; BuoyancyBody.Raft is anything that should pitch and roll. A list of BuoyancyPontoon is the general case.

A barge is four large spheres and a canoe is six small ones along its keel. Matching them to the hull mesh is how a boat ends up floating a hand's width too high; matching them to the collider is how it ends up floating on its bounding box.

⚠ Four and not one, for anything that should lean. A force at a single point cannot produce a torque about that point, so a hull with one pontoon bobs and never rolls — which reads as a boat on rails and is invisible in any test that measures only a height.

The first two are the [UpdateAfter]/[UpdateBefore] attributes on BuoyancySystem, and a test asserts they are there. The third is why WaterClockSystem exists as a separate system at all: the zone fold has to be in PreRender, because a body is rasterised where TransformSystem has just put it, so the clock cannot be advanced there.

⚠ A host that forgets WaterClockSystem gets a still sea rather than a subtly wrong one. That is deliberate — a fallback advance inside the zone system would be a second writer, and one clock is the whole point.

It takes a plane, which is exactly the approximation a wave surface is not. Using it would also put a second definition of the water surface inside the physics engine, where § D2's seam test cannot reach it.

The closed-form wave sum is a function of position and time, so a server can answer *where was the surface six ticks ago* without having simulated the intervening frames. A ripple field is a simulation whose state is its history and cannot answer that at all.

So a buoyant body needs no replication of its own: it rides Vixen.Net.Physics' existing rigid-body path unchanged, because the force is a pure function of things both peers already have — the pontoons (authored), the pose and velocity (replicated), the field and the spectrum (content), and the water time (one clock, derived from the tick).

TransformSystem runs in LateUpdate, so in the fixed step that component holds last frame's pose and a boat floated from it is floated where it was. BuoyancySystem therefore declares no transform access at all.

The verb is Vixen.Rendering.Water's and the pontoon spheres, waterlines and force arrows are BuoyancyDebugDraw's here — § D1 again, since a renderer must not reference the assembly that links Jolt. BuoyancyDebugSystem carries one to the other, and it takes the flag as a delegate rather than reading it, which is what keeps this assembly linkable by a dedicated server that has no renderer:

That is the whole of what a game wires, and Samples/13-ThirdPersonShooter's Arena.cs is where to see it done — under an if (graphics.Debug is { } debug), because the accumulator, the console and the node that drains it are all built by --vixen-overlays and a run without it has none of them.

Three things about the delegate are worth knowing before writing one:

⚠ SystemPhase.PreRender, and both neighbours decide it. TransformSystem writes the WorldTransform the pontoon spheres are placed from in LateUpdate, so anything earlier draws them where the body was; the accumulator is drained during Render, so anything later draws into a frame that has already been recorded. Neither failure says anything — the picture is a lag, or an empty screen. The attribute is on the class and a test asserts it is, for the same reason BuoyancySystem's two ordering attributes are asserted.

Left unwired the toggle sets a bool nothing consumes — which, over a scene with nothing floating in it, looks exactly like a verb that works. BuoyancyDebugSystem.Frames is the counter that separates the two: it counts the steps that actually drew, so verb on, Frames at zero is the join undone and verb on, Frames rising, nothing on screen is a scene with nothing floating in it. Samples/13 prints it at the end of its buoyancy line (log event 14071) precisely so a capture run can tell those two apart without a person at the keyboard.

Reading what happened, which is the difference between "buoyancy is broken" and "two of four pontoons are dry".

Wiring the overlay from a host that may or may not have a renderer. The delegate is the whole seam, so one function covers both: a game passes () => WaterDebug.ShowBuoyancy, and a dedicated server passes null and drives Draw.Enabled itself — or never turns it on at all.

Step is public for the same reason IsJoined is worth writing: a test drives one step and asserts the counter moved, without standing up a runner. Update is that call with the dependency completed first, because the pontoons are placed from a WorldTransform and read a BuoyancyState that TransformSystem and BuoyancySystem have both finished writing by then.

An unset coefficient is one, not zero. A chunk's column is zeroed memory, so a component added from the inspector without the field filled in holds zero — and zero lift is a crate that sinks, which reads as the whole system being unwired rather than as a field nobody typed. BuoyancyBody.Settings is the seam where unset becomes the default.

• Where the water surface is — the kernel this floats things on.
• Swimming — the other half of this assembly: immersion as a movement mode, not a lift.
• Character movement — the three modes swimming is the fourth of.
• docs/plan/35-water.md § D10 — pontoons over Jolt at the fixed step's water time, and why.