@splinetool/runtime 1.10.16 → 1.10.17

package/README.md

@@ -176,6 +176,45 @@ spline.setVariables({ myName: 'Paul', mySize: 100 });
 spline.setVariable('myName', 'Ringo');
 ```
 
+### Procedural Transitions
+
+If you don't want to define your transition as actions in Spline Editor, it's possible to write and control them from this API. Note that you still need to set the object states from Spline editor, this API will only enable transitioning from one state to another, essentially exposing Spline's Transition action.
+
+```js
+import { Easing } from '@splinetool/runtime'
+
+// ...
+
+const sphere = spline.findObjectByName('Sphere')!;
+
+// Simplest way to transition sphere from current state to State.
+// The "to" param is the only mandatory parameter.
+sphere.transition({ to: 'State' });
+
+// Same transition with all params set with their default values
+sphere.transition({
+  from: undefined, // State name to start from, undefined will start from current state
+  to: 'State', // State name to go to, null will go to base state
+  duration: 1000, // in ms
+  delay: 0, // in ms
+  easing: Easing.LINEAR,
+  autoplay: true
+});
+
+// Force transition from Base State
+sphere.transition({ from: null, to: 'State' })
+
+// Chaining two transitions, the second one will be playing after first one is over
+sphere.transition({ to: 'State' }).transition({ to: 'State 2' });
+
+// Save transition object for later use
+const transition = sphere.transition({ to: 'State', autoPlay: false }).transition({ to: 'State 2' });
+transition.play()
+transition.pause()
+transition.reset()
+transition.seek(1000)
+```
+
 ## API
 
 ### Spline Application Methods
@@ -198,10 +237,32 @@ You can call all these different methods on the Spline `Application` instance.
 | `getVariable`         | `(name: string, value: string \| number \| boolean) => void`         | Get current value for a specific variable from its name                                                                             |
 | `stop`                | `() => void`                                                         | Stop/Pause all rendering controls and events.                                                                                       |
 | `play`                | `() => void`                                                         | Play/Resume rendering, controls and events.                                                                                         |
+| `pauseGameControls`.  | `() => void`                                                         | Stop/Pause Game Controls if any.                                                                                                    |
+| `resumeGameControls`. | `() => void`                                                         | Play/Resume Game Controls if any.                                                                                                   |
 | `setBackgroundColor`  | `(color:string) => void`                                             | Manually sets the scene/canvas background color with a css color value.                                                             |
 | `getAllObjects`       | `() => SPEObject[]`                                                  | Returns a flat list of all the objects present in the scene.                                                                        |
 | `getSplineEvents`     | `() => Object[]`                                                     | Returns an array listing all the Spline events used in the scene.                                                                   |
 
+### Spline Objects Methods and Properties
+
+After retrieving a Spline Object with `app.findObjectById` or `app.findObjectByName`, there are a variety of properties and methods you can call on those.
+
+| Name        | Type                        | Description                                                                                                                                |
+| ----------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `position`  | `Vector3`                   | Gets / Sets object position.                                                                                                               |
+| `rotation`  | `Vector3`                   | Gets / Sets object position.                                                                                                               |
+| `scale`     | `Vector3`                   | Gets / Sets object scale.                                                                                                                  |
+| `visible`   | `boolean`                   | Gets / Sets object vibility.                                                                                                               |
+| `state`     | `string\|number\|undefined` | Gets / Sets object's current state by name. undefined is used for default / Base State. You can also set from state index (0, 1, 2 etc...) |
+| `intensity` | `number`                    | Only for light objects. Used to change the light intensity.                                                                                |
+
+| Name         | Type                                   | Description                                                      |
+| ------------ | -------------------------------------- | ---------------------------------------------------------------- |
+| `show`       | `() => void`                           | Change object visible property to true.                          |
+| `hide`       | `() => void`                           | Change object visible property to false.                         |
+| `emitEvent`  | `(eventName: SplineEventName) => void` | Force trigger an event defined in Spline Editor.                 |
+| `transition` | `(params: TransitionParams) => void`   | Used to procedurally trigger a Spline transition between states. |
+
 ### Spline Events
 
 These are all the Spline event types that you can pass to the `addEventListener`, `emitEvent` and `emitEventReverse` function.