API ReferenceGE ExtensionsutiltrackBuilder
Track Pieces
Reference for `extensions/util/trackBuilder/pieces.lua`. Converts abstract track piece descriptions (forward, curve, spiral, loop, bezier) into concrete segment data with positions, headings, and cont
Reference for extensions/util/trackBuilder/pieces.lua. Converts abstract track piece descriptions (forward, curve, spiral, loop, bezier) into concrete segment data with positions, headings, and control points.
Exports
| Key | Signature | Description |
|---|---|---|
toSegment | (piece, tip) | Main dispatcher - converts a piece definition to a segment |
initialTrackPiece | (p?) | Creates the origin segment |
forward | (length) | Straight segment |
curve | (radius, angle, direction, hardness, radiusMult) | Arc or bezier curve |
bezierCurve | (radius, angle, direction, hardness, radiusMult) | Explicit bezier curve |
offsetCurve | (length, xOffset, hardness, isHex) | S-curve with lateral offset |
customBezier | (xOff, yOff, dirOff, fwdLen, bwdLen, isHex, absolute?, empty?) | Free-form bezier segment |
hexSpiral | (size, inside, dir) | Hex-grid spiral transition |
squareSpiral | (size, inside, dir) | Square-grid spiral transition |
freeSpiral | (size, inside, dir, angle) | Free-angle spiral transition |
loop | (xOffset, radius, isHex) | Vertical loop using Euler spiral (Fresnel integrals) |
emptyOffset | (xOff, yOff, zOff, dirOff, absolute, isHex) | Non-rendered positional jump |
getHdgVector | (hdg) → vec3 | Heading angle to direction vector |
rotateVectorByQuat | (v, q) → vec3 | Vector rotation helper |
fresnelSC | (d) → {x, y} | Fresnel spiral integral for loop calculation |
splineTrack | ref | Back-reference to the splineTrack module (set externally) |
Internals
- Grid systems: Supports hex grid (60° snapping, √3 spacing), square grid (90°), and free-form placement.
- Tip piece: Each segment is built relative to the previous segment's endpoint (
tipPiece), carrying forward position and heading. - Segment output format: Each function returns a table with
position,origin,hdg,polyMult,pointsType('bezier'/'arc'/'custom'), and type-specific fields likecontrolPointA/B,radius,angle,customPoints. - Bezier hardness: Controls how "sharp" curves are by adjusting control point distance (0 = optimal circle approximation, negative = tighter, positive = wider).
- Loop math: Uses Fresnel integrals (
fresnelSC) to compute clothoid (Euler spiral) curves for realistic loop entry/exit.
How It Works
toSegment(piece, tip)dispatches based onpiece.piecestring to the appropriate geometry function.- Each function computes the new endpoint position/heading relative to
tipPiece. - The returned segment includes control points for later bezier/arc point generation by
splineTrack. polyMultcontrols point density (higher = more points for smoother curves).
-- A piece definition for a 60° hex curve
local piece = {piece = 'hexCurve', length = 3, direction = 1, hardness = 0}
local segment = pieces.toSegment(piece, previousTip)
-- segment.pointsType == 'arc' (hardness 0) or 'bezier' (hardness ~= 0)Additional Exports
M.bezierCurve- (undocumented)M.curve- (undocumented)M.customBezier- (undocumented)M.emptyOffset- (undocumented)M.forward- (undocumented)M.freeSpiral- (undocumented)M.fresnelSC- (undocumented)M.getHdgVector- (undocumented)M.hexSpiral- (undocumented)M.initialTrackPiece- (undocumented)M.loop- (undocumented)M.offsetCurve- (undocumented)M.rotateVectorByQuat- (undocumented)M.splineTrack- (undocumented)M.squareSpiral- (undocumented)M.toSegment- (undocumented)
See Also
- Track Builder - Basic Borders - Related reference
- Track Builder - Basic Centers - Related reference
- Track Builder - Border Wall Mesh - Related reference
- Game Engine Overview - Guide
Obstacle Placer
Reference for `extensions/util/trackBuilder/obstaclePlacer.lua`. Places static and procedural obstacles (rocks, ramps, rings, etc.) along track segments.
Procedural Primitives
Reference for `extensions/util/trackBuilder/proceduralPrimitives.lua`. Generates mesh data (vertices, normals, UVs, faces) for primitive 3D shapes used as track obstacles.