numberSequence

Roblox-shaped scalar keyframe-curve value type. A NumberSequence is an immutable curve of up to 64 keypoints, each carrying (time, value, envelope). The envelope is a per-keypoint random range half-width applied at :sample(t) time; :evaluate(t) is always deterministic.

Exposed as the NumberSequence Luau global via --!global. Authored scripts call NumberSequence.new(...) directly without a require. The Rust FFI lives at __sequences.* (registered by crates/zero_scripting/src/ffi/bindings/curves.rs); this module is the typed Luau wrapper.

Exports

• NumberSequence.new(...) -> NumberSequenceObj — three signatures:
  • NumberSequence.new(v) — constant value across [0, 1].
  • NumberSequence.new(v0, v1) — two-point lerp from v0 to v1.
  • NumberSequence.new({ { time, value, envelope? }, ... }) — explicit keypoints. envelope defaults to 0. First key must anchor at time = 0, last at time = 1. NaN / Inf rejected.
• NumberSequence.deserialize(payload) -> NumberSequenceObj — rebuild from a { kind = "NumberSequence", keypoints = {...} } payload produced by :serialize().

Methods (called via :)

• seq:evaluate(t) -> number — deterministic linear interpolation at t. t clamps to [0, 1]; NaN coerces to 0.
• seq:sample(t) -> number — evaluate(t) + (math.random() − 0.5)·2·envelope(t). Per-VM math.randomseed controls jitter reproducibility.
• seq:keypoints() -> { NumberKeypoint } — array snapshot, sorted ascending by time.
• seq:duration() -> number — always 1.0 for a well-formed sequence.
• seq:serialize() -> { kind, keypoints } — scene-save payload.
• seq:destroy() — drop the FFI handle. Luau removed __gc on tables, so eager cleanup is the caller's responsibility for per-frame-rebuild patterns; otherwise the entry dies with the VM.

Substrate

Backed by zero_curves::Channel (Linear interp). Each sequence builds the value and envelope channels once at construct time and reaches into them on every sample — zero per-call allocation, safe for hot particle loops. Validation errors name the specific rule ("first keypoint must anchor at time = 0", "too many keypoints (max 64)", …).

Foundation for VFX property-over-lifetime: declarative particles (#2572), GPU emitter (#873), beams, trails. Issue: #2673.