Skip to main content

Embedding the Viewer

The SuperSplat Viewer is published on npm as @playcanvas/supersplat-viewer. It's a self-contained static web app you can drop into your own site, point at any splat file, and configure via URL parameters or a JSON settings document.

Installing​

npm install @playcanvas/supersplat-viewer

The package exports the viewer's index.html, index.css, and index.js as strings, ready to template into your build pipeline:

import { html, css, js } from '@playcanvas/supersplat-viewer';

// The full markup of the viewer page
console.log(html);

// The viewer's stylesheet
console.log(css);

// The viewer's compiled JS bundle
console.log(js);

This is the same machinery the Editor's HTML export uses internally to produce a single-file viewer. Use it when you want to build your own templated bundle — e.g. injecting a particular settings.json, swapping in a custom skybox, or replacing the default poster image — without paying the runtime cost of loading the viewer from a CDN.

URL parameters​

If you'd rather host the viewer's built files yourself and configure each instance through query parameters, the following are supported:

ParameterDescriptionDefault
settingsURL of the Experience Settings JSON file./settings.json
contentURL of the scene file (.ply, .sog, .meta.json, .lod-meta.json, .compressed.ply)./scene.compressed.ply
skyboxURL of an equirectangular skybox image(none)
posterURL of an image to show while the scene loads(none)
nouiHide the viewer's built-in UI(off)
noanimStart with any animation track paused(off)
ministatsShow runtime CPU/GPU performance graphs(off)
unifiedForce unified rendering(off)
aaEnable antialiasing (not supported in unified mode)(off)

These flags are subject to change as the viewer evolves; check the project README for the current set.

Settings JSON​

The settings URL parameter points at an Experience Settings v2 document — the same JSON format Studio saves whenever you hit Save. See the Experience Settings reference for the full schema, defaults, and migration notes.

A complete minimal settings.json (every field the v2 schema requires, populated with the defaults the Studio emits for a fresh scene):

{
  "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 }
  },
  "cameras": [
    { "initial": { "position": [0, 1, -1], "target": [0, 0, 0], "fov": 75 } }
  ],
  "animTracks": [],
  "annotations": [],
  "startMode": "default"
}

For full coverage of every field — post effects parameters, annotations, animation keyframes, tonemapping options, etc. — see the Experience Settings reference.

Programmatic publishing​

If you want to publish splats and update their settings without going through the Editor or Studio UIs, the Splat Publishing API exposes the underlying REST endpoints.

See also​