`AlignToSplineConstraint`

← prev index next →

Rides a node along a spline path by arc-length progress, optionally turning it to face the direction of travel — the way to move an object along an arbitrary 2D or 3D curve.

Declarative element: <sk-align-to-spline-constraint>

Not on the sk.* global — construct via the declarative element or a module import.

Remarks

This is the path-following member of the Constraint family: like every constraint it drives its constrained target — here the target's position, and its orientation when tangential — by recomputing from live scene state each frame, so the target keeps riding the curve even as the curve itself moves or morphs.

Key attributes. progress is arc-length position along the spline: 0 = the start, 1 = the end. A fractional value outside [0, 1] wraps by its fractional part (negative values count back from the end), while whole numbers 1, 2, 3… all rest at the end — so animating it 0 → 1 sweeps the whole path once. spline names the AbstractSpline to follow by #id — any sk-spline, sk-path-spline, or sk-points-spline. tangential turns the target so its +Y axis faces along the direction of travel (the path tangent); leave it off to keep the target's own orientation and only move its position. up-vector disambiguates roll about the tangent when tangential is on and usually needs no override (it defaults to world +Y).

Related. The spline it follows is any member of the AbstractSpline family. Sibling constraints in the Constraint family include sk-orbit-constraint (revolve around a pivot) and sk-target-at-constraint (aim an axis at a node); the GPU-parallel PointConstraint applies path-like displacement to many cloned points.

Constructor

constructor(config?: { spline?: AbstractSpline | string; progress?: number; tangential?: boolean; upVector?: [number, number, number] })

Inherited from: Constraint, SkenraAnimatable — see those pages for inherited members.

Properties

Config Properties

Property	Type	Default	Description	Declared by
`spline`animatable	`AbstractSpline \| string`	—	The spline this constraint positions its target along. The accessor	`AlignToSplineConstraint`
`progress`animatable	`number`	`0.0`	Position of the target along the spline, from 0 (start) to 1 (end).	`AlignToSplineConstraint`
`tangential`animatable	`boolean`	`false`	When true, the target aligns to the spline’s tangent direction.	`AlignToSplineConstraint`
`upVector`	`[number, number, number]`	`[0, 1, 0]`	Up vector used to disambiguate orientation during tangential alignment.	`AlignToSplineConstraint`

Other Properties

Property	Type	Default	Description	Declared by
`progressBase`base value	`number`	—	The base (non-animated) value of `progress`.	`AlignToSplineConstraint`
`target`read-only	`SkenraAnimatable \| null`	—	The node this constraint modifies.	`Constraint`
`priority`	`number`	—	Gets the priority for this modifier in the effect stack.	`Constraint`
`scene`read-only	`any`	—	Gets the Scene this animatable belongs to, if any.	`SkenraAnimatable`
`animations`read-only	`SkenraAnimation[]`	—	Public getter for the animations affecting this target.	`SkenraAnimatable`

Methods

Method	Description	Declared by
`animate(firstArg: TypedKeyframe<this>[] \| TypedPropertyIndexedKeyframes<this> \| Record<string, any> \| globalThis.Keyframe[] \| globalThis.PropertyIndexedKeyframes \| null, secondArg?: number \| KeyframeAnimationOptions \| globalThis.KeyframeAnimationOptions): SkenraAnimation & Animation`	Creates a new SkenraAnimation for this target per Web Animations API.	`SkenraAnimatable`
`removeAnimation(animation: SkenraAnimation): boolean`	Removes a specific animation from this object.	`SkenraAnimatable`
`constrain(type: K, config: ConstraintConfigMap[K]): ConstraintReturnMap[K]`	Creates a constraint on this Animatable using a fluent API.	`SkenraAnimatable`

Example

// Create a spline path
const pathData = 'M 0 0 L 100 0 L 100 100 L 0 100 Z'; // Square path
const spline = new PathSpline({
    id: 'square-path',
    svg: pathData,
    coordinateSpace: 'x-y',
    normalizeScale: 5
});

// Create follower node and constrain it to the spline. The constrained
// node is the constraint's DOM owner, so the factory attaches it to the
// follower for you.
const sphere = new Sphere({ id: 'follower', radius: 0.5 });
const modifier = sphere.constrain('alignToSpline', { spline });

// Animate along path (Web Animations API)
modifier.animate([
    { offset: 0, progress: 0 },
    { offset: 1, progress: 1 }
], { duration: 4000, iterations: Infinity, id: 'follow-path' });

↑ Documentation home · ← All classes