Built-in Relations

PinePaper includes several pre-defined relation types for common behaviors.

orbits

Circular motion around a target.

app.addRelation(moonId, earthId, 'orbits', {
  radius: 100,
  speed: 0.5,
  direction: 'counterclockwise',
  phase: 0
});

follows

Move toward target with smoothing.

app.addRelation(labelId, playerId, 'follows', {
  offset: [0, -50],
  smoothing: 0.1,
  delay: 0
});

attached_to

Move with target (parent-child relationship).

app.addRelation(hatId, characterId, 'attached_to', {
  offset: [0, -30],
  inherit_rotation: true
});

maintains_distance

Stay at fixed distance from target.

app.addRelation(satelliteId, stationId, 'maintains_distance', {
  distance: 200,
  strength: 0.8
});

points_at

Rotate to face target.

app.addRelation(arrowId, targetId, 'points_at', {
  offset_angle: -90,
  smoothing: 0.2
});

mirrors

Mirror position across axis.

app.addRelation(reflectionId, originalId, 'mirrors', {
  axis: 'vertical',
  center: [400, 300]
});

parallax

Move relative to target by depth factor.

app.addRelation(backgroundId, cameraId, 'parallax', {
  depth: 0.5,
  origin: [400, 300]
});

bounds_to

Stay within target’s bounds.

app.addRelation(playerId, arenaId, 'bounds_to', {
  padding: 20,
  bounce: true
});

Manim-Inspired Animation Relations

These relations are inspired by the Manim Community animation library, providing similar animation capabilities in PinePaper’s declarative relation system.

grows_from

Item scales from zero to full size, emanating from a point. Similar to Manim’s GrowFromPoint and GrowFromCenter.

app.addRelation(itemId, null, 'grows_from', {
  origin: 'center',
  duration: 0.5,
  delay: 0,
  easing: 'easeOut'
});

staggered_with

Staggered animation timing for groups. Similar to Manim’s LaggedStart.

// Apply to each item in a group with increasing index
app.addRelation(item1Id, leaderId, 'staggered_with', { index: 0, stagger: 0.1, effect: 'popIn' });
app.addRelation(item2Id, leaderId, 'staggered_with', { index: 1, stagger: 0.1, effect: 'popIn' });
app.addRelation(item3Id, leaderId, 'staggered_with', { index: 2, stagger: 0.1, effect: 'popIn' });

indicates

Temporary highlight effect with scale and color pulse. Similar to Manim’s Indicate.

app.addRelation(itemId, null, 'indicates', {
  scale: 1.2,
  color: '#fbbf24',
  duration: 0.5,
  repeat: 2
});

circumscribes

Draw a temporary shape around the target item. Similar to Manim’s Circumscribe.

app.addRelation(sourceId, targetId, 'circumscribes', {
  shape: 'rectangle',
  color: '#fbbf24',
  strokeWidth: 3,
  padding: 10,
  duration: 1.0,
  fadeOut: true
});

wave_through

Send a wave distortion through the item. Similar to Manim’s ApplyWave.

app.addRelation(itemId, null, 'wave_through', {
  amplitude: 20,
  frequency: 2,
  direction: 'horizontal',
  duration: 1.0
});

camera_follows

View pans to follow a target item. Similar to Manim’s MovingCameraScene.

app.addRelation(null, targetId, 'camera_follows', {
  smoothing: 0.1,
  offset: [0, 0],
  zoom: 1,
  deadzone: 50
});

camera_animates

Keyframe-based camera zoom and pan animation. Uses 'camera' as a virtual item ID.

Each keyframe’s target is given by a polymorphic focus field resolved per-frame against the live scene graph — so the camera chases items as they move, rig, or get nudged. The legacy center: [x, y] field is still honored when focus is absent or unresolvable, for backward compat.

// Cinematic walkthrough — focus on items instead of pixel coordinates.
app.addRelation('camera', null, 'camera_animates', {
  duration: 6,
  loop: true,
  keyframes: [
    { time: 0, zoom: 1,   focus: [400, 300] },                              // literal
    { time: 2, zoom: 2.2, focus: 'hero_shape',            easing: 'easeInOut' }, // item id
    { time: 4, zoom: 2,   focus: { item: 'intro_text', offset: [0, -40] }, easing: 'easeOut' }, // item + offset
    { time: 6, zoom: 1,   focus: [400, 300],              easing: 'easeInOut' }
  ]
});

// Or use the camera helper API
app.camera.zoomIn(2, 0.5);
app.camera.panTo(200, 200, 0.5);
app.camera.moveTo(200, 200, 2, 0.5);
app.camera.reset(0.5);

Keyframe Properties:

Focus resolution:

Because items can themselves be bound by other relations (part_of, follows, attached_to), focus lookups transitively inherit those behaviors — rig a character’s head via skeletal animation and a keyframe with focus: 'head' tracks it automatically. The camera becomes a derivation over the scene graph rather than an independent pixel tour.

Path shapes between keyframes:

The spatial path from one keyframe to the next defaults to a straight line. Four escape hatches let you shape the in-between path:

1. Bezier handles — pathOut on the previous keyframe, pathIn on the next keyframe. Both are 2D offsets relative to the resolved focus point. Either handle alone is enough to promote the segment to a cubic bezier.

   keyframes: [
     { time: 0, focus: 'st_idle',      pathOut: [200, -100] }, // leave going right-and-up
     { time: 3, focus: 'st_error',     pathIn:  [-200, 100]  }, // arrive from upper-right
   ]
   

2. Arc (shorthand) — pathMode: 'arc' on the previous keyframe plus a pivot: [x, y] center. arcDirection: 'ccw' (default) takes the counter-clockwise sweep; 'cw' reverses. Compiles to cubic-bezier handles internally via the standard h = (4/3) tan(Δ/4) r formula.

   keyframes: [
     { time: 0, focus: [100, 0],
       pathMode: 'arc', pivot: [0, 0], arcDirection: 'ccw' },
     { time: 2, focus: [0, 100] },   // quarter-circle around the origin
   ]
   

3. Custom SVG path — pathMode: 'custom' with an SVG-path d string. The camera traces the path at eased progress. Requires Paper.js (i.e. the main-thread renderer); falls back to a straight line in headless environments.

   keyframes: [
     { time: 0, focus: [0, 0],
       pathMode: 'custom', path: 'M 0 0 C 50 -100, 150 -100, 200 0' },
     { time: 2, focus: [200, 0] },
   ]
   

4. Linear — the default when none of the above are present. Identical to the pre-0.5 behavior; existing templates keep working unchanged.

Endpoints always match the keyframe’s focus position regardless of which path mode you pick — pathOut doesn’t shift where the camera leaves the previous keyframe, only how it curves on the way out.

Camera Helper Methods:

morphs_to

Shape morphing animation. Similar to Manim’s Transform. Supports cross-type morphing (e.g., Path to PointText) using particle-based denoising effects.

app.addRelation(sourceId, targetId, 'morphs_to', {
  duration: 1.0,
  delay: 0,
  easing: 'easeInOut',
  morphColor: true,
  morphSize: true,
  hideTarget: true,
  removeTargetOnComplete: false
});

Discovery

getAvailableRelations()

Get a list of all registered relation type names.

Returns: Array<string>

const types = app.getAvailableRelations();
// ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at',
//  'mirrors', 'parallax', 'bounds_to', 'grows_from', 'staggered_with',
//  'indicates', 'circumscribes', 'wave_through', 'camera_follows',
//  'camera_animates', 'morphs_to', 'driven_by', 'wiggle', 'time_expression',
//  'bone_attached', 'ik_target', 'blend_reacts_to', 'blend_transition']

Morph Strategy by Type:

Note: Path segment interpolation works best when source and target have the same number of segments. Cross-type morphs use a particle-based denoising effect for smooth transitions.