storysplat-viewer 2.7.3 → 2.7.4

package/README.md

@@ -12,6 +12,7 @@ A powerful npm package for embedding and interacting with 3D Gaussian Splatting
 - [API Reference](#api-reference)
 - [Controlling the Viewer](#controlling-the-viewer)
 - [Configuration Options](#configuration-options)
+- [Internationalization (i18n)](#internationalization-i18n)
 - [Events](#events)
 - [React Integration](#react-integration)
 - [Analytics & Tracking](#analytics--tracking)
@@ -99,6 +100,27 @@ const viewer = createViewer(
 
 > **Note:** When using `createViewer` with self-hosted scenes, views and bandwidth are not tracked. Use `createViewerFromSceneId` for StorySplat-hosted scenes to get analytics.
 
+### Scene Data Format
+
+When using `createViewer()` with self-hosted JSON, the scene data should match the format exported by the StorySplat editor. Key fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `loadedModelUrl` | `string` | URL to the .splat, .ply, or .ksplat file |
+| `waypoints` | `array` | Camera path waypoints |
+| `hotspots` | `array` | Interactive hotspot markers |
+| `portals` | `array` | Scene-to-scene navigation portals |
+| `activeSkyboxUrl` | `string` | URL to the skybox HDR/image file |
+| `skyboxRotation` | `number` | Skybox rotation offset |
+| `lights` | `array` | Scene lighting configuration |
+| `particleSystems` | `array` | Particle effect systems |
+| `customMeshes` | `array` | Imported 3D models |
+| `uiColor` | `string` | Accent color for UI controls |
+| `uiOptions` | `object` | UI visibility toggles and button labels |
+| `defaultCameraMode` | `string` | Initial camera mode: `'tour'`, `'explore'`, or `'walk'` |
+
+The viewer's transform layer normalizes all field variations automatically, so JSON exported from any version of the editor will work.
+
 ## API Reference
 
 ### createViewerFromSceneId
@@ -163,8 +185,10 @@ async function fetchSceneMeta(
   description: string;
   thumbnailUrl: string;
   userName: string;
+  userSlug: string;
   views: number;
   tags: string[];
+  category?: string;
   createdAt: string | null;
 }>
 ```
@@ -187,21 +211,49 @@ interface ViewerInstance {
   getWaypointCount: () => number;
 
   // Camera
+  setCameraMode: (mode: 'tour' | 'explore') => void;
+  getCameraMode: () => string;
+  setExploreMode: (mode: 'orbit' | 'fly') => void;
   setPosition: (x: number, y: number, z: number) => void;
   setRotation: (x: number, y: number, z: number) => void;
   getPosition: () => { x: number; y: number; z: number };
   getRotation: () => { x: number; y: number; z: number };
 
-  // Playback
+  // Playback / Progress
   play: () => void;
   pause: () => void;
   stop: () => void;
   isPlaying: () => boolean;
+  setProgress: (progress: number) => void;
+  getProgress: () => number;
+
+  // Splat management
+  goToSplat: (url: string) => Promise<void>;
+  goToOriginalSplat: () => void;
+  getCurrentSplatUrl: () => string;
+  isShowingOriginalSplat: () => boolean;
+  getAdditionalSplats: () => Array<{ url: string; name?: string; waypointIndex: number; percentage: number }>;
+
+  // Audio
+  muteAll: () => void;
+  unmuteAll: () => void;
+  isMuted: () => boolean;
+
+  // Hotspots
+  getHotspots: () => Array<{ id: string; title?: string; type: string; position: { x: number; y: number; z: number } }>;
+  triggerHotspot: (id: string) => void;
+  closeHotspot: () => void;
+
+  // Portals
+  navigateToScene: (sceneId: string) => Promise<void>;
 
   // Lifecycle
   destroy: () => void;
   resize: () => void;
 
+  // UI customization
+  setButtonLabels: (labels: Partial<ButtonLabels>) => void;
+
   // Events
   on: (event: ViewerEvent, callback: (...args: any[]) => void) => void;
   off: (event: ViewerEvent, callback: (...args: any[]) => void) => void;
@@ -230,6 +282,7 @@ interface ViewerOptions {
   // Lazy loading
   lazyLoad?: boolean;
   lazyLoadThumbnail?: string;
+  lazyLoadThumbnailType?: 'image' | 'video' | 'gif';  // Thumbnail media type
   lazyLoadButtonText?: string;
 }
 ```
@@ -256,6 +309,90 @@ const viewer = createViewer(container, sceneData, {
 });
 ```
 
+## Internationalization (i18n)
+
+All user-facing UI text can be customized via `ButtonLabels`. This enables full translation or label renaming.
+
+### At Creation Time
+
+Set labels via `uiOptions.buttonLabels` in your scene data:
+
+```javascript
+const sceneData = await fetch('/scene.json').then(r => r.json());
+
+// Override labels before creating the viewer
+sceneData.uiOptions = {
+  ...sceneData.uiOptions,
+  buttonLabels: {
+    tour: 'Recorrido',
+    explore: 'Explorar',
+    walk: 'Caminar',
+    next: 'Siguiente',
+    previous: 'Anterior',
+    waypoints: 'Puntos',
+    close: 'Cerrar',
+    loading: 'Cargando...',
+  }
+};
+
+const viewer = createViewer(container, sceneData);
+```
+
+### At Runtime
+
+Update labels at any time with `setButtonLabels()`:
+
+```javascript
+const viewer = await createViewerFromSceneId(container, sceneId);
+
+// Switch to Spanish
+viewer.setButtonLabels({
+  tour: 'Recorrido',
+  explore: 'Explorar',
+  walk: 'Caminar',
+  next: 'Siguiente',
+  previous: 'Anterior',
+  close: 'Cerrar',
+  loading: 'Cargando...',
+});
+
+// Only update specific labels (others keep their current values)
+viewer.setButtonLabels({ next: 'Suivant', previous: 'Pr\u00e9c\u00e9dent' });
+```
+
+### Available Labels
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `tour` | `"Tour"` | Tour mode button |
+| `explore` | `"Explore"` | Explore mode button |
+| `walk` | `"Walk"` | Walk mode button |
+| `orbit` | `"Orbit"` | Orbit sub-mode button |
+| `fly` | `"Fly"` | Fly sub-mode button |
+| `next` | `"Next"` | Next waypoint button |
+| `previous` | `"Prev"` | Previous waypoint button |
+| `startExperience` | `"Start Experience"` | Start experience button |
+| `fullscreen` | `"Fullscreen"` | Fullscreen button aria-label |
+| `mute` / `unmute` | `"Mute"` / `"Unmute"` | Audio toggle |
+| `waypoints` | `"Waypoints"` | Waypoint dropdown label |
+| `close` | `"Close"` | Hotspot popup close button |
+| `yes` / `cancel` | `"Yes"` / `"Cancel"` | Portal confirmation buttons |
+| `switchScenes` | `"Switch scenes?"` | Portal default prompt |
+| `hotspotDefaultTitle` | `"Hotspot"` | Fallback hotspot title |
+| `openExternalLink` | `"Open External Link"` | Hotspot link button text |
+| `vr` / `ar` | `"VR"` / `"AR"` | XR button labels |
+| `exitVr` / `exitAr` | `"Exit VR"` / `"Exit AR"` | XR exit labels |
+| `loading` | `"Loading..."` | Loading progress text |
+| `loadingScene` | `"Loading {name}..."` | Portal scene loading (`{name}` replaced) |
+| `helpTitle` | `"Controls & Help"` | Help panel title |
+| `helpCameraModes` | `"Camera Modes:"` | Help section header |
+| `helpTourDesc` | `"Follow predefined path"` | Help tour description |
+| `helpExploreDesc` | `"Free movement"` | Help explore description |
+| `helpWalkDesc` | `"First-person walking"` | Help walk description |
+| `errorWebGLTitle` | `"Unable to Initialize 3D Graphics"` | WebGL error heading |
+| `errorWebGLMessage` | `"Your browser or device..."` | WebGL error body |
+| `percentageFormat` | `"{n}%"` | Progress percentage format |
+
 ## Events
 
 ```javascript
@@ -282,11 +419,39 @@ viewer.on('waypointChange', ({ index, waypoint }) => {
 // Playback state
 viewer.on('playbackStart', () => console.log('Playing'));
 viewer.on('playbackStop', () => console.log('Stopped'));
+viewer.on('playbackComplete', () => console.log('Tour finished'));
+
+// Camera mode
+viewer.on('modeChange', ({ mode }) => {
+  console.log(`Camera mode: ${mode}`);
+});
 
-// Errors
+// Scroll progress
+viewer.on('progressUpdate', ({ progress, index }) => {
+  console.log(`Progress: ${(progress * 100).toFixed(0)}%, waypoint ${index}`);
+});
+
+// XR sessions
+viewer.on('xrStart', ({ type }) => console.log(`Entered ${type}`));
+viewer.on('xrEnd', () => console.log('Exited XR'));
+
+// Splat swap
+viewer.on('splatChange', ({ url, isOriginal }) => {
+  console.log(`Splat changed: ${url} (original: ${isOriginal})`);
+});
+
+// Portal activated
+viewer.on('portalActivated', ({ sceneId }) => {
+  console.log(`Navigating to scene: ${sceneId}`);
+});
+
+// Errors and warnings
 viewer.on('error', (error) => {
   console.error('Viewer error:', error);
 });
+viewer.on('warning', ({ type, message }) => {
+  console.warn(`Warning [${type}]: ${message}`);
+});
 ```
 
 ## React Integration
@@ -415,21 +580,48 @@ function goToWaypoint(index) {
 
 | Method | Description |
 |--------|-------------|
-| `viewer.play()` | Start auto-playing through waypoints |
-| `viewer.pause()` | Pause auto-play |
-| `viewer.stop()` | Stop and reset to first waypoint |
-| `viewer.isPlaying()` | Check if currently auto-playing |
+| **Navigation** | |
+| `viewer.goToWaypoint(index)` | Jump to specific waypoint (0-indexed) |
 | `viewer.nextWaypoint()` | Go to next waypoint |
 | `viewer.prevWaypoint()` | Go to previous waypoint |
-| `viewer.goToWaypoint(index)` | Jump to specific waypoint (0-indexed) |
 | `viewer.getCurrentWaypointIndex()` | Get current waypoint index |
 | `viewer.getWaypointCount()` | Get total number of waypoints |
+| **Camera** | |
+| `viewer.setCameraMode(mode)` | Switch mode: `'tour'` or `'explore'` |
+| `viewer.getCameraMode()` | Get current camera mode |
+| `viewer.setExploreMode(mode)` | Switch explore sub-mode: `'orbit'` or `'fly'` |
 | `viewer.setPosition(x, y, z)` | Set camera position |
 | `viewer.setRotation(x, y, z)` | Set camera rotation (Euler angles) |
 | `viewer.getPosition()` | Get current camera position |
 | `viewer.getRotation()` | Get current camera rotation |
+| **Playback / Progress** | |
+| `viewer.play()` | Start auto-playing through waypoints |
+| `viewer.pause()` | Pause auto-play |
+| `viewer.stop()` | Stop and reset to first waypoint |
+| `viewer.isPlaying()` | Check if currently auto-playing |
+| `viewer.setProgress(progress)` | Set scroll progress (0-1) |
+| `viewer.getProgress()` | Get current scroll progress (0-1) |
+| **Splat Management** | |
+| `viewer.goToSplat(url)` | Swap to a different splat file at runtime |
+| `viewer.goToOriginalSplat()` | Switch back to the original splat |
+| `viewer.getCurrentSplatUrl()` | Get the currently loaded splat URL |
+| `viewer.isShowingOriginalSplat()` | Check if showing the original splat |
+| `viewer.getAdditionalSplats()` | Get the list of additional splat swap points |
+| **Audio** | |
+| `viewer.muteAll()` | Mute all audio |
+| `viewer.unmuteAll()` | Unmute all audio |
+| `viewer.isMuted()` | Check if audio is muted |
+| **Hotspots** | |
+| `viewer.getHotspots()` | Get all hotspot data (id, title, type, position) |
+| `viewer.triggerHotspot(id)` | Programmatically open a hotspot popup |
+| `viewer.closeHotspot()` | Close the currently open hotspot popup |
+| **Portals** | |
+| `viewer.navigateToScene(sceneId)` | Navigate to a linked scene via portal |
+| **Lifecycle** | |
 | `viewer.resize()` | Recalculate canvas size (call after container resize) |
 | `viewer.destroy()` | Clean up and remove viewer |
+| **UI** | |
+| `viewer.setButtonLabels(labels)` | Update UI text labels at runtime (see [i18n](#internationalization-i18n)) |
 
 ## Analytics & Tracking
 
@@ -654,7 +846,7 @@ import { generateHTML, generateHTMLFromUrl } from 'storysplat-viewer';
 // From scene data object
 const html = generateHTML(sceneData, {
   title: 'My Scene',
-  description: 'An interactive 3D experience'
+  description: 'An interactive 3D experience',
 });
 
 // From scene JSON URL
@@ -668,6 +860,21 @@ import fs from 'fs';
 fs.writeFileSync('scene.html', html);
 ```
 
+#### GenerateHTMLOptions
+
+```typescript
+interface GenerateHTMLOptions {
+  cdnUrl?: string;           // Custom CDN URL for the viewer bundle (default: unpkg)
+  title?: string;            // HTML page title (default: scene name)
+  description?: string;      // Meta description for SEO
+  faviconUrl?: string;       // Favicon URL
+  customCSS?: string;        // Custom CSS to inject into the page
+  minify?: boolean;          // Minify the output HTML
+  lazyLoad?: boolean;        // Show thumbnail + start button before loading
+  lazyLoadButtonText?: string; // Custom text for the lazy load button
+}
+```
+
 ## Portals (Scene-to-Scene Navigation)
 
 Portals allow users to navigate between multiple 3D scenes by clicking or walking near portal markers.