Animation

Advanced animation system for creating dynamic, procedural, and expression-based animations beyond simple keyframes.

Animation Types

The animation system supports several types beyond traditional keyframes:

• Expression: JavaScript expressions evaluated per frame
• Procedural: Built-in procedural animation patterns
• Sequence: Step-based sequential animations
• Path: Motion along Bezier paths

These advanced animations are defined in the animations array property of elements.

Node Animations vs Keyframes

Node Animations (animations array):

• Procedural, expression-based, or path-following animations
• Evaluated every frame
• Higher priority than keyframes
• Can override keyframe values

Keyframes (keyframes array):

• Simple property interpolation between defined points
• Lower priority
• Predictable, easy to edit

Animation Priority

When multiple animation methods target the same property:

1. Highest: Node animations (expression, procedural, path, sequence)
2. Medium: Keyframe animations
3. Lowest: Static property values

Expression Animations

Expressions are JavaScript code evaluated per frame, with access to animation context variables.

Available Context Variables

{
  time: number; // Current absolute time (seconds)
  localTime: number; // Time relative to element start
  duration: number; // Element duration
  progress: number; // Normalized progress (0-1)
  index: number; // Element index in group
  total: number; // Total elements in group
  fps: number; // Frames per second
  width: number; // Canvas width
  height: number; // Canvas height
  value: any; // Current property value
}

Expression Example

Bounce animation using Math functions:

Complex Expression

Combine multiple effects:

Procedural Animations

Built-in animation patterns with configurable parameters.

Procedural Types

• wiggle: Random oscillation (useful for handheld camera effects)
• wave: Sine/cosine wave motion
• bounce: Elastic bounce effect
• pulse: Rhythmic scaling

Wiggle Example

Sequence Animations

Step-based animations that change values at specific intervals.

Sequence Example

Text cycling through different sizes:

Path Animations

Animate elements along Bezier curve paths.

Path Example

Circular motion:

Property Path Syntax

The target property uses dot notation to specify nested properties:

• Simple: "x", "y", "rotation"
• Nested: "scale.x", "position.y"
• Array: "colors[0]", "points[2].x"

Target Resolution Examples

{
  "target": "x"              // Element's x position
  "target": "scaleX"         // Horizontal scale
  "target": "alpha"          // Opacity
  "target": "fill.color"     // Fill color (if fill is object)
  "target": "points[0].x"    // First point's x coordinate
}

Blend Modes

Control how animations combine when multiple target the same property:

Replace (Default)

{
  "blendMode": "replace",
  "blendWeight": 1.0
}

Completely replaces the property value.

Add

{
  "blendMode": "add",
  "blendWeight": 0.5
}

Adds to the existing value (weighted). Useful for accumulating offsets.

Multiply

{
  "blendMode": "multiply",
  "blendWeight": 1.0
}

Multiplies the existing value. Useful for scaling effects.

Multiple Animations Example

Combining different animation types:

In this example:

• Expression controls horizontal position (replace mode)
• Procedural wiggle adds subtle rotation variation
• Sequence pulses opacity
• Keyframe scales the element (lowest priority)

Important Notes

Expression Sandbox

• Expressions run in a restricted context for security
• Access to animation context variables only
• Cannot access DOM, external libraries, or Node.js APIs
• Evaluation errors will disable the animation

Performance

• Expressions: Evaluated every frame - keep them simple
• Procedural: Optimized built-in functions - very efficient
• Sequence: Minimal overhead, good for discrete changes
• Path: Moderate cost, depends on path complexity

Timing

• startTime and duration are relative to element's start time
• localTime in expressions starts at 0 when the element begins
• Animations respect element's overall duration boundary

Debugging

• If an animation doesn't work, check:
  • enabled: true
  • target property exists on the element
  • Expression syntax is valid JavaScript
  • startTime is within element's duration
  • No property path typos

Common Use Cases

Smooth Following Effect

{
  "type": "expression",
  "target": "x",
  "expression": "value + (targetX - value) * 0.1"
}

Elastic Bounce

{
  "type": "expression",
  "target": "scaleY",
  "expression": "1 + Math.exp(-localTime * 3) * Math.cos(localTime * 8) * 0.5"
}

Camera Shake

{
  "type": "procedural",
  "proceduralType": "wiggle",
  "target": "x",
  "frequency": 10,
  "amplitude": 5
}

Staggered Animation (in groups)

{
  "type": "expression",
  "target": "alpha",
  "expression": "Math.max(0, Math.min(1, (localTime - index * 0.1) * 2))"
}