@trioforge/spline 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @trioforge/spline
+
+## 0.1.1
+
+### Patch Changes
+
+- [#6](https://github.com/Trio-Forge-Studio/packages/pull/6) [`dac820b`](https://github.com/Trio-Forge-Studio/packages/commit/dac820b44abb72c663f694c6125de44e1a1a8fcd) Thanks [@Hezaerd](https://github.com/Hezaerd)! - The source moved to [Trio-Forge-Studio/packages](https://github.com/Trio-Forge-Studio/packages), so the package's repository and issue links point there. The package now ships its `CHANGELOG.md`. The code is the same as the previous version.
+
+## 0.1.0
+
+### Minor Changes
+
+- First release. `catmullRom`, `cubicBezier` and `uniformBSpline` build curves through `Vector2` or `Vector3` points. A curve gives its point, tangent and rotation-minimizing frame at a parameter, converts between parameter and distance along its length, and finds the closest point to a position. Curves can be open or closed. ([Trio-Forge-Studio/spline#2](https://github.com/Trio-Forge-Studio/spline/pull/2))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Trio Forge Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,192 @@
-# Temporary Holding Version
+# @trioforge/spline
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Catmull-Rom, cubic Bezier, and uniform B-spline curves for roblox-ts. Use `Vector2` or `Vector3` points to sample positions, travel by distance, orient objects, and find the closest point on a path.
+
+Read the documentation at <https://website.trio-forge.workers.dev/spline/>.
+
+## Install
+
+```sh
+pnpm add @trioforge/spline
+```
+
+roblox-ts looks for packages in the scopes your project lists. Add `@trioforge` in two places.
+
+1. In `tsconfig.json`, add it to `typeRoots`.
+
+	```json
+	"typeRoots": ["node_modules/@rbxts", "node_modules/@trioforge"]
+	```
+
+2. In your Rojo project, map it beside `@rbxts` under `rbxts_include/node_modules`.
+
+	```json
+	"node_modules": {
+		"$className": "Folder",
+		"@rbxts": { "$path": "node_modules/@rbxts" },
+		"@trioforge": { "$path": "node_modules/@trioforge" }
+	}
+	```
+
+## Quickstart
+
+Create a path through three points and sample its middle joint.
+
+```ts
+import { catmullRom } from "@trioforge/spline";
+
+const path = catmullRom([new Vector3(0, 0, 0), new Vector3(10, 5, 0), new Vector3(20, 0, 0)]);
+print(path.pointAt(0.5).Y);
+// → 5
+```
+
+Parameters run from 0 to 1. Each span gets an equal share of that range. Equal parameter steps need not cover equal distances. Open curves clamp parameters and distances at their ends.
+
+All curve functions are arrow properties. Luau callers use `.`, such as `path.pointAt(0.5)` and `path.length()`. You can detach these functions without binding a receiver.
+
+## Choose a curve
+
+### Catmull-Rom
+
+`catmullRom` passes through its points. `alpha` controls the knot spacing. The default is centripetal, `0.5`. Use `0` for uniform spacing or `1` for chordal spacing.
+
+```ts
+import { catmullRom } from "@trioforge/spline";
+
+const path = catmullRom([new Vector2(0, 0), new Vector2(4, 8), new Vector2(12, 0)], { alpha: 0.5 });
+print(path.pointAt(0.5).Y);
+// → 8
+```
+
+Adjacent duplicate points coalesce. A single point makes a constant curve with zero length.
+
+### Cubic Bezier
+
+`cubicBezier` uses an anchor, two handles, and an anchor for each span. Open curves need `3n + 1` controls. Adjacent spans share their anchor.
+
+```ts
+import { cubicBezier } from "@trioforge/spline";
+
+const path = cubicBezier([new Vector3(0, 0, 0), new Vector3(0, 4, 0), new Vector3(6, 4, 0), new Vector3(6, 0, 0)]);
+print(path.pointAt(0.5).Y);
+// → 3
+```
+
+### Uniform B-spline
+
+`uniformBSpline` approximates its controls. An open curve needs at least four controls and usually does not pass through its endpoints.
+
+```ts
+import { uniformBSpline } from "@trioforge/spline";
+
+const path = uniformBSpline([new Vector3(0, 0, 0), new Vector3(3, 0, 0), new Vector3(6, 0, 0), new Vector3(9, 0, 0)]);
+print(path.pointAt(0).X);
+// → 3
+print(path.pointAt(1).X);
+// → 6
+```
+
+## Move at an even speed
+
+Convert elapsed time to a distance in studs. Pass that distance to `parameterAtDistance` before sampling. The distance table builds on its first use and stays cached.
+
+```ts
+import { cubicBezier } from "@trioforge/spline";
+
+const path = cubicBezier([new Vector3(0, 0, 0), new Vector3(0.5, 0, 0), new Vector3(1, 0, 0), new Vector3(10, 0, 0)]);
+const speed = 5;
+const elapsed = 1;
+const parameter = path.parameterAtDistance(speed * elapsed);
+const position = path.pointAt(parameter);
+print(math.abs(position.X - 5) < 0.001);
+// → true
+print(math.abs(path.distanceAtParameter(parameter) - 5) < 0.001);
+// → true
+```
+
+Call this conversion with the current elapsed time on each update. `length()` returns the total distance along the curve.
+
+## Orient along a path
+
+`frameAt` returns a point, a unit tangent, and a unit normal. Spatial frames minimize rotation along the path. Set `initialNormal` to choose the starting roll. By default the first normal points toward world up. If the path starts straight up or down, or `initialNormal` is zero or parallel to the tangent, it falls back to the world axis least aligned with the tangent.
+
+This matrix points the object's local negative Z axis along the tangent. Its local Y axis follows the normal.
+
+```ts
+import { catmullRom } from "@trioforge/spline";
+
+const path = catmullRom([new Vector3(0, 0, 0), new Vector3(10, 0, 0)], { initialNormal: new Vector3(0, 1, 0) });
+const frame = path.frameAt(0.5);
+if (frame !== undefined) {
+	const right = frame.tangent.Cross(frame.normal);
+	const pose = CFrame.fromMatrix(frame.point, right, frame.normal, frame.tangent.mul(-1));
+	print(pose.LookVector.Dot(frame.tangent) > 0.999);
+	// → true
+}
+```
+
+`tangentAt` and `frameAt` return `undefined` at stationary points. For `Vector2` curves, the normal is the tangent's left perpendicular. Frames build their spatial lookup table on first use.
+
+## Snap to a path
+
+`closest` searches the whole curve. Its `distance` is the distance along the curve. Its `separation` is the straight-line gap to your query.
+
+```ts
+import { catmullRom } from "@trioforge/spline";
+
+const path = catmullRom([new Vector3(0, 0, 0), new Vector3(10, 0, 0)]);
+const found = path.closest(new Vector3(4, 3, 0));
+print(math.abs(found.point.X - 4) < 0.001);
+// → true
+print(math.abs(found.separation - 3) < 0.001);
+// → true
+const ahead = path.pointAt(path.parameterAtDistance(found.distance + 2));
+print(math.abs(ahead.X - 6) < 0.001);
+// → true
+```
+
+`CurveProjection` also returns the `parameter` at the closest point.
+
+## Close a loop
+
+Set `closed` to wrap parameters and distances. Do not repeat the first point at the end. Catmull-Rom drops a repeated last point, but Bezier and B-spline curves count it as another control, which changes the shape or fails the control count. Catmull-Rom needs at least three points after adjacent duplicates coalesce, unless the loop is constant. Closed B-splines need at least three controls. Closed Beziers need `3n` controls, with the last two handles leading back to the first anchor.
+
+```ts
+import { catmullRom } from "@trioforge/spline";
+
+const loop = catmullRom(
+	[new Vector3(0, 0, 0), new Vector3(10, 0, 0), new Vector3(10, 10, 0), new Vector3(0, 10, 0)],
+	{ closed: true },
+);
+print(loop.pointAt(1) === loop.pointAt(0));
+// → true
+print(loop.pointAt(-0.25) === loop.pointAt(0.75));
+// → true
+print(loop.parameterAtDistance(loop.length()));
+// → 0
+```
+
+Closed spatial frames distribute their roll correction along the loop to meet at the seam. Bezier handles determine whether a join's tangent is continuous.
+
+## Types and validation
+
+The package exports `Curve`, `CurveFrame`, `CurveProjection`, `CurveOptions`, `CatmullRomOptions`, and `CurveVector`. A curve preserves its input dimension. `initialNormal` applies only to `Vector3` curves.
+
+Constructors reject empty inputs, mixed dimensions, non-finite points, invalid control counts, and `alpha` values outside 0 to 1. Queries reject non-finite parameters, distances, and points.
+
+## Development
+
+Install Node dependencies with `pnpm install`. Install Lune and StyLua with `rokit install`.
+
+```sh
+pnpm run check
+pnpm run test
+pnpm run examples README.md
+npm pack --dry-run
+```
+
+`check` runs oxfmt, rbxtsc, StyLua, the behavior tests, and every TypeScript example in this README. Tests load the compiled package in `out/` through roblox-ts's runtime. They compare behavior against dense sampling and hand-computed references. See [AGENTS.md](AGENTS.md) for contributor rules.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/out/curve.d.ts

@@ -0,0 +1,34 @@
+export type CurveVector = Vector2 | Vector3;
+export interface CurveFrame<V extends CurveVector> {
+    readonly point: V;
+    readonly tangent: V;
+    readonly normal: V;
+}
+export interface CurveProjection<V extends CurveVector> {
+    readonly parameter: number;
+    readonly point: V;
+    readonly distance: number;
+    readonly separation: number;
+}
+export interface CurveOptions<V extends CurveVector> {
+    readonly closed?: boolean;
+    readonly initialNormal?: V extends Vector3 ? Vector3 : never;
+}
+export interface CatmullRomOptions<V extends CurveVector> extends CurveOptions<V> {
+    readonly alpha?: number;
+}
+export interface Curve<V extends CurveVector> {
+    readonly pointAt: (parameter: number) => V;
+    readonly tangentAt: (parameter: number) => V | undefined;
+    readonly frameAt: (parameter: number) => CurveFrame<V> | undefined;
+    readonly length: () => number;
+    readonly parameterAtDistance: (distance: number) => number;
+    readonly distanceAtParameter: (parameter: number) => number;
+    readonly closest: (query: V) => CurveProjection<V>;
+}
+export declare function catmullRom(points: readonly Vector2[], options?: CatmullRomOptions<Vector2>): Curve<Vector2>;
+export declare function catmullRom(points: readonly Vector3[], options?: CatmullRomOptions<Vector3>): Curve<Vector3>;
+export declare function cubicBezier(points: readonly Vector2[], options?: CurveOptions<Vector2>): Curve<Vector2>;
+export declare function cubicBezier(points: readonly Vector3[], options?: CurveOptions<Vector3>): Curve<Vector3>;
+export declare function uniformBSpline(points: readonly Vector2[], options?: CurveOptions<Vector2>): Curve<Vector2>;
+export declare function uniformBSpline(points: readonly Vector3[], options?: CurveOptions<Vector3>): Curve<Vector3>;

package/out/curve.luau

@@ -0,0 +1,855 @@
+-- Compiled with roblox-ts v3.0.0
+-- Arrow properties compile to dot calls, so Luau callers write curve.pointAt(t) and can detach them.
+local build, catmullRomSpans
+local function catmullRom(points, options)
+	if options == nil then
+		options = {}
+	end
+	local _condition = options.alpha
+	if _condition == nil then
+		_condition = 0.5
+	end
+	local alpha = _condition
+	if not (alpha >= 0 and alpha <= 1) then
+		error(`a Catmull-Rom alpha must be from 0 to 1, got {alpha}`)
+	end
+	return build(points, options, function(lifted, closed)
+		return catmullRomSpans(lifted, closed, alpha)
+	end)
+end
+local bezierSpans
+local function cubicBezier(points, options)
+	if options == nil then
+		options = {}
+	end
+	return build(points, options, bezierSpans)
+end
+local bSplineSpans
+local function uniformBSpline(points, options)
+	if options == nil then
+		options = {}
+	end
+	return build(points, options, bSplineSpans)
+end
+local UP = Vector3.new(0, 1, 0)
+local AXES = { Vector3.new(1, 0, 0), UP, Vector3.new(0, 0, 1) }
+local LENGTH_DEPTH = 40
+local FRAME_DEPTH = 10
+local FRAME_TURN = math.cos(math.rad(5))
+local SEARCH_BUDGET = 20000
+local GAUSS_INNER = math.sqrt(5 - 2 * math.sqrt(10 / 7)) / 3
+local GAUSS_OUTER = math.sqrt(5 + 2 * math.sqrt(10 / 7)) / 3
+local GAUSS = { { 0, 128 / 225 }, { GAUSS_INNER, (322 + 13 * math.sqrt(70)) / 900 }, { -GAUSS_INNER, (322 + 13 * math.sqrt(70)) / 900 }, { GAUSS_OUTER, (322 - 13 * math.sqrt(70)) / 900 }, { -GAUSS_OUTER, (322 - 13 * math.sqrt(70)) / 900 } }
+local function finite(value)
+	return math.abs(value) < math.huge
+end
+local function liftPlanar(point)
+	local _point = point
+	if not (typeof(_point) == "Vector2") then
+		error("a Vector2 curve takes only Vector2 points")
+	end
+	if not finite(point.X) or not finite(point.Y) then
+		error("curve points must be finite")
+	end
+	return Vector3.new(point.X, point.Y, 0)
+end
+local function lowerPlanar(point)
+	return Vector2.new(point.X, point.Y)
+end
+local function liftSpatial(point)
+	local _point = point
+	if not (typeof(_point) == "Vector3") then
+		error("a Vector3 curve takes only Vector3 points")
+	end
+	if not finite(point.X) or not finite(point.Y) or not finite(point.Z) then
+		error("curve points must be finite")
+	end
+	return point
+end
+local function keepSpatial(point)
+	return point
+end
+local createCurve, shape
+function build(points, options, toSpans)
+	if #points == 0 then
+		error("a curve needs at least one point")
+	end
+	local _condition = options.closed
+	if _condition == nil then
+		_condition = false
+	end
+	local closed = _condition
+	local initialNormal = options.initialNormal
+	local _arg0 = points[1]
+	if typeof(_arg0) == "Vector2" then
+		if initialNormal ~= nil then
+			error("initialNormal applies only to Vector3 curves")
+		end
+		local _fn = toSpans
+		-- ▼ ReadonlyArray.map ▼
+		local _newValue = table.create(#points)
+		for _k, _v in points do
+			_newValue[_k] = liftPlanar(_v, _k - 1, points)
+		end
+		-- ▲ ReadonlyArray.map ▲
+		return createCurve(shape(_fn(_newValue, closed), closed, true), liftPlanar, lowerPlanar)
+	end
+	local seed = if initialNormal == nil then nil else liftSpatial(initialNormal)
+	local _fn = toSpans
+	-- ▼ ReadonlyArray.map ▼
+	local _newValue = table.create(#points)
+	for _k, _v in points do
+		_newValue[_k] = liftSpatial(_v, _k - 1, points)
+	end
+	-- ▲ ReadonlyArray.map ▲
+	return createCurve(shape(_fn(_newValue, closed), closed, false, seed), liftSpatial, keepSpatial)
+end
+function shape(spans, closed, planar, initialNormal)
+	local low = spans[1][1]
+	local high = low
+	for _, span in spans do
+		for _1, control in span do
+			if not finite(control.X) or not finite(control.Y) or not finite(control.Z) then
+				error("the curve's controls overflow")
+			end
+			low = low:Min(control)
+			high = high:Max(control)
+		end
+	end
+	local _object = {
+		spans = spans,
+		closed = closed,
+		planar = planar,
+		initialNormal = initialNormal,
+	}
+	local _left = "tolerance"
+	local _high = high
+	local _low = low
+	_object[_left] = math.max(1e-4, 1e-5 * (_high - _low).Magnitude)
+	return _object
+end
+function catmullRomSpans(input, closed, alpha)
+	-- ▼ ReadonlyArray.filter ▼
+	local _newValue = {}
+	local _callback = function(point, index)
+		return index == 0 or point ~= input[index]
+	end
+	local _length = 0
+	for _k, _v in input do
+		if _callback(_v, _k - 1, input) == true then
+			_length += 1
+			_newValue[_length] = _v
+		end
+	end
+	-- ▲ ReadonlyArray.filter ▲
+	local points = _newValue
+	if closed and #points > 1 and points[#points] == points[1] then
+		points[#points] = nil
+	end
+	local count = #points
+	if count == 1 then
+		return { { points[1], points[1], points[1], points[1] } }
+	end
+	if closed and count < 3 then
+		error("a closed Catmull-Rom curve needs three distinct points")
+	end
+	local at = function(index)
+		if closed then
+			return points[(index + count) % count + 1]
+		end
+		if index < 0 then
+			local _exp = points[1] * 2
+			local _arg0 = points[2]
+			return _exp - _arg0
+		end
+		if index >= count then
+			local _exp = points[count] * 2
+			local _arg0 = points[count - 1]
+			return _exp - _arg0
+		end
+		return points[index + 1]
+	end
+	local span = function(index)
+		local p0, p1, p2, p3 = at(index - 1), at(index), at(index + 1), at(index + 2)
+		local d01 = (p1 - p0).Magnitude ^ alpha
+		local d12 = (p2 - p1).Magnitude ^ alpha
+		local d23 = (p3 - p2).Magnitude ^ alpha
+		local _exp = (p1 - p0) / d01
+		local _exp_1 = p2 - p0
+		local _arg0 = d01 + d12
+		local _arg0_1 = (p2 - p1) / d12
+		local m1 = _exp - (_exp_1 / _arg0) + _arg0_1
+		local _exp_2 = (p2 - p1) / d12
+		local _exp_3 = p3 - p1
+		local _arg0_2 = d12 + d23
+		local _arg0_3 = (p3 - p2) / d23
+		local m2 = _exp_2 - (_exp_3 / _arg0_2) + _arg0_3
+		local _arg0_4 = d12 / 3
+		local _arg0_5 = m1 * _arg0_4
+		local _exp_4 = p1 + _arg0_5
+		local _arg0_6 = d12 / 3
+		local _arg0_7 = m2 * _arg0_6
+		return { p1, _exp_4, p2 - _arg0_7, p2 }
+	end
+	local spans = { span(0) }
+	for index = 1, (if closed then count else count - 1) - 1 do
+		local _arg0 = span(index)
+		table.insert(spans, _arg0)
+	end
+	return spans
+end
+function bezierSpans(points, closed)
+	local count = #points
+	if if closed then count % 3 ~= 0 else count < 4 or count % 3 ~= 1 then
+		error(`a {if closed then "closed cubic Bezier needs 3n" else "cubic Bezier needs 3n + 1"} points, got {count}`)
+	end
+	local span = function(start)
+		return { points[start + 1], points[start + 2], points[start + 3], points[(start + 3) % count + 1] }
+	end
+	local spans = { span(0) }
+	for index = 1, math.floor(count / 3) - 1 do
+		local _arg0 = span(index * 3)
+		table.insert(spans, _arg0)
+	end
+	return spans
+end
+function bSplineSpans(points, closed)
+	local count = #points
+	local least = if closed then 3 else 4
+	if count < least then
+		error(`a {if closed then "closed " else ""}uniform B-spline needs {least} points, got {count}`)
+	end
+	local at = function(index)
+		return points[(if closed then (index + count - 1) % count else index) + 1]
+	end
+	local thirdOrSame = function(near, far)
+		local _result
+		if near == far then
+			_result = near
+		else
+			local _exp = near * 2
+			local _far = far
+			_result = (_exp + _far) / 3
+		end
+		return _result
+	end
+	local jointOrSame = function(a, b, c)
+		local _result
+		if a == b and b == c then
+			_result = b
+		else
+			local _a = a
+			local _arg0 = b * 4
+			local _c = c
+			_result = (_a + _arg0 + _c) / 6
+		end
+		return _result
+	end
+	local span = function(index)
+		local q0, q1, q2, q3 = at(index), at(index + 1), at(index + 2), at(index + 3)
+		return { jointOrSame(q0, q1, q2), thirdOrSame(q1, q2), thirdOrSame(q2, q1), jointOrSame(q1, q2, q3) }
+	end
+	local spans = { span(0) }
+	for index = 1, (if closed then count else count - 3) - 1 do
+		local _arg0 = span(index)
+		table.insert(spans, _arg0)
+	end
+	return spans
+end
+local function locate(geometry, parameter)
+	local count = #geometry.spans
+	local wrapped = if geometry.closed then parameter - math.floor(parameter) else math.clamp(parameter, 0, 1)
+	local scaled = wrapped * count
+	local index = math.min(math.floor(scaled), count - 1)
+	return {
+		index = index,
+		span = geometry.spans[index + 1],
+		u = scaled - index,
+	}
+end
+local function bernstein(_param, u)
+	local a = _param[1]
+	local b = _param[2]
+	local c = _param[3]
+	local d = _param[4]
+	local v = 1 - u
+	local _arg0 = v * v * v
+	local _exp = a * _arg0
+	local _arg0_1 = 3 * v * v * u
+	local _arg0_2 = b * _arg0_1
+	local _arg0_3 = 3 * v * u * u
+	local _arg0_4 = c * _arg0_3
+	local _arg0_5 = u * u * u
+	local _arg0_6 = d * _arg0_5
+	return _exp + _arg0_2 + _arg0_4 + _arg0_6
+end
+local function velocity(_param, u)
+	local a = _param[1]
+	local b = _param[2]
+	local c = _param[3]
+	local d = _param[4]
+	local v = 1 - u
+	local _exp = b - a
+	local _arg0 = 3 * v * v
+	local _exp_1 = c - b
+	local _arg0_1 = 6 * v * u
+	local _exp_2 = d - c
+	local _arg0_2 = 3 * u * u
+	return _exp * _arg0 + (_exp_1 * _arg0_1) + (_exp_2 * _arg0_2)
+end
+local function acceleration(_param, u)
+	local a = _param[1]
+	local b = _param[2]
+	local c = _param[3]
+	local d = _param[4]
+	local _arg0 = b * 2
+	local _exp = c - _arg0 + a
+	local _arg0_1 = 6 * (1 - u)
+	local _arg0_2 = c * 2
+	local _exp_1 = d - _arg0_2 + b
+	local _arg0_3 = 6 * u
+	return _exp * _arg0_1 + (_exp_1 * _arg0_3)
+end
+local function direction(vector)
+	local size = vector.Magnitude
+	return if size > 0 then vector / size else nil
+end
+local function travel(span, from, to)
+	local half = (to - from) / 2
+	local middle = (from + to) / 2
+	local sum = 0
+	for _, _binding in GAUSS do
+		local node = _binding[1]
+		local weight = _binding[2]
+		sum += weight * velocity(span, middle + half * node).Magnitude
+	end
+	return sum * half
+end
+local function measure(geometry)
+	local count = #geometry.spans
+	local length = 0
+	local _exp = geometry.spans
+	-- ▼ ReadonlyArray.map ▼
+	local _newValue = table.create(#_exp)
+	local _callback = function(span)
+		local stops = { 0 }
+		local distances = { length }
+		local visit
+		visit = function(from, to, whole, depth)
+			local middle = (from + to) / 2
+			local left = travel(span, from, middle)
+			local right = travel(span, middle, to)
+			local allowed = math.max((geometry.tolerance * (to - from)) / count, 1e-6 * whole)
+			if depth >= 2 and math.abs(left + right - whole) <= allowed then
+				length += left + right
+				local _to = to
+				table.insert(stops, _to)
+				local _length = length
+				table.insert(distances, _length)
+				return nil
+			end
+			if depth >= LENGTH_DEPTH then
+				error("a curve span is too irregular to measure")
+			end
+			visit(from, middle, left, depth + 1)
+			visit(middle, to, right, depth + 1)
+		end
+		visit(0, 1, travel(span, 0, 1), 0)
+		return {
+			stops = stops,
+			distances = distances,
+		}
+	end
+	for _k, _v in _exp do
+		_newValue[_k] = _callback(_v, _k - 1, _exp)
+	end
+	-- ▲ ReadonlyArray.map ▲
+	local spans = _newValue
+	local _object = {
+		spans = spans,
+	}
+	local _left = "ends"
+	-- ▼ ReadonlyArray.map ▼
+	local _newValue_1 = table.create(#spans)
+	local _callback_1 = function(_param)
+		local distances = _param.distances
+		return distances[#distances]
+	end
+	for _k, _v in spans do
+		_newValue_1[_k] = _callback_1(_v, _k - 1, spans)
+	end
+	-- ▲ ReadonlyArray.map ▲
+	_object[_left] = _newValue_1
+	_object.length = length
+	return _object
+end
+local function lastAtMost(values, value)
+	local low = 0
+	local high = #values - 1
+	while low < high do
+		local middle = math.ceil((low + high) / 2)
+		if values[middle + 1] <= value then
+			low = middle
+		else
+			high = middle - 1
+		end
+	end
+	return low
+end
+local function firstAtLeast(values, value, from)
+	if from == nil then
+		from = 0
+	end
+	local low = from
+	local high = #values - 1
+	while low < high do
+		local middle = math.floor((low + high) / 2)
+		if values[middle + 1] >= value then
+			high = middle
+		else
+			low = middle + 1
+		end
+	end
+	return low
+end
+local function distanceAt(arc, at)
+	local _binding = arc.spans[at.index + 1]
+	local stops = _binding.stops
+	local distances = _binding.distances
+	local station = lastAtMost(stops, at.u)
+	if stops[station + 1] == at.u then
+		return distances[station + 1]
+	end
+	return distances[station + 1] + travel(at.span, stops[station + 1], at.u)
+end
+local function parameterAt(geometry, arc, distance)
+	local total = arc.length
+	if geometry.closed then
+		distance -= math.floor(distance / total) * total
+	end
+	if not (distance > 0 and distance < total) then
+		return if geometry.closed or distance <= 0 then 0 else 1
+	end
+	local count = #geometry.spans
+	local index = firstAtLeast(arc.ends, distance)
+	local span = geometry.spans[index + 1]
+	local _binding = arc.spans[index + 1]
+	local stops = _binding.stops
+	local distances = _binding.distances
+	local station = firstAtLeast(distances, distance, 1) - 1
+	local from = stops[station + 1]
+	local start = distances[station + 1]
+	local run = distances[station + 2] - start
+	local low = from
+	local high = stops[station + 2]
+	local u = if run > 0 then low + ((high - low) * (distance - start)) / run else low
+	do
+		local step = 0
+		local _shouldIncrement = false
+		while true do
+			if _shouldIncrement then
+				step += 1
+			else
+				_shouldIncrement = true
+			end
+			if not (step < 40 and high - low > 1e-12) then
+				break
+			end
+			local miss = start + travel(span, from, u) - distance
+			if math.abs(miss) <= geometry.tolerance * 1e-2 then
+				break
+			end
+			if miss > 0 then
+				high = u
+			else
+				low = u
+			end
+			local speed = velocity(span, u).Magnitude
+			local stepped = if speed > 0 then u - miss / speed else low
+			u = if stepped > low and stepped < high then stepped else (low + high) / 2
+		end
+	end
+	return (index + u) / count
+end
+local function perpendicular(vector, tangent)
+	local _vector = vector
+	local _tangent = tangent
+	local _arg0 = tangent:Dot(vector)
+	local flat = _vector - (_tangent * _arg0)
+	local size = flat.Magnitude
+	return if size > 1e-4 * vector.Magnitude then flat / size else nil
+end
+local function seed(tangent, preferred)
+	if preferred == nil then
+		preferred = UP
+	end
+	local normal = perpendicular(preferred, tangent)
+	if normal ~= nil then
+		return normal
+	end
+	local axis = AXES[1]
+	for _, candidate in AXES do
+		if math.abs(candidate:Dot(tangent)) < math.abs(axis:Dot(tangent)) then
+			axis = candidate
+		end
+	end
+	local _axis = axis
+	local _tangent = tangent
+	local _arg0 = tangent:Dot(axis)
+	return (_axis - (_tangent * _arg0)).Unit
+end
+local function minimalRotation(from, to, normal)
+	local _from = from
+	local _to = to
+	local sum = _from + _to
+	local size = sum:Dot(sum)
+	if size <= 1e-12 then
+		return normal
+	end
+	local _normal = normal
+	local _from_1 = from
+	local _arg0 = 2 * from:Dot(normal)
+	local flipped = _normal - (_from_1 * _arg0)
+	local _arg0_1 = (2 * sum:Dot(flipped)) / size
+	local _arg0_2 = sum * _arg0_1
+	return flipped - _arg0_2
+end
+local function transport(from, point, tangent, tolerance)
+	local _point = point
+	local _point_1 = from.point
+	local chord = _point - _point_1
+	local c1 = chord:Dot(chord)
+	local normal
+	if c1 <= (tolerance * 1e-3) ^ 2 then
+		normal = minimalRotation(from.tangent, tangent, from.normal)
+	else
+		local _normal = from.normal
+		local _arg0 = (2 * chord:Dot(from.normal)) / c1
+		local _arg0_1 = chord * _arg0
+		local reflectedNormal = _normal - _arg0_1
+		local _tangent = from.tangent
+		local _arg0_2 = (2 * chord:Dot(from.tangent)) / c1
+		local _arg0_3 = chord * _arg0_2
+		local reflectedTangent = _tangent - _arg0_3
+		local second = tangent - reflectedTangent
+		local c2 = second:Dot(second)
+		local _result
+		if c2 > 0 then
+			local _arg0_4 = (2 * second:Dot(reflectedNormal)) / c2
+			local _arg0_5 = second * _arg0_4
+			_result = reflectedNormal - _arg0_5
+		else
+			_result = reflectedNormal
+		end
+		normal = _result
+	end
+	return perpendicular(normal, tangent) or seed(tangent, from.normal)
+end
+local function frameStops(span)
+	local stops = { 0 }
+	local turns = function(a, b)
+		return if a == nil or b == nil then a ~= b else a:Dot(b) < FRAME_TURN
+	end
+	local visit
+	visit = function(from, fromTangent, to, toTangent, depth)
+		local middle = (from + to) / 2
+		local middleTangent = direction(velocity(span, middle))
+		if depth < FRAME_DEPTH and (depth < 2 or turns(fromTangent, middleTangent) or turns(middleTangent, toTangent)) then
+			visit(from, fromTangent, middle, middleTangent, depth + 1)
+			visit(middle, middleTangent, to, toTangent, depth + 1)
+		else
+			local _to = to
+			table.insert(stops, _to)
+		end
+	end
+	visit(0, direction(velocity(span, 0)), 1, direction(velocity(span, 1)), 0)
+	return stops
+end
+local function transportFrames(geometry)
+	local spanPositions = {}
+	local stations = {}
+	local _exp = geometry.spans
+	-- ▼ ReadonlyArray.forEach ▼
+	local _callback = function(span, index)
+		for _, u in frameStops(span) do
+			local tangent = direction(velocity(span, u))
+			if tangent == nil then
+				continue
+			end
+			local point = bernstein(span, u)
+			local normal = if #stations == 0 then seed(tangent, geometry.initialNormal) else transport(stations[#stations], point, tangent, geometry.tolerance)
+			local _arg0 = index + u
+			table.insert(spanPositions, _arg0)
+			local _arg0_1 = {
+				point = point,
+				tangent = tangent,
+				normal = normal,
+			}
+			table.insert(stations, _arg0_1)
+		end
+	end
+	for _k, _v in _exp do
+		_callback(_v, _k - 1, _exp)
+	end
+	-- ▲ ReadonlyArray.forEach ▲
+	local count = #geometry.spans
+	local first = stations[1]
+	local last = stations[#stations]
+	local seamRoll = 0
+	if geometry.closed and #stations > 0 and spanPositions[1] == 0 and spanPositions[#spanPositions] == count then
+		local arrived = minimalRotation(last.tangent, first.tangent, last.normal)
+		seamRoll = math.atan2(first.tangent:Dot(arrived:Cross(first.normal)), arrived:Dot(first.normal))
+	end
+	return {
+		spanPositions = spanPositions,
+		stations = stations,
+		seamRoll = seamRoll,
+	}
+end
+local function spatialNormal(geometry, frames, at, point, tangent)
+	if #frames.stations == 0 then
+		return seed(tangent, geometry.initialNormal)
+	end
+	local station = frames.stations[lastAtMost(frames.spanPositions, at.index + at.u) + 1]
+	return transport(station, point, tangent, geometry.tolerance)
+end
+local function roll(normal, axis, angle)
+	local _normal = normal
+	local _arg0 = math.cos(angle)
+	local _exp = axis:Cross(normal)
+	local _arg0_1 = math.sin(angle)
+	return _normal * _arg0 + (_exp * _arg0_1)
+end
+local function halve(_param)
+	local a = _param[1]
+	local b = _param[2]
+	local c = _param[3]
+	local d = _param[4]
+	local ab = (a + b) * 0.5
+	local bc = (b + c) * 0.5
+	local cd = (c + d) * 0.5
+	local abc = (ab + bc) * 0.5
+	local bcd = (bc + cd) * 0.5
+	local middle = (abc + bcd) * 0.5
+	return { { a, ab, abc, middle }, { middle, bcd, cd, d } }
+end
+local function boxGap(_param, query)
+	local a = _param[1]
+	local b = _param[2]
+	local c = _param[3]
+	local d = _param[4]
+	local _query = query
+	local _arg0 = query:Max(a:Min(b, c, d)):Min(a:Max(b, c, d))
+	return (_query - _arg0).Magnitude
+end
+local refineClosest
+local function nearest(geometry, query)
+	local tolerance = geometry.tolerance
+	local _object = {
+		index = 0,
+		u = 0,
+	}
+	local _left = "separation"
+	local _exp = geometry.spans[1][1]
+	local _query = query
+	_object[_left] = (_exp - _query).Magnitude
+	local best = _object
+	local offer = function(index, u, point)
+		local _point = point
+		local _query_1 = query
+		local separation = (_point - _query_1).Magnitude
+		if separation < best.separation or (separation == best.separation and index + u < best.index + best.u) then
+			best = {
+				index = index,
+				u = u,
+				separation = separation,
+			}
+		end
+	end
+	local pieces = {}
+	local _exp_1 = geometry.spans
+	-- ▼ ReadonlyArray.forEach ▼
+	local _callback = function(span, index)
+		offer(index, 1, span[4])
+		local _arg0 = {
+			index = index,
+			controls = span,
+			from = 0,
+			to = 1,
+			bound = boxGap(span, query),
+		}
+		table.insert(pieces, _arg0)
+	end
+	for _k, _v in _exp_1 do
+		_callback(_v, _k - 1, _exp_1)
+	end
+	-- ▲ ReadonlyArray.forEach ▲
+	do
+		local step = 0
+		local _shouldIncrement = false
+		while true do
+			if _shouldIncrement then
+				step += 1
+			else
+				_shouldIncrement = true
+			end
+			if not (#pieces > 0) then
+				break
+			end
+			local chosen = 0
+			-- ▼ ReadonlyArray.forEach ▼
+			local _callback_1 = function(piece, position)
+				if piece.bound < pieces[chosen + 1].bound then
+					chosen = position
+				end
+			end
+			for _k, _v in pieces do
+				_callback_1(_v, _k - 1, pieces)
+			end
+			-- ▲ ReadonlyArray.forEach ▲
+			local piece = pieces[chosen + 1]
+			pieces[chosen + 1] = pieces[#pieces]
+			pieces[#pieces] = nil
+			if piece.bound >= best.separation - tolerance then
+				break
+			end
+			if step >= SEARCH_BUDGET then
+				error("the closest point search did not converge")
+			end
+			local middle = (piece.from + piece.to) / 2
+			local _binding = halve(piece.controls)
+			local left = _binding[1]
+			local right = _binding[2]
+			offer(piece.index, middle, left[4])
+			for _, _binding_1 in { { left, piece.from, middle }, { right, middle, piece.to } } do
+				local controls = _binding_1[1]
+				local from = _binding_1[2]
+				local to = _binding_1[3]
+				local bound = boxGap(controls, query)
+				if bound < best.separation - tolerance then
+					local _arg0 = {
+						index = piece.index,
+						controls = controls,
+						from = from,
+						to = to,
+						bound = bound,
+					}
+					table.insert(pieces, _arg0)
+				end
+			end
+		end
+	end
+	return refineClosest(geometry.spans[best.index + 1], query, best)
+end
+function refineClosest(span, query, found)
+	local best = found
+	local u = best.u
+	for step = 0, 7 do
+		local _exp = bernstein(span, u)
+		local _query = query
+		local offset = _exp - _query
+		local speed = velocity(span, u)
+		local slope = speed:Dot(speed) + offset:Dot(acceleration(span, u))
+		if not (slope > 0) then
+			break
+		end
+		u = math.clamp(u - offset:Dot(speed) / slope, 0, 1)
+		local _exp_1 = bernstein(span, u)
+		local _query_1 = query
+		local separation = (_exp_1 - _query_1).Magnitude
+		if not (separation < best.separation) then
+			break
+		end
+		best = {
+			index = best.index,
+			u = u,
+			separation = separation,
+		}
+	end
+	return best
+end
+function createCurve(geometry, lift, lower)
+	local arc
+	local frames
+	local measured = function()
+		if arc == nil then
+			arc = measure(geometry)
+		end
+		return arc
+	end
+	local locateChecked = function(parameter)
+		if not finite(parameter) then
+			error("curve parameters must be finite")
+		end
+		return locate(geometry, parameter)
+	end
+	return {
+		pointAt = function(parameter)
+			local at = locateChecked(parameter)
+			return lower(bernstein(at.span, at.u))
+		end,
+		tangentAt = function(parameter)
+			local at = locateChecked(parameter)
+			local tangent = direction(velocity(at.span, at.u))
+			return if tangent == nil then nil else lower(tangent)
+		end,
+		frameAt = function(parameter)
+			local at = locateChecked(parameter)
+			local tangent = direction(velocity(at.span, at.u))
+			if tangent == nil then
+				return nil
+			end
+			local point = bernstein(at.span, at.u)
+			local normal
+			if geometry.planar then
+				normal = Vector3.new(-tangent.Y, tangent.X, 0)
+			else
+				if frames == nil then
+					frames = transportFrames(geometry)
+				end
+				normal = spatialNormal(geometry, frames, at, point, tangent)
+				if frames.seamRoll ~= 0 then
+					local share = distanceAt(measured(), at) / measured().length
+					normal = roll(normal, tangent, frames.seamRoll * share)
+				end
+			end
+			return {
+				point = lower(point),
+				tangent = lower(tangent),
+				normal = lower(normal),
+			}
+		end,
+		length = function()
+			return measured().length
+		end,
+		parameterAtDistance = function(distance)
+			if not finite(distance) then
+				error("curve distances must be finite")
+			end
+			local lengths = measured()
+			return if lengths.length > 0 then parameterAt(geometry, lengths, distance) else 0
+		end,
+		distanceAtParameter = function(parameter)
+			return distanceAt(measured(), locateChecked(parameter))
+		end,
+		closest = function(query)
+			local target = lift(query)
+			local found = nearest(geometry, target)
+			local count = #geometry.spans
+			local parameter = if geometry.closed and found.index + found.u >= count then 0 else (found.index + found.u) / count
+			local at = locate(geometry, parameter)
+			local point = bernstein(at.span, at.u)
+			return {
+				parameter = parameter,
+				point = lower(point),
+				distance = distanceAt(measured(), at),
+				separation = (point - target).Magnitude,
+			}
+		end,
+	}
+end
+return {
+	catmullRom = catmullRom,
+	cubicBezier = cubicBezier,
+	uniformBSpline = uniformBSpline,
+}

package/out/index.d.ts

@@ -0,0 +1,2 @@
+export { catmullRom, cubicBezier, uniformBSpline } from "./curve";
+export type { CatmullRomOptions, Curve, CurveFrame, CurveOptions, CurveProjection, CurveVector } from "./curve";

package/out/init.luau

@@ -0,0 +1,8 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local exports = {}
+local _curve = TS.import(script, script, "curve")
+exports.catmullRom = _curve.catmullRom
+exports.cubicBezier = _curve.cubicBezier
+exports.uniformBSpline = _curve.uniformBSpline
+return exports

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@trioforge/spline",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Catmull-Rom, cubic Bezier, and uniform B-spline curves for roblox-ts",
+  "keywords": [
+    "roblox",
+    "roblox-ts",
+    "spline",
+    "catmull-rom",
+    "bezier",
+    "b-spline"
+  ],
+  "homepage": "https://website.trio-forge.workers.dev/spline/",
+  "bugs": "https://github.com/Trio-Forge-Studio/packages/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Trio-Forge-Studio/packages.git",
+    "directory": "packages/spline"
+  },
+  "license": "MIT",
+  "main": "out/init.luau",
+  "types": "out/index.d.ts",
+  "files": [
+    "out",
+    "!**/*.tsbuildinfo",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@rbxts/compiler-types": "3.0.0-types.0",
+    "@rbxts/types": "^1.0.958",
+    "@trioforge/tooling": "0.0.0",
+    "roblox-ts": "^3.0.0",
+    "typescript": "5.5.3"
+  },
+  "scripts": {
+    "build": "rbxtsc --type package",
+    "test": "rbxtsc --type package && lune run test",
+    "check": "stylua --check test .lune && rbxtsc --type package && lune run test && pnpm run examples README.md",
+    "examples": "check-examples --run"
+  }
 }