Utility Scripts

Closest Point Query

Finds the nearest point on real Jolt collision geometry without changing the physics world.

jolt_closest_point searches managed rigid bodies for the collision surface nearest to a public Z-up world-space position. It returns the existing JoltBody wrapper, the exact target-surface point, an outward world-space normal and the Euclidean point-to-surface distance. For one known body, JoltBody.get_closest_point performs the same narrow-phase measurement without searching the world.

Syntax#

jolt_closest_point(x, y, z, options=undefined)
body.get_closest_point(x, y, z)

Arguments#

Argument	Type	Description
x	Real	Finite public world-space X coordinate of the query point.
y	Real	Finite public world-space Y coordinate of the query point.
z	Real	Finite public world-space Z coordinate of the query point.
options	Struct or undefined	Optional world-search distance, layer, body, motion and sensor filters.

World-search options#

Field	Default	Description
max_distance	Unlimited	Optional positive finite surface distance. A supplied zero or negative value is invalid.
layers	undefined	One JoltLayer or an array, converted with the normal query mask rules.
mask	undefined	Numeric layer mask; when present it takes precedence over layers.
ignore	undefined	One live JoltBody from the managed default world to exclude.
motion	All types	JOLT_MOTION_STATIC, JOLT_MOTION_KINEMATIC or JOLT_MOTION_DYNAMIC.
include_sensors	true	Set false to exclude sensor bodies from the search.

Result#

Field	Description
hit	True when an eligible collision surface was found.
body / body_handle / body_valid	Existing managed wrapper, opaque handle and current wrapper validity.
entity	The selected body's user_data value.
position	Exact closest point on the target collision surface in public world space.
normal	Outward world-space target-surface normal.
distance	Euclidean distance from the original query point to position.
target_sub_shape_id	Native target sub-shape identifier, useful for Compound and complex geometry diagnostics.
candidate_count	Accepted broad-phase candidates, or visited managed bodies during unlimited search.
exact_body_tests	Bodies that passed every filter and reached Jolt narrow phase.
error_code / error_message	JOLT_ERROR_NONE and an empty string on a valid result or ordinary miss.

Surface semantics#

The query uses Jolt 5.6 narrow-phase collision geometry rather than body centres or axis-aligned bounds.
Rotated primitives, Convex, Mesh, HeightField, Compound child transforms, reusable shapes and OffsetCenterOfMassShape are measured against their real surfaces.
For a point inside a solid convex shape, the result is the nearest exit surface selected by Jolt and distance remains positive. A point on the surface returns approximately zero.
At exact symmetry several surface points may be equally valid, so the selected direction should not be used as a stable gameplay identifier.
Mesh and HeightField normals follow authored triangle winding; inside has a useful meaning only for suitably closed and consistently wound meshes.
Equal world-search distances are resolved deterministically by the lower public body handle within a small numeric tolerance.

World search and body-specific query#

Form	Use
jolt_closest_point(...)	Searches eligible managed rigid bodies and supports all options and filters.
body.get_closest_point(...)	Tests one known live body directly; it does not search or evaluate any other body.

Behaviour and performance#

Queries are read-only, include sleeping bodies and never activate them.
A finite max_distance lets Jolt cull candidates through broad phase and is recommended when gameplay has a known interaction radius.
An unlimited global search deliberately scans the managed body registry and is O(N) in the number of managed rigid bodies.
candidate_count and exact_body_tests expose query work for diagnostics without altering simulation state.
With JOLT_DEBUG_SHAPE_QUERIES enabled, the debug renderer records the input point, surface segment, closest marker and normal.

Example#

var nearest = jolt_closest_point(player_x, player_y, player_z, {
    max_distance: 5,
    ignore: player_body,
    include_sensors: false
});

if (nearest.hit) {
    show_debug_message("Distance: " + string(nearest.distance));
    show_debug_message("Body: " + string(nearest.body.data.name));
}

Known-body example#

var surface = crate.get_closest_point(player_x, player_y, player_z);
if (surface.hit) show_debug_message(surface.distance);

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.

Symbol / owner	Signature	Operation contract
jolt_closest_point	jolt_closest_point(x,y,z,options=undefined)	World XYZ m; options max_distance>0 if supplied(otherwise unbounded), motion defaults all, include_sensorstrue, layers/mask/ignore. Hit snapshot or hit:false:position, normal, distance, body/body_handle/body_valid/entity, target_sub_shape_id, candidate_count, exact_body_tests, error_code/message.