Fmtion Format Overview

The unified animation file format for FasterMotion - DOM, Canvas, Lottie, and 3D animations in one file

The .fmtion format is the unified animation file format for FasterMotion. It provides a single, comprehensive structure for defining all types of animations in one declarative JSON file.

What is .fmtion?

A .fmtion file (pronounced "eff-motion") is a JSON file that can contain:

DOM Animations - CSS property animations on HTML elements
Canvas 2D - GPU-accelerated canvas animations with skeletal systems
Lottie - After Effects animations with state machines
Three.js 3D - WebGL 3D scenes and animations

All driven by a unified parameter system that responds to scroll position, user interactions, and time.

Key Design Principles

Principle	Description
Parameter-Driven	Animations are driven by hierarchical parameters (`hero/hovered`, `menu/open`)
Event-Driven	DOM events trigger parameter changes via listeners
Unified Loading	Single `FasterMotion.load()` function for all content types
Declarative	Define what you want, not how to implement it

Quick Example

{
  "meta": { "name": "Hero Animation" },
  "parameters": {
    "hero/scrollProgress": { "type": "float", "default": 0 },
    "hero/hovered": { "type": "bool", "default": false }
  },
  "scrollBindings": [{
    "id": "hero-scroll",
    "parameter": "hero/scrollProgress",
    "trigger": ".hero",
    "start": "top top",
    "end": "bottom top"
  }],
  "listeners": [{
    "id": "hero-hover",
    "target": ".hero-card",
    "event": "mouseenter",
    "actions": [{ "set": "hero/hovered", "value": true }]
  }],
  "dom": [{
    "selector": ".hero-title",
    "driver": "hero/scrollProgress",
    "from": { "opacity": 0, "y": 50 },
    "to": { "opacity": 1, "y": 0 }
  }],
  "canvas": [],
  "lottie": []
}

Loading .fmtion Files

Use the unified FasterMotion.load() function:

// Load from URL
const result = await FasterMotion.load('/animations/hero.fmtion');

// Load from object
const result = await FasterMotion.load(fmtionData);

// Control playback
result.play();
result.pause();
result.seek(0.5);

// Cleanup
result.destroy();

File Structure Overview

FmtionFile
├── meta                 # File metadata (name, author, duration)
├── smoothScroll?        # Smooth scroll configuration
├── parameters           # Hierarchical parameters (the control system)
├── scrollBindings       # Map scroll position to parameters
├── listeners            # DOM events that change parameters
├── pointerFollow?       # Cursor-following image effects
├── dom                  # DOM element animations
├── canvas               # Canvas 2D scenes with skeletal animation
├── lottie?              # Lottie animations with states
├── three?               # Three.js 3D scenes
└── assets?              # Shared asset library

Content Types

DOM Animations

Animate CSS properties on HTML elements with text splitting and stagger effects.

{
  "dom": [{
    "selector": ".title",
    "driver": "hero/visible",
    "driverType": "bool",
    "from": { "opacity": 0, "y": 40 },
    "to": { "opacity": 1, "y": 0 },
    "splitText": "words",
    "stagger": 0.08,
    "duration": 800
  }]
}

Canvas 2D

Full-featured canvas rendering with skeletal animation, IK, mesh deformation, and state machines.

{
  "canvas": [{
    "id": "character",
    "mountSelector": "#canvas",
    "width": 800,
    "height": 600,
    "skeletons": [{ ... }],
    "animations": [{ ... }],
    "stateMachines": [{ ... }]
  }]
}

Lottie

After Effects animations with scroll sync, state machines, and mouse tracking.

{
  "lottie": [{
    "id": "mascot",
    "container": "#hero",
    "src": "/animations/mascot.json",
    "scroll": {
      "trigger": ".hero",
      "scrub": true
    }
  }]
}

Three.js 3D

WebGL 3D scenes with cameras, lights, objects, and animations.

{
  "three": {
    "defaultSceneId": "main",
    "scenes": [{
      "id": "main",
      "camera": { "type": "perspective", "position": [0, 5, 10] },
      "lights": [{ ... }],
      "objects": [{ ... }],
      "tracks": [{ ... }]
    }]
  }
}

Documentation Sections

Section	Description
Loading	`FasterMotion.load()` API reference
File Structure	Complete file format specification
Parameters	Parameters, scroll bindings, and listeners
DOM Animations	DOM animation configuration
Canvas	Canvas 2D and skeletal animation
Lottie	Lottie integration and state machines
3D Content	Three.js 3D scenes

Best Practices

1. Use Hierarchical Parameters

// Good - organized by component
"hero/title/visible"
"hero/title/hovered"
"menu/items/0/active"

// Avoid - flat naming
"heroTitleVisible"
"menuItem0Active"

2. Separate Concerns

Scroll bindings only update parameters
Listeners only respond to DOM events
Animations react to parameter changes

3. Use Bool Drivers for Interactions

{
  "driver": "card/hovered",
  "driverType": "bool",
  "reverseOnFalse": true
}

File Extension

The standard file extension is .fmtion. Files are JSON format and can be:

Minified for production
Pretty-printed for development
Compressed with gzip/brotli for serving

Fmtion Format Overview

On this page