@splinetool/runtime 0.9.37 → 0.9.40

package/README.md

@@ -1,3 +1,149 @@
-# Runtime
+# Spline Runtime
 
-The code for the smaller spline build needed only to run the HTML export.
+**runtime** allows you to run Spline scenes in javascript.
+
+## Install
+
+```bash
+yarn add @splinetool/runtime
+```
+
+or
+
+```bash
+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:
+
+```js
+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 app = new Application(canvas);
+app.load('https://prod.spline.design/2qM3cW5Cx15m3cJ7/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)._
+
+```js
+import { Application } from '@splinetool/runtime';
+
+const canvas = document.getElementById('canvas3d');
+const app = new Application(canvas);
+app
+	.load('https://prod.spline.design/2qM3cW5Cx15m3cJ7/scene.splinecode')
+	.then(() => {
+		const obj = spline.findObjectByName('my object');
+		// or
+		// const obj = spline.findObjectById('8E8C2DDD-18B6-4C54-861D-7ED2519DE20E');
+
+		console.log(obj); // Spline Object => { name: 'my object', id: '8E8C2DDD-18B6-4C54-861D-7ED2519DE20E', 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.
+
+```js
+import { Application } from '@splinetool/runtime';
+
+const canvas = document.getElementById('canvas3d');
+const app = new Application(canvas);
+app
+	.load('https://prod.spline.design/2qM3cW5Cx15m3cJ7/scene.splinecode')
+	.then(() => {
+		app.addEventListener('mousedown', (e) => {
+			if (e.target.name === 'my object') {
+				// doSomething();
+			}
+		});
+	});
+```
+
+You can find a list of all of the Spline Event listeners in the [API](#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](#spline-events) and the ID of your object.
+
+_(You can get the ID of the object in the `Develop` pane of the right sidebar)._
+
+```js
+import { Application } from '@splinetool/runtime';
+
+const canvas = document.getElementById('canvas3d');
+const app = new Application(canvas);
+app
+	.load('https://prod.spline.design/2qM3cW5Cx15m3cJ7/scene.splinecode')
+	.then(() => {
+		app.emitEvent('mouseHover', '8E8C2DDD-18B6-4C54-861D-7ED2519DE20E');
+	});
+```
+
+Or you can query the spline object first, and then trigger the event:
+
+```js
+import { Application } from '@splinetool/runtime';
+
+const canvas = document.getElementById('canvas3d');
+const app = new Application(canvas);
+app
+	.load('https://prod.spline.design/2qM3cW5Cx15m3cJ7/scene.splinecode')
+	.then(() => {
+		const obj = spline.findObjectByName('my object');
+		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](#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, uuid: string) => void` | Triggers a Spline event associated to an object with provided uuid in reverse order. Starts from first state to last state. |
+| `emitEventReverse` | `(eventName: SplineEventName, uuid: string) => void` | Triggers a Spline event associated to an object with provided 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.                                                                                         |
+
+### 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    |