Scene & Template Format

PinePaper uses a unified JSON format for both scenes and templates. This page documents the complete schema.

Reserved Keywords

The following are reserved property names with special meaning. Any other properties are treated as custom data.

Top-Level Reserved

Item Reserved Properties

Type-Specific Reserved

Relation Reserved Values

Custom Properties

Any property not listed above is treated as custom data:

{
  "id": "my-item",
  "type": "circle",
  "position": [100, 100],
  "myCustomProp": "hello",
  "score": 42
}

Top-Level Structure

{
  "version": "1.0",
  "width": 800,
  "height": 600,
  "backgroundColor": "#1e293b",
  "items": [],
  "relations": [],
  "interactions": [],
  "metadata": {}
}

Item Schema

Each item in the items array:

{
  "id": "item_1",
  "type": "circle",
  "position": [400, 300],
  "radius": 50,
  "scale": 1,
  "rotation": 0,
  "opacity": 1,
  "fillColor": "#4a9eff",
  "strokeColor": null,
  "strokeWidth": 0,
  "interactive": true,
  "animation": null,
  "keyframes": null
}

Common Properties

Item Types

Text Properties

{
  "type": "text",
  "content": "Hello World",
  "position": [400, 300],
  "fontSize": 48,
  "fontFamily": "Inter, sans-serif",
  "fontWeight": "bold",
  "fontColor": "#ffffff",
  "alignment": "center"
}

Circle Properties

{
  "type": "circle",
  "position": [400, 300],
  "radius": 50,
  "fillColor": "#4a9eff"
}

Star Properties

{
  "type": "star",
  "position": [400, 300],
  "points": 5,
  "radius1": 50,
  "radius2": 25,
  "fillColor": "#fbbf24"
}

Animation Schema

Simple animations are defined inline:

{
  "animation": {
    "type": "pulse",
    "speed": 1
  }
}

Animation Types

Animation Properties

Keyframe Animation Schema

For complex animations:

{
  "keyframes": [
    { "time": 0, "properties": { "position": [100, 300], "opacity": 0 }, "easing": "easeIn" },
    { "time": 1, "properties": { "position": [400, 300], "opacity": 1 }, "easing": "easeOut" },
    { "time": 2, "properties": { "position": [700, 300], "opacity": 0.5 } }
  ],
  "animationDuration": 2,
  "animationLoop": true
}

Keyframe Properties

Animatable Properties

• position - Position as [x, y]
• x, y - Individual position components
• scale, scaleX, scaleY - Scale
• rotation - Rotation in degrees
• opacity - Transparency
• fillColor - Fill color (interpolated)
• fontColor - Text color
• strokeColor - Stroke color
• fontSize - Text size

Easing Functions

• linear - Constant speed
• easeIn - Slow start
• easeOut - Slow end
• easeInOut - Slow start and end
• bounce - Bounce effect

Relation Schema

Relations define dynamic behaviors between items:

{
  "from": "item_1",
  "to": "item_2",
  "type": "orbits",
  "params": {
    "radius": 100,
    "speed": 0.5
  }
}

Relation Properties

Relation Types

Mouse Relations

Use "to": "mouse" for cursor-based behaviors:

{
  "from": "item_1",
  "to": "mouse",
  "type": "repels",
  "params": {
    "force": 100,
    "maxDistance": 200
  }
}

Interaction Schema

Define click/hover behaviors:

{
  "id": "trigger_1",
  "itemId": "button_1",
  "event": "click",
  "action": "navigate",
  "params": { "step": 2 },
  "once": false
}

Interaction Properties

Event Types

• click - Mouse click / touch tap
• hover / enter - Mouse enters item
• leave - Mouse leaves item
• drag - Mouse drag on item

Action Types

• navigate - Step navigation
• show / hide - Toggle visibility
• animate - Apply animation
• setState - Update state variable

Template Metadata

Adding metadata makes a scene into a saveable template:

{
  "version": "1.0",
  "width": 800,
  "height": 600,
  "backgroundColor": "#1e293b",
  "items": [...],
  "metadata": {
    "name": "My Animation",
    "category": "creative",
    "description": "A beautiful animation",
    "tags": ["animation", "text"],
    "thumbnail": "/thumbnails/my-animation.svg",
    "difficulty": "intermediate"
  }
}

Metadata Fields

Multi-Scene Sequences

Add scenes array for multi-scene sequences:

{
  "version": "1.0",
  "width": 800,
  "height": 600,
  "backgroundColor": "#1e293b",
  "items": [...],
  "scenes": [
    {
      "id": "scene_2",
      "items": [...],
      "transitions": [
        { "to": "scene_3", "trigger": "click" }
      ]
    }
  ]
}

Complete Example

{
  "version": "1.0",
  "width": 800,
  "height": 600,
  "backgroundColor": "#0f172a",
  "items": [
    {
      "id": "sun",
      "type": "circle",
      "position": [400, 300],
      "radius": 60,
      "fillColor": "#fbbf24",
      "animation": { "type": "pulse", "speed": 0.5 }
    },
    {
      "id": "planet",
      "type": "circle",
      "position": [550, 300],
      "radius": 20,
      "fillColor": "#3b82f6"
    },
    {
      "id": "moon",
      "type": "circle",
      "position": [580, 300],
      "radius": 8,
      "fillColor": "#9ca3af"
    },
    {
      "id": "label",
      "type": "text",
      "position": [400, 500],
      "content": "Solar System",
      "fontSize": 24,
      "fontColor": "#ffffff"
    }
  ],
  "relations": [
    {
      "from": "planet",
      "to": "sun",
      "type": "orbits",
      "params": { "radius": 150, "speed": 0.1 }
    },
    {
      "from": "moon",
      "to": "planet",
      "type": "orbits",
      "params": { "radius": 30, "speed": 0.3 }
    }
  ],
  "metadata": {
    "name": "Solar System",
    "category": "education",
    "tags": ["space", "animation", "orbits"]
  }
}