agentleFS
xenodevexenodeve/xeno-skills/skills/vendor/spline-interactive/SKILL.md

spline-interactive

Skill2 starsChanged 35 days agoMITView on GitHub

Browser-based 3D design tool with visual editor, animation, and web export. Use this skill when creating 3D scenes without code, designing interactive web experiences, prototyping 3D UI, exporting to React/web, or building designer-friendly 3D content. Triggers on tasks involving Spline, no-code 3D, visual 3D editor, 3D animation, state-based interactions, React Spline integration, or scene export. Alternative to Three.js for designers who prefer visual tools over code.

  • Installs packages

4 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 7 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

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

    line 284
  2. Distinctive:

    Export from Spline: Use GLTF/GLB export

    line 430
  3. Distinctive:

    Enhance with code: Add custom shaders, physics, or effects

    line 432
  4. Distinctive:

    Use simple materials when possible

    line 523
  5. Distinctive:

    Use React.lazy() as shown in Pattern 6

    line 528
  6. Distinctive:

    Create separate mobile scenes with lower detail

    line 553
  7. Distinctive:

    No CORS errors in console

    line 593
  8. Distinctive:

    Run scripts from the skill directory:

    line 746

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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' }}>
        <Spline scene="https://prod.spline.design/YOUR-SCENE-ID/scene.splinecode" />
      </div>
    </main>
  );
}

Benefits:

  • Placeholder image shown during SSR
  • Faster perceived load times
  • Better SEO with fallback content

Pattern 6: Lazy Loading for Performance

Use Case: Defer Spline loading until needed

Implementation:

import React, { Suspense } from 'react';

// Dynamically import Spline
const Spline = React.lazy(() => import('@splinetool/react-spline'));

export default function LazyScene() {
  return (
    <div>
      <h1>My Page Content</h1>

      <Suspense fallback={<div>Loading 3D scene...</div>}>
        <div style={{ width: '100%', height: '500px' }}>
          <Spline scene="https://prod.spline.design/YOUR-SCENE-ID/scene.splinecode" />
        </div>
      </Suspense>

      <p>More content below</p>
    </div>
  );
}

Benefits:

  • Reduces initial bundle size
  • Improves page load performance
  • Shows custom loading UI

Pattern 7: Responsive Spline Scenes

Use Case: Make Spline scenes adapt to different screen sizes

Implementation:

import Spline from '@splinetool/react-spline';
import { useState, useEffect } from 'react';

export default function ResponsiveScene() {
  const [isMobile, setIsMobile] = useState(false);

  useEffect(() => {
    const checkMobile = () => {
      setIsMobile(window.innerWidth < 768);
    };

    checkMobile();
    window.addEventListener('resize', checkMobile);
    return () => window.removeEventListener('resize', checkMobile);
  }, []);

  return (
    <div style={{
      width: '100%',
      height: isMobile ? '400px' : '600px'
    }}>
      <Spline
        scene={
          isMobile
            ? "https://prod.spline.design/YOUR-MOBILE-SCENE/scene.splinecode"
            : "https://prod.spline.design/YOUR-DESKTOP-SCENE/scene.splinecode"
        }
      />
    </div>
  );
}

Alternative Approach (Single Scene):

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

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

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

  function adjustForScreenSize() {
    if (!splineApp.current) return;

    const camera = splineApp.current.findObjectByName('Camera');
    const isMobile = window.innerWidth < 768;

    if (isMobile) {
      // Zoom out on mobile
      splineApp.current.setZoom(0.7);
      // Adjust camera position
      camera.position.z = 1500;
    }
  }

  useEffect(() => {
    window.addEventListener('resize', adjustForScreenSize);
    return () => window.removeEventListener('resize', adjustForScreenSize);
  }, []);

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

Integration Patterns

With Three.js (threejs-webgl)

For advanced use cases, combine Spline-designed assets with Three.js code:

  1. Export from Spline: Use GLTF/GLB export
  2. Import in Three.js: Load using GLTFLoader
  3. Enhance with code: Add custom shaders, physics, or effects
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader';

const loader = new GLTFLoader();
loader.load('spline-model.glb', (gltf) => {
  scene.add(gltf.scene);
  // Add custom behaviors
});

With GSAP (gsap-scrolltrigger)

Trigger Spline animations on scroll:

import { useEffect, useRef } from 'react';
import Spline from '@splinetool/react-spline';
import gsap from 'gsap';
import ScrollTrigger from 'gsap/ScrollTrigger';

gsap.registerPlugin(ScrollTrigger);

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

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

    ScrollTrigger.create({
      trigger: '.scene-container',
      start: 'top center',
      onEnter: () => {
        app.emitEvent('mouseHover', 'Product');
      }
    });
  }

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

With Framer Motion (motion-framer)

Animate container while Spline handles 3D:

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

export default function AnimatedContainer() {
  return (
    <motion.div
      initial={{ opacity: 0, y: 50 }}
      animate={{ opacity: 1, y: 0 }}
      transition={{ duration: 0.8 }}
      style={{ width: '100%', height: '600px' }}
    >
      <Spline scene="https://prod.spline.design/YOUR-SCENE-ID/scene.splinecode" />
    </motion.div>
  );
}

Performance Optimization

1. Enable On-Demand Rendering

Render only when scene changes, not every frame:

<Spline
  scene="https://prod.spline.design/YOUR-SCENE-ID/scene.splinecode"
  renderOnDemand={true} // Default is true
/>

2. Optimize Scene in Spline Editor

In Spline:

  • Reduce polygon count (use decimation)
  • Compress textures (lower resolution, use JPG over PNG)
  • Limit lights (2-3 lights maximum)
  • Use simple materials when possible
  • Enable LOD (Level of Detail) for distant objects

3. Lazy Load Heavy Scenes

Use React.lazy() as shown in Pattern 6

4. Preload Critical Scenes

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

export default function PreloadedScene() {
  useEffect(() => {
    // Preload scene assets
    const link = document.createElement('link');
    link.rel = 'prefetch';
    link.href = 'https://prod.spline.design/YOUR-SCENE-ID/scene.splinecode';
    document.head.appendChild(link);
  }, []);

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

5. Mobile Optimizations

  • Create separate mobile scenes with lower detail
  • Reduce canvas resolution on mobile
  • Disable shadows and reflections
  • Use simpler materials
<Spline
  scene={isMobile ? mobileSceneUrl : desktopSceneUrl}
  style={{
    width: '100%',
    height: isMobile ? '300px' : '600px'
  }}
/>

Common Pitfalls and Solutions

Pitfall 1: Scene Not Loading

Problem: Spline component renders but scene doesn't appear

Solutions:

// ❌ Wrong: Invalid scene URL
<Spline scene="my-scene.splinecode" />

// ✅ Correct: Full URL from Spline export
<Spline scene="https://prod.spline.design/KFonZGtsoUXP-qx7/scene.splinecode" />

// Check for errors
function onLoad(app) {
  console.log('Scene loaded successfully', app);
}

<Spline scene={sceneUrl} onLoad={onLoad} />

Also Check:

  • Scene is published in Spline editor
  • Network tab shows successful file downloads
  • No CORS errors in console

Pitfall 2: Object References Lost After Re-render

Problem: Object refs become undefined after component updates

Solution:

// ❌ Wrong: Storing objects without proper refs
let myObject;

function onLoad(spline) {
  myObject = spline.findObjectByName('Cube'); // Lost on re-render
}

// ✅ Correct: Use React refs
const myObject = useRef();

function onLoad(spline) {
  myObject.current = spline.findObjectByName('Cube');
}

Pitfall 3: Performance Issues on Mobile

Problem: Scene runs slowly on mobile devices

Solutions:

// Create mobile-optimized version in Spline editor
// - Fewer polygons (< 50k triangles)
// - Smaller textures (512x512 or less)
// - No shadows or reflections
// - Simpler materials

// Load appropriate version
const isMobile = window.innerWidth < 768;
const sceneUrl = isMobile
  ? 'https://prod.spline.design/MOBILE-SCENE/scene.splinecode'
  : 'https://prod.spline.design/DESKTOP-SCENE/scene.splinecode';

<Spline scene={sceneUrl} renderOnDemand={true} />

Pitfall 4: Events Not Firing

Problem: Click or hover events don't trigger

Solutions:

// ❌ Wrong: Using wrong event name
<Spline onMouseDown={handler} /> // Not a Spline prop

// ✅ Correct: Use Spline event props
<Spline onSplineMouseDown={handler} />

// Also ensure object has events in Spline editor:
// 1. Select object in Spline
// 2. Add event in "Events" panel
// 3. Assign state transition or action

Pitfall 5: Animation Not Triggering Programmatically

Problem: emitEvent() doesn't trigger animation

Solutions:

// ❌ Wrong: Calling before scene loads
function triggerAnimation() {
  splineApp.current.emitEvent('mouseHover', 'Button'); // Error if not loaded
}

// ✅ Correct: Ensure scene is loaded
const [isLoaded, setIsLoaded] = useState(false);

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

function triggerAnimation() {
  if (isLoaded && splineApp.current) {
    splineApp.current.emitEvent('mouseHover', 'Button');
  }
}

// Also verify in Spline editor:
// - Object has the correct name ('Button')
// - mouseHover event is configured
// - Event has action (state transition, etc.)

Pitfall 6: Hydration Errors in Next.js

Problem: Mismatch between server and client render

Solution:

// ❌ Wrong: Using standard import in Next.js
import Spline from '@splinetool/react-spline';

// ✅ Correct: Use Next.js-specific import
import Spline from '@splinetool/react-spline/next';

// Or use dynamic import with ssr: false
import dynamic from 'next/dynamic';

const Spline = dynamic(
  () => import('@splinetool/react-spline'),
  { ssr: false }
);

Resources

Official Documentation

Spline Editor

Learning Resources

Export Formats

  • React component (via @splinetool/react-spline)
  • Vanilla JavaScript (Web Code API)
  • GLTF/GLB (for Three.js, Babylon.js)
  • USDZ (for Apple AR)
  • STL (for 3D printing)
  • Video/GIF (for marketing)

Related Skills

  • threejs-webgl: For code-first 3D development with more control
  • react-three-fiber: For building 3D scenes with React and JSX
  • babylonjs-engine: Alternative 3D engine with editor workflow
  • motion-framer: For animating Spline containers and UI elements
  • gsap-scrolltrigger: For scroll-driven Spline animations
  • figma-dev-mode: For design-to-code workflow (similar visual approach)

Scripts

This skill includes utility scripts:

  • project_generator.py - Generate Spline + React starter projects
  • component_builder.py - Build Spline component wrappers with events

Run scripts from the skill directory:

./scripts/project_generator.py
./scripts/component_builder.py

Assets

Starter templates and examples:

  • starter_spline/ - Complete React + Spline template
  • examples/ - Real-world integration patterns

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.