Loading .fmtion Files

FasterMotion.load(urlOrData: string | FmtionFile, options?: LoadOptions): Promise<LoadResult>

import { FasterMotion } from 'faster-motion';

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

// Load from object
const result = await FasterMotion.load({
  meta: { name: 'My Animation' },
  parameters: {},
  scrollBindings: [],
  listeners: [],
  dom: [],
  canvas: []
});

interface LoadOptions {
  // Base path for resolving relative URLs (auto-derived from URL if not provided)
  basePath?: string;

  // Runtime hooks for animation events
  hooks?: {
    onStart?: (animationId: string) => void;
    onUpdate?: (animationId: string, progress: number) => void;
    onComplete?: (animationId: string) => void;
    onReverse?: (animationId: string) => void;
    onEnter?: (animationId: string) => void;
    onLeave?: (animationId: string) => void;
    onStateChange?: (animationId: string, from: string, to: string) => void;
    onFrame?: (animationId: string, frame: number) => void;
  };

  // Progress callback during load
  onProgress?: (loaded: number, total: number) => void;
}

const result = await FasterMotion.load('/animation.fmtion', {
  basePath: '/assets/',
  hooks: {
    onStart: (id) => console.log(`Animation ${id} started`),
    onComplete: (id) => console.log(`Animation ${id} completed`),
    onStateChange: (id, from, to) => {
      console.log(`${id}: ${from} -> ${to}`);
    }
  },
  onProgress: (loaded, total) => {
    console.log(`Loading: ${Math.round(loaded / total * 100)}%`);
  }
});

interface LoadResult {
  // Unified format result (if FmtionFile was loaded)
  fmtion?: FmtionLoadResult;

  // Legacy animations (for backwards compatibility)
  animations?: any[];

  // Get animation by ID
  get: (id: string) => any | null;

  // Destroy/dispose all resources
  destroy: () => void;

  // Play all animations
  play: () => void;

  // Pause all animations
  pause: () => void;

  // Seek all animations to progress (0-1)
  seek: (progress: number) => void;

  // Get current progress (from first animation)
  getProgress: () => number;

  // Check if any animation is playing
  isPlaying: () => boolean;
}

const result = await FasterMotion.load('/hero.fmtion');

// Basic controls
result.play();
result.pause();
result.seek(0.5);  // Seek to 50%

// Check state
console.log(result.getProgress());  // 0.5
console.log(result.isPlaying());    // true/false

// Get specific animation
const heroAnim = result.get('hero-fade');

const result = await FasterMotion.load('/page.fmtion');

// DOM animations are automatically set up
// They respond to scroll and interaction listeners

const result = await FasterMotion.load('/character.fmtion');

// Access canvas timeline
result.fmtion?.canvas?.timeline.play();
result.fmtion?.canvas?.timeline.pause();
result.fmtion?.canvas?.timeline.seek(0.5);

// Access skeletons
const skeleton = result.fmtion?.canvas?.skeletons?.get('character');

const result = await FasterMotion.load('/interactive.fmtion');

// Access Lottie controllers
const lottie = result.fmtion?.lottie?.[0];
lottie?.play();
lottie?.pause();
lottie?.goToFrame(30);

// Change state (if using state machine)
lottie?.setState('hover');

const result = await FasterMotion.load('/3d-scene.fmtion');

// Start 3D rendering
result.fmtion?.three?.start();

// Access scene
const scene = result.fmtion?.three?.getScene('main');

const result = await FasterMotion.load('/interactive.fmtion');

// Get/set parameters
result.fmtion?.parameters?.set('hero/hovered', true);
result.fmtion?.parameters?.set('menu/open', false);
result.fmtion?.parameters?.toggle('menu/open');

// Get parameter value
const isOpen = result.fmtion?.parameters?.get('menu/open');

const result = await FasterMotion.load('/hero.fmtion');

// ... use animations ...

// Cleanup when component unmounts or page changes
result.destroy();

import { useEffect, useRef } from 'react';
import { FasterMotion } from 'faster-motion';

function HeroSection() {
  const resultRef = useRef(null);

  useEffect(() => {
    async function loadAnimation() {
      resultRef.current = await FasterMotion.load('/hero.fmtion');
    }

    loadAnimation();

    // Cleanup on unmount
    return () => {
      resultRef.current?.destroy();
    };
  }, []);

  return <div className="hero">...</div>;
}

try {
  const result = await FasterMotion.load('/animation.fmtion');
} catch (error) {
  if (error.message.includes('Failed to fetch')) {
    console.error('Animation file not found');
  } else if (error.message.includes('Invalid data format')) {
    console.error('Invalid .fmtion file format');
  } else {
    console.error('Failed to load animation:', error);
  }
}

const result = await FasterMotion.load({
  meta: { name: 'Inline Animation' },
  parameters: {
    'hero/progress': { type: 'float', default: 0, min: 0, max: 1 }
  },
  scrollBindings: [{
    id: 'hero-scroll',
    parameter: 'hero/progress',
    trigger: '.hero',
    start: 'top top',
    end: 'bottom top'
  }],
  listeners: [],
  dom: [{
    selector: '.hero-title',
    driver: 'hero/progress',
    from: { opacity: 0, y: 50 },
    to: { opacity: 1, y: 0 }
  }],
  canvas: [],
  lottie: [{
    id: 'mascot',
    container: '#hero-lottie',
    src: '/mascot.json',
    scroll: {
      trigger: '.hero',
      scrub: true
    }
  }]
});

import { FasterMotion, FmtionFile, LoadOptions, LoadResult } from 'faster-motion';

const options: LoadOptions = {
  hooks: {
    onComplete: (id: string) => console.log(`Done: ${id}`)
  }
};

const fmtionData: FmtionFile = {
  meta: { name: 'Typed Animation' },
  parameters: {},
  scrollBindings: [],
  listeners: [],
  dom: [],
  canvas: []
};

const result: LoadResult = await FasterMotion.load(fmtionData, options);