Convex

Builds the smallest convex hull around local 3D points.

Points need not be ordered or define faces and may be inside or on the hull. Use Convex for moving irregular convex objects. Split concave objects into Compound parts or use Static Mesh.

Syntax#

jolt_convex_create_dynamic(points, x, y, z, options=undefined)
jolt_convex_create_static(points, x, y, z, options=undefined)
jolt_convex_create_kinematic(points, x, y, z, options=undefined)

points format#

var points = [[x, y, z], {x:x, y:y, z:z}];

The array contains 4..4096 entries with finite real components. Points are local; creator x,y,z is the world origin and no automatic pivot offset is applied. Rotate through common options or body methods.

Hull limits and validation#

• The resulting Jolt hull has at most 256 vertices.
• Interior, duplicate, and face points need not become hull vertices.
• Coincident, collinear, coplanar, and zero-volume sets are rejected.
• Nearly-degenerate data can fail tolerance checks.
• Failure or practical-limit overflow returns undefined with JOLT_ERROR_CREATION_FAILED.
• Default ConvexHullShapeSettings are used; hull tolerance, convex radius, per-face material, and predefined faces are not exposed.

Return and behaviour#

Returns a JoltBody or undefined. It supports the standard JoltBody properties, collision layers, sensor mode, contacts, and raycasts; motion-type restrictions still apply to forces, mass, and velocity. Dynamic hulls support mass, forces, and impulses. Debug draw does not show true faces; it connects every pair among at most the first 64 input points.

Reusable JoltShape#

var shape = jolt_shape_convex(points, cache_key=undefined);
shape.create_dynamic(x, y, z, options);
shape.create_static(x, y, z, options);
shape.create_kinematic(x, y, z, options);

It has the same limits and is useful for repeated geometry. jolt_shape_load() supports Convex .jcol.

Low-Level / Advanced API#

No ergonomic low-level GML array creator exists. jolt_world_geometry_create(world, payload) expects an internal versioned base64 payload; use jolt_convex_create_dynamic() or jolt_shape_convex().

Example#

var points = [
    [-0.9,-0.7,-0.6], [0.8,-0.8,-0.5],
    [1.0,0.6,-0.4], [-0.7,0.9,-0.55],
    [-0.35,-0.25,0.95], [0.55,0.2,0.75]
];
var rock = jolt_convex_create_dynamic(points, 0, 0, 6, {
    mass:1.7, friction:0.7, restitution:0.05
});

Verified operation contracts#

These contracts distinguish units, return values, errors and lifetime according to the current implementation. Check results: false, 0 and undefined can mean different things for different methods.