curve

import curve from "curve";
import math3d from "math3d";

let c = curve.cubic_Vec2(math3d.vec2(0.0, 0.0), math3d.vec2(0.0, 4.0),
                         math3d.vec2(4.0, 4.0), math3d.vec2(4.0, 0.0));
let mid = c.at(0.5);                       // (2, 3)
let arc = c.arc();                         // distance -> parameter
let p = c.at(arc.param(2.5));              // 2.5 units along the curve

curve has the curves a game moves things along: Bézier segments, Hermite segments, Catmull-Rom splines through points, uniform B-splines, a table that turns distance along a curve into its parameter (so motion keeps an even speed), keyframe tracks, and sprite-sheet frame tracks. Everything is f32, on math3d’s vectors, and every value is plain (no heap): keep it in a var and copy it like a struct.

Each curve comes in four forms: f32, Vec2, Vec3 and Vec4, the type’s name at the end (cubic_f32, cubic_Vec3, Track_Vec4). Below, T stands for any of them.

Bézier segments

let c = curve.cubic_f32(0.0, 0.0, 10.0, 10.0);
let s = c.split(0.25);
// s.first runs 0..0.25 of c, s.second 0.25..1; s.first.p3 == s.second.p0
let q = curve.quadratic_Vec2(math3d.vec2(0.0, 0.0), math3d.vec2(2.0, 4.0), math3d.vec2(4.0, 0.0));
let top = q.at(0.5);                       // (2, 2)
let dir = q.tangent(0.0);                  // (4, 8)

A Cubic_T is the shape every cubic segment ends up in: the other kinds below are made into one, so at, tangent, split and arc work on all of them.

Hermite, Catmull-Rom and B-spline segments

alpha spaces Catmull-Rom’s knots: curve.UNIFORM (0), curve.CENTRIPETAL (0.5) or curve.CHORDAL (1). Centripetal is the one to use when points are unevenly spaced: it never makes a loop or a cusp inside a segment. Uniform is the classic Catmull-Rom (the tangent at a point is half the chord between its neighbours). Points on top of each other are fine.

A B-spline is smoother than Catmull-Rom but passes near its points, not through them.

let h = curve.hermite_f32(0.0, 3.0, 1.0, 3.0);   // leaves and arrives with slope 3
let seg = curve.catmull_rom_Vec2(a, b, c, d, curve.CENTRIPETAL);   // b to c

Splines through points

The spline functions take the points as a slice, []const T:

var path: [4]math3d.Vec2 = [math3d.vec2(0.0, 0.0), math3d.vec2(10.0, 5.0),
                            math3d.vec2(20.0, 0.0), math3d.vec2(30.0, 5.0)];
let at_second = curve.catmull_rom_at_Vec2(path[..], curve.CENTRIPETAL, 1.0);   // path[1]
let heading = curve.catmull_rom_segment_Vec2(path[..], 1, curve.CENTRIPETAL).tangent(0.5);

A Catmull-Rom spline goes through every point. Its first and last segment have no outer neighbour, so the next point is mirrored to stand in for it. A B-spline over n points starts near pts[1] and ends near pts[n - 2]; write a point three times to start or end exactly on it. A u outside the range is clamped. Too few points (fewer than 2 for Catmull-Rom, 4 for a B-spline) or a segment index out of range stops the program with a trap.

Arc length

A curve’s parameter is not distance: a point at t = 0.5 is not half way along, and stepping t evenly moves at an uneven speed. An ArcTable measures the curve (the lengths of 64 short chords along its whole parameter range) and maps back:

let arc = c.arc();
var s: f32 = 0.0;
while (s < arc.length()) {
    let p = c.at(arc.param(s));            // equal steps of s: an even speed
    s = s + 0.5;
}

The table is a plain value of 65 numbers: build it once, when the curve is made, and keep it beside the curve. It is a little under the true length (a quarter circle comes out 0.0025% short). For a spline of many segments, 64 chords spread thin: measure each segment’s arc() instead.

Keyframe tracks

A track is a value over time from keys: at each key a time (milliseconds, f32), a value, and how the value moves on to the next key. The keys are yours, as many as you like, in an array, a Vec or a loaded file; the track reads them where they are.

let keys = [curve.key_f32(0.0, 0.0, curve.Interp.Cubic),
            curve.key_f32(250.0, 40.0, curve.Interp.Cubic),
            curve.key_eased_f32(500.0, 10.0, easing.Ease.BounceOut),
            curve.key_f32(800.0, 0.0, curve.Interp.Step)];
let y = curve.track_f32(keys[..], curve.Wrap.Loop);
let now = y.at(clock_ms);                  // any time, in any order

curve.Interp is how a key moves on to the next one:

curve.Wrap is what a time before the first key or after the last gives:

w.fold(t, span) is the same folding on its own: a time t counted from the start, into 0..span (curve.Wrap.PingPong.fold(130.0, 100.0) is 70), for a clock of your own.

Keys go in time order. Two keys at the same time make a jump. A key earlier than the one before it, or at on a track with no keys, stops the program with a trap. The track keeps a view of your keys, not a copy: keep them alive as long as the track, and copying a track copies no keys.

A track is not a tween: a tween is played (you step it, it remembers where it is, it can repeat and retarget), while a track just answers “what is the value at this time” for whatever clock you keep. Many objects can share one track, each at its own time.

Sprite-sheet frames

A frame track says which frame of a sprite sheet to draw:

var walk = curve.frame_strip(8, 6, 80.0, curve.Wrap.Loop);   // frames 8..13, 80 ms each
let frame = walk.at(clock_ms);

let frames = [curve.frame(0, 2000.0),     // open for 2 s
              curve.frame(1, 100.0),      // closed briefly
              curve.frame(0, 100.0)];
let blink = curve.frame_track(frames[..], curve.Wrap.Clamp);

Clamp holds the last frame, Loop starts again, and PingPong runs back and forth without showing the end frames twice (4 5 6 7 6 5 4 5 …). at with no frames stops the program with a trap.

Your own types

gen_curve makes every function above for a type of your own: a struct with + and - of two values, * and / by an f32, and length() -> f32.

pub struct Pt { x: f32; y: f32; }
pub fn Pt.op_add(self, o: Pt) -> Pt { return Pt { x: self.x + o.x; y: self.y + o.y; }; }
pub fn Pt.op_sub(self, o: Pt) -> Pt { return Pt { x: self.x - o.x; y: self.y - o.y; }; }
pub fn Pt.op_mul(self, s: f32) -> Pt { return Pt { x: self.x * s; y: self.y * s; }; }
pub fn Pt.op_div(self, s: f32) -> Pt { return Pt { x: self.x / s; y: self.y / s; }; }
pub fn Pt.length(self) -> f32 { return @sqrt(self.x * self.x + self.y * self.y); }

@tape { curve.gen_curve(Pt); }             // cubic_Pt, Track_Pt, catmull_rom_at_Pt, ...

The struct must be pub, as for any generator.

Last modified: 2026-10-31 22:34:56 UTC