2D, 3D, And Runtime Modes
Choose body types for the motion you want, then set
PhysicsSettings.RuntimeMode for the interaction you want. Use SolidBody
and an LSCollider for 3D, or SolidBody2D and an LSCollider2D for
planar X/Z motion. Those concrete types define the body's domain throughout
its lifetime.
Quick Read
Put a planar circle and a 3D sphere at the same host position (2, 5, 3).
With Both, the two simulations run side by side and the shapes create no
mixed pair. With Mixed, the circle gets a finite vertical extent for 3D contact
tests. A sphere that overlaps this slab can contact it when the pair passes
collision filters. The circle still moves only in X/Z.
flowchart TB
accTitle: Runtime mode for a planar circle and a 3D sphere
accDescr: Both runs separate 2D and 3D simulation without cross-dimensional contacts. Mixed lets an eligible 3D sphere contact the finite slab of a planar circle.
Shapes["2D circle and 3D sphere"]
Shapes -->|"Both"| Isolated["Separate<br/>simulation paths"]
Shapes -->|"Mixed"| Contact["Mixed contact<br/>is possible"]
If your scene uses only one dimension, choose TwoD for planar motion or
ThreeD for full spatial motion. See the runtime mode table,
2D coordinates, and mixed embedding.
Runtime Mode
PhysicsSettings.RuntimeMode selects which dimensional services a
GravitasWorldContext advances:
| Mode | Services advanced | Cross-dimensional contacts |
|---|---|---|
ThreeD |
3D physics, 3D collision, 3D queries/visualization | No |
TwoD |
2D physics, 2D collision, 2D queries/visualization | No |
Both |
2D and 3D services side by side | No |
Mixed |
2D, 3D, plus mixed collision/query/CCD lifecycle | Yes |
The context clock, coroutines, diagnostics, replay hash service, and lifecycle
hooks remain shared. Runtime modes are validated exactly; None and arbitrary
bit combinations are rejected as settings values.
Supported Geometry
Collider preparation uses an inclusive maximum effective reach of 4,096 world
units, exposed by ColliderSettings.MaximumGeometryReach and
ColliderSettings2D.MaximumGeometryReach. It measures the prepared local
geometry after owner and compound-part scale, independently of world position.
For a body-owned collider, its attachment to the body origin counts toward the
budget. A compound also counts each part's attachment plus that part's reach;
opposing attachment offsets do not cancel this conservative budget. Mixed
colliders include physical half-thickness after the complete planar reach.
Oversized candidates fail before committed geometry is replaced. Compound
centered proxies separately enclose the published child centers, preserving
final child-center rounding in that physical enclosure.
Large authored dimensions can be scaled down before initialization. A
collider-owned mesh prepares runtime geometry when its effective scale is known;
requesting its detached runtime mesh first requires admissible geometry at that
detached scale. Change collider-owned mesh poses and scales through the
collider, body or host transform. Calling PhysicsMesh.UpdatePosition or
UpdateTransform on a collider-owned mesh throws; independently constructed
PhysicsMesh instances retain these transformation APIs and validate their own
reach.
The ceiling uses world units chosen by the host. It limits each runtime collider's conservative reach, rather than total world extent, ray length or swept travel. Position still has to satisfy each API's representability rules. It does not guarantee representable mass, inertia, speed or arbitrarily small features. Grid cell size and the number of covered cells remain independent memory and performance choices.
Calculate Effective Reach
Let C(v) mean the smallest Q32.32 value enclosing the exact length of v. The
following measures use prepared effective dimensions and vertices after scale,
retaining the existing final rounding:
| Shape | Intrinsic reach |
|---|---|
| Sphere or circle | Radius. |
| Capsule or stadium | Radius plus half the core length, rounding an odd raw half-length outward. |
| Cuboid or AABB | C(halfExtents). |
| Cone or cylinder | C([radius, outwardHalfHeight, radius]), a conservative box diagonal. |
| Mesh | Maximum C(vertex) in its recentered local frame. |
| Polygon collider | Maximum C(vertex) about its local collider origin. |
| Compound | Maximum of each part's outward attachment length plus its intrinsic reach. |
Add the body-owned root's outward attachment length once to obtain complete
reach P; a bodyless root adds zero. Attachment lengths retain exact scaled
products until outward measurement. Opposed root/part offsets do not cancel:
offsets +3,000 and -3,000 with radius 1 consume 6,001, so normalize the
authored frames to admit that physically compact arrangement. For mixed 2D
slabs, require C([P, physicalHalfThickness]) <= 4,096. Half-thickness is
unscaled physical Y thickness; host Y position does not consume reach.
Unsupported effective geometry throws a descriptive argument/validation error before runtime publication; it is neither clamped nor reported as a collision miss. Failed live candidates preserve committed geometry and derived runtime state. Host-authored transforms and partially applied records have their own ownership boundaries; see restored-state semantics. Context query services use the corresponding numeric-source rules, including the exact vertex mean for public world-polygon queries. Trusted internal CCD padding and lower-level geometry workers retain their separate contracts.
Terrain And Unit Migration
Split terrain into spatial chunks whose individually prepared reach fits the budget. Recenter each chunk and retain its world placement. Adding huge offsets to a single body-owned compound still consumes attachment reach; it does not create a large-world bypass. A uniformly coarser host length unit is another option, but convert all length-dependent inputs and physical units consistently. Changing only collider scale changes the simulated scene.
Separate chunks retain their collider IDs, partition memberships, collision
pairs, contact events, and query hits. Use a
continuous static surface to
declare intended joins across 3D triangle-surface mesh pieces (Concave mode)
or 2D AABB/convex polygon pieces. Bodyless and explicit-static members are both
supported. Undeclared pieces retain independent finite boundaries; declared
membership removes only
geometrically certified internal spans.
Chunking still has preparation and runtime costs; validate the intended shapes,
grounding, friction, and CCD settings.
In mixed mode, 2D movers can contact joined 3D sheets and 3D movers can contact
joined embedded 2D solids. Planar adjacency alone does not erase differences in
host Y or slab thickness: only shared finite spans join, while real vertical
steps and exposed caps remain physical boundaries. Both still has no
cross-dimensional contacts. These APIs use existing collider geometry; Gravitas
has no specialized heightfield backend.
Public Surface
| Domain | Bodies | Colliders | Constraints | Queries |
|---|---|---|---|---|
| 3D | SolidBody |
built-in LSCollider implementations |
Joint3D, RagdollRuntime3D |
context.Query3D |
| 2D | SolidBody2D |
built-in LSCollider2D implementations |
Joint2D, RagdollRuntime2D |
context.Query2D |
| Mixed 2D/3D | Existing 3D and 2D bodies | 3D colliders plus embedded 2D slabs | Mixed contacts, not mixed joints | context.QueryMixed |
Supported 3D collider types:
| Collider | Shape family |
|---|---|
LSSphereCollider |
Sphere |
LSCapsuleCollider |
Capsule |
LSCuboidCollider |
Cuboid |
LSCylinderCollider |
Finite cylinder |
LSConeCollider |
Finite cone |
LSMeshCollider |
Mesh target and convex mesh sweep source |
LSCompoundCollider |
Stable authored 3D parts under one public collider ID |
Supported 2D collider types:
| Collider | Shape family |
|---|---|
LSCircleCollider2D |
Circle |
LSCapsuleCollider2D |
Capsule |
LSAABBoxCollider2D |
Axis-aligned box |
LSPolygonCollider2D |
Convex polygon and triangle helper output |
LSCompoundCollider2D |
Stable authored 2D parts under one public collider ID |
Supported mixed narrow phase covers 3D sphere, cuboid, capsule, finite cylinder, finite cone, compound, and mesh colliders against embedded 2D circle, capsule, AABB, convex polygon, and compound slabs.
3D Bodies And Colliders
SolidBody is constructed from an IMatterAgent and an LSCollider. The agent
supplies the context and host transform bridge. Dynamic 3D bodies publish
authoritative Vector3d position and FixedQuaternion rotation back to the
host FixedTransform during Visualize() whenever the runtime mode runs the 3D
service (ThreeD, Both, or Mixed). Kinematic 3D bodies read the agent
transform during LateSimulate().
3D body mobility is explicit:
| Concern | API |
|---|---|
| Runtime role | MotionType, SetMotionType(...) |
| Freeze translation/rotation | SolidBody.FreezeAxes, BodyFreezeAxes3D |
| Solver linear mobility | CanTranslate, EffectiveInverseMass |
| Solver angular mobility | CanRotate, EffectiveInverseInertiaTensor |
| Body-local COM | LocalCenterOfMassOffset |
| World COM | WorldCenterOfMass |
| Immediate linear impulse | AddLinearImpulse(...) |
| Queued linear force | AddForce(...) |
| Immediate angular impulse | AddAngularImpulse(...) |
| Queued angular torque | AddTorque(...) |
Linear impulse uses mass-distance-per-time units and changes velocity
immediately by impulse * EffectiveInverseMass. Angular impulse uses
mass-distance-squared-per-time units and changes angular velocity immediately
through EffectiveInverseInertiaTensor. Neither impulse API applies DeltaTime
or advances pose. AddForce(...) and AddTorque(...) instead queue continuous
inputs whose acceleration is integrated during the next fixed step.
3D Friction And Support
Grounded 3D bodies also apply a material-driven friction term after queued driving forces and torques. Linear friction opposes motion tangent to the support within the body's permitted axes; it preserves separating normal motion. Angular friction retains the constrained inertia-tensor response. Each friction impulse is bounded at its kinetic-energy minimum, so increasing the time step or reducing inertia cannot make friction drive motion through rest and add energy. A constrained anisotropic body can retain residual spin.
This body-level angular term uses the existing unit-world-length effective lever
arm for its torque budget; it is an empirical grounding model, separate from
contact-point Coulomb friction. An oversized intermediate correction is retained
until the completed velocity is materialized. A genuinely unrepresentable
completed velocity throws OverflowException.
3D contact response uses full 3D COM-relative contact arms, Fixed3x3 inverse
inertia tensors, collider surface materials, normal impulses, tangent friction,
deterministic warm-start caches, grounding state, and sleep/wake rules. Shape
mutation wakes sleeping bound bodies before broad-phase refresh, matching the 2D
mutation contract.
Automatic 3D grounding casts downward with the selected ray or swept-sphere
probe and selects the nearest physically eligible static or kinematic support,
with collider ID breaking equal-distance ties. Both colliders' ignored layers
apply, and the source collider cannot support itself. Triggers do not provide
automatic support in either dimension. SolidBody.GroundMinNormalDot compares
the normalized candidate normal with world up. Its default of one half accepts
slopes through 60 degrees; values in [0, 1] configure the slope limit, with an
inclusive boundary. Zero permits any upward-facing normal. Horizontal,
downward-facing and zero normals never supply automatic 3D support, even for
probes starting inside or tangent to geometry.
Manual grounding retains the host's supplied normal. Automatic 2D grounding applies its planar support-normal policy against its resolved up direction.
Automatic 3D height snapping places the body origin at the support height.
Author a feet-origin body with its collider above that origin, such as a sphere
with LocalOffset = Vector3d.Up * Radius. A collider centered on the snapped
origin penetrates the support and still receives discrete collision correction.
Use manual grounding when the host owns a different pose/support convention.
Changing the 3D threshold invalidates the automatic probe cache and wakes the body so its next simulation step uses the new limit. Equal assignments are no-ops; manual grounding remains host-owned. Recorded loads restore the limit without waking the body or discarding its saved probe timing. Older records that omit the setting use one half.
The existing 3D query worker collects and sorts raw hits into a retained
per-body buffer before grounding checks body eligibility. Compound colliders
reduce their parts to one owner witness before that eligibility check. All raw
intersections contribute to the RayQuery hit count and nearest raw witness
independently of the accepted GroundProbe witness, so an ignored or dynamic
nearest hit remains visible in query diagnostics. Traversal and mesh counters
retain the complete query work. RayQuery precedes GroundProbe, and ground
state is stored before the OnGrounded callback runs. Ray segment length must
be positive; swept-sphere segment length must exceed Epsilon. A resolved
sphere radius at or below Epsilon uses a ray while ground-probe diagnostics
retain the resolved mode and radius.
2D Coordinate Contract
For the circle from the example, a host position of (2, 5, 3) gives a
planar position of (2, 3). X and Z are the motion axes. The value 5
is the height the host retains and mixed collision uses for the slab center.
| 2D value | World/host value |
|---|---|
Vector2d.x |
Vector3d.x |
Vector2d.y |
Vector3d.z |
| Positive scalar rotation | Rotates planar right toward planar forward; embeds as negative world-Y yaw |
World Vector3d.y |
Height or mixed embedding metadata |
Use FixedTransform.WorldPositionXZ and WorldRotationXZRadians at the host
boundary. Their local counterparts are for authored local components, not
hierarchy-aware physics state. Vector3d.ToVector2d() remains the direct X/Z
vector conversion.
2D body motion has no HeightPos, 3D step offset, or y-up platform state.
Grounding is modeled as planar support in the 2D simulation plane:
SolidBody2D.IsGrounded, WasGrounded, GroundNormal, GroundPoint, and
LastGroundedPosition are X/Z-plane values.
Planar Support
Automatic 2D probes select the nearest physically eligible support by distance,
then collider ID. A nearer rejected normal or ignored collider does not hide
farther support. Each compound first reduces its authored parts to one witness;
automatic grounding then applies the body's support policy to that witness. This
differs from explicit Query2D.QuerySupport, which filters support parts before
reduction. Automatic ray probes accept positive representable travel lengths
below Epsilon; swept-circle probes require travel longer than Epsilon.
Contained-start ray probes use the target's geometric outward normal, so a point
on or inside a flat wall cannot gain support from a diagonal center-based
fallback. Their zero-distance point remains the probe start. See
hit witnesses for ambiguous-feature and
compound reduction rules.
SolidBody2D.GroundMinNormalDot uses the same [0, 1] range and one-half
(default 60-degree) slope limit as 3D, measured against resolved planar up. Both
query probes and collision-contact support require a strictly positive
normalized up-dot, including when the configured limit is zero. Invalid limits
reject without changing state. Gravity supplies up when
UseGravityDerivedGroundUpDirection is enabled and gravity is nonzero;
GroundUpDirection supplies the normalized fallback.
Changing the slope limit or effective up direction invalidates automatic probe and pending contact support and wakes the body. Equal assignments, changes to an unused fallback, and gravity magnitude changes that preserve up do not wake it. Motion projection and callback completion also check current eligibility, so obsolete support cannot suppress motion or survive a callback policy change. Manual grounding retains host-owned support and projection. Populate restores validated policy without waking saved bodies; transient 2D support ownership and probe timing are rebuilt through the existing load contract. Older sparse records that omit the limit retain the default of one half.
Host Transform Publication
Dynamic 2D bodies publish their authoritative planar position and yaw rotation
back to the host FixedTransform during Visualize() whenever the runtime mode
runs the 2D service (TwoD, Both, or Mixed). The host transform's
world-space Y value is preserved because it is not part of 2D physics. Gravitas
stores authoritative scalar yaw in the canonical half-open range [-Pi, Pi);
+Pi and equivalent multi-turn inputs therefore use the single -Pi
representative.
2D Bodies And Colliders
SolidBody2D is constructed from an IMatterAgent and an LSCollider2D,
matching the host-facing shape of the 3D body API. The agent supplies the
context and host transform bridge. Kinematic 2D bodies read the agent transform
during LateSimulate() and project its X/Z position into authoritative
Vector2d state.
2D body mobility is explicit:
| Concern | API |
|---|---|
| Runtime role | MotionType, SetMotionType(...) |
| Freeze planar translation/yaw | SolidBody2D.FreezeAxes |
| Solver linear mobility | CanTranslate, EffectiveInverseMass |
| Solver yaw mobility | CanRotate, EffectiveInverseMomentOfInertia |
| Body-local COM | LocalCenterOfMassOffset |
| World COM | WorldCenterOfMass |
| Immediate planar impulse | AddLinearImpulse(...) |
| Queued planar force | AddForce(...) |
| Immediate yaw impulse | AddAngularImpulse(...) |
| Queued yaw torque | AddTorque(...) |
Pure 2D impulse and continuous-force units match the 3D contract. Planar and yaw
impulses change velocity immediately without applying DeltaTime or advancing
pose; planar force and yaw torque are integrated during the next fixed step.
BodyFreezeAxes2D.PositionX maps to world X. BodyFreezeAxes2D.PositionY maps
to world Z. MotionType uses PhysicsMobilityType to select solver-controlled
Dynamic, host-controlled Kinematic, or immobile Static ownership in both
dimensions. Freeze masks then constrain dynamic degrees of freedom without
changing that role. A fully position-frozen dynamic body has zero effective
linear mass but may retain angular response; a yaw-frozen body may retain linear
response. Static, kinematic, inactive, and non-positive-mass states contribute
zero applicable solver mobility.
2D contact response uses planar COM-relative contact arms, scalar inverse
moment, collider surface materials, normal impulses, tangent Coulomb friction,
and deterministic warm-start caches. ContactManifold2D retains up to two
finite samples per independent surface group, with no pair-wide group limit.
Inspect GroupCount, GetGroupStartIndex and GetGroupContactCount when group
boundaries matter. Ordinary convex/convex face contacts use one group;
circle/circle and circle/convex contacts ordinarily retain one sample.
Pure 2D and mixed 2D bodies obtain friction from physical contact impulses. Manual or query-only grounding does not add the 3D body's empirical friction torque or tangential deceleration term.
LSCollider2D.InitializeWithNoBody(IMatterAgent) binds bodyless static geometry
and bodyless trigger volumes to the same host contract. Bodyless 2D colliders
participate in queries, triggers, layer filtering, cleanup, and static collision
response.
LSPolygonCollider2D validates both authored and scaled runtime vertices and
rejects concave or collinear boundaries. Positive scale can still collapse a
small feature through fixed-point rounding; invalid scaled geometry is rejected
before initialization or refresh publishes shape or partition state. Unchanged
scaled vertices retain their existing validation. A rotated box should use a
convex polygon; LSAABBoxCollider2D remains axis-aligned by design. Triangle
authoring helpers materialize as three-vertex convex polygons.
Shape Definitions And Mass Properties
Shape definitions are data-only authoring/import surfaces. Runtime collider shells own context binding, collider IDs, partition state, pair state, events, and query stamps.
| Domain | Definition types | Runtime materialization | Mass properties |
|---|---|---|---|
| 3D | ColliderShapeDefinition, CompoundColliderPart |
built-in LSCollider implementations and private LSCompoundCollider parts |
local center of mass, shape-derived mass distribution, and Fixed3x3 inertia tensor |
| 2D | ColliderShapeDefinition2D, CompoundColliderPart2D |
built-in LSCollider2D implementations and private LSCompoundCollider2D parts |
local center of mass, area, and scalar moment of inertia |
3D compound assets should serialize CompoundColliderPart values, not private
runtime part colliders. LSCompoundCollider aggregates private parts in stable
part order and uses each part's local offset, local rotation, local scale,
material, center of mass, and inertia contribution under one public 3D collider
identity.
2D compound assets should serialize CompoundColliderPart2D values, not private
runtime part colliders. LSCompoundCollider2D aggregates private parts in
stable part order, assigns area-proportional part mass, applies owner local
offset, and honors authored part scale/rotation before computing center of mass
and scalar moment.
FixedTransform.LocalScale is general authored transform data and may be signed
or zero. Gravitas collider dimensions are a stricter boundary: runtime colliders
require every consumed authored local axis throughout the transform ancestry and
the strictly composed world TRS scale axis to be greater than zero before body
registration, shape, mass, bounds, or partition state is mutated. Pure 2D
consumes X/Z and rejects a composed basis that leaves its simulation plane; 3D
consumes X/Y/Z. Multiple negative scales do not become valid merely because
their signs cancel, and rotated nonuniform hierarchy scale that produces real
shear is rejected instead of being approximated as diagonal scale. Invalid
physics scale is rejected atomically without rewriting the host's authored local
transform.
Compound owner and part scales are retained as separate factors until the final canonical dimension or centered coordinate is formed. Exact fused admission therefore accepts a representable final value even when an ordinary chained multiply would have saturated, while still rejecting an unrepresentable or nonpositive physical result.
Broad Phase
3D and 2D broad phase are both GridForge-backed. Colliders own their dimension-specific bounds and runtime services map those bounds into partition payloads attached to GridForge voxels.
| Domain | Bounds | Partition payload | Coordinate rule |
|---|---|---|---|
| 3D | FixedBoundBox |
PhysicsPartition |
Full X/Y/Z voxel coverage |
| 2D | FixedBoundArea |
PhysicsPartition2D |
X/Z coverage stored on the internal Y=0 GridForge plane |
| Mixed | FixedBoundBox derived from 2D X/Z bounds plus slab Y/thickness |
PhysicsMixedPartition |
Full 3D candidate coverage for cross-dimensional pairs |
Partitions store collider IDs, split static/kinematic/dynamic membership, keep awake dynamic sets where the solver needs them, and distribute candidates in sorted deterministic order.
2D partition storage on Y=0 is a stable voxel identity for broad-phase lookup;
it is not public 3D thickness and does not imply mixed collision. The 2D runtime
does not expose a public bounds/config bridge; bounds ownership stays on
LSCollider2D and runtime services.
Constraints
3D and 2D constraints are native to their domains:
| Domain | Service | Joint types | Runtime notes |
|---|---|---|---|
| 3D | context.Constraints3D |
ball-socket, hinge, cone-twist, fixed | Joint3D uses two local FixedTransform frames, optional angular limits, optional FixedQuaternion motor targets, linked-collider suppression, replay hashing, and joint diagnostics. |
| 2D | context.Constraints2D |
distance, pin/revolute, weld/fixed, prismatic/slider | Joint2D uses planar anchors, scalar yaw limits, scalar/linear motors, linked-collider suppression, replay hashing, and joint diagnostics. |
3D joints solve inside 3D response islands during LateSimulate() and respect
SolidBody.CanTranslate, CanRotate, EffectiveInverseMass, and
EffectiveInverseInertiaTensor.
2D limits and motors use Fixed64 scalar values. Distance limits are world
units, slider limits are signed translation along the joint axis, angular limits
are radians, angular motors target scalar local angle, and linear motors target
slider translation.
Enabled Joint2D rows solve inside the same 2D response islands as contact rows
during LateSimulate(). The island graph wakes linked sleeping bodies when an
awake participant exists, applies cached joint impulses on the first iteration,
and respects SolidBody2D.CanTranslate, CanRotate, EffectiveInverseMass,
and EffectiveInverseMomentOfInertia.
RagdollDefinition3D/RagdollRuntime3D and
RagdollDefinition2D/RagdollRuntime2D are authoring/runtime conveniences over
ordinary bodies and colliders in their own domains. Animation, IK, and pose
blending remain host or animation-library responsibilities.
Mixed 2D Embedding
Place that same circle at host height Y = 5 with a mixed half-thickness
of 0.5. Its slab spans Y = 4.5 through Y = 5.5, while its
planar shape stays centered at (2, 3). The slab's finite height matters
when the circle interacts with a 3D collider.
LSCollider2D carries the data for this embedding.
| Value | Purpose |
|---|---|
MixedHalfThicknessOverride |
Optional per-collider slab half-thickness. |
PhysicsSettings.Mixed2DHalfThickness |
Context default positive half-thickness. |
MixedSlabCenterY |
Cached from the host FixedTransform.WorldPosition.y. |
MixedBounds3D |
FixedBoundBox from 2D X/Z bounds plus the Y slab. |
The mixed 3D bounds do not change 2D collision truth or 2D partition storage. They are the mixed broad-phase and mixed narrow-phase embedding volume only.
Mixed Runtime Model
PhysicsRuntimeMode.Both and PhysicsRuntimeMode.Mixed are intentionally
different:
| Mode | Meaning |
|---|---|
Both |
Run 2D and 3D services side by side without cross-dimensional contacts. |
Mixed |
Run 2D and 3D services plus GravitasMixedCollisionService. |
Mixed contacts embed 2D colliders into 3D as finite X/Z prisms centered on the
host transform's Y position. CollisionPairMixed owns stable mixed pair
identity, wake propagation, resting-pair retention, pooled pair reuse, mixed
contact events, and trigger-only mixed events.
CollisionDetectionMixed.TryBuildManifold(...) fills a caller-owned
ContactManifold: A identifies the 3D collider and B the embedded 2D collider.
Compound parts retain their materials and separate provenance. Finite mesh
surfaces retain physical shape supports clipped to the filled face and genuine
perimeter constraints; authored triangulation seams are not physical features.
Flat support regions remain distinct across holes. Curved supports retain one
point, and support lines retain their actual endpoints. Circular normal response
uses the geometric center's planar lever, preserving zero yaw torque about that
center; friction still uses the surface lever.
Deep finite penetration can overlap a face without reaching those ordinary support or perimeter witnesses. Its fallback requires exact filled-domain admission and a true finite-feature contact that supplies a separating support plane for the whole owner. This clearance can be conservative for concave surfaces; it does not promise their shortest escape. Holes remain absent material.
CollisionDetectionMixed.TryCollide(...) and CollisionPairMixed.Contact
expose the deepest retained representative. Its depth describes that constraint,
not a translation guaranteed to escape a nonconvex owner. Inspect
CollisionPairMixed.Manifold when the complete contact set matters. Response,
awake coupling and CCD use all retained constraints; enter/stay/exit events
remain once per pair.
Mixed Contact Response
CollisionResponseMixed applies the constrained response model:
- planar correction and impulses can move 2D bodies in X/Z.
- planar impulse components can spin 2D bodies around scalar yaw from the planar COM-relative contact arm.
- vertical Y correction and impulse treat the 2D body as having infinite constrained mass.
- material-resolved restitution and friction follow the mixed contact normal policy.
Multipoint mixed pairs use DiscreteSolverIterations. Rows retain independent
impulse accumulation and the incoming motion used for restitution. Equal-normal
rows share the deepest positional correction, while their contact arms remain
independent velocity constraints. Accumulation is per step; mixed pairs do not
apply cross-frame warm starts.
Mixed contact processing runs during LateSimulate() after both dimension-local
services have integrated bodies and refreshed their own collider partitions.
Queries
3D queries live on GravitasWorldContext.Query3D:
context.Query3D.Raycast(origin, direction, maxDistance, out Physics3DHit rayHit, mask);
context.Query3D.SweepSphere(origin, radius, direction, maxDistance, out Physics3DHit sphereHit, mask);
context.Query3D.SweepCapsule(capsuleSource, displacement, mask, out Physics3DHit capsuleHit);
context.Query3D.OverlapCone(origin, direction, length, endRadius, out Physics3DHit coneHit, mask);
All-hit overloads write into caller-owned SwiftList<Physics3DHit> buffers.
Batch overloads accept spans of request structs and caller-owned hit spans. 3D
queries gather GridForge-backed partition candidates, suppress duplicates, apply
layer masks, run exact 3D shape or mesh checks, and sort by deterministic hit
ordering.
2D queries live on GravitasWorldContext.Query2D. Its explicit QuerySupport
operation selects physically eligible static/kinematic support before reducing
compound hits; see Physical 2D Support.
Ordinary geometry queries remain independent of physical pair filtering:
context.Query2D.OverlapCircle(center, radius, out Physics2DHit circleHit);
context.Query2D.OverlapAabb(center, size, out Physics2DHit areaHit);
context.Query2D.OverlapPolygon(vertices, out Physics2DHit polygonHit);
context.Query2D.Raycast(start, end, out Physics2DHit hit);
context.Query2D.SweepCircle(start, end, radius, out Physics2DHit hit);
All-hit overloads write into caller-owned SwiftList<Physics2DHit> buffers.
They gather GridForge-backed partition candidates, suppress duplicates, apply
layer masks, run exact 2D shape checks, and sort by deterministic hit ordering.
Explicit mixed queries live on GravitasWorldContext.QueryMixed:
context.QueryMixed.SweepSphereAgainst2D(
start3D,
end3D,
radius,
mask,
out PhysicsMixedHit hit);
context.QueryMixed.SweepCircleAgainst3D(
start2D,
end2D,
radius,
slabY,
halfThickness,
mask,
out PhysicsMixedHit hit);
Query2D and Query3D stay dimension-local. Mixed CCD uses QueryMixed only
when PhysicsRuntimeMode.Mixed is active, so Both remains isolated.
Read Query Services for the full query API surface and reducer policies.
Rules That Matter
- Do not model 2D as hidden 3D with one axis ignored.
- Do not compare plain collider IDs across 2D and 3D services; use dimension-tagged keys.
- Keep mixed behavior behind
PhysicsRuntimeMode.Mixed. - Keep 2D X/Z conversion explicit.
- Unsupported mixed shape pairs must be explicit, tested, and documented.
- Mixed diagnostics should preserve dimension tags so host tools can route 2D and 3D payloads without guessing.
Source Map
- Runtime modes
- 3D service
- 3D body
- 3D colliders
- 3D constraints
- 2D service
- 2D body
- 2D colliders
- 2D constraints
- Mixed collision service
- Mixed detection/response
- Mixed queries