Spline Interactive

Spline Interactive - Browser-Based 3D Design and Animation

Overview

Spline is a browser-based 3D design and animation platform that enables creators to build interactive 3D experiences without requiring code or specialized software knowledge. It provides a collaborative visual editor for designing, animating, and exporting 3D scenes across multiple platforms.

Key Features:

• Visual 3D modeling with parametric shapes, extrusion, and boolean operations
• State-based animation system with timeline controls
• Interactive event system (mouse, keyboard, collision, scroll)
• Multiple export options (React components, web code, public URLs)
• Real-time collaboration with team libraries
• AI-powered generation (3D from text, textures, style transfer)
• Built-in physics and particle systems

When to Use This Skill:

• Creating 3D web experiences without writing Three.js code
• Designing interactive product showcases or configurators
• Prototyping 3D UI/UX concepts visually
• Building marketing pages with 3D elements
• Collaborating with designers on 3D content
• Exporting scenes for React or vanilla JS integration

Alternatives:

• Three.js (threejs-webgl): For developers who prefer code-first approach and need maximum control
• Babylon.js (babylonjs-engine): For game-focused projects with built-in physics
• React Three Fiber (react-three-fiber): For React developers who want to build 3D with JSX

Core Concepts

1. Scene Structure

Spline organizes projects into scenes containing:

• Objects: 3D models, shapes, text, images
• Lights: Directional, point, spot lights
• Cameras: Orbital, perspective, orthographic
• Events: Interaction triggers
• States: Animation keyframes

2. Components System

Reusable elements that can be:

• Created from any object or group
• Instantiated multiple times
• Updated across all instances
• Overridden per instance

3. State-Based Animation

Animations are defined as transitions between states:

• Default State: Initial appearance
• Additional States: Target appearances
• Events: Triggers that cause state transitions
• Transitions: Duration, easing, properties

4. Interactivity Model

Event-driven system with:

• Events: User actions or scene triggers
• Conditions: Logic gates (if/else)
• Actions: State changes, audio, scene switches
• Variables: Dynamic data from APIs or user input

5. Export Options

Multiple deployment methods:

• Public URL: Direct shareable link
• Code Export: React component or vanilla JS
• Spline Viewer: Embedded iframe
• Self-Hosted: Download and host independently

Common Patterns

Pattern 1: Basic React Integration

Use Case: Embed a Spline scene in a React application

Implementation:

# Installation
npm install @splinetool/react-spline @splinetool/runtime

import Spline from '@splinetool/react-spline';

export default function Hero() {
  return (
    <div style={{ width: '100%', height: '600px' }}>
      <Spline scene="https://prod.spline.design/YOUR-SCENE-ID/scene.splinecode" />
    </div>
  );
}

Key Points:

• Scene URL comes from Spline export dialog
• Component fills parent container
• Automatically handles loading and rendering

Pattern 2: Event Handling and Object Interaction

Use Case: Respond to user clicks on specific objects

Implementation:

import Spline from '@splinetool/react-spline';

export default function InteractiveScene() {
  function onSplineMouseDown(e) {
    // Check if clicked object is the button
    if (e.target.name === 'Button') {
      console.log('Button clicked!');

      // Get object properties
      console.log('Position:', e.target.position);
      console.log('Rotation:', e.target.rotation);
      console.log('Scale:', e.target.scale);
    }
  }

  function onSplineMouseHover(e) {
    if (e.target.name === 'Button') {
      console.log('Hovering over button');
    }
  }

  return (
    <Spline
      scene="https://prod.spline.design/YOUR-SCENE-ID/scene.splinecode"
      onSplineMouseDown={onSplineMouseDown}
      onSplineMouseHover={onSplineMouseHover}
    />
  );
}

Available Event Handlers:

• onSplineMouseDown - Mouse press on object
• onSplineMouseUp - Mouse release
• onSplineMouseHover - Mouse over object
• onSplineKeyDown - Keyboard press
• onSplineKeyUp - Keyboard release
• onSplineStart - Scene loaded and started
• onSplineLookAt - Camera look-at event
• onSplineFollow - Camera follow event
• onSplineScroll - Scroll event

Pattern 3: Programmatic Object Control

Use Case: Modify object properties from React code

Implementation:

import { useRef } from 'react';
import Spline from '@splinetool/react-spline';

export default function ProductViewer() {
  const cube = useRef();
  const splineApp = useRef();

  function onLoad(spline) {
    // Save Spline instance
    splineApp.current = spline;

    // Find object by name
    const obj = spline.findObjectByName('Product');
    // Or by ID
    // const obj = spline.findObjectById('8E8C2DDD-18B6-4C54-861D-7ED2519DE20E');

    cube.current = obj;
  }

  function rotateProduct() {
    if (cube.current) {
      // Rotate 45 degrees around Y axis
      cube.current.rotation.y += Math.PI / 4;
    }
  }

  function changeColor() {
    if (cube.current) {
      // Change material color (hex color)
      cube.current.material.color.set(0xff6b6b);
    }
  }

  function moveProduct() {
    if (cube.current) {
      cube.current.position.x += 50;
      cube.current.position.y += 10;
    }
  }

  return (
    <div>
      <Spline
        scene="https://prod.spline.design/YOUR-SCENE-ID/scene.splinecode"
        onLoad={onLoad}
      />
      <div style={{ position: 'absolute', top: 20, left: 20 }}>
        <button onClick={rotateProduct}>Rotate</button>
        <button onClick={changeColor}>Change Color</button>
        <button onClick={moveProduct}>Move</button>
      </div>
    </div>
  );
}

Object Properties You Can Modify:

• position - { x, y, z }
• rotation - { x, y, z } (radians)
• scale - { x, y, z }
• material.color - Color hex value
• visible - Boolean

Pattern 4: Triggering Spline Animations

Use Case: Trigger animations defined in Spline from React

Implementation:

import { useRef } from 'react';
import Spline from '@splinetool/react-spline';

export default function AnimatedCard() {
  const splineApp = useRef();

  function onLoad(app) {
    splineApp.current = app;
  }

  function triggerHoverAnimation() {
    // Emit mouseHover event on 'Card' object
    splineApp.current.emitEvent('mouseHover', 'Card');
  }

  function triggerClickAnimation() {
    // Emit mouseDown event on 'Button' object
    splineApp.current.emitEvent('mouseDown', 'Button');
  }

  function reverseAnimation() {
    // Play animation in reverse
    splineApp.current.emitEventReverse('mouseHover', 'Card');
  }

  return (
    <div>
      <Spline
        scene="https://prod.spline.design/YOUR-SCENE-ID/scene.splinecode"
        onLoad={onLoad}
      />
      <button onClick={triggerHoverAnimation}>Hover Effect</button>
      <button onClick={triggerClickAnimation}>Click Effect</button>
      <button onClick={reverseAnimation}>Reverse</button>
    </div>
  );
}

Available Event Types:

• mouseDown - Mouse press
• mouseHover - Hover effect
• mouseUp - Mouse release
• keyDown - Key press
• keyUp - Key release
• start - Start event
• lookAt - Look at camera
• follow - Follow camera

Pattern 5: Next.js Integration with SSR

Use Case: Use Spline in Next.js with server-side rendering benefits

Implementation:

// app/page.js (Next.js 13+ App Router)
import Spline from '@splinetool/react-spline/next';

export default function Home() {
  return (
    <main>
      <div style={{ width: '100vw', height: '100vh' }}>