Vehicles

Repositions a vehicle from OUTSIDE its own simulation — the receiving half of a swept contact rewind (GAP-19), and of anything else that legitimately says "you were never there".

• bool ApplyExternalDisplacement(long entityId, float deltaX, float deltaZ)

  Offsets a registered vehicle by an exact world-space delta, updating its simulation state and its world entity together. Velocity, yaw and every other part of the sim state are untouched — this answers "where", not "how fast": a contact rewind pairs it with an impulse, which is what carries the change of motion.

Where the ground is under a vehicle — the seam that gives the XZ-planar sim a vertical axis, and the reason it is declared in CONTRACTS rather than server-side: both tiers must ground a car the same way or the client predicts a height the server disagrees with, and every reconciliation is a visible vertical jump. The server implements it over the world's 3D geometry (IWorldQueries3D.GroundProbe); the client implements it over its mirror of the same baked mesh, exactly as IWorldSurfaceMap / IClientWorldSurfaceMap already pair up. The failure this closes. Height used to be a value copied around a loop and never computed: the sim handed the mover the Y it already had and read the same number straight back. A car therefore kept its SPAWN height for its whole life — floating over every dip and buried under every rise. On a circuit that climbs 57 world units the error reached thirteen car lengths, and no game could fix it from outside: only one system may own an entity's transform, and touching the server's Y is authority. Absent (no sampler registered) nothing changes at all — the height passes through as before, which is exactly right for a flat arena, a top-down game, or any world with no baked geometry. Genre-agnostic: karts, tanks, boats and hovercraft all need "sit on the ground and tilt with it", and a game whose arena is a plane never notices this exists.

• bool TrySampleGround(string zone, float x, float fromY, float z, float maxDrop, out float floorY, out float normalX, out float normalY, out float normalZ)

  The ground under (x, z) in a zone, searched from fromY downward.

Where the predictor's neighbours come from — implemented by the GAME, because only the game knows which interpolated entities are vehicles and what bodies they carry (it is already rendering them). The framework ships no default: absent, prediction computes exactly the numbers it always did, which is the removable-piece rule applied to a seam.

• int GetNeighbours(long selfEntityId, string zone, float nearX, float nearZ, float radius, Span<VehicleNeighbour> into)

  Writes the vehicles near (nearX, nearZ) into into, excluding selfEntityId, ordered by entity id ascending.

What a vehicle would HIT on its way from one place to the next — the lateral sibling of IVehicleGroundSampler, and declared in CONTRACTS for exactly the same reason: both tiers must stop a car at the same rock, or the client predicts straight through something the server refused and every reconciliation is a visible shove. The failure this closes. Vehicles only ever asked geometry a DOWNWARD question. A substep probed for the floor under each wheel, adopted that height, and then moved horizontally with nothing consulted at all — so a car drove through stone, trees and fences, and the world's solid geometry existed only as something to stand on. Worse, it degraded as terrain improved: a boulder in the bake is a thing the car CLIMBS, because a downward probe on top of it reports a perfectly good floor. The game's own note that adding vegetation to its bake "would turn trees into ramps the car climbs rather than obstacles it hits" is this gap stated from the outside. Why a sweep and not a point test. A point test misses at speed for the same reason discrete contact did: at 56 units/s a 60 Hz substep travels nearly a metre, so a fence post fits entirely between two samples. Asking "what does the body touch along this segment" cannot tunnel, and it is a query the shared MeshCollision.SweepCapsule already answers on both tiers over the same baked triangles. Why a CAPSULE, and why the signature grew (GAP-30). This seam used to carry a radius and nothing else, so a 4.2 × 1.8 m car was swept as a ball on both tiers. That was never a judgement about cars: a sphere was the only swept volume the server provider and the Unity client mirror could SHARE, and matching each other mattered more than matching the silhouette. Both tiers now share MeshCollision.SweepCapsule over the same bake, so the compromise is gone and the axis travels through the seam. The parameters were ADDED to the existing method rather than hidden behind a defaulted overload deliberately: a game with its own sampler gets a compile error and one line to write, instead of a car that silently keeps being swept as a ball however its class is configured. A zero axis is exactly a sphere, so a sampler that ignores it is honest, just less faithful. Absent (no sampler registered) nothing changes at all — and so is a class that leaves ObstacleRadius at 0, which never asks. A flat arena, a top-down game, or any world whose only solid is its floor behaves exactly as it did before this existed.

• bool TrySweepBody(string zone, float fromX, float fromY, float fromZ, float toX, float toY, float toZ, float radius, float axisHalfX, float axisHalfY, float axisHalfZ, uint mask, out float hitFraction, out float normalX, out float normalY, out float normalZ)

  Sweeps the vehicle's body volume along a segment and reports the FIRST thing it touches.

Server-authoritative vehicle motion for heading+speed vehicles (cars, karts, boats, hovercraft, tanks — the piece never knows which): register a live world entity under a configured class and the per-tick substepped VehicleIntegrator drives it through the swept movement pipeline — walls gate every substep, observers get the ordinary batched EntityMove broadcast, and the owning client (for a player entity) gets a full-state VehicleState ack for prediction. Registering a PLAYER entity flips the Movement piece's motion authority (its raw MoveInput path drops; this sim is its motion); unregister — or despawn — hands it back. SetInput is THE one validated path: the wire handler and a game's AI drivers both go through the same ladder.

• bool ApplyExternalImpulse(long entityId, float deltaVelocityX, float deltaVelocityZ, float deltaSpinRate)

  Applies an external impulse to a registered vehicle: a change in world velocity, and a spin.

• int Count { get; }

  Number of registered vehicles (diagnostics).

• void NotifyExternalContact(long entityIdA, long entityIdB, float magnitude)

  The vehicle-vs-vehicle contact intake: reports that two entities touched with the given magnitude. When BOTH are registered vehicles, raises VehicleContact (ids ordered lowest first); anything else — unknown ids, a non-finite or negative magnitude — is dropped harmlessly. Fed by the Hosting Contact bridge or the game's own detection.

• bool Register(long entityId, ushort classId)

  Registers a live world entity as a vehicle of a configured class (Classes): seeds the sim from the entity's current position/yaw and, for a PLAYER entity, takes motion authority (IMotionAuthority.SetServerDriven). Registering an already-registered entity re-seeds it under the (possibly new) class. The registration dies with the entity.

• bool SetDriver(long entityId, ISession driver)

  Seats a session in a vehicle's DRIVER seat — the session whose VehicleInput steers this vehicle, and the session its full-state ack is sent to. Pass null to empty the seat.

• bool SetInput(long entityId, uint tick, float steer, float drive, byte flags)

  THE one validated intent path — the wire handler and a game's AI both call it. The ladder: registered id; finite axes (NaN/Inf dropped); axes clamped to [-1, 1]; monotonic tick (stale/duplicate dropped); tick within the ahead window (MaxInputAheadTicks). Accepted intent is HELD (latest wins) and integrated every substep until replaced — or until it goes stale (InputStaleTicks) and the vehicle coasts.

• bool SetLocomotion(long entityId, byte locoState)

  Sets the locomotion byte broadcast with the vehicle's EntityMove stream — pure presentation vocabulary (the game maps sim state to e.g. idle/rolling/boosting ids and the client maps them onto its own visuals; the framework never reads it).

• bool SetSurface(long entityId, byte surfaceId)

  Sets the opaque surface id stamped on the vehicle's sim state and echoed on the owner ack (game vocabulary — pair it with an IVehicleParamsProvider for surface-dependent handling).

• bool TryGetClass(long entityId, out ushort classId)

  Reads the class id an entity registered under.

• bool TryGetDrivenVehicle(ISession session, out long entityId)

  Reads the vehicle a session currently drives through a seat — NOT its own avatar, which needs no seat. The inverse of SetDriver.

• bool TryGetState(long entityId, out VehicleSimState state)

  Reads a snapshot of a vehicle's current integrator state (position, velocity, yaw, smoothed axes, drift, surface).

• bool Unregister(long entityId)

  Unregisters a vehicle and, for a player entity, returns motion authority (the input-driven path resumes). Automatic when the entity leaves the world.

• event Action<long, long, float> VehicleContact

  Raised when two REGISTERED vehicles make contact: (lower entity id, higher entity id, magnitude — the overlap depth or impact measure the reporter supplied). Fed by NotifyExternalContact (the Hosting Contact bridge, or the game's own detection); the piece performs no vehicle-vs-vehicle detection itself.

• event Action<long, ushort> VehicleRegistered

  Raised after an entity registers (or re-registers under a new class): (entityId, classId). The Hosting Contact bridge profiles the vehicle from this.

• event Action<long> VehicleUnregistered

  Raised after an entity unregisters (explicitly, or automatically on despawn).

• event Action<long, float> WallContact

  Raised when a vehicle's intended substep motion was blocked (fully or partly) by the world bounds: (entityId, blocked approach speed in units/s). Cooldown-gated per vehicle (WallContactCooldownSeconds) and thresholded (WallContactMinSpeed) — SFX/damage hooks, the game's meaning.

Vehicle simulation tuning (defaults here, never inline). Per-CLASS tuning is not options — it is the Classes table of VehicleClassSpec entries.

• Dictionary<string, VehicleAutoRegisterRule> AutoRegister { get; set; }

  Composition-bridge table (used by the Hosting layer, never by this piece): which entities entering which zone BECOME vehicles, keyed by zone id — or by an instance PREFIX, resolved with the same rule every per-zone table uses. Register is otherwise reachable only from game C#, which makes the whole piece unreachable from a game that ships configuration rather than server code; this table is that switch, expressed as data. Empty (the default) = no bridge is composed and nothing auto-registers — a game driving registration from its own code sees byte-for-byte the previous behaviour. Genre-agnostic: "the entities in this zone drive" is a kart track, a tank battle, a boat race and a delivery sim alike; the piece still never learns which.

• bool BridgeAgentDrivers { get; set; }

  Composition-bridge knob (used by the Hosting layer, never by this piece): when true, an entity that is BOTH a registered vehicle and a brain-driven agent is driven rather than slid — the Hosting bridge converts wherever its brain wants to go into steer/drive intent and feeds it through the IVehicleDriver seam, i.e. the same validated path a player's packet takes. Without it the two systems fight: the brain writes positions while the sim integrates permanently-zero axes underneath, and ResyncDistance makes them alternate. False (the default) = no bridge is composed and agents move exactly as they always have. This is what turns any existing config-driven brain (wander / patrol / chase / state machine) into a driver, so bots need no new steering vocabulary and no server C#.

• bool BridgeContact { get; set; }

  Composition-bridge knob (used by the Hosting layer, never by this piece): when true, the Hosting Contact bridge profiles every registered vehicle on the Contact piece (its class's OBB half-extents, weight, layer — Hard resolution) and relays vehicle-vs-vehicle ContactBegan pairs into NotifyExternalContact. False (the default) = no bridge is composed and vehicles do not collide with each other.

• Dictionary<ushort, VehicleClassSpec> Classes { get; set; }

  The vehicle class table, keyed by the class id passed to Register — config/content-bindable (Crossplay:Vehicles:Classes:{id}). Empty (the default) = nothing can register and the piece is inert.

• VehicleDriverTuning DriverTuning { get; set; }

  Composition-bridge tuning (used by the Hosting layer, never by this piece): how a "go to this point" intent becomes steer/drive axes. Ignored unless BridgeAgentDrivers is on.

• int FrameBufferInitialBytes { get; set; }

  Initial capacity (bytes) of the reused outbound frame buffer (the owner VehicleState ack). Grows to the high-water mark and never shrinks. Default 128.

• bool GroundVehicles { get; set; }

  Whether vehicles are GROUNDED on the world's 3D geometry each substep — height and slope taken from IWorldQueries3D.GroundProbe through the shared IVehicleGroundSampler seam, rather than a car keeping its spawn height for its whole life. Default true, and inert without geometry: a zone with nothing baked answers "no ground", the probe returns false and the height passes through exactly as it always did, so a flat arena or a top-down game never notices. Set false for vehicles that are deliberately not on the ground — a flying racer, a hover craft holding a fixed altitude, a game that drives Y from its own system. Per-class probe distances and ride height live in the class table (both tiers must agree on them), not here.

• int InputBurst { get; set; }

  Burst allowance (token-bucket capacity) for the VehicleInput rate seed — absorbs a client's post-hiccup catch-up burst. Default 90.

• int InputStaleTicks { get; set; }

  Server ticks without a NEWLY accepted input after which the held axes are treated as zero — the vehicle coasts (drag slows it) instead of driving forever on the last packet of a disconnected or stalled client. Default 10 (0.5 s at a 20 Hz tick).

• double InputsPerSecond { get; set; }

  Sustained per-session rate cap (messages/second) seeded into Core's per-message rate limits for VehicleInput — comfortably above the ~20-30 Hz send cadence, far below a flood. A composer's configureRateLimit entry or Crossplay:RateLimit:PerMessage config wins over the seed. Default 60.

• uint MaxInputAheadTicks { get; set; }

  How far past the newest accepted input tick a new input's tick may jump (the ahead window). Rejects absurd tick leaps (a hostile uint.MaxValue would otherwise lock every later legitimate input out as "stale"). Default 300 (~15 s of 20 Hz input ticks).

• int MaxSubstepsPerTick { get; set; }

  Most integrator substeps run in one tick (the spiral-of-death guard): a long stall's accumulated time past this is dropped rather than simulated in a burst. Default 8.

• int MaxVehicles { get; set; }

  Most entities registered as vehicles at once; Register refuses beyond it. Default 1024.

• float ResyncDistance { get; set; }

  If the entity's world position drifts farther than this (world units) from the sim's position — a Teleport, a zone move, some other system repositioning it — the sim re-seeds from the entity instead of fighting it. Default 2.

• float SpeedEnvelopeSlack { get; set; }

  The absolute speed-envelope slack: each substep the vehicle's horizontal speed is hard- clamped to MaxSpeed × MaxSpeedMult × this whatever the integrator (or a buggy params provider) produced, and the excess increments the EnvelopeClamps metric. Above 1 so legitimate drift (forward cap + lateral carry) never trips it. Default 1.25.

• float StateSendRateHz { get; set; }

  Owner VehicleState ack rate, Hz, while inputs flow (0 or less = every tick). The ack is one small unreliable frame to ONE recipient; 20 matches the default input cadence so the predictor reconciles once per sent input. Default 20.

• float SubstepHz { get; set; }

  Integrator substep rate, Hz. Each server tick runs SubstepHz / TickHz substeps and every substep routes through the swept movement pipeline, so the per-substep travel — not the per-tick travel — is what the wall gate sees: 60 Hz keeps a top-speed vehicle from tunneling a thin wall that a whole 20 Hz step would bridge. Default 60.

• Dictionary<byte, SurfaceHandlingSpec> SurfaceHandling { get; set; }

  Composition-bridge table (used by the Hosting layer, never by this piece): the handling overlay each opaque SURFACE id imposes — the config-only implementation of IVehicleParamsProvider over the world's baked surface plane (IWorldSurfaceMap). Keys are the ids stamped into the bake; what a value MEANS (dirt, sand, ice, water) stays entirely the game's vocabulary. Surface 0 — the conventional default/unknown id, and the answer for every zone without a plane — and any id with no row here run NEUTRAL (every multiplier 1), so an unbaked track drives like plain road rather than like whatever row happened to sort first. Empty (the default) = no bridge is composed at all.

• float WallContactCooldownSeconds { get; set; }

  Minimum seconds between WallContact events for one vehicle, so grinding along a wall is one event, not one per substep. Default 0.25.

• float WallContactMinSpeed { get; set; }

  Blocked-approach speed (units/s) at or above which a wall hit raises WallContact — grazes below it just slide. Default 1.

• float WallContactSpeedLoss { get; set; }

  Fraction of the vehicle's speed lost when a wall-contact event fires (the crash cost; the blocked velocity component is always removed regardless). Default 0.25.