Rigid Bodies

OPTIONAL engine seam: a server-authoritative physics engine that RigidBodies drives. A game or sample implements this over Bepu, Jolt, PhysX, a deterministic solver, or a toy integrator; the piece steps it at RigidBodyOptions.PhysicsStepHz and then PULLS each tracked body's pose back out to broadcast it. RigidBodies references NO engine — this interface names only engine-agnostic primitives (Vec3, Quat, entity ids), so a Bepu adapter depends on RigidBodies, never the reverse (Prime Directive). Pull, not push (by design). The backend is a pure read surface: Step advances the simulation and TryReadBody reads a pose — the backend never calls back into IRigidBodyService, so a physics adapter has ZERO knowledge of Crossplay's service and stays a drop-in the game can test in isolation. The drive loop (PhysicsBackendDriver) owns the fixed timestep and the body set (RigidBodies already tracks exactly the registered bodies), so the two never drift. If no backend is registered the drive loop does not exist and the game reports transforms manually via IRigidBodyService.Update — today's model, unchanged.

• bool OwnsBody(long entityId)

  Reads a body's post-step transform + velocities. Returns false when the backend does not own or simulate entityId (the driver then skips it — a body that lives outside this engine is simply not pulled). Returning false for a sleeping/settled body is a valid cheap optimization: RigidBodies' own sleep gate already suppresses re-broadcast, so a body the backend stops reporting just stops moving on the wire. Must not allocate. LB-GAP-15 — whether this engine holds a body of ANY kind for the entity: dynamic, kinematic or static. The probe a graph/engine consistency sweep asks, and the reason it is not TryReadBody: that one reads a DYNAMIC body's pose and answers false for the kinematic anchors every structure's foundation course is made of.

• void Step(float deltaSeconds)

  Advances the simulation by one fixed step. Called at RigidBodyOptions.PhysicsStepHz (with catch-up bounded by RigidBodyOptions.MaxPhysicsStepsPerTick). Poll-thread only.

• bool TryReadBody(long entityId, out Vec3 position, out Quat orientation, out Vec3 linearVelocity, out Vec3 angularVelocity)

Supplies the bodies near the one being stepped, so a predicted or simulated body can see the others.

• int GetNeighbours(long selfEntityId, in Vec3 near, float radius, Span<NeighbourBody> into)

  Writes the bodies near near into into, excluding selfEntityId, ordered by entity id ascending.

The bodies hosted on the portable step, as the composition layer sees them — the seam GAP-46 needs so a Hosting bridge can give portable bodies pair contact with ZERO piece-to-piece references, exactly as IVehicleService's registration events and ApplyExternalImpulse do for vehicles.

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

  Moves a hosted body by an exact world-space offset — the receiving end of a contact SEPARATION (and of a swept rewind). Reaches the simulation state itself, which is the only write that sticks; see the interface remarks for why writing the world entity instead would flicker.

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

  Applies an externally computed velocity change to a hosted body — the receiving end of a contact impulse. The change lands on the body's persistent state, so the next step integrates it exactly as it integrates its own forces.

• event Action<long> BodyHosted

  Raised when an entity becomes a hosted portable body — after its simulation exists and its first transform has been reported, so a subscriber that profiles it acts on a real pose.

• event Action<long> BodyReleased

  Raised when a hosted body stops being simulated — its entity despawned, or its zone's rule no longer claims it. A subscriber that profiled it on BodyHosted clears that profile here.

• bool TryDescribeBody(long entityId, out PortableBodyDescription description)

  The footprint of a hosted body, derived from its own shape and mass.

The game's seam onto rigid-body transform sync. A body IS a server entity: the game spawns it through IServerEntities.Spawn (opaque appearance = whatever the body is), then reports its physics transform here every server tick. Crossplay owns none of the physics — it only ships the result: quantizing, sleep-gating (a settled body sends nothing), interest-culling (via World's ObserversOf), batching, and broadcasting to nearby players. Single-threaded (poll-thread) by contract, like every other piece.

• event Action<long> BodyExpired

  Raised when a body has lain still for its expiry period — "this is finished; retire it". Deliberately does NOT remove anything. The listener despawns the entity, World announces the removal, and tracking drops through the one route that already existed. A second removal path here is how the backend body, the world entity and the broadcast record start disagreeing about what exists. Fires once per settling. If the body moves again it is rearmed, so something knocked back into motion is not retired mid-roll.

• event Action<long> BodyReleased

  Raised when a body stops being tracked, for ANY reason — expiry, an explicit Remove, or its world entity despawning. This is the signal a physics backend needs and did not have. Before it, despawning a body's entity dropped the broadcast record and left the ENGINE's body behind forever: invisible, un-networked, still in the broadphase, still colliding with things. A leak with no symptom until a demolition-scale world made it one.

• bool Register(long entityId)

  Starts tracking a body for transform sync in the default ServerInterpolated mode (Pattern A). The id must be a live SERVER entity (never a player). Returns false for an unknown id or a player entity. Optional — Update auto-registers a valid server entity on first call — but explicit registration is clearer when a body exists before it first moves.

• bool Register(long entityId, PhysicsNetMode mode, long ownerAccountId = 0)

  Starts tracking a body with an explicit networking mode (per-body pattern selection). For ClientPredicted (Pattern B), ownerAccountId is the account of the ONE client that controls and predicts the body: that client receives a full-precision RigidBodyReconcile (and is excluded from the interpolation batch), while every other observer interpolates the body normally. For ServerInterpolated the owner is ignored. Re-registering an existing body updates its mode/owner in place. Returns false for an unknown id or a player entity, or when ClientPredicted is requested with no (0) owner.

• bool Remove(long entityId)

  Stops tracking a body (its transform stops broadcasting). Returns false for an untracked id. Despawning the underlying server entity removes it automatically too — no leak either way.

• bool SetExpiry(long entityId, float secondsAtRest)

  Gives one body its own resting lifetime, overriding RigidBodyOptions.ExpireAfterRestingSeconds. Positive = that many seconds; NEGATIVE = never (how a game protects something important in a world that expires debris by default); 0 = inherit the option.

• bool TryAcceptInput(long entityId, ISession sender, uint sequence)

  Validates one inbound input frame and, if it is good, records its sequence as the latest folded into this body — which is what the next reconcile echoes back as LastProcessedInput. Called by the piece's own handler before it reaches IRigidBodyInputSink; a game normally never calls it. It is on the interface because the four checks it performs are the ones only the piece can make, and a game that builds its own input transport should be able to reuse them rather than reimplement them (and get one wrong). Refuses, silently and without side effects, when: the body is not tracked (a client naming an id that does not exist — note this deliberately does NOT auto-register, unlike the server-side reporting path); it is not ClientPredicted; the sender is not its owner; or the sequence is not strictly newer than the last accepted one.

• bool Update(long entityId, Vec3 position, Quat orientation, Vec3 linearVelocity, Vec3 angularVelocity)

  Reports a body's current transform for this physics tick. Cheap: it only records the latest state — the broadcast (quantize, cull, batch) happens on the piece's own broadcast tick, which decouples the physics rate from BroadcastHz. Auto-registers a valid, untracked server entity (as ServerInterpolated). Returns false for an unknown id or a player entity.

• bool Update(long entityId, Vec3 position, Quat orientation, Vec3 linearVelocity, Vec3 angularVelocity, uint lastProcessedInput)

  Reports a ClientPredicted body's transform together with the lastProcessedInput sequence — the last input the game folded into this authoritative state from the owning client. That sequence rides the owner's next RigidBodyReconcile so it can reconcile precisely (the rigid-body analogue of acknowledging a MoveInput.Tick). Harmless on a ServerInterpolated body (the sequence is stored but never sent). Auto-registers a valid, untracked server entity. Returns false for an unknown id or a player entity.

LB-GAP-10 — what the broadcast pass needs to know about chunks, and nothing more.

• long ChunkOf(long entityId)

  The chunk this entity currently rides, or 0. A member's own transform is not sent — the client derives it from the chunk's, which is where the bandwidth win is.

• event Action<RigidBodyChunkComposition, string> CompositionChanged

  A chunk was created, split or dissolved — the reliable message a client needs, and the zone to send it to.

• bool TryGetComposition(long chunkEntityId, out RigidBodyChunkComposition composition)

  The composition of a live chunk, for interest-reveal replay. The returned instance is REUSED; serialize it before the next call.

Configurable RigidBodies parameters (defaults here; never inlined in logic). The quantum and bit values are also the wire protocol — a client decoding these batches must use the SAME PositionQuantum, OrientationBits and VelocityQuantum.

• float AngularEpsilon { get; set; }

  Sleep threshold for ORIENTATION (radians): a body whose rotation changed by less than this angle since its last SENT snapshot is not re-broadcast. ~0.01 rad ≈ 0.57°.

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

  Composition-bridge table (used by the Hosting layer, never by this piece): which spawned entities BECOME simulated physics bodies, keyed by zone id — or by an instance PREFIX, resolved with the same rule every per-zone table uses. The gap this closes. Creating a dynamic body meant game C#: build a shape, call the engine's IPhysicsBodyFactory, then Register so it broadcasts. Nothing in configuration could do it, and the entity-body path deliberately will not (Crossplay:Physics:EntityBodies handles KINEMATIC and STATIC profiles — things something else drives, and scenery — and skips Dynamic ones precisely because their size, pose and velocity come from whatever spawned them). So a game shipping client + content + configuration and no server code could install this piece, install an engine, and never simulate a single barrel. This table is that switch, expressed as data: 886 immovable authored props become barrels that roll and crates that scatter without one line of server code. Empty (the default) = the bridge is not composed at all and a server behaves byte-for-byte as before. Genre-agnostic: "the props in this zone are simulated" is a warehouse, a racetrack, a dungeon and a demolition derby alike, and the piece still never learns which.

• string Backend { get; set; }

  Which named physics backend this server should run. Empty (the default) or none means no engine: the game reports transforms itself through Update, which is a completely ordinary way to use the piece and not a degraded one. What this does and does not select. A transport is picked from config out of implementations that all SHIP — LiteNetLib, WebSocket, QUIC. Physics is nearly the same now: Crossplay.Physics.Bepu is server infra that ships inside every generated server, and a project which installs this piece gets it composed. But this setting still only chooses among the backends the COMPOSITION offered by NAME, and offers nothing on its own — it is a named socket, not a menu of built-ins. The shipped engine is registered unconditionally, so leaving this empty runs it; a game that offers two named engines uses this to pick. What it buys is real all the same: turning a named engine off, or swapping engines, or running the same build with an engine in one environment and none in another, stops being an edit to a machine-owned generated file.

• bool BridgeContact { get; set; }

  Composition-bridge knob (used by the Hosting layer, never by this piece): when true, the Hosting contact bridge profiles every PORTABLE-hosted body on the Contact piece — its shape's bounds as a yaw-oriented OBB with a vertical extent, its authored mass as the weight, Impulse resolution — and routes the resulting impulses and separations back into the host's simulation (GAP-46). The exact mirror of Crossplay:Vehicles:BridgeContact, for the portable step. False (the default) = no bridge is composed and portable bodies pass through each other, exactly as BodyIntegrator documents ("no body-vs-body contact"). Engine-backed bodies are never bridged either way: an engine already owns contact for its own bodies, and profiling them on the Contact piece as well would resolve every pair twice.

• List<BroadcastBand> BroadcastBands { get; set; }

  LB-GAP-13 — per-observer distance bands for how OFTEN a body updates. EMPTY (the default) is today's single rate for everyone, byte-for-byte (rule 21).

• float BroadcastHz { get; set; }

  How many times per second moving bodies are broadcast. The service is an IServerTickable driven at the host tick rate; it broadcasts at most once per tick and no more often than this. 20 Hz mirrors the movement broadcast.

• float DormantCheckSeconds { get; set; }

  PHYS-15: seconds between proximity checks for DORMANT structures (StructurePlacement.RealizeRadius). Only runs while something is dormant, so a game that uses no radius pays nothing whatever this says. Not every tick, deliberately: a check walks the zone's entities, and a player cannot cross a realisation radius meaningfully in a fraction of a second. The default trades a half-second of lead time for twenty times less work.

• float ExpireAfterRestingSeconds { get; set; }

  How long a body may lie at rest before it is retired, seconds. 0 (the default) means bodies live until something removes them, which is today's behaviour and the right one for a world of doors and crates. Why this exists: demolition. A wall that comes apart into 200 pieces adds 200 PERMANENT bodies, and the second wall adds 200 more. Nothing reclaims them, so an hour into a session the simulation is carrying every brick anyone has ever knocked over. The broadcast side is already defended — a settled body sends nothing at all — but it is still in the broadphase, can still be woken by a neighbour, and still costs memory. Measured from when the body last MOVED, not from when it spawned: "gone thirty seconds after it stops rolling" is what a game means, and a spawn-time lifetime would delete debris mid-flight.

• int FrameBufferInitialBytes { get; set; }

  Initial capacity (bytes) of the reused outbound frame buffer. Grows to the high-water mark and never shrinks; sizing it past the largest batch frame makes steady state allocation-free.

• Dictionary<string, BodyInputProfile> InputProfiles { get; set; }

  Named input maps for driven bodies — the config-driven default over the IRigidBodyInputSink seam (GAP-48). Each profile says what the axes of a validated input frame BECOME: a force, a torque, a steer angle, a drive force. An InputProfile names an entry here. Empty (the default) composes nothing: inputs stay validated, sequenced and discarded — today's behaviour exactly. A game that registers its own sink still wins the seam; these tables then sit unread. Case-insensitive, for the same reason the physics profile table is: a name typed in two config sections will disagree about capitals eventually, and the failure would be a silently undriven body.

• float LinearEpsilon { get; set; }

  Sleep threshold for POSITION (world units): a body whose position moved less than this since its last SENT snapshot is not re-broadcast. A settled body sends nothing — the big bandwidth win. Also the position half of the dead-reckoning gate.

• int MaxBodiesPerFrame { get; set; }

  Cap on the number of MOVING bodies whose transform is broadcast per tick. A mass wake-up (an explosion scatters hundreds of crates) degrades to a bounded per-tick cost — excess bodies broadcast on later ticks, round-robin so none starve (freshest state each time), exactly the graceful trade the movement-broadcast budget makes. 0 = unbounded.

• int MaxBodiesPerPacket { get; set; }

  Cap on how many bodies ride in ONE state-batch packet. An observer owed more than this gets several packets in the same tick rather than one oversized one. This is a datagram limit, not a tuning preference. The batch is sent UNRELIABLY, and an unreliable datagram cannot be fragmented — LiteNetLib refuses anything past its single-packet maximum (1023 bytes on a default MTU) by THROWING, and that exception unwinds through the broadcast tick and kills the server process. MaxBodiesPerFrame does not protect against it: that budget bounds how many bodies are PROCESSED per tick, not how many end up addressed to one observer, and its own default of 256 is an order of magnitude past what fits in a datagram. A hundred physics bodies in one player's interest is not an exotic load, and it took the server down. 24 (the default) is derived, not picked: a quantized RigidBodyState is 36 bytes (id + 3 packed positions + a smallest-three orientation + 6 velocity shorts), so 24 of them plus the message header sit comfortably inside 1023 with room for a smaller path MTU. Raise it only alongside a measured MTU; 0 means unbounded and restores the crash.

• int MaxExpiryChecksPerFrame { get; set; }

  How many bodies the expiry sweep examines per broadcast tick. Bounded for the same reason MaxBodiesPerFrame is: a demolition leaves hundreds of settled bodies and not one of them is urgent.

• int MaxInputPayloadBytes { get; set; }

  Largest accepted RigidBodyInput.Payload, in bytes. 0 disables the cap. The piece cannot infer this: the payload is opaque by design, so it has no idea whether a game's input frame is two bytes or two hundred, and only the composition knows. It has to be a number rather than a guess because the alternative is an unbounded blob from an unauthenticated- as-to-content source arriving at the input rate. 64 covers any plausible frame — a throttle, a steering angle, a few buttons — with room to spare.

• int MaxPhysicsStepsPerTick { get; set; }

  Cap on how many fixed physics steps the driver runs in one host tick — the spiral-of-death guard: after a hitch the driver runs at most this many catch-up steps, then drops the remaining backlog rather than stepping unbounded (which would deepen the stall). 0 = unbounded.

• int MaxStructurePiecesPerTick { get; set; }

  PHYS-15: most structure pieces raised in one tick, staged over as many ticks as it takes. 0 (the default) builds every placement at once — today's behaviour exactly. Why it exists. PHYS-08 measured a burst: 200 pieces cost 2.37 ms and a 4.28 ms worst tick, and 500 cost 11.5 ms and spiked a tick to 69.8 ms — four dropped frames of server time at the moment a zone is furnished. A demolishable house is 400-900 pieces before anyone has broken one. Staging removes the spike outright, and a building appearing over a handful of ticks is invisible to a player who is still loading into the zone. It admits whole BUILDINGS until the budget is spent — it never half-builds one. A structure is two passes (every piece becomes a body, THEN every joint is created, because a joint needs both ends present), so a structure stopped between them is a wall with no welds, which falls over. So this bounds how many buildings may be raised in the same tick, not how large one may be: a zone with four 150-piece buildings and a budget of 200 raises one per tick, and a single 900-piece building still costs one tick. Splitting a structure itself is a different and much harder change.

• int OrientationBits { get; set; }

  Bits per stored quaternion component for smallest-three compression (8–10; 10 → a 32-bit code, ~4 bytes vs 16 raw). Coarser bits give a wider effective sleep tolerance. Must match the client. See SmallestThree.

• float PhysicsStepHz { get; set; }

  Fixed rate (Hz) at which a registered IPhysicsBackend is stepped by the PhysicsBackendDriver. Independent of BroadcastHz: the sim can run at 60 Hz while transforms broadcast at 20. Only used when a backend is composed (AddCrossplayRigidBodiesBackend); with no backend nothing reads it. 0 disables stepping.

• int PortableInputLeadSteps { get; set; }

  How many fixed steps a driven body may run AHEAD of server real time before further input frames are dropped until the clock catches up — the anti-speed-hack budget for the portable host. An honest client sends one input per fixed step and lands exactly on budget; this slack absorbs network jitter bunching two or three frames together. A client sending faster than real time gains at most this many steps ONCE, then never again, because the budget refills only as real time passes. A dropped frame's sequence still acks (the client already simulated it locally), so the punishment for flooding is a reconcile, not a desync.

• float PositionQuantum { get; set; }

  Position wire resolution in world units (one fixed-point step). 0.001 = 1 mm — sub-visible stepping that client interpolation smooths out, while keeping positions exact and deterministic. Must match the client.

• bool PrioritizeUnderBudget { get; set; }

  LB-GAP-13 — when more bodies are dirty than MaxBodiesPerFrame allows, send the ones that matter first instead of taking whoever the round-robin cursor happened to reach. False (the default) is today's fair rotation.

• float PriorityAngularWeight { get; set; }

  LB-GAP-13 — how much a body's SPIN counts toward its priority score, relative to its linear speed. Only read when PrioritizeUnderBudget is on. Not zero, because a piece tumbling in place is visibly stuttering when it defers, and not one, because radians and world units are not the same quantity: 0.25 makes a chunk spinning at 4 rad/s rank like one travelling at 1 unit/s, which is roughly how they read.

• int PriorityMaxSkips { get; set; }

  LB-GAP-13 — the most consecutive broadcasts a dirty body may be deferred before it jumps the ordering outright. Only read when PrioritizeUnderBudget is on. At the default BroadcastHz of 20, 3 means nothing waits longer than about 150 ms.

• bool ServeGeometryQueries { get; set; }

  Whether a query-capable physics backend also answers World's 3D geometry queries — i.e. whether AddCrossplayRigidBodiesBackend registers the engine's broad/narrow-phase as an IWorldGeometryProvider (GAP-35). True (the default) composes it, exactly as before. What false buys. The engine keeps everything else — pose authority, level geometry, entity bodies, the IPhysicsQueryBackend seam itself — but its broadphase leaves the IWorldQueries3D fan-out entirely, so server-only consumers (AI line of sight, spawn validation) stop seeing engine geometry too. The PREDICTED vehicle path never consults it either way (it injects the mirrored-only view); turn this off when the engine tier should not answer ANY world query — for example when the analytic + baked providers already carry the level and a second copy of it is pure cost.

• string ShapesPath { get; set; }

  Directory of baked .shapes3d libraries — the last link in "a model in Unity becomes a collision volume on the server". Empty (the default) registers no shape library, so a profile's Shape name resolves to nothing and falls back to its inline primitive. This is the knob that made the chain reachable.FilePhysicsShapeLibrary shipped, was tested, and was registered by NOTHING: there was no configuration that produced an IPhysicsShapeLibrary, so every baked shape a game authored was unreachable and every car was whatever box somebody typed into a profile. Same convention as Collision3D's ContentPath; a missing directory or no files means an EMPTY library, not an exception, because a game that bakes no shapes is not misconfigured.

• StructureChunkOptions StructureChunks { get; set; }

  LB-GAP-10: connected-chunk debris — a detached section simulates and replicates as ONE body. Off by default, and with it off no service is composed at all (rule 21). The single biggest smoothness + CPU + bandwidth lever at collapse scale: a 40-piece wall corner goes from 40 bodies and 40 transform streams to one of each (~28.8 KB/s → ~0.72 KB/s while moving), lands as a coherent slab you can climb, and — with RideProbeDistance — carries the furniture standing on it down with the floor.

• StructureConsistencyOptions StructureConsistency { get; set; }

  LB-GAP-15: the graph/engine consistency detector. Off by default (CheckSeconds 0), and with it off no sweep is composed at all (rule 21). This registry is told about changes rather than observing them, so a removal path that forgets to tell it makes the two states drift apart silently — a building reads as more intact than it is, and collapse warnings and objectives quietly stop working. THE FINALS shipped that exact bug (update 8.9). Turn this on for a bench run or a playtest; it inspects one structure per pass and reports, never repairs.

• StructureDetachOptions StructureDetach { get; set; }

  PHYS-29: how a detach spreads on a KINEMATICALLY-held structure (StructureDefinition.KinematicUntilDetached). Only read by structures in that mode; a solver-held building breaks welds and never consults this.

• StructureFractureOptions StructureFracture { get; set; }

  PHYS-22: whether, and how readily, a broken weld takes its neighbours with it. Off by default (PropagationChance 0), and with it off no propagation pass is composed at all — a break is exactly what the solver sheared, as it always was (rule 21).

• StructureIntegrityOptions StructureIntegrity { get; set; }

  PHYS-21: how the structural-integrity queries answer. Everything in it is off by default, so a composition that never touches it behaves byte-for-byte as it did (rule 21).

• StructureSettleOptions StructureSettle { get; set; }

  PHYS-28: when a structure that has stopped moving is allowed to stop costing anything. Off by default (AfterSeconds 0), and with it off no sweep is composed at all — a structure sleeps exactly when the engine's velocity heuristic says so, as it always did (rule 21). Turn it on for anything finely shattered. Measured on a 1,140-piece slab-on-pillars: standing perfectly still it never slept and cost 14.2 ms a step for ever, because a chunk welded on every face rocks at 0.15–0.23 rad/s and the engine's angular sleep threshold is 0.1. With this on, 0.04 ms.

• StructureStrainOptions StructureStrain { get; set; }

  LB-GAP-11: load-aware failure for KinematicUntilDetached structures — "strain-lite". Off by default (Enabled false), and with it off no sweep is composed at all (rule 21). The middle this framework did not have: a solver-held building carries real load and costs eight substeps a tick; a kinematic one costs ~0 and is load-BLIND, so it can never sag, be overloaded, or come down from weight redistribution. This decides failures over the graph the registry already owns and lets the ordinary detach cascade do the falling.

• Dictionary<string, List<StructurePlacement>> Structures { get; set; }

  Composition-bridge table (used by the Hosting layer, never by this piece): which BUILDINGS stand in which zone, keyed by zone id — or by an instance PREFIX, so one row furnishes every instance of a dungeon template. The gap this closes (PHYS-11). PHYS-07 built four links of a five-link chain — a Unity baker, the .structure3d format, IStructureLibrary with a file loader, and StructureBuilder, which turns a definition into bodies and joints in a live world — and then nothing called the last one. A game could bake a house, configure StructuresPath, start a server that reported no error, load the definitions, and get an empty level. Placing it took server C#: resolve five services, find the world's zone-activation event, and call TryBuild with a hardcoded pose. Empty (the default) composes no bridge at all, so a server behaves byte-for-byte as before.

• string StructuresPath { get; set; }

  Directory of baked .structure3d libraries — an artist's wall, as a building the server holds up and can knock down. Empty (the default) registers no structure library. Exactly the same story as ShapesPath: FileStructureLibrary existed with no way to compose it, which is the difference between "the framework supports destructible structures" and "a designer can make one".

• float VelocityQuantum { get; set; }

  Velocity wire resolution (units/s per quantized step) for both linear and angular velocity. 1/256 ≈ 0.0039 — animation/extrapolation data, not simulation state. Must match the client.

LB-GAP-10 tuning — connected-chunk debris. Off by default (rule 21).

• byte CarrierAppearanceKind { get; set; }

  LB-GAP-17 — the opaque appearance KIND byte a chunk CARRIER entity is spawned with. 0 (the default) spawns it with an empty blob, exactly as it shipped. What a carrier is, and why a game has to be able to tell. A chunk spawns one extra world entity to be the thing the engine simulates and the wire moves; it is not a piece, has no appearance of its own, and a client that draws every entity it is told about will draw something for it. Until now the only way to recognise one was "its blob is empty", which is an accident rather than a contract — an ordinary piece whose bake carried no appearance looks identical. The AUTHORITATIVE answer is not this. A carrier is named by RigidBodyChunkComposition.ChunkEntityId, which is sent reliably to the zone when a chunk forms and replayed on interest reveal, so a client that reads compositions knows every carrier by id and needs nothing here. This option is for the simpler client that only has the spawn: give carriers a blob your game recognises (a reserved kind byte, say) and the spawn alone is enough. Opaque, as every appearance blob in this framework is: the byte means whatever the game says it means and no Crossplay package looks inside it. One byte, and reached from config the same way StructurePlacement.AppearanceKind is, because that is this framework's spelling of "what should a client draw for this".

• bool ChunkDetachedGroups { get; set; }

  Simulate a detached connected group as ONE compound body instead of one body per piece. False (the default) composes nothing at all.

• int MaxChunkOpsPerTick { get; set; }

  The most chunk operations — creations, splits, dissolves — one tick may perform. The amortization discipline every other burst in this piece follows: a collapse that detaches six sections at once must not build six compounds in one tick.

• int MaxChunkPieces { get; set; }

  The most pieces one chunk may hold. A cap, not a tuning knob: a compound with a thousand children is one broadphase entry and a very slow narrowphase, which trades one problem for another.

• int MinChunkPieces { get; set; }

  The fewest pieces a detached group must have to be worth chunking. Two bricks are two bodies either way; the win starts at a section.

• float RideProbeDistance { get; set; }

  LB-GAP-10 tier 3 — how far below a world entity to look for a detaching group's piece when deciding whether that entity RIDES the section down. 0 disables riding entirely. "Objects remain attached when structures fall" is the FINALS Season 9 note, and the reason it matters is a collapsing floor with levitating furniture on it reads as broken. Riding is free: the entity's pose is derived from the chunk, so it costs no body and no extra wire.

• float RideProbeRadius { get; set; }

  How far horizontally a resting entity may be from a chunk piece's centre and still count as standing on it, world units.

LB-GAP-15 tuning. Everything off by default, so a composition that ignores it behaves byte-for-byte as it did (rule 21).

• float CheckSeconds { get; set; }

  Seconds between passes; each pass inspects ONE structure, round-robin. 0 (the default) composes no sweep at all. A debug/soak instrument, not a production tick cost: 5–15 seconds is enough to catch a missing telling-path during a bench run or a playtest, which is when it is worth catching.

• float RepeatSeconds { get; set; }

  Seconds before the SAME structure may report a divergence again. A missing telling-path diverges on every pass forever; it is one defect and deserves one line.

How readily a detach spreads, and how much of one is allowed in a single act.

• int MaxPerDetach { get; set; }

  Cap on pieces one detach may take, including the cascade. A structure standing on one chunk can legitimately lose all of itself at once, and that is a very large amount of work to do inside one interaction — so it is bounded, and the rest comes off on the next sweep.

• float PropagationChance { get; set; }

  Chance a neighbour of a detached piece comes off with it — the donor's ChunkConnectionStrength, expressed the way round it is actually used. Its rule is random > strength * depth, so a scene setting of 0.6 means a 40% chance at one hop and never at two. 0 (the default) spreads nothing: a hit takes exactly what it hit.

• int PropagationDepth { get; set; }

  How many hops a detach may spread. 1 matches the donor at its usual settings.

• int Seed { get; set; }

  Seed for the propagation dice. The same seed and the same hits give the same rubble.

PHYS-22 tuning. Ships OFF: with PropagationChance at 0 (the default) nothing is composed, nothing is decided, and a break is exactly what the solver sheared — today's behaviour byte-for-byte (rule 21). A structural game that wants physical honesty changes nothing.

• int MaxPropagatedBreaksPerStep { get; set; }

  Cap on propagated breaks per step, across every structure. A pathological chain on a 500-piece building must be bounded the same way MaxStructurePiecesPerTick bounds staging. 0 = unbounded.

• StructureFractureSource PropagateFrom { get; set; }

  LB-GAP-17 — WHICH breaks are allowed to start a shockwave. Ships as AnyBreak, which is what shipped: every break seeds, byte-for-byte as before (rule 21). Set it to BlowsOnly and a weld that gave way under WEIGHT no longer starts a chain — only one that something hit does. What it is for, measured. Everything above is written about a blow: "a sledgehammer and a nudge should not make the same hole". Until PhysicsJointBreakCause existed there was no way to ask, so a structure settling onto its own marginal welds seeded the shockwave exactly as a hammer did. On a baked 34-piece wall (min weld 394 N·s, mean 3 821) three welds gave way to the wall's own weight in the first two steps after it was raised; at chance 0.5 and depth 2 those three became forty-one welds in one step, and the building had lost 63 of its 94 welds before a player connected — silently, because a fractured wall whose welds are gone still stands there interlocked. With this set to BlowsOnly the same wall keeps 89 of 94, and a hammer blow still brings a hole out of it because a blow is what the sample reading measures. It is a choice, not a correction. A game whose collapses are meant to run away as redistributed weight re-breaks welds wants AnyBreak and should keep it.

• float PropagationChance { get; set; }

  How readily a break spreads to a neighbouring weld, 0..1. 0 (the DEFAULT) is today's behaviour exactly: only what the solver sheared. 1 takes everything connected, within the depth below. Why this exists. A weld breaks when the impulse across it exceeds its threshold, and ONLY then — which is physically defensible and is what PHYS-03 and PHYS-19 built. It also means that to make a HOLE in a wall you must independently deliver enough impulse to shear every weld around the hole's perimeter, because each is evaluated on its own. Measured on the demo house at 400 N.s welds: a 1,200 N.s hammer blow breaks 3 of 66 welds — one brick comes loose. A brick in the middle of a wall has four to six welds, so a hammer that removes a BRICK is affordable and a hammer that makes a HOLE is not; a hole is what a demolition game is about. Every workaround is worse. Lowering the threshold so one blow shears six welds is a building that no longer holds its own weight. Raising the tool's impulse to thousands of newton-seconds launches the pieces rather than dislodging them — momentum that shears six welds is momentum a 12 kg brick leaves at highway speed. Damage-then-detach works and is the drill's verb, but it removes one named piece at a time and cannot express "a chunk came out".

• int PropagationDepth { get; set; }

  How far a break may spread through the graph. Each step multiplies the chance down, so depth 2 at chance 0.8 is 0.8 for a direct neighbour and 0.64 one further out.

• float PropagationMinExcess { get; set; }

  Excess below which nothing propagates — a weld that only just gave way should not start a chain. Expressed as a MULTIPLE of the threshold: 2 means "the blow had to be twice what the weld could take". 0 (the default) propagates from any break.

• float PropagationWeakArea { get; set; }

  Contact area at or below which a weld is treated as FULLY weak for propagation — the ragged-edge dial. Propagating preferentially into small contacts rather than uniformly at random produces plausible holes for free, and the deriver already measured the area of every weld. 0 (the default) ignores area entirely and every neighbour rolls the same chance. Set it to about the area of a full brick face and a corner contact becomes far likelier to go than a bedded one.

• bool ScaleByExcess { get; set; }

  Whether the chance scales by how much the blow EXCEEDED the weld's threshold. True by default, because it is the more honest version of the same dial and costs one multiply. The donor engine's roll is flat — it has no such number. Ours does: a blow that beat the weld by ten times should spread further than one that beat it by 1.01, and a sledgehammer and a nudge should not make the same hole.

• ulong Seed { get; set; }

  Seed for the propagation rolls. Combined with each structure's id, so two identical buildings on the same site do not fracture identically and the SAME building fractures the same way on a replay. Why a seed at all.Random.value on one machine is fine when there is one machine. Ours must be identical on the server and reproducible in a replay (Crossplay.Replay would otherwise diverge), so the roll is seeded rather than inherited.

PHYS-21 tuning. Everything here is off by default, so a composition that ignores it behaves byte-for-byte as it did (rule 21).

• float MaxHorizontalSupportDistance { get; set; }

  How far a piece may be from its nearest anchored piece, measured HORIZONTALLY, and still count as supported. Infinity (the default) turns the rule off entirely and no geometry is consulted. What it buys. Connectivity alone says a beam cantilevered twenty metres out over nothing is "supported", because there is an unbroken chain of welds back to the foundation. No player would accept that, and no survey tool should render it. This is the donor engine's ChunkHorizontalRadiusSupportStrength: a one-line stand-in for a bending moment, and exactly what makes an overhang read correctly. It changes what IsSupported and SupportPathCount REPORT. It changes nothing about the simulation — the solver is never overridden, and a piece this calls unsupported does not start falling because of it (see the interface remarks on why that distinction is the whole design). Measured in the DEFINITION's own space, as built. That is the right frame — "how far out does this beam hang" is a property of the building, not of where it was dropped — and it is unaffected by the structure's placement for every rotation a placement can express, because StructurePlacement offers a YAW and a yaw preserves horizontal distances. A game calling StructureBuilder.TryBuild with an arbitrary quaternion that tips a building onto its side is the one case where "horizontal" in the definition is not horizontal in the world; the rule then measures the building's own horizontal, which is stated here rather than silently assumed.

PHYS-28 — when a structure that has stopped moving is allowed to stop costing anything. Off by default (AfterSeconds = 0): with it off no sweep is composed at all and a structure sleeps exactly when the engine's own velocity heuristic says so, as it always did (rule 21).

• float AfterSeconds { get; set; }

  How long every piece of a structure must hold still before its island is put to sleep, seconds. 0 turns this off. Why any number here is safe and a bigger sleep threshold is not. This is not a guess about velocity — it is an observation that the building did not move. A piece that is genuinely creeping never accumulates the window, so the pass cannot freeze a slow collapse; that is the exact failure a raised SleepThreshold produces, and it is recorded in docs/DESTRUCTION-PERFORMANCE.md under "sleep MASKS an under-converged structure". A second or two is right: long enough that a settling collapse is finished, short enough that a player watching a building stop does not see it burn a core afterwards.

• float CheckSeconds { get; set; }

  Seconds between sweeps. Not every tick, deliberately: the sweep reads every piece of every AWAKE structure, and a building cannot become still and then move again inside a quarter second in a way that matters.

• int MaxPiecesPerSweep { get; set; }

  Cap on pieces examined in one sweep, so a zone full of structures cannot turn a settle check into the most expensive thing in the tick. The sweep resumes at the next structure the following time, so nothing is skipped — it just takes longer to notice.

• float MoveEpsilon { get; set; }

  How far a piece may move between sweeps and still count as still, world units. Bigger than the residual jitter of a stiff weld grid (measured: a 1,140-piece slab drifts under 0.0005 units per quarter second at 8 substeps) and far smaller than anything a player could see.

How to break a solid volume into pieces — PHYS-23 phase 3, for box volumes. Every number that decides what the rubble looks like is here, because a shatter is a content decision and a game will want a slab, a plank and a pane to shatter differently.

• float AnchorBelowY { get; set; }

  Anchor any piece whose UNDERSIDE is at or below this height (in the same space as the volume's centre). NegativeInfinity, the default, anchors nothing. This is the donor's support plane in one number: everything the plane touches becomes a support chunk. A structure needs at least one anchored piece or it is a free-floating object that simply falls — and it must NOT be all of them, because a weld between two anchored pieces is refused, so a fully anchored shatter derives no joints at all.

• byte[] Appearance { get; set; }

  PHYS-12's per-piece opaque blob. Null/empty leaves each piece inheriting the structure's, which is what a single-material volume wants.

• float Density { get; set; }

  Mass per cubic world unit when TotalMass is 0. The default is roughly concrete.

• string Group { get; set; }

  PHYS-20's part tag for every piece produced. Empty leaves them untagged.

• float MinMass { get; set; }

  Floor on a single piece's mass, so a small chunk of a light volume is still something the solver can push around predictably.

• float MinPieceSize { get; set; }

  Smallest a piece may be on ANY axis, world units. This is not a cosmetic bound — see MinContactArea: a sliver welds to its neighbours across a face so small that the area-scaled break impulse rounds to nothing, so a shatter that produces slivers produces a structure whose weakest joints are in a pattern nobody chose.

• float OffAxisChance { get; set; }

  Chance a cut is taken on a RANDOM axis rather than the widest one. Zero always cuts the widest axis, which drives every piece toward a cube — the structurally sane default, because a cube welds to six neighbours across broad faces. Raise it for sawn-looking debris.

• int Seed { get; set; }

  Seed. The same seed and volume give byte-identical pieces on both tiers and in a test — which is what makes a shattered structure bakeable content rather than a surprise.

• float SizeVariation { get; set; }

  How far off centre a cut may fall, as a fraction of the legal range. 0 splits every piece exactly in half — a perfect lattice, and instantly readable as one. 1 puts the cut anywhere the size floor allows, which is what reads as fractured material.

• int TargetPieces { get; set; }

  How many pieces to aim for. The result can be FEWER: splitting stops when no piece can be cut again without a child going under MinPieceSize, which is the honest answer to "shatter this pane into a thousand" rather than emitting slivers.

• float TotalMass { get; set; }

  Mass for the WHOLE volume, kilograms, split between the pieces in proportion to their volume (the donor engine's TotalMass × RelativeVolume). 0 uses Density. Usually what you want: a slab's weight is a gameplay number, and deriving it from a density makes a 12-unit slab weigh 276 tonnes, which is correct and unplayable.

LB-GAP-11 tuning — "strain-lite". Everything off by default, so a composition that ignores it behaves byte-for-byte as it did (rule 21).

• bool Enabled { get; set; }

  Turns load-aware failure on. False (the default) composes no sweep at all.

• float EvaluateSeconds { get; set; }

  Seconds between passes. The evaluation is a flood per structure, so it is deliberately not per-tick — and it only visits structures something has actually changed.

• float ImpactLoadDecay { get; set; }

  How quickly transient impact load bleeds away, as a fraction remaining per evaluation. 0 makes an impact a single-evaluation event; 1 would make it permanent, which is a building that remembers every pebble for ever.

• float ImpactLoadScale { get; set; }

  Turns a reported impact into transient LOAD on the piece it struck, scaled by this. 0 (the default) ignores impacts entirely. This is the chain reaction between structures. In the kinematic mode a piece has infinite mass, so falling debris bounces off a second building and nothing happens — which is exactly the behaviour THE FINALS' strain system does not have. With this above 0, debris from one collapse can bring down the next.

• int MaxFailuresPerEvaluation { get; set; }

  The most connections one evaluation may fail. A single overloaded course can put a whole wall over threshold at once; letting it all go in one pass is a spike, and letting it go over the next few passes is a collapse.

• int MaxStrainEvaluationsPerTick { get; set; }

  The most structures one pass may evaluate. The amortization discipline every other burst in this piece follows, and the one Embark describes: "amortize strain, physics and replication".

• float SafetyFactor { get; set; }

  How far past a connection's built capacity its load may go before it gives. 1.0 fails a connection the moment it is carrying exactly what it was built for, which is a building that collapses as soon as it is finished; above 1 is the margin a real structure has.

• float WeakenBeforeFail { get; set; }

  A connection's FIRST offence weakens it to this fraction of its capacity instead of failing it; the second fails. 1.0 skips the warning stage and fails immediately. Creaky, and fair: a player gets one audible, visible round of warning — the weaken raises nothing on the wire by itself, but the support change it eventually causes does — before the wall actually goes.

The RigidBodies piece, client side: renders server-synced physics bodies and drives client-side prediction for the bodies THIS client owns. Two per-body patterns, chosen automatically: Pattern A (default) — a body seen only on the interpolation channel (RigidBodyStateBatch) is snapshot-interpolated. Pattern B — a body for which a RigidBodyReconcile arrives (or that the game declares via PredictOwned) is predicted locally and reconciled; it is skipped on the interpolation channel. The reconcile channel is itself the ownership signal — only the owner receives it — so no un-owned body is ever predicted. Pattern C — a body the game declares via PredictShared is simulated locally by EVERY client at present time (no interpolation delay) and smoothed toward each authoritative batch state — the Rocket-League-ball pattern for an un-owned body whose feel matters. Purely a client-side rendering choice: the server keeps broadcasting the ordinary batch. Presentation is the game's: bind an id to a view through IRigidBodyViewFactory; supply local physics through IRigidBodyIntegrator. Both optional — a headless client still decodes the streams (and the diagnostics panel still works).

• void PredictOwned(long entityId, RigidBodyPose initialPose)

  Declares a body this client owns and predicts (Pattern B), seeded at initialPose (typically its spawn pose). The body then consumes reconciles only and is skipped on the interpolation channel. Idempotent — safe to call before or after the first reconcile. Optional: the first reconcile also marks a body owned, but calling this lets the game start RecordInput immediately, before the first reconcile lands.

• void RecordInput(long entityId, uint sequence, RigidBodyInput input)

  Records a locally-produced input for an owned predicted body — the game sends the SAME sequence + input to its own server handler (which folds it in and echoes the sequence back on the next RigidBodyReconcile). Advances local prediction and buffers the input for replay. Sequences must be monotonically increasing and start at 1. No-op for an unknown / non-predicted body, or when no IRigidBodyIntegrator is bound (the body then simply snaps to each reconcile with no local replay).

• void PredictShared(long entityId)

  Declares a body EVERY client should simulate locally instead of interpolating (Pattern C) — the un-owned but latency-critical body: the match ball, the bomb, the puck. Between batches the body advances through the bound IRigidBodyIntegrator (or ballistically from its last velocities when none is bound); each authoritative batch state is adopted as the new simulation base with the visual jump absorbed by the same smoother prediction uses. Idempotent; an already-interpolated body migrates its view across the switch. A body this client OWNS belongs in PredictOwned instead (input replay beats re-simulation).

• void Forget(long entityId)

  Stops tracking a body (call on despawn): drops its interpolator/reconciler and releases its view through Release. Harmless for an untracked id.

• void CollectTrackedBodies(List<RigidBodyPlacement> into)

  Appends every tracked body's id and current RENDER pose to into — PHYS-14's read side (the list is cleared first). Not the diagnostics rows. Monitors is display data, rebuilt on a repaint cadence for a panel that may not even be open; reading collision out of it would make a client's prediction depend on whether someone had a debug window up. This is the same poses, on demand. The RENDER pose, deliberately — the one being drawn. An interpolated body is shown an interpolation window in the past, so standing on one means standing where it is SEEN to be. That is a few centimetres of disagreement with the server, which the reconciler exists to absorb, and it is a vastly smaller error than falling through the thing entirely.

• int InterpolatedCount

  Number of bodies currently interpolated (Pattern A).

• int PredictedCount

  Number of bodies currently predicted (Pattern B).

• int SharedPredictedCount

  Number of bodies currently shared-predicted (Pattern C).

• float LastCorrectionMeters

  Distance (metres) the most recent reconcile corrected a PREDICTED (Pattern B) body by, across every body this client owns — ~0 when prediction agrees with authority (GAP-37a; the same diagnostic the Movement and Vehicles clients expose). Statistics over raw metres are partly statistics about speed; use LastCorrectionSeconds for the invariant form.

• float LastCorrectionSeconds

  The last correction expressed as TIME: LastCorrectionMeters divided by the reconcile's authoritative speed — how much travel authority rewound, which means the same thing at every speed. 0 when that body was stationary: a nonzero correction at zero speed cannot be latency and is its own, different signal. Compare against StateIntervalSeconds: ≈1 interval is prediction's floor; ≥3 is a rewind.

• float StateIntervalSeconds

  One reconcile interval, seconds — the floor LastCorrectionSeconds is compared against. The owner reconcile rides the broadcast pass, so this is 1 / RigidBodyClientOptions.StateSendRateHz (the client's mirror of the server's Crossplay:RigidBodies:BroadcastHz).

• IReadOnlyList<RigidBodyMonitor> Monitors

  A snapshot of the tracked bodies for diagnostics — rebuilt on the client's repaint cadence.

• event Action MonitorsChanged

  Raised when the monitor snapshot has been rebuilt (the diagnostics panel repaints here).

Narrow contract the presenter drives. UI-only and intent-free: RigidBodies is a push-only render piece (the game reports transforms server-side; the client only receives), so this view only renders — a diagnostics monitor, never a request path.