storysplat-viewer 2.7.1 → 2.7.2

package/README.md

@@ -668,6 +668,204 @@ import fs from 'fs';
 fs.writeFileSync('scene.html', html);
 ```
 
+## Portals (Scene-to-Scene Navigation)
+
+Portals allow users to navigate between multiple 3D scenes by clicking or walking near portal markers.
+
+### How Portals Work
+
+Portals are configured in the scene JSON with a `targetSceneId`:
+
+```json
+{
+  "portals": [
+    {
+      "id": "portal-1",
+      "targetSceneId": "abc123xyz",
+      "targetSceneName": "Campervan Interior",
+      "position": { "x": 2, "y": 0, "z": -3 },
+      "type": "sphere",
+      "activationMode": "click"
+    }
+  ]
+}
+```
+
+### Portal Paths for Self-Hosted Scenes
+
+**Important:** By default, portals use StorySplat scene IDs and fetch from `discover.storysplat.com`. For fully self-hosted portals, you need to intercept the `portalActivated` event and implement custom navigation.
+
+#### Self-Hosted Portal Example
+
+```javascript
+import { createViewer } from 'storysplat-viewer';
+
+// Your self-hosted scene folder structure:
+// /scenes/
+//   ├── scene_campervan/
+//   │   └── scene.json
+//   ├── scene_cabin/
+//   │   └── scene.json
+//   └── scene_garden/
+//       └── scene.json
+
+// Load initial scene
+const initialScene = await fetch('/scenes/scene_campervan/scene.json').then(r => r.json());
+let viewer = await createViewer(container, initialScene);
+
+// Handle portal navigation with custom paths
+viewer.on('portalActivated', async (data) => {
+  console.log('Portal clicked:', data.targetSceneId);
+
+  // Map scene IDs to your folder paths
+  const scenePaths = {
+    'cabin-scene-id': '/scenes/scene_cabin/scene.json',
+    'garden-scene-id': '/scenes/scene_garden/scene.json',
+    // Or use the scene ID directly as folder name:
+    // [data.targetSceneId]: `/scenes/${data.targetSceneId}/scene.json`
+  };
+
+  const scenePath = scenePaths[data.targetSceneId];
+  if (!scenePath) {
+    console.error('Unknown scene:', data.targetSceneId);
+    return;
+  }
+
+  // Fetch from YOUR server
+  const newSceneData = await fetch(scenePath).then(r => r.json());
+
+  // Dispose old viewer and create new one
+  viewer.destroy();
+  viewer = await createViewer(container, newSceneData);
+
+  // Re-attach portal handler for the new scene
+  viewer.on('portalActivated', arguments.callee);
+});
+```
+
+#### Using Relative Paths
+
+If you want to use the `targetSceneId` directly as a folder name:
+
+```javascript
+viewer.on('portalActivated', async (data) => {
+  // targetSceneId becomes the folder name
+  const scenePath = `/scenes/${data.targetSceneId}/scene.json`;
+
+  const newSceneData = await fetch(scenePath).then(r => r.json());
+  viewer.destroy();
+  viewer = await createViewer(container, newSceneData);
+});
+```
+
+Then structure your folders to match:
+```
+/scenes/
+  ├── campervan/        ← targetSceneId: "campervan"
+  │   └── scene.json
+  ├── cabin/            ← targetSceneId: "cabin"
+  │   └── scene.json
+```
+
+#### Fully Self-Hosted (No StorySplat at All)
+
+If both scenes are created locally and **never uploaded to StorySplat**, you have full control over the `targetSceneId` values. They don't need to be real StorySplat IDs—use any string identifier you want:
+
+**Step 1: Edit your scene.json files to add portals with custom IDs**
+
+```json
+// scenes/campervan/scene.json
+{
+  "name": "Campervan Tour",
+  "portals": [
+    {
+      "id": "portal-1",
+      "targetSceneId": "cabin",
+      "targetSceneName": "Mountain Cabin",
+      "position": { "x": 2, "y": 0, "z": -3 },
+      "type": "sphere",
+      "activationMode": "click"
+    }
+  ]
+}
+```
+
+```json
+// scenes/cabin/scene.json
+{
+  "name": "Mountain Cabin",
+  "portals": [
+    {
+      "id": "portal-back",
+      "targetSceneId": "campervan",
+      "targetSceneName": "Back to Campervan",
+      "position": { "x": -1, "y": 0, "z": 2 },
+      "type": "sphere",
+      "activationMode": "click"
+    }
+  ]
+}
+```
+
+**Step 2: Complete self-hosted viewer code**
+
+```javascript
+import { createViewer } from 'storysplat-viewer';
+
+const container = document.getElementById('viewer');
+
+// Map your scene identifiers to file paths
+const SCENES = {
+  'campervan': '/scenes/campervan/scene.json',
+  'cabin': '/scenes/cabin/scene.json',
+  'garden': '/scenes/garden/scene.json'
+};
+
+let currentViewer = null;
+
+async function loadScene(sceneId) {
+  // Cleanup previous viewer
+  if (currentViewer) {
+    currentViewer.destroy();
+  }
+
+  // Fetch scene from YOUR server
+  const sceneData = await fetch(SCENES[sceneId]).then(r => r.json());
+
+  // Create viewer
+  currentViewer = await createViewer(container, sceneData);
+
+  // Handle portal clicks - loads target scene from your server
+  currentViewer.on('portalActivated', (data) => {
+    loadScene(data.targetSceneId);
+  });
+}
+
+// Start with initial scene
+loadScene('campervan');
+```
+
+**Key point:** The `targetSceneId` is just a string you define. It doesn't need to exist on StorySplat—you map it to your own file paths.
+
+#### Portal Events
+
+| Event | Description | Data |
+|-------|-------------|------|
+| `portalActivated` | Portal clicked or proximity triggered | `{ portalId, targetSceneId, targetSceneName }` |
+| `portalNavigationStart` | Navigation beginning | `{ targetSceneId }` |
+| `portalNavigationComplete` | New scene loaded | `{ sceneId }` |
+| `portalNavigationError` | Navigation failed | `{ error, targetSceneId }` |
+
+### Q: Where does the viewer look for scene files?
+
+**A: It depends on how you load scenes:**
+
+- **`createViewerFromSceneId()`** - Fetches from `discover.storysplat.com/api/scene/{id}`
+- **`createViewer(sceneData)`** - Uses the data object you pass in directly (no fetch)
+- **Splat file URLs in scene JSON** - Can be absolute URLs or relative to your page
+
+The viewer itself has no "base path" concept - splat file paths in your scene JSON should be absolute URLs or relative to your HTML page, not to the viewer JS file.
+
 ## Support
 
 - GitHub Issues: [github.com/SonnyC56/storysplat-viewer/issues](https://github.com/SonnyC56/storysplat-viewer/issues)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "storysplat-viewer",
-  "version": "2.7.1",
+  "version": "2.7.2",
   "description": "PlayCanvas-based 3D viewer for StorySplat scenes - HTML export & dynamic embedding",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",