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.