Added pure/impure function registration and integrated it with continuous easing

Author: KenanMillet

Sequence/README.md

@@ -91,6 +91,7 @@ Leave blank for linear. Type a curve name for ease-in, or `~name` for ease-out.
 | `power(3)` | Parametric ease-in |
 | `bezier(0.42,0,0.58,1)` | CSS ease-in-out |
 | `step` | Instant jump at end of segment |
+| `continuous` | Re-evaluate expression every tick (no lerp). Required for `t`-based animations. |
 
 For ease-in-out: add an empty row at the midpoint with `~curve` as the easing — this switches the curve for subsequent lerps without moving the token.
 
@@ -105,21 +106,50 @@ Available in value cell expressions:
 | `orig` / `original` | Attribute value at start of playback |
 | `prev` / `previous` | Accumulated value at the previous keyframe |
 | `curr` / `current` | Current live value on the token (lazy-fetched) |
+| `t` | Normalized time (0–1) within the current playback cycle. Requires `continuous` easing. |
 
 Available in time cell expressions:
 
 | Variable | Meaning |
 |----------|---------|
 | `prev` | Previous resolved timestamp (ms) |
 
+## Constants
+
+| Constant | Value |
+|----------|-------|
+| `PI` | π (3.14159…) |
+| `TAU` | 2π (6.28318…) — one full rotation in radians |
+
+Color constants (`color.red`, `color.blue`, etc.) are also available — run `!sequence man vars` for the full list.
+
 ## Built-in Functions
 
-`rand(min, max)`, `randInt(min, max)`, `pick(a, b, ...)`, `clamp(v, lo, hi)`, `abs`, `round`, `floor`, `ceil`, `min`, `max`, `sqrt`, `pow`, `sin`, `cos`, `tan`, `log`, `exp`
+`rand(min, max)`, `randInt(min, max)`, `pick(a, b, ...)`, `freeze(value)`, `clamp(v, lo, hi)`, `abs`, `round`, `floor`, `ceil`, `min`, `max`, `sqrt`, `pow`, `sin`, `cos`, `tan`, `log`, `exp`
+
+**`freeze(value)`** — memoizes its result for the duration of the segment. Use in `continuous` easing to stabilize impure values:
+```
+=orig + freeze(rand(-50,50)) + cos(t * TAU) * 140
+```
+This gives a stable random offset with continuous oscillation. The frozen value resets each loop cycle.
+
+**Impure functions** (`rand`, `randInt`, `pick`) are automatically memoized in non-continuous segments (stable for the segment). In `continuous` segments they re-evaluate every tick — wrap in `freeze()` to stabilize.
 
 Color functions (value context only): `color.rgb(r,g,b)`, `color.hsl(h,s,l)`, `color.mix(a,b,t)`, `color.rotateHue(c,deg)`, `color.darken(c,amt)`, `color.lighten(c,amt)`, `color.saturate(c,amt)`
 
 Run `!sequence man func` in chat for the full list with descriptions and examples.
 
+## Continuous Animations
+
+For animations driven by mathematical functions rather than lerp between keyframes, use `continuous` easing with the `t` variable:
+
+| Time | left | left:easing |
+|------|------|-------------|
+| `=0` | | `continuous` |
+| `=3000` | `=orig + cos(t * TAU) * 140` | |
+
+Play with `--loop` for endless orbiting. `t` goes from 0→1 over the segment duration and resets each loop.
+
 ## Supported Attributes
 
 All standard graphic token properties: `left`, `top`, `rotation`, `width`, `height`, `bar1_value`–`bar3_value`, `bar1_max`–`bar3_max`, `aura1_radius`, `aura2_radius`, `light_radius`, `light_dimradius`, `light_angle`, `light_losangle`, `tint_color`, `aura1_color`, `aura2_color`, `light_color`, `flipv`, `fliph`, `showname`, `layer`, and more.

Sequence/Sequence.js

@@ -969,21 +969,48 @@ var Sequence = Sequence || (() => {
         // receives ctx as its final argument regardless of how it's called.
         // Core functions live as flat properties; namespaced functions live
         // under their namespace chain for natural dot-access in eval.
-        const _wrapNode = function(node) {
+        //
+        // Memoization: discrete functions are memoized per call-site within a
+        // segment. In a non-continuous segment, ALL functions are memoized.
+        // In a continuous segment, only discrete functions are memoized.
+        const _memoCache = context && context.memo ? context.memo : null;
+        const _isContinuousSeg = !!(context && context.isContinuousSegment);
+        var _callCounter = 0;
+
+        const _wrapNode = function(node, regKey) {
             if (typeof node === 'function') {
+                var reg = FN_REGISTRY[regKey] || null;
+                var isImpure = !!(reg && !reg.pure);
+                var isFreeze = regKey === 'core/freeze';
+                // Memoize if: freeze (always), OR impure function in non-continuous segment
+                var shouldMemo = _memoCache && (isFreeze || (isImpure && !_isContinuousSeg));
+
+                if (shouldMemo) {
+                    return function() {
+                        var idx = _callCounter++;
+                        var key = (regKey || 'fn') + ':' + idx;
+                        if (key in _memoCache) return _memoCache[key];
+                        var args = Array.prototype.slice.call(arguments);
+                        var result = node.apply(null, [_ctx].concat(args));
+                        _memoCache[key] = result;
+                        return result;
+                    };
+                }
                 return function() {
+                    _callCounter++;
                     var args = Array.prototype.slice.call(arguments);
                     return node.apply(null, [_ctx].concat(args));
                 };
             }
             if (node === null || typeof node !== 'object') return node;
             var wrapped = {};
             Object.keys(node).forEach(function(k) {
-                wrapped[k] = _wrapNode(node[k]);
+                var childKey = regKey ? regKey + '/' + k : 'core/' + k;
+                wrapped[k] = _wrapNode(node[k], childKey);
             });
             return wrapped;
         };
-        var _wrapped = _wrapNode(EXPR_SCOPE);
+        var _wrapped = _wrapNode(EXPR_SCOPE, '');
 
         // Declare each top-level name as a local var so eval can access it.
         // Core functions become flat locals (rand, clamp, etc.).
@@ -1112,6 +1139,7 @@ var Sequence = Sequence || (() => {
         reg.args        = reg.args        || [];
         reg.returns     = reg.returns     || 'number';
         reg.examples    = reg.examples    || [];
+        reg.pure        = reg.pure !== undefined ? reg.pure : true;
         reg.source      = src;
 
         insertIntoScope(scope, namespace, name, reg.fn);
@@ -1203,6 +1231,7 @@ var Sequence = Sequence || (() => {
         {
             name: 'rand', namespace: 'core',
             description: 'Returns a uniformly distributed random number between min (inclusive) and max (exclusive).',
+            pure: false,
             args: [
                 { name: 'min', type: 'number', description: 'Lower bound (inclusive)' },
                 { name: 'max', type: 'number', description: 'Upper bound (exclusive)' },
@@ -1214,6 +1243,7 @@ var Sequence = Sequence || (() => {
         {
             name: 'randInt', namespace: 'core',
             description: 'Returns a random integer between min and max (both inclusive).',
+            pure: false,
             args: [
                 { name: 'min', type: 'number', description: 'Lower bound (inclusive)' },
                 { name: 'max', type: 'number', description: 'Upper bound (inclusive)' },
@@ -1225,11 +1255,20 @@ var Sequence = Sequence || (() => {
         {
             name: 'pick', namespace: 'core',
             description: 'Returns one of the provided values chosen uniformly at random.',
+            pure: false,
             args: [{ name: '...values', type: 'any', description: 'Values to pick from' }],
             returns: 'any',
             examples: ['=pick(0,90,180,270)  random cardinal rotation'],
             fn: (ctx, ...args) => args[Math.floor(Math.random() * args.length)],
         },
+        {
+            name: 'freeze', namespace: 'core',
+            description: 'Memoizes its argument — evaluates once per segment, returns the cached value on subsequent ticks. Use in continuous easing to stabilize non-deterministic values.',
+            args: [{ name: 'value', type: 'any', description: 'Value to freeze' }],
+            returns: 'any',
+            examples: ['=orig + freeze(rand(-50,50)) + cos(t * TAU) * 140  stable random offset with continuous orbit'],
+            fn: (ctx, val) => val,
+        },
         {
             name: 'clamp', namespace: 'core',
             description: 'Clamps value to the range [lo, hi].',
@@ -2573,7 +2612,7 @@ var Sequence = Sequence || (() => {
      * @param {object} prevState     - running state before this keyframe (prev)
      * @param {object} liveObj       - Roll20 graphic object (curr)
      */
-    const resolveDeltas = (deltas, initialState, prevState, liveObj, cumulative, t) => {
+    const resolveDeltas = (deltas, initialState, prevState, liveObj, cumulative, t, memo) => {
         const resolved = {};
         Object.entries(deltas || {}).forEach(([attrName, parsed]) => {
             if (!parsed || !parsed.expr) { resolved[attrName] = parsed; return; }
@@ -2586,7 +2625,7 @@ var Sequence = Sequence || (() => {
 
             try {
                 const val = evalExpr(parsed.expr, orig, prev, curr,
-                    { obj: liveObj, t: t || 0, cumulative: cumulative || {} });
+                    { obj: liveObj, t: t || 0, memo: memo || null, isContinuousSegment: false, cumulative: cumulative || {} });
                 if (parsed.mode === 'abs') {
                     resolved[attrName] = { abs: val };
                 } else if (parsed.mode === 'mul') {
@@ -2755,7 +2794,7 @@ var Sequence = Sequence || (() => {
                 }
                 pb.startTime      = Date.now();
                 pb.lastKfIndex    = -1;
-                pb.resolvedExprs  = {}; // re-evaluate value expressions on next loop
+                pb.memoCache      = {}; // reset function memo on next loop
                 pb.cumulative     = {}; // reset scratchpad each loop cycle
                 pb.currentEasings = {}; // reset easing switches each loop cycle
                 pb.rotNudgeDir    = 1;  // reset nudge direction each loop
@@ -2834,7 +2873,7 @@ var Sequence = Sequence || (() => {
                 const prevState = stateAt(i - 1);
                 const state     = stateAt(i);
                 // Resolve any expression deltas before applying
-                const resolvedDeltas = resolveDeltas(kf.deltas, pb.initialState, prevState, obj, pb.cumulative, tNorm);
+                const resolvedDeltas = resolveDeltas(kf.deltas, pb.initialState, prevState, obj, pb.cumulative, tNorm, {});
                 // Re-apply with resolved deltas via shadow
                 const shadow = makeShadow(prevState);
                 Object.entries(resolvedDeltas || {}).forEach(([attrName, parsed]) => {
@@ -2893,24 +2932,29 @@ var Sequence = Sequence || (() => {
                         const isContinuous = srcEasing === 'continuous';
                         const orig = pb.initialState[attrName] !== undefined ? pb.initialState[attrName] : 0;
                         const prev = prevAbsState[attrName] !== undefined ? prevAbsState[attrName] : orig;
+
+                        // Per-segment memo cache for function memoization
+                        const memoKey = `${nextIdx}:${attrName}`;
+                        if (!pb.memoCache) pb.memoCache = {};
+                        if (!pb.memoCache[memoKey]) pb.memoCache[memoKey] = {};
+                        const memo = pb.memoCache[memoKey];
+
                         try {
                             const val = evalExpr(nextParsed.expr, orig, prev, undefined,
-                                { obj, reg, t: tNorm, cumulative: pb.cumulative || {} });
+                                { obj, reg, t: tNorm, memo, isContinuousSegment: isContinuous, cumulative: pb.cumulative || {} });
                             let resolved = nextParsed.mode === 'abs' ? { abs: val }
                                 : nextParsed.mode === 'mul' ? { delta: val }
                                 : { delta: (nextParsed.sign || 1) * val };
+                            // In continuous segments, use resolved value directly (no lerp)
                             if (isContinuous) {
-                                // Continuous: use resolved value directly, no lerp, no cache
                                 const shadow = makeShadow(prevAbsState);
                                 if ('abs' in resolved)        reg.set(shadow, resolved.abs);
                                 else if ('delta' in resolved) reg.apply(shadow, resolved.delta);
                                 interpolated = shadow._state[attrName];
                             } else {
-                                // Cache the resolved value so all ticks in this segment agree
-                                if (!pb.resolvedExprs) pb.resolvedExprs = {};
-                                const key = `${nextIdx}:${attrName}`;
-                                if (!(key in pb.resolvedExprs)) pb.resolvedExprs[key] = resolved;
-                                nextParsed = pb.resolvedExprs[key];
+                                // Non-continuous: memoization ensures same result each tick,
+                                // so we can use it as the lerp target
+                                nextParsed = resolved;
                             }
                         } catch(e) {
                             log(`${SCRIPT_NAME}: lerp expr error for ${attrName}: ${e.message}`);
@@ -3943,7 +3987,8 @@ var Sequence = Sequence || (() => {
                     const argList = (r.args || []).map(a =>
                         a.optional ? `[${escHtml(a.name)}]` : escHtml(a.name)
                     ).join(', ');
-                    let html = `<b>${ns}${escHtml(r.name)}(${argList})</b> → <i>${escHtml(r.returns || 'number')}</i>${fmtContexts(r)}<br>`;
+                    const unstable = r.pure === false ? ' [unstable]' : '';
+                    let html = `<b>${ns}${escHtml(r.name)}(${argList})</b> → <i>${escHtml(r.returns || 'number')}</i>${unstable}${fmtContexts(r)}<br>`;
                     if (r.description) html += `${escHtml(r.description)}<br>`;
                     if (r.args && r.args.length) {
                         html += (r.args.map(a =>
@@ -4668,7 +4713,13 @@ var Sequence = Sequence || (() => {
             li(`${c('ctx.curr')} — current live value (lazy-fetched)`),
             li(`${c('ctx.cumulative')} — per-loop scratchpad, reset each cycle`),
         );
-        html += p(b('Struct fields: ') + c('name') + ', ' + c('namespace') + ', ' + c('fn') + ', ' + c('description') + ', ' + c('args') + ', ' + c('returns') + ', ' + c('examples') + '.');
+        html += p(b('Struct fields: ') + c('name') + ', ' + c('namespace') + ', ' + c('fn') + ', ' + c('description') + ', ' + c('args') + ', ' + c('returns') + ', ' + c('examples') + ', ' + c('pure') + '.');
+        html += p(b('pure') + ' (boolean, default ' + c('true') + '): '
+            + 'Set to ' + c('false') + ' for functions that may return different values on repeated calls with the same arguments '
+            + '(e.g. random, stateful, or time-dependent functions). '
+            + 'Impure functions (' + c('pure: false') + ') are automatically memoized per call-site in non-continuous easing segments, '
+            + 'ensuring stable values for the duration of the segment. In ' + c('continuous') + ' segments, impure functions re-evaluate every tick. '
+            + 'Users can wrap impure calls in ' + c('freeze()') + ' to force memoization in continuous segments.');
         html += pre(
 `Sequence.registerValueFunction('MyScript', {
     name: 'wave', namespace: 'anim',
@@ -4899,7 +4950,8 @@ if (opacityReg) opacityReg.set(obj, 0.5);`
             const ns      = r.namespace === 'core' ? '' : `${b(r.namespace + '.')}&shy;`;
             const argList = (r.args || []).map(a =>
                 a.optional ? `[${a.name}]` : a.name).join(', ');
-            let s = `${b(ns + r.name + `(${argList})`)} → ${i(r.returns || 'number')}${fmtContexts(r)}<br>`;
+            const unstable = r.pure === false ? ' [unstable]' : '';
+            let s = `${b(ns + r.name + `(${argList})`)} → ${i(r.returns || 'number')}${unstable}${fmtContexts(r)}<br>`;
             if (r.description) s += `${r.description}<br>`;
             if (r.args && r.args.length)
                 s += ul(r.args.map(a =>
@@ -4952,6 +5004,7 @@ if (opacityReg) opacityReg.set(obj, 0.5);`
             ['orig / original', 'Attribute value at start of playback. Stable for entire session.'],
             ['prev / previous', 'Accumulated value at the previous keyframe.'],
             ['curr / current',  'Current live value on the token (fetched lazily).'],
+            ['t',               'Normalized time (0–1) within the current playback cycle. Requires continuous easing.'],
         ];
         const timeVars = [
             ['prev', 'Previous resolved timestamp (ms) — the only available variable in time expressions'],
@@ -4987,13 +5040,30 @@ if (opacityReg) opacityReg.set(obj, 0.5);`
             li(`${c('power(3)')} — parametric curve with arguments`),
             li(`${c('~bezier(0.42,0,0.58,1)')} — reversed parametric`),
             li(`${c('step')} — instant jump at end of segment`),
+            li(`${c('continuous')} — re-evaluate expression every tick (no lerp). Required for ${c('t')}-based animations.`),
         ].join(''));
         html += p(`Available curves: ${c(EASING_NAMES().join(', '))}.`);
         html += p('For ease-in-out, add an empty row at the midpoint with a '
             + c('~curve') + ' easing. An empty-row easing cell (no delta for that attribute) '
             + 'switches the easing for future lerps of that attribute at that timestamp, '
             + 'without moving the token.');
 
+        html += h(2, 'Continuous Animations');
+        html += p('For animations driven by mathematical functions (orbit, oscillation, etc.), '
+            + 'use ' + c('continuous') + ' easing with the ' + c('t') + ' variable. '
+            + 'The expression re-evaluates every tick instead of lerping between two values.');
+        html += p(i('Example: orbit at radius 140px over 3 seconds, looping:'));
+        html += ul([
+            li('Row 1: time ' + c('=0') + ', easing ' + c('continuous') + ', no delta'),
+            li('Row 2: time ' + c('=3000') + ', left ' + c('=orig + cos(t * TAU) * 140') + ', top ' + c('=orig + sin(t * TAU) * 140')),
+        ].join(''));
+        html += p(b('freeze(value)') + ' — memoizes its result for the segment. '
+            + 'Use to stabilize impure functions in continuous easing: '
+            + c('=orig + freeze(rand(-50,50)) + cos(t * TAU) * 140'));
+        html += p('Impure functions (' + c('rand') + ', ' + c('randInt') + ', ' + c('pick')
+            + ') are automatically memoized in non-continuous segments. '
+            + 'In ' + c('continuous') + ' segments they re-evaluate every tick.');
+
         html += h(2, 'Expression Variables (Value Context)');
         html += ul(vars.map(([name, desc]) => li(`${b(name)} — ${desc}`)).join(''));
 
@@ -5067,7 +5137,8 @@ if (opacityReg) opacityReg.set(obj, 0.5);`
             const ns2     = `${b(r.namespace + '.')}&shy;`;
             const argList = (r.args || []).map(a =>
                 a.optional ? `[${a.name}]` : a.name).join(', ');
-            let s = `${b(ns2 + r.name + `(${argList})`)} → ${i(r.returns || 'number')}${fmtContexts(r)}<br>`;
+            const unstable = r.pure === false ? ' [unstable]' : '';
+            let s = `${b(ns2 + r.name + `(${argList})`)} → ${i(r.returns || 'number')}${unstable}${fmtContexts(r)}<br>`;
             if (r.description) s += `${r.description}<br>`;
             if (r.args && r.args.length)
                 s += ul(r.args.map(a =>