Skip to content

Search

Documentation

collider2d component

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

Sur cette page

2d · physics · 66 properties · 2D

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

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

Properties

property type default description
a vec2 [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 vec2 [1,0] Second corner, when kind is triangle or segment, and a capsule's other end when its height is 0
c vec2 [0,1] Third corner, when kind is triangle
center_of_mass vec2 [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 rectangle, triangle, convex_hull, convex_polygon or a convex_decomposition's pieces by this radius, so it 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, the outline of its triangles, or every edge of them One of chain, outline, 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 an outline fills its inside or only its edge, for voxelized_mesh and a vhacd or voxels decomposition One of solid, surface.
fill_cavities bool false When a solid fill floods an outline, leave the holes it walls off empty
fit enum convex_hull The shape fitted to the mesh, when kind is fit; a fitted box keeps the pose it was fitted at One of convex_hull, aabb, obb.
fix_internal_edges bool true Take neighbouring triangles into account for a triangle_mesh's contacts, so a body does not catch on the seam between two of them
fix_self_intersections bool false When a solid fill floods an outline, handle the places it crosses itself
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, when kind is capsule; height 0 runs the capsule from a to b instead At least 0.
heightfield asset · heightfield — A row of heights, when kind is heightfield: a side-scroller's ground, with the asset's holes cut out
hull_downsampling int 4 How coarsely a piece's hull is sampled while choosing a cut; 1 uses every point At least 1.
inertia float 0 This collider's resistance to spin; 0 with a center_of_mass takes the shape's own about that centre At least 0.
keep_collinear bool false Keep the points that lie on a straight edge of a convex_polygon instead of dropping them
kind enum rectangle Collision shape One of circle, rectangle, capsule, triangle, segment, world_boundary, triangle_mesh, convex_hull, convex_decomposition, polyline, heightfield, voxels, voxelized_mesh, fit, convex_polygon, 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.1 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 — Points and triangles for a triangle_mesh, convex_hull, convex_polygon, convex_decomposition, polyline, fit, voxelized_mesh or voxelized_points collider: the same asset a polygon draws
method enum exact How a convex_decomposition is cut: exact, over the mesh's own triangles; vhacd, into hulls over a voxelised outline; or voxels, into voxel parts One of exact, vhacd, voxels.
normal vec2 [0,1] Which way the infinite line faces, when kind is world_boundary
offset vec2 [0,0] Where the shape sits relative to the node
offset_rotation float 0 How the shape is turned relative to the node; 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 vec2 [0,1] The side a one-way platform holds bodies on, in the collider's own axes: [0, 1] lands them from above and lets them up through from below
oriented bool false Treat a triangle_mesh or polyline as one-sided: the winding decides which side is solid, counter-clockwise enclosing the solid
overlap float 0.9 How far an exact convex_decomposition piece grows through each seam it shares, so nothing wedges into one: 0 leaves the plain pieces, 1 grows flush with the face that stops it Range 0–1.
plane_downsampling int 4 How coarsely the cutting planes are searched first; 1 tries every one At least 1.
radius float 0.5 Circle radius, when kind is circle or capsule At least 0.01.
resolution int 256 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 vec2 [1,1] Width and height scale of a heightfield
sensor bool false Detects overlaps without colliding: bodies pass through and are reported
size vec2 [1,1] Whole size along each axis, when kind is rectangle
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 vec2 [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 One of x, y.
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.collider2d, the handle a node carrying this component exposes. Every handle also has get(), set(table), patch(table), has() and remove().

From physics2d:

method what it does
aabb() -> float, float, float, float The world-space box the collider currently occupies, as its two opposite corners.
broad_phase_aabb() -> 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 }.
collider_mesh() -> any A voxel collider's outline as points and the segments between them, #{ points, indices }, for drawing it or for spawning the pieces it broke into.
collider_volume() -> float How much area the shape encloses.
collision_aabb() -> 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) Empty every cell outside the cells from (min_x, min_y) to (max_x, max_y), 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) -> bool Whether a heightfield segment has no ground.
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 collider2d table: kind, radius, size, friction, and the rest of the component's own vocabulary.
set_heightfield_hole(int, bool) Remove or restore one segment of a heightfield's ground, numbered from the first height.
set_voxel(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) Resize every cell of a voxel collider, keeping which cells are filled.
swept_aabb() -> 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) -> bool Whether one cell of a voxel collider is filled.
voxel_at(float, float) -> int, int The cell a world position falls in, as two whole numbers.
voxel_size() -> any How big one cell of a voxel collider is, along each axis.