# StorySplat — Documentation and Integration Reference

This reference describes the current source implementation. Runtime behavior depends on the version deployed or pinned for a scene. Follow the feature guides for configuration details; use the installed SDK types when writing code.

StorySplat provides a browser scene editor, hosted scene viewing and a PlayCanvas-based viewer SDK. It supports guided waypoint tours, hotspots, scene portals, audio and visual scene elements. Feature prerequisites and current limitations are described in the documentation below.

Normal hosted embeds require a public or unlisted scene. Private scenes require an authorized viewing path and cannot be embedded on an unrelated website. Unlisted scenes are omitted from StorySplat catalog and indexing paths; external search engines may retain older indexed URLs.

Scene-ID embeds fetch saved content on initialization or navigation. An already-open viewer is not subscribed to editor changes. Self-hosted exports are snapshots and require a web server and validation of packaged assets and linked scenes. Authored external content can still require a network.

## Imports and generation

- The editor accepts PLY, SOG, SPLAT, SPZ, LCC/LCC2 folders and GLB/GLTF scene sources. Format and container versions matter; an extension alone does not establish compatibility.
- Native SPZ v4 uses the PlayCanvas SPZ parser. Older gzip SPZ and raw SPLAT require conversion; the editor import path converts them to SOG for preview.
- Browser conversion tools have specific input lists. Compression savings depend on the input and settings; decompression cannot restore information lost during compression.
- Photo and panorama generation are separate cloud workflows. Normal photos have a 10 MiB limit; panoramas have a 50 MiB limit and require a 2:1 equirectangular layout. Generations require the applicable entitlement, remaining credits, storage and service availability.
- A generated image or splat is an inferred result. Generation does not guarantee structural accuracy or automatically create usable walk collision.
- Virtual Staging overlays a generated image at a saved camera pose. It does not reconstruct a replacement 3D scene. Inspect generated geometry and furnishings before using the result.

## Authoring and viewing

- Published navigation uses Tour and Explore modes; Explore offers Orbit, Fly and Walk subject to scene configuration. FPV drone mode has separate controls.
- Tours use waypoints, path interpolation, easing and optional authored curves. Paths do not automatically avoid walls. Generic waypoint proximity-trigger handlers are currently placeholders; audio has its own trigger system.
- Walk mode requires usable collision data. Its height, speed and distances are expressed in scene units. Imported captures are not necessarily scaled in metres.
- Measurements require calibration against a known distance. Starting calibration clears the measurement list.
- HTML meshes use DOM/CSS 3D panels above the canvas and are not occluded by splats. Legacy fit-strategy and background-color fields are saved but ignored by this renderer.
- Relighting modulates captured splat colors with ambient and light contributions. It does not remove baked lighting or reconstruct surface normals.
- Particle, fog, mirror, post-processing and animation costs depend on configuration and device. No fixed frame rate or memory capacity is guaranteed.
- Water-plane runtime support exists, but the editor's water feature flag is disabled in this source configuration.

## SDK integration

Install `storysplat-viewer` with its compatible `playcanvas` peer dependency for npm builds. The bundled CDN script includes PlayCanvas. Pin an exact tested runtime version when reproducibility matters.

`createViewerFromSceneId(container, sceneId, options)` loads hosted scene data. `createViewerFromUrl(container, url, options)` fetches scene JSON. `createViewer(container, sceneData, options)` uses a supplied scene object. Create only in the browser, in a nonzero-sized container. Await creation to obtain the API; asset loading continues separately. Catch creation failures and handle later `error` events. Events are not replayed to late subscribers.

Destroy instances when removing or replacing their host, including instances that finish creation after unmount. Give overlapping asynchronous creations separate host elements. The framework examples include this cleanup.

Tour navigation requires Tour mode. Tour autoplay needs at least two waypoints. `autoPlay: true` requests initial playback through the presentation gate; false does not override authored autoplay. Browser policy can block audible media until a gesture. `isPlaying()` reports tour autoplay; `isFrameSequencePlaying()` reports frame playback.

The `backgroundColor` viewer option is currently ignored. Set it in scene configuration for `createViewer`. A `portalActivated` listener takes over default scene-portal navigation; a logging-only listener prevents that default navigation.

4DGS playback takes an ordered `frameUrls` array of supported frame assets. It has no built-in manifest loader or video-to-splat reconstruction pipeline. Host the frames yourself with the required read access and cross-origin response policy. `frameChange` passes frame index and total as separate callback arguments. Initial player creation is not proof the first frame has downloaded.

## Analytics, access and external integrations

Visitor tracking depends on scene/embed settings and browser privacy signals. Bandwidth accounting has separate rules. `disableAnalytics: true` disables the viewer's built-in session, Google-tag and bandwidth reporting; user-authored external content has its own behavior. Counts and visitor identifiers are measurements with collection limits, not proof of a business outcome or a person's identity.

The WordPress plugin uses hosted iframes. Its shortcode defaults and Gutenberg block attributes are separate. Webflow integration can use an iframe or bundled script in an allowed Code Embed element. An oEmbed consumer decides whether and how to render provider HTML; a successful provider response does not guarantee a specific third-party platform will display it.

The current custom-script wrapper fails compilation because it binds `eval` in strict mode; editor preview and published script execution are affected. The intended custom-script API uses an allowlist of viewer methods and shadowed globals in the page. This is not an isolated browser sandbox. Scripts must clean up their API listeners and timers when re-executed.

Self-hosted export access and watermark controls are enforced by account entitlements. Check current account terms and pricing rather than inferring rights from the availability of scene JSON. The desktop build uses local project storage and local export workflows; optional provider-backed AI still requires its configured provider connection. Review the desktop delivery instructions for the particular build and license supplied.

## Feature guides

- [Introduction](https://discover.storysplat.com/docs/introduction)
- [Quick Start Guide](https://discover.storysplat.com/docs/quick-start)
- [Sharing & Visibility](https://discover.storysplat.com/docs/visibility)
- [Image to Splat](https://discover.storysplat.com/docs/image-to-splat)
- [Virtual Staging](https://discover.storysplat.com/docs/virtual-staging)
- [Camera & Navigation](https://discover.storysplat.com/docs/camera-controls)
- [Waypoints & Timeline](https://discover.storysplat.com/docs/waypoints)
- [Interactive Hotspots](https://discover.storysplat.com/docs/hotspots)
- [Connections](https://discover.storysplat.com/docs/portals)
- [Lighting](https://discover.storysplat.com/docs/lighting)
- [Skybox & Environment](https://discover.storysplat.com/docs/skybox)
- [Audio](https://discover.storysplat.com/docs/audio)
- [3D Models](https://discover.storysplat.com/docs/meshes)
- [HTML Mesh](https://discover.storysplat.com/docs/html-mesh)
- [Particle Effects](https://discover.storysplat.com/docs/particles)
- [Weather & Fog](https://discover.storysplat.com/docs/atmosphere)
- [Splat Editing](https://discover.storysplat.com/docs/splat-editing)
- [Measurements](https://discover.storysplat.com/docs/measurements)
- [Animation](https://discover.storysplat.com/docs/animation)
- [Collision](https://discover.storysplat.com/docs/collision)
- [Splat Swap](https://discover.storysplat.com/docs/splat-swap)
- [Compare Mode](https://discover.storysplat.com/docs/compare)
- [Mirror Planes](https://discover.storysplat.com/docs/mirror-planes)
- [Post-Processing](https://discover.storysplat.com/docs/post-processing)
- [Splat Relighting](https://discover.storysplat.com/docs/relighting)
- [Guided Narration](https://discover.storysplat.com/docs/narration)
- [Walk Mode](https://discover.storysplat.com/docs/walk-mode)
- [Theme Customization](https://discover.storysplat.com/docs/theme-customization)
- [Custom Menu Links](https://discover.storysplat.com/docs/menu-links)
- [Custom Scripts](https://discover.storysplat.com/docs/custom-scripts)
- [Web Embeds](https://discover.storysplat.com/docs/embeds)
- [oEmbed & Iframely](https://discover.storysplat.com/docs/oembed)
- [Analytics](https://discover.storysplat.com/docs/analytics)
- [Webflow](https://discover.storysplat.com/docs/webflow)
- [WordPress](https://discover.storysplat.com/docs/wordpress)
- [StorySplat Viewer](https://discover.storysplat.com/docs/viewer-overview)
- [API Controls](https://discover.storysplat.com/docs/api-controls)
- [4DGS Playback](https://discover.storysplat.com/docs/4dgs-playback)
- [Format Conversion](https://discover.storysplat.com/docs/format-conversion)
- [Hosting 4DGS](https://discover.storysplat.com/docs/hosting-4dgs)
- [AI Agent Instructions](https://discover.storysplat.com/docs/agent-instructions)

## Product links

- [Editor](https://storysplat.com/editor)
- [Current plans](https://storysplat.com/pricing)
- [Viewer SDK](https://www.npmjs.com/package/storysplat-viewer)