PineWidget Overview

PineWidget is a lightweight, embeddable animation player that renders PinePaper scenes on any website. It’s designed for embedding interactive motion graphics without requiring the full PinePaper editor.

Features

• Zero Dependencies: Pure Canvas 2D API - no Paper.js or other libraries required
• Interactive: Supports mouse/touch interactions (repel, follow, hover)
• Animations: Full support for keyframe and simple animations
• Relations: Supports behavior relations (orbits, follows, repels)
• Custom Element: Use as <pine-widget> HTML element
• Responsive: Adapts to container size

Quick Start

1. Include PineWidget

<!-- Self-hosted -->
<script src="js/PineWidget.js"></script>

<!-- Or via CDN (when available) -->
<script src="https://cdn.pinepaper.studio/pine-widget.min.js"></script>

2. Add a Widget Container

<div id="my-widget" style="width: 100%; max-width: 800px; aspect-ratio: 16/9;"></div>

3. Initialize with Scene

PineWidget.create('#my-widget', {
  url: 'widget-scene.json',  // Scene exported from PinePaper
  autoplay: true,
  loop: true,
  interactive: true
});

Using the Custom Element

PineWidget registers a custom HTML element for declarative usage:

<!-- Basic usage -->
<pine-widget src="scene.json" autoplay loop></pine-widget>

<!-- With options -->
<pine-widget
  src="my-animation.json"
  autoplay
  loop
  interactive
  width="800"
  height="600"
></pine-widget>

<!-- Inline scene data -->
<pine-widget autoplay loop>
  <script type="application/json">
    {
      "width": 400,
      "height": 300,
      "background": "#1e293b",
      "items": [...]
    }
  </script>
</pine-widget>

Scene Format

PineWidget uses a JSON format that’s exported from PinePaper:

{
  "version": "1.0",
  "width": 800,
  "height": 600,
  "background": "#1e293b",
  "items": [
    {
      "id": "item_1",
      "type": "circle",
      "x": 400,
      "y": 300,
      "radius": 50,
      "fillColor": "#4a9eff",
      "animation": {
        "type": "pulse",
        "speed": 1
      }
    }
  ],
  "relations": [
    {
      "from": "item_1",
      "to": "mouse",
      "type": "repels",
      "params": { "force": 100 }
    }
  ]
}

Exporting from PinePaper

1. Create your scene in the PinePaper editor
2. Click the Export button
3. Choose “Embeddable Widget” from the format options
4. Download the scene JSON file
5. Host the JSON and PineWidget script on your server

Comparison with Other Formats

Use PineWidget when you need:

• Interactive animations that respond to user input
• Small file sizes for fast loading
• Dynamic content that can be updated
• Integration with JavaScript

Use video when you need:

• Maximum compatibility
• Complex visual effects
• Audio support
• Social media sharing

Architecture Note

PineWidget is intentionally Paper.js-free.

While the PinePaper editor uses Paper.js for its powerful vector manipulation capabilities, PineWidget uses pure Canvas 2D API for playback. This separation provides:

1. Smaller bundle size - No large library dependencies
2. Faster loading - Minimal JavaScript to parse and execute
3. Future-proof - Decoupled from any specific rendering library
4. Portable - Easy to adapt to other rendering backends (WebGL, etc.)

The scene JSON format acts as an interchange format between the Paper.js-based editor and the pure Canvas 2D player, enabling the best of both worlds.