Skip to content

Search

Documentation

collider3d component

The node's 3D collision shape, chosen by kind. It belongs to the node's body3d or the nearest body above it; without one it is static geometry.

En esta página

3d · physics · 64 properties · 3D

The node's 3D collision shape, chosen by kind. It belongs to the node's body3d or the nearest body above it; without one it is static geometry.

In a scene, collider3d is the node key that applies it. A script reaches each property below as a field on node.collider3d: reading one asks the running component, and assigning one leaves the rest alone. The whole table is node.collider3d.get() and node.collider3d.set(table).

Properties

property type default description
a vec3 [0,0,0] First corner, when kind is triangle or segment, and a capsule's first end when its height is 0
approximate_hulls bool true Estimate each piece's hull while cutting rather than building it exactly
b vec3 [1,0,0] Second corner, when kind is triangle or segment, and a capsule's other end when its height is 0
c vec3 [0,1,0] Third corner, when kind is triangle
center_of_mass vec3 [0,0,0] Where this collider's mass sits, in its own space; read with inertia, and both 0 keep the shape's own
collision_layer flags ["1"] The layers this collider is on One of 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32.
collision_margin float 0 A margin the solver treats as already touching; stops thin shapes tunnelling and jittering At least 0.
collision_mask flags [] The layers it collides with; empty means every layer One of 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32.
collision_test enum both Whether a pair is tested when both colliders' layers accept the other, or when either does; two colliders that differ use both One of both, either.
connected_components bool false Work out which triangles form each separate piece of the mesh
contact_force_threshold float 0 How hard a contact must be before on_contact_force is called At least 0.
contact_pairs flags ["dynamic_dynamic","dynamic_kinematic","dynamic_static"] Which pairs of body kinds this collider is tested against; a sensor watching kinematic platforms needs more than the default One of dynamic_dynamic, dynamic_kinematic, dynamic_static, kinematic_kinematic, kinematic_static, static_static.
density float 1 Mass per volume, so the shape's size sets its mass; 0 makes a collider that adds no mass to its body At least 0.
drop_bad_topology bool false Drop the triangles that stop the mesh's edge topology from being built
drop_degenerate_triangles bool false Drop triangles that name one vertex twice; merges vertices too
drop_duplicate_triangles bool false Drop a triangle whose three vertices another one already names; merges vertices too
edge_radius float 0 Rounds a box, cylinder, cone, triangle, convex_hull, convex_mesh or vhacd convex_decomposition by this radius; a rounded shape slides over seams instead of catching on them At least 0.
edges enum chain Which edges a polyline takes from its mesh: the points in order, or every edge of its triangles One of chain, mesh.
enabled bool true Collide at all; a disabled collider keeps its shape and costs nothing
events flags [] What this collider reports to its node's script: on_collision_enter and on_collision_exit, or on_contact_force One of collision, contact_force.
fill enum solid Whether voxelizing a mesh fills its inside or only its shell, for voxelized_mesh and a convex_decomposition's voxel grid One of solid, surface.
fill_cavities bool false When a solid fill floods a mesh, leave the cavities a closed surface walls off empty
fit enum convex_hull The shape fitted to the mesh, when kind is fit One of convex_hull, aabb, obb, convex_decomposition.
fix_internal_edges bool true Smooth the seams between a triangle_mesh's triangles, so a character does not catch on flat ground
friction float 0.5 Surface friction; 0 is ice At least 0.
friction_combine enum average How this surface's friction combines with the other one's One of average, min, multiply, max, clamped_sum, geometric_mean.
height float 2 Length tip to tip, for capsule, cylinder and cone; a capsule with height 0 runs from a to b instead At least 0.
heightfield asset · heightfield — Terrain grid, when kind is heightfield; the asset's holes are cut out of it
hull_downsampling int 4 How coarsely a piece's hull is sampled while choosing a cut; 1 uses every point At least 1.
inertia vec3 [0,0,0] This collider's resistance to spin about each axis; 0 with a center_of_mass takes the shape's own about that centre
inertia_rotation vec3 [0,0,0] Turns the axes inertia is measured about, x first; read with a non-zero inertia. Euler radians in the file
kind enum box Collision shape One of sphere, box, capsule, cylinder, cone, triangle, segment, world_boundary, triangle_mesh, convex_hull, convex_decomposition, polyline, heightfield, voxels, voxelized_mesh, fit, convex_mesh, voxelized_points.
mass float 0 Mass in kilograms, overriding what density works out to; 0 keeps the density At least 0.
max_concavity float 0.01 How deep a dent a piece may keep before it is cut again At least 0.
max_convex_hulls int 1024 The most pieces a decomposition is asked to leave; parry 0.31 passes it on unread, so it limits nothing yet At least 1.
merge_vertices bool false Merge vertices at exactly the same place when building a triangle_mesh
mesh asset · mesh — Geometry for a triangle_mesh, convex_hull, convex_mesh, convex_decomposition, polyline, fit, voxelized_mesh or voxelized_points collider
method enum vhacd How a convex_decomposition is cut: into convex hulls, or into voxel parts One of vhacd, voxels.
normal vec3 [0,1,0] Which way the infinite plane faces, when kind is world_boundary
offset vec3 [0,0,0] Where the shape sits relative to the node
offset_rotation vec3 [0,0,0] How the shape is turned relative to the node, x first; Euler radians in the file
one_way bool false A platform bodies land on from the side one_way_axis names and pass through from the other
one_way_angle float 0.1 How far a contact's normal may lean from one_way_axis and still hold the body; radians in the file Range 0–180.
one_way_axis vec3 [0,1,0] The side a one-way platform holds bodies on, in the collider's own axes: [0, 1, 0] lands them from above and lets them up through from below
oriented bool false Treat the triangle_mesh as a closed, outward-facing surface, which makes inside and outside meaningful
plane_downsampling int 4 How coarsely the cutting planes are searched first; 1 tries every one At least 1.
radius float 0.5 Radius, for ball, capsule, cylinder and cone At least 0.01.
resolution int 64 How fine the voxel grid a decomposition cuts is At least 1.
restitution float 0 Bounciness: 0 is a dead stop, 1 a full rebound, and above 1 each bounce gains energy At least 0.
restitution_combine enum average How this surface's bounciness combines with the other one's One of average, min, multiply, max, clamped_sum, geometric_mean.
revolution_bias float 0.05 How much a cut prefers an axis of revolution Range 0–1.
scale vec3 [1,1,1] Cell size and height scale of a heightfield
sensor bool false Detects overlaps without colliding: bodies pass through and are reported
size vec3 [1,1,1] Whole size along each axis, when kind is box
solver_layer flags ["1"] Layers for the solver alone: a pair can be detected but not resolved One of 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32.
solver_mask flags [] Which solver layers this one pushes against; empty means all of them One of 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32.
solver_test enum both The same choice for the solver layers One of both, either.
surface_velocity vec3 [0,0,0] How fast the surface slides along itself, in the collider's own axes: a conveyor belt carries what rests on it
symmetry_bias float 0.05 How much a cut prefers a plane of symmetry Range 0–1.
topology bool false Build the mesh's half-edge topology
two_sided_edges bool false fix_internal_edges for a mesh hit from both sides: a contact from behind a triangle is kept and smoothed, not dropped
up_axis enum y The axis a capsule lies along; cylinder and cone stand along y One of x, y, z.
voxel_size float 0 How big one cell is: 0 keeps a voxels asset's own cell size, and is 0.25 for voxelized_mesh and voxelized_points At least 0.
voxels asset · voxels — Filled cells, when kind is voxels; a script may dig into them while the game runs

Asset types this component references: heightfield, mesh, voxels.

Script functions

Methods of node.collider3d, the handle a node carrying this component exposes. Every handle also has get(), set(table), patch(table), has() and remove().

From physics3d:

method what it does
aabb() -> float, float, float, float, float, float The world-space box the collider currently occupies, as its two opposite corners.
broad_phase_aabb() -> float, float, float, float, float, float The box the broad phase files the collider under, which also reaches ahead by its body's speculative_distance.
collider_mass() -> float What this collider weighs, density and size together.
collider_mass_properties() -> any What this collider adds to its body, in its own space: #{ mass, center_of_mass, inertia, inertia_rotation }.
collider_mesh() -> any The collider's shape as points and triangles, including a voxel grid's, for drawing it or for spawning the pieces it broke into.
collider_volume() -> float How much space the shape encloses.
collision_aabb() -> float, float, float, float, float, float The box the narrow phase tests the collider in: its shape's box grown by its collision_margin and the world's prediction distance.
combine_voxels(node) Tell two voxel colliders on one lattice about each other's cells, so a body sliding from one onto the other does not catch on the seam. Both must share a cell size and a rotation.
contacts() -> any Every contact point on this node's collider this step: #{ node, point, normal, impulse } each. Empty for a sensor, which has no contacts by definition.
crop_voxels(int, int, int, int, int, int) Empty every cell outside the cells from (min_x, min_y, min_z) to (max_x, max_y, max_z), both included. A range holding no filled cell leaves the grid as it was.
handles() -> any The rapier handles behind this node, its body and its colliders, as #{ body, colliders } of index and generation pairs. For matching a log line against rapier's own output.
heightfield_hole(int, int) -> bool Whether a heightfield cell has no ground.
max_contact_impulse() -> float The hardest contact this node took in the last step, zero when nothing touched it: a damage threshold in one number.
overlaps() -> [node] The nodes this one currently intersects; rapier reports a pair only when one of the two colliders is a sensor.
pose_in_body() -> any Where the collider sits in its body's frame, as #{ position, rotation }; nothing for a collider with no body.
set_collider(any) Replace the node's collider from a collider3d table: kind, radius, size, friction, and the rest of the component's own vocabulary.
set_heightfield_hole(int, int, bool) Remove or restore the ground of one heightfield cell, named by the row and column of its first corner.
set_voxel(int, int, int, bool) Fill or empty one cell of a voxel collider: digging a hole, or building a wall, while the game runs.
set_voxel_size(float, float, float) Resize every cell of a voxel collider, keeping which cells are filled.
swept_aabb() -> float, float, float, float, float, float The box the collider covers over the next fixed step, from where it is to where its body's velocity and forces carry it.
voxel(int, int, int) -> bool Whether one cell of a voxel collider is filled.
voxel_at(float, float, float) -> int, int, int The cell a world position falls in, as three whole numbers.
voxel_size() -> any How big one cell of a voxel collider is, along each axis.