spline-interactive

仓库: freshtechbro/claudedesignskills
安装量: 55
排名: #13523

安装

npx skills add https://github.com/freshtechbro/claudedesignskills --skill 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
-
rotation
- { x, y, z } (radians)
scale
-
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:
Export from Spline
Use GLTF/GLB export
Import in Three.js
Load using GLTFLoader
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 Docs
:
https://docs.spline.design
React Spline GitHub
:
https://github.com/splinetool/react-spline
Spline Community
:
https://spline.community
Spline Editor
Web App
:
https://app.spline.design
Desktop App
Available for macOS, Windows, Linux
Learning Resources
Tutorials
:
https://spline.design/tutorials
YouTube Channel
Official Spline tutorials Examples Gallery : https://spline.design/community 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)
← 返回排行榜