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