2D and 3D shapes, triggers, material, and filters.

Colliders

A collider is the shape the physics simulation actually sees. This page explains what a collider carries besides geometry, walks through every 2D and 3D shape, and shows how triggers, materials, and filters fit together.

What a collider is

Drawn art is not enough for collisions. A hero sprite may be 64 pixels wide but should only be blocked by a narrow 20 pixel core; a crate model’s visible mesh may be far too detailed to test against. A collider is a simple proxy shape attached to an entity that the simulation uses for contact tests.

Each collider bundles three jobs:

• Shape — a box, circle, capsule, polygon, edge, sphere, or convex hull with a size and an offset from the entity origin.
• Material — friction, restitution, and (in 2D) density, which decide how the contact feels.
• Filter — layer, category_bits, and mask_bits, which decide who is allowed to touch whom. Full rules live in Physics layers.

A collider without a rigidbody is a static obstacle. Adding a rigidbody is what makes the shape move.

2D shapes

2D colliders live on the XY plane and work for flat games and isometric play alike.

Every 2D collider also accepts these shared fields:

{
  "CircleCollider2D": {
    "radius": 0.4,
    "offset": [0, 0.1],
    "is_trigger": false,
    "layer": "player",
    "friction": 0.4,
    "restitution": 0.1,
    "density": 1.0,
    "category_bits": 1,
    "mask_bits": 65535
  }
}

3D shapes

3D colliders use the same filter and material ideas, with one strict rule: exactly one collider per entity.

Shared fields match the 2D list minus density: offset [x, y, z], is_trigger, layer, friction, restitution, category_bits, mask_bits.

{
  "Rigidbody3D": { "body_type": "dynamic", "mass": 40 },
  "CapsuleCollider3D": {
    "radius": 0.35,
    "height": 1.7,
    "offset": [0, 0.85, 0],
    "is_trigger": false,
    "layer": "player",
    "friction": 0.3,
    "restitution": 0.0
  }
}

• radius and height define the capsule. The height is the full extent including both caps; invalid combinations (height shorter than the caps) are rejected at validation.
• offset [0, 0.85, 0] lifts the capsule so its base sits at the entity origin — the usual way to keep feet on the floor.
• is_trigger, layer, friction, and restitution behave exactly like the 2D fields.

One collider per entity, and why

Validation rejects a second 3D collider on the same entity. The reason is that one entity is one simulated body, and a body has one shape. Stacking two shapes would silently change mass, contact ordering, and how forces resolve.

When you need several convex parts as one body, author a compound *.collider.json source, import it as a Collider3D asset, and attach it through one ModelCollider3D component. A compound asset can belong to a static, kinematic, or dynamic body. A triangle-mesh asset remains static-only.

Two more validation rules protect you from silent misconfiguration:

• A moving body cannot use a triangle-mesh collider. Use a convex hull or compound asset for movers.
• A moving body needs a collider of its own. A mover with no shape would fall through the world with nothing to hit.

Reusable 3D collider assets

A self-contained *.collider.json source needs no model or prefab. It keeps geometry in source and obtains its stable identity from a generated *.asset.json manifest:

{
  "format_version": 1,
  "shape": "convex_hull",
  "points": [[0, 0, 0], [1, 0, 0], [0, 1, 0], [0, 0, 1]]
}

Convex hulls require 4–256 finite, non-coplanar local points. A compound source uses "shape": "compound" and a parts array of uniquely named convex hulls. Part IDs survive reordering; a 3D raycast can return collider_part_id for the part it struck. Shape casts and overlap queries do not report part IDs.

demi asset import props/barrel.collider.json --project path/to/game --id asset://colliders/barrel
demi asset reimport path/to/game/assets/colliders/barrel/barrel.collider.asset.json

The .collider.json suffix selects the collider-shape importer. In the editor, select a Model3D asset and use Generate Collider Asset... for model-derived geometry, then add Collider Asset 3D to an entity and choose its Collider3D asset. The Inspector attaches the ModelCollider3D component and reference together. Generation of an existing collider requires an explicit replacement confirmation.

Scene references load through normal scene asset discovery. For an asset used only by later scripted creation, load its URI with Assets.load, wait on the returned request ID with Assets.is_ready, then create the body. Unreferenced manifests are not automatically resident.

Triggers versus solid colliders

A solid collider blocks movement and generates collision events. A trigger (is_trigger: true) never blocks anything; it only notices overlap and generates trigger events.

In Skyforge, the landing pad is solid so ships rest on it; the pad’s wider trigger ring announces arrivals without stopping the ship.

Friction, restitution, and density

These three describe how a contact behaves after the shapes meet.

• Friction resists sliding. Both bodies contribute, so an icy crate on a rubber floor still slides less than on ice. Use low friction for floating debris, high friction for tires.
• Restitution is bounciness. A dropped tool with restitution: 0 lands with a thud. A data-sphere with restitution: 0.8 pings around the hangar.
• Density (2D only) converts shape area into mass for dynamic bodies. A large low-density panel is easy to shove; a small high-density slug is not.

3D mass lives on the Rigidbody3D instead, so 3D colliders skip density.

Offset: shape without moving art

The entity origin is often at the feet or the center of a sprite, while the collision shape wants to sit somewhere else. offset is a local-space shift applied to the shape only:

{
  "BoxCollider2D": {
    "size": [0.6, 1.2],
    "offset": [0, 0.6]
  }
}

• size [0.6, 1.2] is the box width and height in world units.
• offset [0, 0.6] lifts the box half its height so the bottom sits on the entity origin (the feet).
• The sprite, shadow, and gameplay position stay at the origin; only the collision shape moves. Nothing is returned — this is authored data.

Picking shapes

• Prefer the simplest shape that blocks correctly. Circles and boxes are cheaper and more predictable than polygons.
• Use capsules for characters: they slide around corners without catching on edges.
• Use edges for terrain outlines that things should roll along, not inside.
• Never fake a sphere as a box for convenience — queries and debug drawing show the authored shape, and players feel the difference.

Once shapes are in place, decide who meets whom in Physics layers, then react to contacts with Physics events or probe the world with Queries.

Found an issue or missing topic? The full engine sources and markdown notes live in the DemiEngine repository.