Collider Shape Reference

Use this guide to choose collider geometry and check which shape pairs the runtime can evaluate. Start with the 3D or 2D pair matrix when you already know your shapes. See the collision pipeline for where shape tests run.

Quick Read

A crouched character uses a 1-unit-tall capsule on a floor at y = 0. To stand up, the host passes a 2-unit-tall capsule definition and a root position of y = 1 to SolidBody.TryReconfigureCollider(...). The candidate keeps its lower end on the floor. Touching the floor is allowed. Penetrating a low ceiling blocks the resize and preserves the crouched shape and position.

flowchart TB
    accTitle: Standing up with a capsule collider
    accDescr: The same registered capsule accepts taller geometry and its requested position when clear. A low ceiling blocks the change and the crouched state stays committed.
    Request["Request a taller capsule"]
    Request -->|"Room to stand"| Apply["Publish new shape<br/>and pose"]
    Request -->|"Ceiling penetration"| Block["Keep crouched shape<br/>and pose"]

The shape definition describes the geometry to try. The runtime collider owns the registered identity and commits geometry after validation. For several shapes that should move and report events as one collider, see hierarchy versus compound.

Runtime Shape State

LSCollider and LSCollider2D separate host-facing collider identity from dense mutable state used by shape rebuilds, partition ownership, query duplicate suppression, pair cleanup, and hierarchy filtering.

The 3D runtime-shape snapshot watches:

  • world-space center.
  • rotation.
  • the standalone owner scale and compound-part scale as separate factors.
  • local offset.
  • unscaled local size.
  • unscaled local radius.

Mutating LocalOffset, Radius, or Size marks the runtime shape dirty. Changing host/body scale, position, or rotation is detected from the snapshot on the next Simulate() call. If the snapshot has not changed, the collider skips the rebuild and keeps existing partition state. Shape mutation wakes a sleeping bound body before broad-phase refresh.

Every changed 3D snapshot is prepared and validated before its canonical geometry, bounds, mesh transforms, compound parts, runtime version, mass properties, or partition ownership are published. A failed live scale, rotation, or geometry candidate therefore leaves the last committed runtime shape intact; correcting the input allows the next simulation pass to rebuild normally. Compound preparation walks every part in authored order and publishes none of them until every candidate succeeds.

2D colliders use the same helper pattern where the payload is dimension-free. Runtime-shape dirtying uses a 2D snapshot payload; query stamps, pair state, and hierarchy state are shared concepts. Partition coordinates stay 2D-specific because they store X/Z planar coverage.

Hierarchy Versus Compound

Hierarchy binding and compound colliders solve different problems:

Concept Meaning
SetParent(...) Links independently registered colliders so same-host parent/child or sibling collisions can be suppressed.
LSCompoundCollider Owns several authored parts under one public 3D collider ID, body binding, broad-phase entry, and event surface.
LSCompoundCollider2D Owns several authored 2D parts under one public 2D collider ID, body binding, broad-phase entry, and event surface.

Hierarchy state stores a dimension-tagged top-parent collider key. It does not walk engine transform trees during simulation. When a parent collider deactivates, child bindings are cleared before the service unregisters the parent collider ID.

Compound parts are not registered with the physics service, cannot be parented independently, and are scanned in stable declaration order by the owning compound collider. Public CompoundColliderPart and CompoundColliderPart2D values are data-first authored descriptors, not independent runtime identities.

Authoring Surfaces

Authoring type Runtime owner
ColliderShapeDefinition built-in LSCollider implementations and LSCompoundCollider parts
CompoundColliderPart 3D compound authoring
ColliderShapeDefinition2D built-in LSCollider2D implementations and LSCompoundCollider2D parts
CompoundColliderPart2D 2D compound authoring

Shape definitions should be used by importers, tooling, and offline-authored compound assets. Runtime collider shells own context binding, collider IDs, partition coordinates, pair state, events, and query stamps.

For a registered SolidBody, TryReconfigureCollider(...) treats a ColliderShapeDefinition as geometry input rather than as a replacement runtime collider. The definition kind must match the current sphere, capsule, or finite-cylinder family. The operation stages exact canonical geometry and bounds on a detached candidate, rejects positive penetration, then publishes authored and committed shape state together. Material, physical filters, hierarchy, event subscriptions, rotation, identity, and motion state remain on the existing collider and body. Other shape families are deliberately outside this focused public contract.

CompoundColliderPart scale-safely normalizes its authored local rotation once at construction, with a zero quaternion resolving to identity. The stored value is therefore the single orientation consumed by bounds, mass properties, queries, diagnostics, and replay hashing.

3D Shape Families

Shape Runtime notes
Sphere Center/radius support, simple mass and inertia.
Capsule Canonical center, normalized rigid frame, local axis, full cylindrical axis length, and radius; rotation-aware projected frontal area and solid capsule mass properties with sphere and thin-rod limits.
Cuboid Face, edge, corner support; Cuboid covers axis-aligned and oriented cuboid dispatch.
Finite cylinder Canonical center, normalized rigid frame, local axis, full axis length, and radius; flat-cap and side relations derive conceptual endpoints only inside exact operations.
Finite cone Canonical center, normalized rigid frame, local base-to-apex axis, full height, and radius; analytic support/closest-surface geometry and COM stay center-relative.
Mesh Convex or concave target geometry with triangle candidates and cached mass properties.
Compound Stable part-order reduction under one public collider identity, with solid-volume mass distribution and deterministic equal-mass fallback when every part measure quantizes to zero.

Cone Geometry and Mass Properties

Cones use analytic support and closest-surface geometry instead of generating a runtime triangle fan. Mesh colliders use cached closed-volume mass properties by default when angular dynamics are enabled and keep an explicit uniform thin-shell mass policy for open meshes.

Cone Volume (also published through its shape-specific Area property) rounds the complete fixed-Pi Pi*r*r*h/3 expression once. Only an unrepresentable final volume saturates to Fixed64.MaxValue; this diagnostic scalar does not reject otherwise valid geometry or narrow compound mass weights. Compound weighting retains the existing fixed-point Pi/3 coefficient and unnarrowed dimension products. Pose changes reuse the committed volume when effective radius and height are unchanged; geometry changes prepare a new value before publication.

Capsule and Cylinder Limits

For a 3D capsule with normalized motion direction n, world-space axis Rotation * Vector3d.Up, radius r, and cylindrical height h, the projected frontal area is pi*r^2 + 2*r*h*sqrt(max(0, 1 - dot(n, axis)^2)). A near-zero direction returns the collider's total Area, matching the other 3D primitive drag-area APIs. Solid capsule inertia assigns cylinder and cap masses in proportion to volume. The paired hemispheres contribute mCaps*(2*r^2/5 + d^2 + 3*d*r/4) transversely for d = h/2, including their centroid displacement from the cap centers, and 2*mCaps*r^2/5 axially. A capsule with no cylindrical span uses the solid-sphere limit 2*m*r^2/5.

If fixed-point scaling leaves a positive span but quantizes the radius and both volumes to zero, the tensor uses the thin-rod limit diag(m*h^2/12, 0, m*h^2/12) before applying any requested parallel-axis shift.

A finite cylinder must retain a positive scaled full axis length when its runtime shape is rebuilt. Gravitas does not require an odd raw-unit length to have a representable half-height or materialized cap centers; exact centered-axis relations retain the full length through classification and witness selection. A positive authored height that scales to zero is still rejected because it does not retain the cylinder's flat-cap contract. Capsules remain different by design: a collapsed capsule center segment is the well-defined sphere limit.

Compound Mass and Bounds

3D compound colliders distribute uniform-density mass by each solid part's volume rather than by the public Area value, whose drag/diagnostic meaning is shape-specific. Closed-volume meshes contribute their validated scaled volume. Meshes explicitly authored with SurfaceApproximation contribute scaled triangle surface area and use physical uniform thin-shell COM/inertia integration. Surface density and solid volume density are not dimensionally interchangeable, so the policy stays an explicit authoring choice. Fixed-point mass division preserves the requested total mass by assigning the rounding residual to the last positive-weight authored part. If every part measure quantizes to zero, part centers and masses use equal authored-order weights with the same residual rule.

Part centers of mass and anisotropic center tensors are transformed into the compound owner's local frame before parallel-axis shifts. Aggregate frontal area remains the deterministic sum of part projections; it is conservative for overlapping projections rather than an exact silhouette union.

ScaledRadius conservatively encloses the aggregate shape about the owner center. Detached polygon and mesh parts are measured from their effective authored vertices, including part scale, before runtime preparation. An unrepresentable vertex enclosure returns Fixed64.MaxValue; inspection does not admit or publish runtime geometry, so a later host scale can still compensate oversized authoring. After publication, the radius describes committed geometry until the next successful shape transaction.

There is no aggregate ScaledSize contract: a world AABB cannot represent an owner-local size under arbitrary part rotations, and canonical primitive geometry exposes radius, full axis length, or half-extents explicitly.

3D Shape-Pair Matrix

A / B Sphere Capsule Cuboid Cylinder Cone Mesh Compound
Sphere Supported Supported Supported Supported Supported Supported Supported
Capsule Supported Supported Supported Supported Supported Supported Supported
Cuboid Supported Supported Supported Supported Supported Supported Supported
Cylinder Supported Supported Supported Supported Supported Supported Supported
Cone Supported Supported Supported Supported Supported Supported Supported
Mesh Supported Supported Supported Supported Supported Supported Supported
Compound Supported Supported Supported Supported Supported Supported Supported

Cylinder/Mesh and Cone/Mesh are normalized to Mesh/Cylinder and Mesh/Cone by pair priority so contact data is written in the mesh-to-curved-primitive direction.

2D Shape Families

Shape Runtime notes
Circle Center/radius tests, support points, area, and scalar moment.
Capsule Segment plus radius; analytic closest-point geometry rather than polygon approximation.
Axis-aligned box X/Z-aligned bounds and 2D separating-axis checks.
Convex polygon Deterministic vertex-order SAT, triangle helper output, convexity validation, and collinearity rejection.
Compound Stable part-order reduction under one public 2D collider identity.

Boxes and polygons use 2D separating-axis tests over deterministic center-relative vertex order. Absolute world vertices are best-effort presentation values through TryGetWorldVertex; collision, query, mixed-prism, and replay paths keep the collider origin separate so a conceptual vertex may cross a Fixed64 scalar face without deforming the polygon. LSPolygonCollider2D rejects concave and collinear input up front. Concave 2D runtime collision should be authored as stable convex compound parts.

Polygon area, centroid and centered moment integrals are cached per effective geometry. Pose-only updates reuse them. The requested mass is applied before final moment normalization, preserving representable inertia even when scalar area would overflow or an intermediate density would round to zero.

2D Shape-Pair Matrix

A / B Circle Capsule AABB Convex Polygon Compound
Circle Supported Supported Supported Supported Supported
Capsule Supported Supported Supported Supported Supported
AABB Supported Supported Supported Supported Supported
Convex Polygon Supported Supported Supported Supported Supported
Compound Supported Supported Supported Supported Supported

Compound/primitive and compound/compound pairs scan owned parts in stable declaration order and reduce back to the public owning collider identity.

Narrow Phase Rules

The separating-axis invariant is the broad rule behind convex SAT paths: if a candidate axis projects two convex shapes into non-overlapping intervals, the shapes cannot be colliding. A collision is possible only when every required axis overlaps.

Candidate axes must be generated and tested in stable order. Contact normals must be oriented by the pair convention rather than by ad hoc shape-pair sign fixes. If a response pair appears to need an impulse sign exception, audit normal orientation and pair priority first.

SAT and mesh candidate paths use context-owned scratch state through GravitasWorldContext. CollisionSatScratch owns reusable collision context, object-info buffers, triangle candidate buffers, and SAT axis sets, including the ordered cuboid/capsule axes, for one world context. Every reducer clears its owned logical buffer before rebuilding it; concurrent worlds keep isolated scratch, while repeated checks in the same world avoid per-check allocations and pool churn.

Mesh Policy

Meshes as Collision and Query Targets

Mesh colliders are valid simulation colliders and query targets. 3D raycasts and swept-sphere queries test mesh triangle candidates and return the owning LSMeshCollider once. Convex mesh source sweeps also support concave mesh targets by testing only target triangles inside the source swept bounds and reducing hits back to the target owner.

Convex Volume and Triangle Surfaces

MeshColliderMode.Convex enforces a geometry contract. Construction accepts either one connected, consistently wound, closed convex manifold shell or one connected, consistently wound, open coplanar triangulation that fills a single convex polygon. It rejects unused vertices, duplicate faces, disconnected components, non-manifold edges, inconsistent winding, disconnected vertex links, reflex closed edges, bent or folded open surfaces, holes, and overlapping open triangles. Exact-position duplicates are welded only in the temporary topology view so common hard-normal and UV seam exports validate without changing authored vertices, triangle order, or query tie-breaking.

MeshColliderMode.Concave selects authored triangle-surface collision; the geometry may itself be convex or nonconvex, open or closed, or disconnected. Both modes reject unreferenced vertices. PhysicsMesh.IsClosedSurface and LSMeshCollider.IsClosedSurface cache whether the complete exact-position-welded surface is one connected, consistently wound, closed two-manifold. The property describes topology only; TryGetClosedVolumeMassProperties(...) remains the richer volume and representability contract. MeshVolumeValidationResult.NonManifoldVertex distinguishes a pinched or disconnected vertex fan from an ordinary open edge.

Closed topology does not imply a filled collision volume. For sphere contacts, a closed Convex mesh provides convex-volume collision; the same vertices and triangles constructed in Concave mode retain triangle-surface contacts. For example, a radius-0.25 sphere centered inside a closed cube spanning [-1,1] on every axis does not touch any triangle in Concave mode, while Convex mode detects its containment. A sphere overlapping a wall can contact that wall in either mode. Closure and volume-based mass-property validation remain separate from the collision mode.

StaticSurface membership requires Concave mode and accepts eligible closed shells as well as open panels. It does not convert those shells into filled volumes or establish a Boolean union of closed solids. Exact join validation still determines which boundary spans join. Convex-mode meshes can collide with a declared surface as moving participants, but cannot be its members.

Exact concave mesh/mesh contact is supported, but dense overlapping tessellated surface pairs are an experimental, capacity-sensitive per-step workload. Cost scales with BVH-admitted triangle pairs and their exact full-domain SAT axes. Prefer Convex when the authored geometry satisfies its enforced contract; otherwise use deterministic convex decomposition, authored compound proxies, or partitioned static concave surfaces for competitive runtime paths.

Closest Points and Projected Overlaps

Mesh closest-surface queries always return a point on an authored triangle. They seed an exact upper-bound candidate, query the local triangle BVH inside a conservative cube that contains every point capable of improving that bound, and use a stable, allocation-free full triangle scan only when the bound cannot be represented. Broad-phase bounds are never substituted for mesh geometry, including mesh/sphere contacts and circle overlap queries. Full-domain FixedMathSharp triangle and squared-distance predicates preserve the closest authored candidate even when public Q32.32 distance values would saturate. Primitive, mesh, and compound closest-surface selection likewise owns a semantic surface anchor before optional point or scalar-distance materialization.

Projected overlap queries classify exact X/Z geometry and retain that real 3D anchor; clipped broad-phase boxes and invented coordinates are never narrow-phase substitutes.

For existing mesh assets, this validation is intentionally breaking for those that previously selected Convex despite violating its geometry contract. Author raw terrain, triangle soups, bent open surfaces, and nonconvex shells as Concave; use deterministic convex decomposition when a moving or support-mapped collider needs multiple convex parts.

Authored Mesh Placement and Scale

Runtime meshes preserve the authored transformation before rounding.

poseOrigin
+ placementRotation * (localOffset * ownerScale)
+ geometryRotation * ((sourcePoint - authoredBoundsCenter)
                      * ownerScale * partScale)

For a standalone collider, both rotations are its committed rotation, part scale is one, and the default local offset is the authored bounds center. A compound part places its center using its parent's rotation and owner scale. Its geometry uses the normalized combined rotation and both scale factors. Direct PhysicsMesh placement specifies the centered mesh reference.

Scale products, reference subtraction and placement remain exact through finite collision/query admission and selection. Only final physical witnesses are rounded to Q32.32 in their translated contact frame. Public Center remains a rounded placement summary, and GetLocalTriangleVertices remains a rounded, centered inspection view; neither replaces exact runtime geometry. Independently centered pieces under an identical authored map therefore keep identical shared edges without tolerance welding. Rotations must be normalized. Scale factors must be strictly positive and diagonal, and must preserve the supported reach, representable centered inspection coordinates, physical triangle areas, total area and selected mass properties. Invalid standalone meshes reject before collider registration. Compound owners prepare every mesh part before publishing any part, so a failed scale/rotation change cannot leave half-updated geometry.

Scaled mesh bounds use FixedMathSharp's full-domain nearest-even midpoint. Same-sign extreme coordinates are therefore valid when the exact bounds size, triangle geometry, and selected mass properties remain representable; a saturated endpoint sum is not itself grounds for rejecting the mesh.

Collider broad-phase boxes are analytical conservative intersections with the representable coordinate domain. Clipping applies only to final AABB endpoints; it is never reused as narrow-phase geometry. Cuboids retain FixedOrientedBox(center, orientation, halfExtents), while capsules, cylinders, and cones retain center, normalized rigid-frame rotation, normalized local axis, full axis length, and radius. Their public WorldAxis values are derived convenience projections for callers and diagnostics; exact support and contact construction stays in the authoritative rigid frame.

Direct PhysicsMesh transform APIs retain this strict validation contract. Compound-part authoring reaches the same mesh path only after CompoundColliderPart has normalized its stored local orientation.

Topology, Bounds Index, and Mass Properties

Source vertices, triangle indices, authored face normals, convex SAT edge topology, and support topology are immutable and exposed only through read-only views or internal query seams. Positive diagonal scale and rigid pose preserve authored incidence, coplanarity and convex fill, so seam ownership is classified once from source geometry. Scale changes prepare bounds, support ordering and face normal/area caches before committing them together. The triangle BVH indexes authored coordinates when required by exact scale or placement, and uses the existing compact scaled chart when it represents identical geometry. Pose updates do not rebuild it. World normals use the rigid rotation of the inverse-transpose-scaled local normal and are normalized before projection.

Frontal area is the positive projected physical triangle area and is invariant to direction magnitude.

Closed-volume integration retains signed tetrahedron weights and moment products until final volume, centered COM and unit tensor normalization. Source properties are cached in the recentered geometry frame. Diagonal scaling reuses analytic covariance when representable; if source properties or an intermediate cached scale cannot represent otherwise valid final geometry, centered scaled source products are integrated before final public normalization. Compound integration retains the existing finite guard fractions after summing those products. SurfaceApproximation performs stable two-pass thin-shell integration: area-weighted COM relative to scaled bounds, then authored-order triangle central tensors plus parallel-axis shifts. Checked fixed-point arithmetic rejects volume collapse, saturation, and nonrepresentable COM/tensors rather than publishing sentinel values.

True hierarchy shear is outside this contract. Hosts that compose rotated nonuniform parent scales into shear must bake that affine deformation into authored mesh vertices or provide a future explicit affine-mesh API; Gravitas does not silently approximate shear as diagonal scale plus rotation.

Concave mesh-as-source sweeping and automatic runtime decomposition are not part of the public runtime query surface. Author concave movers as offline decomposed LSCompoundCollider assets with stable convex part order.

Mixed Shape Policy

Mixed collision embeds 2D colliders into 3D as finite slabs/prisms. CollisionDetectionMixed supports 3D primitive, compound, and mesh colliders against embedded 2D circle, capsule, AABB, convex polygon, and compound slabs.

Compound mixed contacts scan owned parts in stable order and retain each leaf's namespace and material. A mesh consisting entirely of one certified convex coplanar patch uses its finite corner/perimeter geometry against AABB and convex polygon prisms. Other mesh mixed contacts use local-BVH candidates and the finite surface/slab owners; holes and disconnected surfaces remain distinct.

Mixed shape-pair support belongs to the explicit mixed service. 2D and 3D collision dispatch should not fall through to accidental mixed response.

Source Map