@splinetool/runtime

Spline Runtime

runtime allows you to run Spline scenes in javascript.

Install

yarn add @splinetool/runtime

or

npm install @splinetool/runtime

Usage

To use runtime, first you have to go to the Spline editor, click on the Export button, select "Code" and then "Vanilla JS".

You can copy the URL there and pass it to the .load() function:

import { Application } from '@splinetool/runtime';

// make sure you have a canvas in the body
const canvas = document.getElementById('canvas3d');

// start the application and load the scene
const spline = new Application(canvas);
spline.load('https://prod.spline.design/6Wq1Q7YGyM-iab9i/scene.splinecode');

You should be able to see the scene you exported in your canvas.

:warning: Only .splinecode files should be loaded through this API. .spline files are meant to be used in the editor.

Read and modify Spline objects

You can query any Spline object via findObjectByName or findObjectById.

(You can get the ID of the object in the Develop pane of the right sidebar).

import { Application } from '@splinetool/runtime';

const canvas = document.getElementById('canvas3d');
const spline = new Application(canvas);
spline
	.load('https://prod.spline.design/6Wq1Q7YGyM-iab9i/scene.splinecode')
	.then(() => {
		const obj = spline.findObjectByName('Cube');
		// or
		// const obj = spline.findObjectById('7AF5EBC0-09BB-4720-B045-F478F8053AA4');

		console.log(obj); // Spline Object => { name: 'Cube', id: '7AF5EBC0-09BB-4720-B045-F478F8053AA4', position: {}, ... }

		// move the object in 3D space
		obj.position.x += 10;
	});

Listen to events

You can listen to any Spline Event you set in the Events panel of the editor by attaching a listener to the Spline instance.

import { Application } from '@splinetool/runtime';

const canvas = document.getElementById('canvas3d');
const spline = new Application(canvas);
spline
	.load('https://prod.spline.design/6Wq1Q7YGyM-iab9i/scene.splinecode')
	.then(() => {
		spline.addEventListener('mousedown', (e) => {
			if (e.target.name === 'Cube') {
				console.log('I have been clicked!');
			}
		});
	});

You can find a list of all of the Spline Event listeners in the API section.

Trigger Spline events from outside

You can trigger any animation Event you set in the Events panel in the Spline Editor.

You can use the emitEvent function, passing the event type and the name or ID of your object.

(You can get the ID of the object in the Develop pane of the right sidebar).

import { Application } from '@splinetool/runtime';

const canvas = document.getElementById('canvas3d');
const spline = new Application(canvas);
spline
	.load('https://prod.spline.design/6Wq1Q7YGyM-iab9i/scene.splinecode')
	.then(() => {
		spline.emitEvent('mouseHover', 'Cube');
	});

Or you can query the spline object first, and then trigger the event:

import { Application } from '@splinetool/runtime';

const canvas = document.getElementById('canvas3d');
const spline = new Application(canvas);
spline
	.load('https://prod.spline.design/6Wq1Q7YGyM-iab9i/scene.splinecode')
	.then(() => {
		const obj = spline.findObjectByName('Cube');
		objectToAnimate.emitEvent('mouseHover');
	});

You can find a list of all of the Spline Events you can pass to the emitEvent function in the Spline Events section.

API

Spline Application Methods

You can call all these different methods on the Spline Application instance.

Name	Type	Description
emitEvent	(eventName: SplineEventName, nameOrUuid: string) => void	Triggers a Spline event associated to an object with provided name or uuid in reverse order. Starts from first state to last state.
emitEventReverse	(eventName: SplineEventName, nameOrUuid: string) => void	Triggers a Spline event associated to an object with provided name or uuid in reverse order. Starts from last state to first state.
findObjectById	(uuid: string) => SPEObject	Searches through scene's children and returns the object with that uuid.
findObjectByName	(name: string) => SPEObject	Searches through scene's children and returns the first object with that name.
setZoom	(zoom: number) => void	Sets the initial zoom of the scene.
setSize	(width: number, height:number) => void	Sets the size of the application and canvas. When called, Spline will stop automatic size updates.

Spline Events

These are all the Spline event types that you can pass to the emitEvent or emitEventReverse function.

Name	Description
mouseDown	Refers to the Spline Mouse Down event type
mouseHover	Refers to the Spline Mouse Hover event type
mouseUp	Refers to the Spline Mouse Up event type
keyDown	Refers to the Spline Key Down event type
keyUp	Refers to the Spline Key Up event type
start	Refers to the Spline Start event type
lookAt	Refers to the Spline Look At event type
follow	Refers to the Spline Mouse Up event type