Host Integration
Use this guide to wire your game engine, server, or test harness into Gravitas. Your host creates the objects, applies commands in a stable order, and calls Gravitas on the fixed-step schedule.
Getting Started builds a complete first world. Runtime Architecture maps the services behind it, and Serialization And Replay covers saving and restoring its state.
Quick Read
Suppose the host receives a command to push the sphere from
Getting Started. The host applies that command before
Simulate(). LateSimulate() completes the authoritative step. A replay
hash can record the result there. The render loop can independently call
Visualize() and LateVisualize() to present it.
flowchart TB
accTitle: Fixed step and presentation for one sphere command
accDescr: Apply the sphere impulse before Simulate and finish the fixed step with LateSimulate. Hash the completed state if needed. Presentation runs from the render loop.
Commands["Apply ordered impulse"]
Commands --> Simulate["Simulate()"]
Simulate --> Late["LateSimulate()"]
Late -->|"Optional"| Hash["Hash state"]
Late -.->|"On a render update"| Visualize["Publish pose"]
- Set up a simulation with one context, grid coverage, and
an
IMatterAgentthat exposes the object'sFixedTransform. - Choose a body and collider for 3D or the 2D counterparts for planar motion.
- Drive the fixed loop, run spatial queries, and release registrations before pooling host objects.
Public Surface
| Need | Use |
|---|---|
| Create an owned world | GravitasWorldContext.CreateOwned(...) |
| Attach a host-owned world | GravitasWorldContext.Attach(world, takeOwnership) |
| Bind a host object | IMatterAgent |
| Register a 3D body | new SolidBody(agent, collider).Initialize(...) |
| Register a 2D body | new SolidBody2D(agent, collider).Initialize(...) |
| Register bodyless geometry | collider.InitializeWithNoBody(agent) |
| Reconfigure a 3D primitive body | body.TryReconfigureCollider(...) |
| Set runtime mode | context.Settings.RuntimeMode |
| Run 3D constraints/ragdolls | context.Constraints3D |
| Run 2D constraints/ragdolls | context.Constraints2D |
| Query 3D, 2D, or mixed geometry | context.Query3D, context.Query2D, context.QueryMixed |
| Hash replay state | context.ComputeReplayHash() |
| Reset a session | context.Reset() |
| End a context | context.Dispose() |
Lifecycle Contract
Use the LSF lifecycle names as a mental model, not as engine-specific APIs:
| Phase | Host responsibility | Gravitas call |
|---|---|---|
Setup |
Create package defaults, host resources, and worlds. | Create or attach GravitasWorldContext. |
Initialize |
Bind agents, transforms, colliders, bodies, settings, and grids. | Initialize colliders and bodies. |
Execute |
Apply deterministic commands or network input in ordered frame batches. | No direct call. Mutate host-owned state before simulation. |
Simulate |
Advance the authoritative fixed step. | context.Simulate(). |
LateSimulate |
Finish deterministic end-of-frame work. | context.LateSimulate(). |
Visualize |
Interpolate or publish presentation state. | context.Visualize(). |
LateVisualize |
Finish presentation-only work. | context.LateVisualize(). |
Deactivate |
Pool/despawn agents and release registrations. | body.Deactivate() or collider.Deactivate(). |
Quit |
Shut down the host process/session. | context.Dispose() when the context is no longer needed. |
Authoritative simulation state belongs in Simulate and LateSimulate.
Visualize and LateVisualize are for interpolation and presentation; do not
use them to apply gameplay commands or physics corrections.
The context owns its clock. When integrating Trailblazer, advance each context once per gameplay step with matching represented step durations; the adapter does not synchronize clocks or compensate for a missed advance. Apply rate changes to both contexts at the same fixed-step boundary. Their numeric frames can differ if initial world preparation advanced one earlier.
Reset is a host-coordinated lifecycle boundary, not rollback. Stop the loop, discard pending work and old waits, coordinate context resets and runtime-shell reconstruction, then resume. Populating a body does not restore the world clock; neither context exposes a live-clock rewind API.
Minimal Setup
Host Agent
The host provides IMatterAgent so Gravitas can bind an object to a context and
fixed transform without depending on an engine, ECS, rendering, or a specific
object model.
using FixedMathSharp;
using Gravitas;
internal sealed class HostMatterAgent : IMatterAgent
{
public HostMatterAgent(
GravitasWorldContext context,
FixedTransform transform,
bool isParent = true)
{
Context = context;
Transform = transform;
IsParent = isParent;
}
public GravitasWorldContext Context { get; }
public FixedTransform Transform { get; }
public bool IsParent { get; }
public bool IsInteracting { get; set; }
}
IsParent marks whether an agent is intended to be a top-level hierarchy owner.
Hierarchy collision filtering is bound explicitly on colliders:
weaponCollider.SetParent(characterCollider);
leftFootCollider.SetParent(characterCollider);
rightFootCollider.SetParent(characterCollider);
SetParent(...) stores a dimension-tagged top-parent collider key, so sibling
filtering does not depend on an engine transform hierarchy. Mixed mode can bind
2D colliders under 3D colliders, or the reverse, without aliasing the separate
collider ID tables. Use ClearParent() when a collider leaves the hierarchy
without being deactivated.
Context And Grid
Use CreateOwned(...) when Gravitas should own the GridWorld lifetime:
using Gravitas;
using GravitasWorldContext context = GravitasWorldContext.CreateOwned();
Use Attach(...) when the host creates and owns the GridWorld:
using Gravitas;
using GridForge.Grids;
using GridWorld world = new();
using GravitasWorldContext context = GravitasWorldContext.Attach(world);
Pass takeOwnership: true to Attach(...) only when disposing the context
should also dispose the supplied world. One active GridWorld can be attached
to only one active GravitasWorldContext.
Colliders partition into existing GridForge voxels. Add grids that cover the simulation area before initializing bodies and colliders:
using FixedMathSharp;
using GridForge.Configuration;
context.World.TryAddGrid(
new GridConfiguration(
new Vector3d(-16, -4, -16),
new Vector3d(16, 8, 16)),
out _);
If no voxel exists for a collider's bounds, the collider cannot be distributed into partitions and will not participate in partition-backed collision/query work for that area.
Collider Authoring And Adapter Boundary
LSCollider and LSCollider2D are public polymorphic runtime types, not
extension points for engine-owned geometry. Gravitas owns their concrete shape
implementations and keeps their base constructors assembly-only so every
registered collider has a supported deterministic geometry contract.
Engine adapters should translate host collider assets into the data-only shape definitions, then create an unbound runtime collider:
ColliderShapeDefinition shape =
ColliderShapeDefinition.Sphere(
Fixed64.Half,
PhysicsMaterial.Default);
LSCollider collider = shape.CreateCollider();
ColliderShapeDefinition2D shape2D =
ColliderShapeDefinition2D.Circle(Fixed64.Half);
LSCollider2D collider2D = shape2D.CreateCollider();
The definitions snapshot mesh and polygon inputs and validate dimensions before
creating the matching Gravitas-owned runtime shape. Direct construction of
LSSphereCollider, LSCircleCollider2D, and the other concrete types remains
available when an adapter already knows the exact shape. No engine reference,
reflection, or custom collider subclass is required.
Dynamic 3D Body
Dynamic 3D matter usually has a host agent, one LSCollider, and one
SolidBody.
using FixedMathSharp;
using Gravitas;
using Gravitas.Colliders;
using Gravitas.Materials;
FixedTransform transform = new(
Vector3d.Zero,
FixedQuaternion.Identity,
Vector3d.One);
HostMatterAgent agent = new(context, transform);
LSSphereCollider collider = new();
collider.Material = new PhysicsMaterial(
staticFriction: Fixed64.One,
dynamicFriction: Fixed64.Half,
restitution: Fixed64.FromFraction(1, 4));
SolidBody body = new(agent, collider)
{
Mass = Fixed64.One
};
body.Initialize(
Vector3d.Zero,
FixedQuaternion.Identity,
PhysicsMobilityType.Dynamic);
Initialization binds the body and collider to agent.Context, allocates
context-local body/collider IDs, calculates runtime shape data, and partitions
the collider. FixedTransform and Gravitas body admission both preserve a
normalized orientation invariant. Scaled or extreme finite quaternion inputs are
scale-safely normalized, and a zero quaternion resolves to identity before
runtime shape state is published.
2D Body
2D scenes use the same host-agent shape, but select the 2D runtime path and create 2D body/collider types:
context.Settings.RuntimeMode = PhysicsRuntimeMode.TwoD;
LSCircleCollider2D collider = new(Fixed64.Half);
SolidBody2D body = new(agent, collider)
{
Mass = Fixed64.One
};
body.Initialize(
agent.Transform.WorldPositionXZ,
motionType: PhysicsMobilityType.Dynamic);
The 2D projection uses the LSF X/Z convention: world X maps to 2D X and world Z
maps to 2D Y. World Y remains vertical height or mixed embedding metadata.
Positive planar rotation turns Vector2d.Right toward Vector2d.Forward and is
exposed as WorldRotationXZRadians; its 3D embedding is a negative Y-axis
quaternion rotation. Gravitas canonicalizes authoritative 2D yaw to
[-Fixed64.Pi, Fixed64.Pi), including serialized and multi-turn inputs.
FixedTransform distinguishes authored local components from hierarchy-aware
world views. Host adapters should populate LocalPosition, LocalRotation, and
LocalScale from their engine object, then use the explicit World* members
when synchronizing physics. Gravitas kinematic readback and dynamic publication
use world position/rotation and preserve a 2D host's world Y. A failed parent
inverse is reported rather than silently writing the wrong local pose.
Bodyless Geometry
Use InitializeWithNoBody(...) for static or trigger geometry that does not
need body-owned state. IsTrigger is valid only on bodyless colliders; use a
normal body-owned collider for the moving participant that should receive
trigger callbacks:
using Gravitas.Colliders;
LSCuboidCollider floor = new();
floor.InitializeWithNoBody(agent);
Non-trigger bodyless colliders block dynamic bodies in discrete response in both
3D and pure 2D. They contribute collision geometry and material, with zero
velocity, inverse mass and inverse inertia. Only the body-owned participant
receives correction or impulse. Use an explicit PhysicsMobilityType.Static body
when the host needs body-owned state; it is not required for a solid floor.
A body with all translation axes frozen is different from a static body or a bodyless collider. Select the runtime role explicitly:
| Role | Ownership |
|---|---|
PhysicsMobilityType.Dynamic |
Solver controlled. FreezeAxes independently constrains translation and rotation. |
PhysicsMobilityType.Kinematic |
Host controlled. Gravitas samples deterministic host motion and CCD, but applies no solver impulse. |
PhysicsMobilityType.Static |
Immobile and excluded from simulated-body iteration. Use explicit pose setters to reposition it between fixed steps. |
For example, a rotating platform that must not translate is a Dynamic body
with BodyFreezeAxes3D.Position; the 2D equivalent uses
BodyFreezeAxes2D.Position. Freezing every axis does not silently change the
body role. LSCollider.IsStatic and LSCollider2D.IsStatic report only an
explicit Static body or bodyless ownership.
Call SetMotionType(...) to change a registered body's role between fixed-step
transactions. The transition preserves body, collider, pair, and joint identity,
but clears incompatible motion, sleep, CCD, contact warm-start, and joint-solver
state before repartitioning. It rejects calls before initialization, after
deactivation or context reset, during an open fixed-step transaction, and from
simulation callbacks. Ragdoll role changes use their atomic runtime operation
rather than transitioning links individually.
Continuous Static Surfaces
Declare continuity explicitly after registering the colliders. Use
context.Physics.CreateStaticSurface(ReadOnlySpan<LSMeshCollider>) for 3D
meshes using triangle-surface mode (MeshColliderMode.Concave), or
context.Physics2D.CreateStaticSurface(ReadOnlySpan<LSCollider2D>) for 2D AABB
and convex polygon pieces:
// Each piece is already active and registered with this context.
using StaticSurface floor = context.Physics.CreateStaticSurface(
new LSMeshCollider[] { leftMesh, rightMesh });
using StaticSurface2D wall = context.Physics2D.CreateStaticSurface(
new LSCollider2D[] { leftPiece, rightPiece });
// Replace the complete declaration when streaming pieces between fixed steps.
floor.ReplaceMembers(new LSMeshCollider[] { rightMesh, nextMesh });
Concave names the collision policy, not a requirement that the geometry be
nonconvex. A flat convex panel or closed convex-shaped shell can use this mode.
Closed shells retain triangle-surface behavior rather than filled convex-volume
behavior; see
mesh modes and closed topology.
Members must be distinct, independent colliders in the owning context, either bodyless or owned by explicit static bodies. A collider belongs to at most one surface. Dynamic and kinematic bodies, compound parts, convex 3D mesh volumes, and 2D circles or capsules are not eligible members. The handle declares which pieces may join; geometric validation decides which boundary spans actually do. See continuous static surface geometry for exact joins, genuine edges, materials, and deep-placement limits.
Create, replace, load membership, and dispose only between complete fixed steps,
after LateSimulate() and before the next Simulate(). ReplaceMembers(...)
publishes the complete candidate set atomically; invalid membership leaves the
previous declaration usable. Empty membership is allowed, so a host can retain
the handle while all pieces are streamed out. Geometry and filtering changes
invalidate dependent contacts and support; moving a piece can open a real gap.
Deactivating or unregistering a member, or changing it away from static
ownership, removes its membership. Reactivation requires an explicit declaration
again. Dispose() removes the declaration without deactivating its colliders;
repeated disposal is harmless. Context reset or disposal invalidates every owned
surface handle. Create a new handle for the new context lifetime. Restore uses
host-created handles and typed collider links.
Runtime mass changes
Assign SolidBody.Mass or SolidBody2D.Mass between complete fixed steps. An
actual change refreshes inertia from the committed collider shape and COM,
clears contact and connected-joint impulse caches and CCD state, wakes the body,
and immediately synchronizes awake membership in pure and mixed partitions. The
body keeps its role, freeze axes, registration, pose, velocities, and already
accepted accelerations. Queued force/torque inputs have already been converted
to acceleration; changing mass does not retroactively rescale those inputs.
Zero and negative mass disable applicable solver motion without converting a dynamic body into a static one. Restoring positive mass restores the unfrozen degrees of freedom and collision eligibility. Assigning the current value is a no-op, including for sleeping bodies and during a simulation callback.
Changed values reject during an open fixed-step transaction, in simulation callbacks, or after a context registration reset. Inertia calculation completes before publishing the new mass, so a calculation failure preserves mass, inertia, sleep, and caches. Before initialization or after deactivation, mass is configuration only; initialization derives inertia from the committed shape. Recorded-state loading retains saved sleep and motion rather than applying the public setter's wake policy.
Built-in primitive mass calculations use the effective shape dimensions before and after initialization. These dimensions also supply primitive compound contributions. Detached shapes use their authored dimensions and part scales; initialized shapes use committed owner and part scales. A sphere takes the largest radial scale across X/Y/Z, while a cone, cylinder, or 3D capsule uses X/Z for radius and Y for height.
Primitive intrinsic inertia retains geometry and mass products through final
rounding. Existing fixed coefficients retain their Q32.32 quantization,
including the sphere's 2/5 coefficient. Capsules retain exact internal
component weights; a 2D capsule includes both semicircular caps' complete polar
moment about its center. A box rounds the sum of its axis contributions once.
Primitive scalar formulas saturate only an unrepresentable final value, so a
large intermediate radius square does not discard a representable final moment.
Compounds retain volume or area weights, intrinsic moments and parallel-axis terms until parent mass is applied. Children do not receive rounded mass allocations. Polygon and mesh integrals include the first-moment residual when their published COM is rounded, and reference-point overrides participate in the same final calculation. An unrepresentable final compound tensor or moment throws before body mass is changed. Completed geometry is cached for mass and world-pose changes; changing owner scale, local offset or the requested reference refreshes it.
3D tensor transport follows the same active rotation as collider geometry,
including temporary CCD poses. Mesh public unit-tensor data remains a Q32.32
projection. Runtime mesh inertia retains its integrals through mass application
and reference translation, including the first-moment residual of a rounded
published COM. Closed-volume and surface policies cache their own geometry; pose
changes reuse it. Standalone results saturate only an unrepresentable final
entry, while compound results remain checked. PhysicsMesh applies signed mass
algebraically after geometry validation; collider APIs return zero for
nonpositive mass. Public mass-property data objects continue to scale their
published unit-tensor projections.
Standalone 2D polygons likewise retain centered integrals and the first-moment residual through complete reference translation and final mass-applied rounding. References are body-local: host yaw does not affect the scalar moment, while an authored compound-part rotation rotates the residual into the parent's frame. An unrepresentable final standalone polygon moment saturates when its semantic center is representable; if both are outside the scalar domain, the request throws.
Explicit body pose changes
Static bodies do not poll their host transforms. SetPosition(...),
SetRotation(...), and 3D UpdateRotation(...) are the authoritative explicit
repositioning surface; they refresh pure and mixed partition membership
immediately so queries observe the new pose without a simulation step. A pose
change first prepares the complete collider candidate, including exact scale,
canonical geometry, bounds, and mass properties. If that candidate is invalid,
the body pose, host transform, committed collider state, and partitions remain
unchanged.
Bodyless 3D and 2D colliders rebuild from their agent transform during the next
fixed-step partition preparation. If the host mutates a bodyless collider's
transform and needs query results before the next step, call
collider.Simulate() after the mutation to refresh bounds and partition
membership immediately. The bodyless 3D LSCollider.Position and Rotation
setters are the transactional alternative: they validate the tentative world
pose and publish the host transform, canonical geometry, mass properties, and
partitions only after the whole candidate succeeds.
Reconfiguring A Registered Body
Use SolidBody.TryReconfigureCollider(...) when a registered 3D agent changes
physical profile without changing runtime identity: for example, standing to
crouching, then returning to standing. The current focused surface supports
sphere, capsule, and finite-cylinder bodies. A definition must stay in the
collider's existing shape family; it cannot turn a capsule into a sphere or
replace compound, cuboid, cone, or mesh geometry.
Call it between fixed steps with the complete desired geometry, local offset, and authoritative body-root position:
using FixedMathSharp;
using Gravitas;
using Gravitas.Colliders;
ColliderReconfigurationStatus result = body.TryReconfigureCollider(
ColliderShapeDefinition.Capsule(
radius: Fixed64.Half,
height: Fixed64.One),
localOffset: Vector3d.Up * Fixed64.Half,
position: body.Position3d,
out LSCollider? blocker,
out System.Exception? notificationException,
publishSynchronizedState: null);
Applied means the geometry and pose were published together. Unchanged means
the requested authored and committed state already matched. Blocked returns
the first physically eligible collider, in stable registration order, that the
candidate would positively penetrate. Exact touching at a support or floor
contact is accepted, and trigger volumes do not block reconfiguration.
The definition contributes geometry only. The existing collider keeps its material, filters, hierarchy, event subscriptions, rotation, service identity, and body motion state. An accepted change refreshes mass properties, pure and mixed broad-phase membership, and query visibility; it invalidates existing contact pairs, warm starts, CCD trajectories, and joint solver caches. A blocked or invalid attempt leaves the authored and committed shape, body and host pose, partitions, pairs, serialized payload, and replay hash unchanged. Default, unsupported, wrong-family, unrepresentable, and unsafe-lifecycle requests throw rather than partially publishing state.
The native counterpart is SolidBody2D.TryReconfigureCollider(...), with
ColliderShapeDefinition2D, planar Vector2d offset/root position, and an
LSCollider2D blocker. It supports circle-to-circle and capsule-to-capsule
replacement in pure TwoD mode. A capsule with height 2 * radius is a compact
posture of the same collider, not a replacement identity. Host world Y and the
accepted rotation are retained. Other runtime modes reject rather than omit
potential cross-dimensional blockers.
What Counts As A Blocker
Both 2D and 3D admission distinguish exact touching from positive penetration before contact-depth rounding. Even a penetration smaller than one raw fixed-point unit rejects the transaction; a rounded solver depth of zero is not evidence that a replacement fits. Classification uses committed geometry and authoritative rigid frames for direct colliders and each compound part, without generating contact manifolds. In 3D, a closed convex mesh also blocks enclosure; open and concave meshes test their authored surfaces, not an invented filled interior.
Both transactions test the whole replacement shape against physically eligible registered colliders, including blockers outside physics grids. This rare explicit operation can scan the registry and allocate. Semantic validation is completed before publication; this is not a promise to recover from process-level allocation failure. Hosts must prepare their own fallible navigation/controller state before calling, then publish that prepared state through the callback.
Publish Host State Before Callbacks
Pair-separation callbacks from an accepted reconfiguration run after the new
geometry, root pose, mass properties, and partitions are coherent. A
coordinating adapter can supply publishSynchronizedState; Gravitas invokes it
after physical publication (or confirmation of Unchanged) and before any
separation callback, and does not invoke it for Blocked. The publisher must
leave dependent state committed even if a host notification throws because the
physical transaction cannot roll back at that point.
Pair retirement continues in stable order if the publisher or a separation
callback throws. Gravitas returns one failure directly through
notificationException, or several as an AggregateException. That value
reports a post-commit notification failure; it does not change result from
Applied or Unchanged, and the host must not retry the accepted
reconfiguration. A coordinating adapter should rethrow the returned exception
with its original stack only after the call completes.
If a callback deactivates and reinitializes a body, retirement from the old transaction cannot clear pairs belonging to the replacement registration.
Scale And Coordinate Conversion
Authored FixedTransform.LocalScale may be signed or zero, but physical
collider dimensions may not. Gravitas requires every consumed authored local
axis throughout the transform ancestry to remain positive: X/Z for 2D colliders
and X/Y/Z for 3D colliders. Gravitas then composes the hierarchy's strict
local-to-world matrices and admits only a representable, nonsingular TRS
decomposition. This rejects canceled reflections and genuine hierarchy shear
instead of approximating either as a rotation plus diagonal scale. Pure 2D also
requires the composed X/Z basis to remain in the simulation plane.
Initialization and runtime rebuild reject invalid scale before changing body
registration, host pose, canonical geometry, mass properties, or partition
state.
The host's authored local transforms remain untouched so an adapter or authoring tool can correct them explicitly.
Owner scale and compound-part scale stay separate through shape preparation. Each final radius, axis length, half-extent, offset, mesh coordinate, or mass property is formed with an exact fused operation and rejected only when that final canonical value is not representable or physically valid. Intermediate Q32.32 saturation is never accepted as a plausible runtime dimension.
Use FixedTransform.TransformPoint(...), InverseTransformPoint(...), and
their explicit X/Z counterparts when converting through the current authored or
presentation snapshot.
Use SolidBody.GetWorldPoint(...) / GetLocalPoint(...), or the matching
SolidBody2D methods, for gameplay conversion through the authoritative physics
pose. These body methods use the collider's last committed owner-scale snapshot,
not a newly read host scale, so render interpolation or a pending adapter
mutation cannot change simulation queries. Their Try* counterparts return
false with a zero output before the first shape commit or when the final
coordinate is outside the Q32.32 domain.
Engine adapters should treat Gravitas as the sole simulation authority. Publish the visual pose to the engine transform, and disable native rigid-body simulation or interpolation that would apply a second motion source or double-interpolate the Gravitas result.
Representable Body Positions
Gravitas rejects an unrepresentable authoritative position with
OverflowException during integration, contact correction, or CCD trajectory
publication. Frozen axes are projected before validation. A position exactly at
Fixed64.MinValue or Fixed64.MaxValue is valid; movement beyond it is not
silently shortened.
Contact corrections prepare both participants' endpoints before moving either. CCD response also checks the outgoing trajectories before publishing body state or reserving candidate refresh. These checks protect the individual operation; a simulation step is not a rollback transaction. Earlier bodies, solver rows, clock advances, and force integration may already have run when an exception escapes. Stop the failed step and restore a known state before continuing.
The scalar coordinate limits do not define playable-world boundaries or grid walls. Hosts remain responsible for their own world limits and explicit coordinate-frame changes. Valid ordinary integration keeps multiply-then-add rounding.
Common Configuration
Surface Materials
PhysicsMaterial is deterministic collider surface data. Assign it before
simulation when a surface needs explicit static friction, dynamic friction,
restitution, or combine policies:
collider.Material = PhysicsMaterial.Frictionless;
Shape definitions and compound parts can also carry materials:
var compound = new LSCompoundCollider(
CompoundColliderPart.Sphere(
Fixed64.Half,
-Vector3d.Right,
PhysicsMaterial.Bouncy),
CompoundColliderPart.Cuboid(
Vector3d.One,
Vector3d.Right,
PhysicsMaterial.Default));
Compound parts without an explicit material use the owning compound collider's material when private part colliders are materialized.
Local Physical Filtering
IgnoredCollisionLayers is a collider-owned physical filter:
projectileCollider.Layer = new PhysicsLayer(3);
ownerCollider.IgnoredCollisionLayers =
PhysicsLayerMask.FromLayer(projectileCollider.Layer);
The rule is symmetric at pair time: if either collider ignores the other
collider's layer, the physical interaction is rejected. This affects discrete
collision pairs, trigger pairs, internal CCD target eligibility, and
grounding/support acceptance. Public query services use the caller's
PhysicsLayerMask instead.
Settings And Environment
Each context owns its own PhysicsSettings and PhysicsEnvironment.
ApplySettings binds a mutable settings instance to one context; attaching it
to another context throws until the first replaces it or is disposed. Create a
separate settings instance for each simultaneous context.
Apply settings and change RuntimeMode or Mixed2DHalfThickness between fixed
steps. Those changes preflight every registered 2D collider's complete mixed
envelope before assignment, respecting collider thickness overrides. A rejected
change preserves the settings, clock and committed collider state. This scan
belongs to explicit configuration changes and adds no unchanged-frame work. Pure
2D modes do not impose a mixed-size budget on unused thickness.
context.SetFrameRate(60);
PhysicsSettings settings = PhysicsSettings.DefaultSettings();
settings.PoolingEnabled = true;
settings.RestitutionVelocityThreshold = Fixed64.FromFraction(1, 4);
context.ApplySettings(settings);
context.Environment.Gravity = Fixed64.FromFraction(49, 5);
Different contexts can run at different frame rates and settings in the same
process. Timing values such as DeltaTime, FrameCount, and ElapsedTime are
read through the context. Frame rates must stay between 1 and
PhysicsSettings.MaxResolvableFrameRate; ordinary lockstep rates are far below
that ceiling.
FrameCount is a long; ElapsedTime is a Chronicler ChronicleTimestamp.
Keep integration math in Fixed64 using DeltaTime. For a measured interval,
subtract two timestamps from the same context lifetime before converting the
duration to Fixed64. See Clock State
for waits, step changes, and reset behavior.
Per-body gravity tuning lives on the body. SolidBody.GravityScale multiplies
context gravity for that body; Fixed64.Zero disables environment-gravity
acceleration and grounded weight. SolidBody2D.GravityScale applies the same
policy to that body's planar gravity vector.
Constraints And Ragdolls
context.Constraints3D owns deterministic 3D joints and ragdoll runtimes.
context.Constraints2D owns deterministic 2D joints and ragdoll runtimes.
| Domain | Runtime types | Joint shape | Solved with |
|---|---|---|---|
| 3D | Joint3D, RagdollRuntime3D |
Local frames, angular axes, 3D motors/limits | 3D contact islands in LateSimulate() |
| 2D | Joint2D, RagdollRuntime2D |
Planar anchors, scalar angles, scalar motors/limits | 2D contact islands in LateSimulate() |
3D example:
using Gravitas.Constraints;
Joint3D shoulder = context.Constraints3D.RegisterJoint(new JointDefinition3D(
upperArmBody,
torsoBody,
upperArmLocalFrame,
torsoLocalFrame,
JointType3D.ConeTwist,
JointLimit3D.ConeTwist(maxConeAngle, maxTwistAngle),
JointMotor3D.Disabled,
JointCollisionPolicy.SuppressLinked));
2D example:
using Gravitas.Constraints;
Joint2D hinge = context.Constraints2D.RegisterJoint(new JointDefinition2D(
forearmBody2D,
upperArmBody2D,
new JointFrame2D(Vector2d.Right * Fixed64.Half, Fixed64.Zero),
new JointFrame2D(-Vector2d.Right * Fixed64.Half, Fixed64.Zero),
JointType2D.Pin,
JointLimit2D.Angular(-Fixed64.HalfPi, Fixed64.HalfPi),
JointMotor2D.Disabled,
JointCollisionPolicy.SuppressLinked));
Enabled joints use PhysicsSettings.DiscreteSolverIterations. Linked sleep/wake
behavior follows the island graph. Linked-collider collision suppression affects
physical collision/CCD pair creation, not public query include-mask semantics.
Ragdolls are authoring conveniences over the same joint model:
RagdollRuntime3D ragdoll = context.Constraints3D.RegisterRagdoll(
new RagdollDefinition3D(
links,
joints,
RagdollSelfCollisionPolicy.SuppressAdjacentLinks));
ragdoll.ActivateDynamic();
ragdoll.DeactivateToKinematic();
Animation, IK, pose selection, engine animator hooks, and blending remain host or animation-package responsibilities. A deterministic animation package can compute motor payloads and pass them before the fixed step.
Fixed Loop
A simple deterministic loop looks like this:
while (running)
{
ApplyOrderedCommandsForFrame();
context.Simulate();
context.LateSimulate();
context.Visualize();
context.LateVisualize();
}
Most real hosts call Simulate and LateSimulate from a fixed-rate scheduler
and call visualization phases from the render/update loop.
The high-level order is:
context.Simulate()advances the clock, runs simulate-phase services, advances lockstep coroutines, and invokes simulate hooks.context.LateSimulate()integrates bodies, processes CCD, refreshes partitions, distributes pairs, solves contacts and joints, refreshes grounding/support, handles mixed contacts when enabled, and invokes late-simulate hooks.context.Visualize()updates visual/presentation transforms for enabled services and invokes visualize hooks.context.LateVisualize()invokes hooks only.
For the 3D path, the fixed-step order is integrate-then-collide inside
LateSimulate: queued forces affect motion before the discrete collision pass
for that same frame.
For kinematic CCD, hosts must write deterministic target transforms before
context.LateSimulate(). Gravitas captures the body pose at the start of the
late step, reads the host transform as the requested target, and sweeps between
those two poses when continuous collision is enabled. The first static-style
blocker clips the kinematic pose and writes the clipped transform back to the
host binding.
In 2D, SolidBody2D.Rotation is the accepted scalar yaw. If the host
orientation still represents that yaw, idle and translation-only steps
preserve the scalar exactly. Gravitas projects a changed host orientation
onto X/Z to obtain a new rotation target.
For scenario budgets, partition comparisons, and long-session measurements, see Workload And Tuning.
Queries And Grounding
2D, 3D, and mixed queries are explicit context services:
using Gravitas.Queries;
using Gravitas.Support;
using SwiftCollections;
PhysicsLayerMask layerMask = PhysicsLayerMask.FromLayer(0);
bool rayHitFound = context.Query3D.Raycast(
origin,
direction,
maxDistance,
out Physics3DHit rayHit,
layerMask);
SwiftList<Physics2DHit> planarHits = new();
int planarHitCount = context.Query2D.RaycastAll(
start2D,
end2D,
layerMask,
planarHits);
SwiftList<PhysicsMixedHit> mixedHits = new();
int mixedHitCount = context.QueryMixed.SweepSphereAgainst2DAll(
origin,
origin + direction * maxDistance,
radius,
layerMask,
mixedHits,
excludedCollider: null);
All-hit APIs use caller-owned buffers. Batch APIs use typed request spans,
caller-owned output spans or shared hit lists, and PhysicsQueryHitRange
buffers.
Choose A Grounding Policy
Ground checks use context.Settings.GroundCheckLayerMask; hosts should set this
explicitly for their layer model. SolidBody.GroundingMode and
SolidBody2D.GroundingMode can stay automatic or switch to manual host-owned
support through UseManualGrounding(...), SetManualGrounding(...),
ClearManualGrounding(), and UseAutomaticGrounding(...). Automatic 3D support
requires an upward normal; SolidBody.GroundMinNormalDot sets the minimum
normalized dot product with world up, defaulting to one half (slopes through 60
degrees). Horizontal and downward-facing candidate normals cannot ground a body.
See the grounding contracts for probe
selection and 2D support policy. SolidBody2D.GroundMinNormalDot applies the
same limit range against planar resolved up for both probes and contact support.
Actual changes to its limit or effective up direction invalidate automatic
support and wake the body; manual grounding remains host-owned.
Keep Sleeping Support Current
An established solid contact is also a sleep dependency. Removing that contact, or changing the counterpart's committed shape, explicit pose, or material, wakes its sleeping participant. Automatic grounding is invalidated before the next motion step; manual grounding remains the host's responsibility. Trigger exits, equal assignments, and ordinary solver corrections do not invalidate an unchanged solid contact. Mixed contacts wake a 2D participant only when the old or replacement constraint couples to its planar motion.
Automatic probes can also supply support without a physical contact. Their cached collider lifetime, committed geometry and current filtering are checked before sleeping motion is skipped. Changed dependencies or probe mode, radius, origin or reach trigger a fresh query. An identical ground point and normal preserve sleep; a changed or lost result wakes the body. Loading reconstructs this derived cache using the same rule. Triggers are excluded from automatic support in both dimensions; ordinary public queries retain their explicit trigger policy.
Read Query Services for the full query surface.
Replay Contract
For deterministic runs, apply ordered commands before context.Simulate().
Given the same initial context, settings, world state, command order, and frame
count, Gravitas should replay to the same authoritative body, collider, clock,
and contact state.
using Chronicler.Hashing;
context.Simulate();
context.LateSimulate();
ChronicleHash hash = context.ComputeReplayHash();
SendFrameHashToLockstepPeer(context.FrameCount, hash);
ComputeReplayHash() hashes context settings, physical environment values,
clock state, body state, collider shape/filter state, retained
continuation-affecting pair/contact state, and active CCD handoff state. It does
not hash host object identity, delegates, diagnostics buffers, debug draw
commands, query scratch buffers, or visualization interpolation caches.
The returned ChronicleHash is a deterministic conformance signal, not a
cryptographic hash and not a compatibility promise across package versions.
Deactivation And Disposal
Deactivate runtime objects before pooling or destroying their host wrappers:
body.Deactivate();
floor.Deactivate();
SolidBody.Deactivate() deactivates the collider, removes the body from the
physics service, and clears the dynamic ID. LSCollider.Deactivate() clears
partition membership, removes collision-pair references, clears explicit parent
binding, returns active pairs to the pool when enabled, and releases the
collider ID.
Use context.Reset() for a reusable session context. Reset detaches Gravitas
partition payloads from GridForge voxels and clears context-local runtime state
while preserving the world and its grids. Registration and simulation buffers
release references from the ended session, including stale scratch slots beyond
their current counts, while retaining reusable capacity. Caller-owned results
and host references retain their own lifetimes. Use context.Dispose() when the
context is finished.
Rules That Matter
- Do not mutate authoritative physics state from visualization phases.
- Do not read wall-clock time from runtime simulation logic.
- Keep command ordering deterministic before
Simulate(). - Add grid coverage before initializing colliders.
- Keep public query buffers caller-owned in hot paths.
- Use explicit runtime modes:
ThreeD,TwoD,Both, orMixed. - Use
Mixedonly when cross-dimensional contacts are intended. - Treat Chronicler as populate-existing-shell infrastructure, not an object factory.
Source Map
- Context and lifecycle
- Host agent
- 3D body and service
- 2D body and service
- Settings
- Constraints
- Query implementations
- Replay hash service