Paths

Path Control Points

Defines positions, roll, and optional explicit tangents for a smooth path.

Control points use public right-handed Z-up coordinates. Each point contributes a position and roll angle; tangents can be generated automatically or supplied explicitly.

Automatic tangent#

track.add_point(x, y, z, roll=0);

Explicit tangent#

track.add_point_tangent(
    x, y, z,
    tangent_x, tangent_y, tangent_z,
    roll=0
);

The explicit tangent must be finite and non-zero. Its direction and length directly shape the Hermite curve around that control point.

Reading points#

var count = track.get_point_count();
var point = track.get_point(1);

Field	Meaning
index	Zero-based control-point index.
x, y, z	Public control-point position.
roll	Roll around the path tangent in degrees.
tangent_x/y/z	Explicit or generated tangent.
explicit_tangent	Whether add_point_tangent() supplied the tangent.

Limits and validation#

A path can contain at most 2048 control points.
All positions, tangents, and roll values must be finite.
Consecutive points may not occupy the same position.
An out-of-range get_point() index returns undefined and sets a high-level error.

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
JoltPath.add_point	JoltPath.add_point(x, y, z, roll = 0)	Boolean; local XYZ m and roll° default 0, at most2048 points. Explicit tangent finite nonzero, its length affects the Hermite curve. Editing discards the old build; run build_smooth afterward.
JoltPath.add_point_tangent	JoltPath.add_point_tangent(x, y, z, tx, ty, tz, roll = 0)	Boolean; local XYZ m and roll° default 0, at most2048 points. Explicit tangent finite nonzero, its length affects the Hermite curve. Editing discards the old build; run build_smooth afterward.
JoltPath.get_point	JoltPath.get_point(index)	set_loop Boolean result, change discards build; is_loop Boolean, count number/0 on error. get_point(zero-based index) copies position/roll/tangent/explicit_tangent or returns undefined.
JoltPath.get_point_count	JoltPath.get_point_count()	set_loop Boolean result, change discards build; is_loop Boolean, count number/0 on error. get_point(zero-based index) copies position/roll/tangent/explicit_tangent or returns undefined.