Skip to main content

Embedding the Viewer

The SuperSplat Viewer is published on npm as @playcanvas/supersplat-viewer. You can host the prebuilt viewer and configure it with URL parameters, generate a page around it, or create viewers inside your own web app.

If your splat is already published on superspl.at, the simplest embed is an <iframe> from the Embed dialog on its scene page.

Choosing an approach​

ApproachUse when
Host the prebuilt viewerYou want to serve the viewer's static files and point them at a splat and settings.json, configuring each page with URL parameters.
Generate a page with renderViewerHtmlYour server or build writes the HTML page, with the asset URLs and settings filled in.
Create a viewer in your page with createViewerYour web app owns the page, and creates, controls and destroys viewers itself.

Installing​

npm install @playcanvas/supersplat-viewer

The package has these entry points:

ImportProvides
@playcanvas/supersplat-viewerrenderViewerHtml, and the viewer's stylesheet and bundle as the strings css and js
@playcanvas/supersplat-viewer/viewercreateViewer, with playcanvas (2.24.1 or later) as a peer dependency
@playcanvas/supersplat-viewer/viewer.cssThe stylesheet createViewer needs
@playcanvas/supersplat-viewer/settingsSettings types, defaults, validation and migration. See Experience Settings.

The main entry also exports the viewer's page as the string html, but it is deprecated: its formatting changes between releases, so use renderViewerHtml instead.

Hosting the prebuilt viewer​

The package's public/ folder holds the standalone viewer: index.html, index.js, index.css, and the WebAssembly decoders (.wasm files) that some formats need. Copy the folder to your web server and open index.html. With no parameters, it loads ./settings.json and ./scene.compressed.ply from beside it.

The .wasm files are fetched only for content that needs them, such as version 4 .spz files. Serve them as application/wasm.

URL parameters​

Configure each page with query parameters, for example index.html?content=./museum/lod-meta.json&settings=./museum/settings.json. These parameters are subject to change as the viewer evolves; the project README lists the current set, along with a few more for developers.

Content​

ParameterDescriptionDefault
settingsURL of the Experience Settings JSON file./settings.json
contentURL of the splat. See Supported content../scene.compressed.ply
skyboxURL of an equirectangular skybox image(none)
posterURL of an image shown, blurred, while the scene loads(none)
collisionURL of collision data for walk mode: a .voxel.json file (with its .voxel.bin beside it), or a .glb mesh. voxel is an alias.(none)

UI​

ParameterDescription
nouiHide the viewer's built-in UI
noanimStart with the camera animation paused
reticleShow a center reticle in fly and walk mode while the mouse is captured
ministatsShow runtime CPU/GPU performance graphs
langThe UI language: de, en, es, fr, ja, ko, pt-BR, ru or zh-CN. By default, the browser's language.
vrShow a Tap to enter VR prompt while the scene loads, where VR is available. See Viewing in VR and AR.

Rendering​

ParameterDescription
webglUse WebGL. By default the viewer uses WebGPU where it's available.
aaForce the anti-aliasing compensation for splats trained with anti-aliasing: aa, aa=1, aa=true or aa=enable turn it on for every splat, any other value turns it off. Without it, each splat file's own training mode decides.
hprOverride the settings' highPrecisionRendering: hpr, hpr=1, hpr=true or hpr=enable turn it on, any other value off.
nofxTurn off post effects
budgetThe Gaussian budget, in millions, overriding every Quality position
fullloadLoad all of a streamed scene's detail before the first frame
stochasticExperimental. Force the stochastic splat renderer that Performance Mode uses: stochastic in its per-pixel mode, stochastic=mobile in its mode for phones and headsets, or stochastic=off to keep the standard renderer. Each hides the Performance Mode setting. WebGPU only.
colorizeColor the Gaussians by level of detail
heatmapDraw the collision overlay as a heat map. Needs WebGPU and voxel collision; turn the overlay on with Show Collision or V.
debugOpen the developer debug panel on load (Ctrl+Shift+D toggles it)

Supported content​

The viewer picks the format from the content's file name:

FormatFile
PLY.ply, .compressed.ply
SOG.sog, or the meta.json of an unbundled SOG
Streamed SOGlod-meta.json
SPZ.spz (versions 3 and 4)
XGRIDS LCC2.lcc2, streamed on demand like a Streamed SOG

SOG v3 files written by splat-transform 3.11.0 or 3.11.1 use an earlier layout that the viewer no longer reads. Convert them again with a current splat-transform.

Generating a page​

If your server or build generates the page around the viewer, use renderViewerHtml. It returns a complete HTML document, with your asset URLs and settings supplied in a single JSON block:

import { renderViewerHtml } from '@playcanvas/supersplat-viewer';

const page = renderViewerHtml({
bootstrap: {
settings, // an object, or omit it and set settingsUrl
contentUrl: 'scene.sog',
posterUrl: 'poster.jpg'
},
baseHref: '/viewer/', // serving from a sub-path
backgroundColor: [0, 0, 0], // components are 0..1, not 0..255
headExtras: '<script src="analytics.js"></script>',
inlineCss: true // no sibling index.css needed
});
OptionDescription
bootstrapThe page's assets and settings: settings or settingsUrl, contentUrl, contentFilename, posterUrl, skyboxUrl, collisionUrl and zstdDecoderUrl
baseHrefThe page's base URL, for serving the viewer from a sub-path
backgroundColorThe page background before the first frame, as 0–1 RGB like the settings' background.color
headExtras / bodyStartExtrasMarkup added to the <head>, or at the start of the <body>
inlineCss / inlineJsInline the stylesheet or the bundle instead of loading index.css and index.js from beside the page

Called with no options, it returns the page the package ships, unchanged. URL parameters on the served page still override the bootstrap's asset URLs, so each instance stays configurable, except inline settings, which take precedence over ?settings=.

For a single self-contained file, set both inlineCss and inlineJs, pass the settings inline, and pass the splat as a data: URI in contentUrl. A data: URI has no file name, so name the content with contentFilename, such as scene.sog:

const page = renderViewerHtml({
bootstrap: {
settings,
contentUrl: sogDataUri,
contentFilename: 'scene.sog'
},
inlineCss: true,
inlineJs: true
});

A single-file page that loads a version 4 .spz file also needs the decoder inline: set zstdDecoderUrl to zstd-decoder.wasm as a data: URL. zstdDecoderUrl has no URL parameter, since a link could otherwise run any WebAssembly in your page's origin.

Creating a viewer in your own page​

If your web app owns the page, create the viewer inside one of its elements:

import { createViewer } from '@playcanvas/supersplat-viewer/viewer';
import '@playcanvas/supersplat-viewer/viewer.css';

const viewer = await createViewer({
container: document.getElementById('viewer'),
settings: './settings.json',
contentUrl: './scene.sog'
});

// later
viewer.destroy();

The returned handle controls loading, playback, the camera, annotations, fullscreen and XR, and the built-in UI can be restyled or replaced. See Viewer API.

Settings JSON​

The settings parameter or option points at an Experience Settings v2 document, the same JSON format Studio saves. This is the complete document that defaultSettings() from @playcanvas/supersplat-viewer/settings generates:

{
"version": 2,
"tonemapping": "linear",
"highPrecisionRendering": false,
"background": {
"color": [0, 0, 0]
},
"postEffectSettings": {
"sharpness": { "enabled": false, "amount": 0 },
"bloom": { "enabled": false, "intensity": 0.1, "blurLevel": 2 },
"grading": { "enabled": false, "brightness": 1, "contrast": 1, "saturation": 1, "tint": [1, 1, 1] },
"vignette": { "enabled": false, "intensity": 0.5, "inner": 0.3, "outer": 0.75, "curvature": 1 },
"fringing": { "enabled": false, "intensity": 0.5 }
},
"animTracks": [],
"cameras": [
{ "initial": { "position": [0, 2, 0], "target": [2, 2, 0], "fov": 85 } }
],
"annotations": [],
"startMode": "default"
}

That camera looks across a captured space from inside it; defaultSettings('object') frames a subject from outside instead. For every field, the authoring limits, and the helpers for generating, validating and migrating settings, see the Experience Settings reference.

Programmatic publishing​

To publish splats to superspl.at from your own pipeline instead of the Editor, use the SuperSplat API. A scene published this way starts with the default settings, and its viewing experience is curated in Studio.

See also​