@splinetool/runtime 1.12.97 → 2.0.1

package/README.md

@@ -266,34 +266,207 @@ app.load('scene.spline').then(async () => {
 });
 ```
 
+### HTML content
+
+Scenes can carry an HTML document authored in the editor's HTML frame
+(`scene.publish.htmlContent` in the `.splinecode`). When present, the runtime
+automatically presents it over the canvas after `load()`/`start()`, connected
+to the Application through the injected `spline` API — variables, object
+queries, transient transforms, events. Pointer events on the page background
+pass through to the canvas, so orbit and scene interactions keep working. It
+is removed on `dispose()`. No setup is required; the canvas's parent element
+hosts the content (it is given `position: relative` when static).
+
+The `htmlContentMode` constructor option picks the presentation:
+
+- `sandbox` (default) — a sandboxed iframe (no `allow-same-origin`): the
+  content's scripts run in an opaque origin and cannot touch the host page.
+  Keep this wherever a page embeds scenes it didn't author; `spline.*` calls
+  cross a postMessage boundary, so writes land one frame late.
+- `inline` — the content is grafted into the host document and its scripts
+  run as ordinary page scripts, with `window.spline` bound directly to the
+  Application: calls execute synchronously inside the caller's frame (the
+  API stays promise-returning, so the same authored code runs unchanged in
+  either mode). Spline's own web exports use this. Only pass it when the
+  page author is the scene author — inline scripts run with the page's
+  origin. Inline mode additionally exposes `spline.createCustomMaterial`
+  (custom three.js/TSL materials — see below), which the sandbox cannot
+  carry.
+- `none` — don't present the HTML content at all.
+
 ## API
 
 ### Spline Application Methods
 
 You can call all these different methods on the Spline `Application` instance.
 
-| Name                  | Type                                                                 | Description                                                                                                                                        |
-| --------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `addEventListener`    | `(eventName: SplineEventName, cb: (e: SplineEvent) => void) => void` | Add an event listener for Spline events.                                                                                                           |
-| `removeEventListener` | `(eventName: SplineEventName, cb: (e: SplineEvent) => void) => void` | Remove an event listener for Spline events.                                                                                                        |
-| `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 camera zoom, expects a number value > 0 where 1 is base zoom.                                                                             |
-| `setSize`             | `(width: number, height: number) => void`                            | Sets the size of the application and canvas. When called, Spline will stop automatic size updates.                                                 |
-| `setVariables`        | `(variables: Record<string, string \| number \| boolean>) => void`   | Updates values for passed variables by name.                                                                                                       |
-| `setVariable`         | `(name: string, value: string \| number \| boolean) => void`         | Updates value for passed variable by name.                                                                                                         |
-| `getVariables`        | `() => Record<string, string \| number \| boolean>`                  | Returns a record mapping variable names to their respective current values.                                                                        |
-| `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.                                                                                  |
-| `swapGeometry`        | `(target: string, content: string \| Uint8Array) => Promise<void>`   | Replace the geometry from target if it is a mesh. Target parameter can be object name or uuid. Content parameter is url to `.splinegeometry` file. |
+| Name                  | Type                                                                       | Description                                                                                                                                                               |
+| --------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `addEventListener`    | `(eventName: SplineEventName, cb: (e: SplineEvent) => void) => void`       | Add an event listener for Spline events.                                                                                                                                  |
+| `removeEventListener` | `(eventName: SplineEventName, cb: (e: SplineEvent) => void) => void`       | Remove an event listener for Spline events.                                                                                                                               |
+| `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 camera zoom, expects a number value > 0 where 1 is base zoom.                                                                                                    |
+| `setSize`             | `(width: number, height: number) => void`                                  | Sets the size of the application and canvas. When called, Spline will stop automatic size updates.                                                                        |
+| `setVariables`        | `(variables: Record<string, string \| number \| boolean>) => void`         | Updates values for passed variables by name.                                                                                                                              |
+| `setVariable`         | `(name: string, value: string \| number \| boolean) => void`               | Updates value for passed variable by name.                                                                                                                                |
+| `getVariables`        | `() => Record<string, string \| number \| boolean>`                        | Returns a record mapping variable names to their respective current values.                                                                                               |
+| `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.                                                                                                         |
+| `swapGeometry`        | `(target: string, content: string \| Uint8Array) => Promise<void>`         | Replace the geometry from target if it is a mesh. Target parameter can be object name or uuid. Content parameter is url to `.splinegeometry` file.                        |
+| `createObject`        | `(type: string, options?: CreateObjectOptions) => Promise<SPEObject>`      | Creates a new object in the loaded scene (shapes, groups, lights, text) and returns its SPEObject proxy. See [Creating objects at runtime](#creating-objects-at-runtime). |
+| `cloneObject`         | `(source: string \| SPEObject, options?: CloneObjectOptions) => SPEObject` | Deep-clones an existing object (any type, including its subtree) with fresh ids and returns the clone's proxy.                                                            |
+| `removeObject`        | `(target: string \| SPEObject) => boolean`                                 | Removes an object (and its whole subtree) from the scene. Returns false when no object matched.                                                                           |
+
+### Creating objects at runtime
+
+`createObject` builds a new Spline object in the loaded scene. Objects created
+this way live only in the current runtime session — they are never persisted
+back to the Spline file.
+
+```js
+// A shape: the 'Geometry' suffix is optional, geometry parameters are flat.
+const cube = await spline.createObject('Cube', {
+	position: [0, 100, 0],
+	width: 150,
+	cornerRadius: 12,
+	material: { color: '#ff3b30', roughness: 0.4 },
+});
+cube.position.y = 200; // the returned proxy is the same handle findObjectByName gives
+
+// Reuse a shared material from the document by its name — the material stays
+// genuinely shared, so restyling it restyles every object using it.
+await spline.createObject('Sphere', {
+	material: 'Chrome',
+	position: { x: 120 },
+});
+
+// Text (loads the text feature + font on demand the first time).
+await spline.createObject('Text', { text: 'hello', fontSize: 48 });
+
+// Raw vertex geometry — compute the arrays yourself (terrain, low-poly rocks,
+// generative sculpture). Winding slips are safety-netted: closed solids wound
+// inside-out are flipped, open surfaces render double-sided.
+await spline.createObject('CustomMesh', {
+	vertices: [0, 0, 0, 100, 0, 0, 50, 100, 0], // flat [x,y,z, …]; Float32Array ok
+	indices: [0, 2, 1], // optional (omit for non-indexed, per-face vertices)
+	color: '#8a5a2b',
+});
+
+// Groups and lights.
+const group = await spline.createObject('Group', { name: 'Spawned' });
+await spline.createObject('PointLight', {
+	parent: group,
+	intensity: 2,
+	color: '#88f',
+});
+
+// Clone anything already in the scene — including types createObject can't
+// build (imported models, vectors, booleans, …).
+const copy = spline.cloneObject('Rocket', { position: [50, 0, 0] });
+
+// And remove objects again.
+spline.removeObject(copy);
+```
+
+Supported `createObject` types: `Cube`, `Sphere`, `Plane`, `Rectangle`,
+`Ellipse`, `Triangle`, `Polygon`, `Star`, `Cone`, `Cylinder`, `Pyramid`,
+`Torus`, `TorusKnot`, `Dodecahedron`, `Icosahedron`, `Helix`, `Backdrop`,
+`Lathe`, `Text`, `CustomMesh`, `Group`, `PointLight`, `SpotLight`,
+`DirectionalLight`. For anything else (paths, vectors, booleans, particles,
+UI…), clone an existing object with `cloneObject`.
+
+`CustomMesh` options: `vertices` (required — flat `[x,y,z, …]` `number[]` or
+`Float32Array`, max 60000 vertices), `indices` (triangle vertex indices,
+optional), `normals`/`uvs` (optional; normals are computed when omitted).
+Vertices are used at their real world-unit size. Indexed meshes get smooth
+normals; for a faceted look omit `indices` and duplicate vertices per
+triangle.
+
+Notes:
+
+- `rotation` in the options is in **degrees** (Spline's convention); the
+  returned proxy's `.rotation` is a three.js Euler in **radians**.
+- In the code-split build, the first `createObject('Text')` fetches the text
+  feature chunk and the font on demand. Per-scene compiled builds that were
+  exported without the text feature reject Text creation with a clear error.
+- Created/cloned objects don't join an already-initialized physics simulation.
+
+#### Custom WebGPU Three.js TSL shader materials — `createCustomMaterial`
+
+For custom shaders, build a TSL NodeMaterial with `createCustomMaterial`. The
+factory receives the runtime's **bundled** three instance — the only one TSL
+node graphs can compile in (TSL keeps per-module global state, so a material
+built from your own `three/webgpu` import can never work; the runtime bundles
+its own copy of three). The namespace carries the full `tsl` function object
+(`Fn`, `uniform`, `vec3`, `texture`, `wgslFn`, `positionLocal`, …), the
+NodeMaterial classes, and core essentials (`Color`, vectors, texture classes,
+side/blending/wrapping constants).
+
+```js
+const pulse = await spline.createCustomMaterial((three) => {
+	const { tsl } = three;
+	const m = new three.MeshStandardNodeMaterial();
+	m.colorNode = tsl.mix(
+		tsl.vec3(1, 0, 1),
+		tsl.vec3(0, 1, 1),
+		tsl.sin(tsl.time).mul(0.5).add(0.5)
+	);
+	return m;
+});
+
+// Reusable: share one material across any number of objects.
+await spline.createObject('Sphere', { material: pulse });
+await spline.createObject('Torus', { material: pulse, position: [200, 0, 0] });
+
+// createObject also accepts the factory form directly (like setMaterial):
+await spline.createObject('Cone', {
+	material: (three) => new three.MeshNormalNodeMaterial(),
+});
+
+// And replace an EXISTING mesh's material (instance or factory) — pinned:
+// states/transitions no longer restyle it, and there is no unset.
+await spline.setMaterial('Cube', pulse);
+```
+
+Typing escape hatch — with `@types/three` installed, cast the namespace for
+full TSL types (keep your `three` on the runtime's minor, 0.185):
+
+```ts
+const t = three as unknown as typeof import('three/webgpu') & {
+	tsl: typeof import('three/tsl');
+};
+```
+
+Support matrix:
+
+- **WebGPU backend only** (the default wherever WebGPU is available).
+- **Built-in materials** (`MeshStandardMaterial`, `MeshPhysicalMaterial`,
+  `MeshBasicMaterial`, `MeshNormalMaterial`, `MeshMatcapMaterial`, …) — they
+  are converted by three's node library, which looks materials up by their
+  `type` string, so your own three module instance is fine. **TSL
+  NodeMaterials** are supported when built with `createCustomMaterial` (instances
+  from your own `three/webgpu` import throw — separate module instance).
+  **GLSL `ShaderMaterial`/`RawShaderMaterial` throw** (the WebGPU node
+  pipeline can't compile GLSL) — port custom shaders to TSL via
+  `createCustomMaterial`.
+- Scene **lights and shadows apply**; Spline's environment/HDRI IBL does
+  **not** — set your own `envMap` if you need reflections.
+- Spline's side/flat-shading panel data no longer applies to the mesh — set
+  `material.side` yourself (e.g. `THREE.DoubleSide` for open CustomMesh
+  surfaces).
+- The material is **yours**: the runtime never disposes it, and the returned
+  proxy's `.material` is your instance (behind a transparent change-tracking
+  wrapper, so edits through it re-render automatically), not a layered
+  snapshot.
 
 ### Spline Objects Methods and Properties