Skip to main content

Experience Settings

Experience Settings is the JSON document that defines a published splat's viewing experience — tonemapping, post effects, background, cameras, animations, annotations, and the scene's start mode. It's the single contract between two products:

You don't normally edit this JSON by hand — Studio is the supported authoring surface. But if you're embedding the Viewer in your own application, generating settings from a build pipeline, or consuming the published settings directly, the schema below is what to write against.

Current schema (v2)​

type ExperienceSettings = {
version: 2;

tonemapping: 'none' | 'linear' | 'filmic' | 'hejl' | 'aces' | 'aces2' | 'neutral';
highPrecisionRendering: boolean;
soundUrl?: string;

background: {
color: [number, number, number]; // RGB, 0-1
skyboxUrl?: string; // optional .webp/.jpg/.png URL (see below)
};

postEffectSettings: {
sharpness: { enabled: boolean; amount: number };
bloom: { enabled: boolean; intensity: number; blurLevel: number };
grading: { enabled: boolean; brightness: number; contrast: number; saturation: number; tint: [number, number, number] };
vignette: { enabled: boolean; intensity: number; inner: number; outer: number; curvature: number };
fringing: { enabled: boolean; intensity: number };
};

cameras: Array<{ // the viewer uses the first camera
initial: {
position: [number, number, number];
target: [number, number, number];
fov: number; // degrees
};
}>;

animTracks: Array<{ // the viewer plays the first track
name: string;
duration: number; // seconds
frameRate: number;
loopMode: 'none' | 'repeat' | 'pingpong';
interpolation: 'step' | 'spline';
smoothness: number; // 0-1
keyframes: {
times: number[]; // in frames, ascending
values: {
position: number[]; // flat array of [x, y, z] per keyframe
target: number[]; // flat array of [x, y, z] per keyframe
fov: number[]; // one FOV per keyframe
};
};
}>;

annotations: Array<{
position: [number, number, number];
title: string;
text: string; // shown as plain text
camera: { initial: { position: [number, number, number]; target: [number, number, number]; fov: number } };
extras?: Record<string, unknown>;
}>;

// 'default' — start at the first camera in `cameras`
// 'animTrack' — start by playing the first track in `animTracks`
// 'annotation' — accepted, but the viewer currently starts as for 'default'
startMode: 'default' | 'animTrack' | 'annotation';

hasStartPose?: boolean;
};

Most fields are authored in a Studio control. The camera animation can also come from the SuperSplat Editor's Timeline, baked in at publish time. Follow the cross-references for details.

FieldAuthored in
tonemapping, highPrecisionRenderingLook & Tone
background.color, background.skyboxUrlLook & Tone
postEffectSettingsPost Effects
camerasCameras
animTracksCamera Animation, or the Editor Timeline (baked in when publishing). Studio saves only a track that has keyframes.
annotationsAnnotations
startModePlay animation on open in the Animation section: animTrack when it is on, default when it is off. The initial value is set when publishing from the Editor.
hasStartPoseSet when publishing from the Editor
Collision voxel dataStored separately as a Scene Asset, not in this JSON

How the viewer reads it​

A few fields behave in ways the schema alone doesn't show:

  • background.skyboxUrl — the open-source viewer doesn't load the skybox from the settings. On superspl.at, scene pages and embeds still show the skybox you upload in Studio, because superspl.at passes it to the viewer itself. When you host the viewer yourself, pass the image with the skybox URL parameter or the skyboxUrl option.
  • soundUrl — the sound starts on the visitor's first click in the viewer, since browsers block audio that plays on its own.
  • cameras and animTracks — the format allows several, but the viewer uses only the first camera and plays only the first track.
  • annotations[].text — shown as plain text, so HTML markup isn't rendered.
  • startMode: 'annotation' — accepted, but the viewer starts as it does for default.
  • antiAlias — not part of the schema above, but Studio adds it: its Anti-aliasing switch stores antiAlias: false when turned off. Scene pages and embeds on superspl.at apply it, with compensation on unless it's false. The open-source viewer doesn't read it from the settings file: there, the aa URL parameter sets it, and without that each splat file's own anti-aliasing tag decides.

Authoring limits​

The viewer renders whatever the schema allows, but tools that write settings should keep to these bounds, which validateSettings(settings, { limits: true }) checks:

FieldLimit
Camera and annotation fov10 to 120 degrees
annotationsAt most 50, each with a title of up to 60 characters and text of up to 280
animTracksAt most 10, each with a name of up to 120 characters, a duration of 0.1 to 600 seconds, a whole frameRate of 1 to 120, a smoothness of 0 to 1, and 1 to 1,000 keyframes at whole, ascending frame numbers
sharpness.amount0 to 1
bloom.intensity / bloom.blurLevel0 to 0.1 / 1 to 16
grading.brightness / contrast / saturation0 to 3 / 0.5 to 1.5 / 0 to 2
vignette.intensity / inner / outer / curvature0 to 1 / 0 to 3 / 0 to 3 / 0.01 to 10
fringing.intensity0 to 100

Some settings already published fall outside these bounds, such as a bloom.intensity of 1 from older defaults, so the viewer doesn't enforce these limits when it loads a file.

Generating and validating settings​

The viewer's npm package exports the schema types and helpers from its /settings entry, so a pipeline can write settings the viewer accepts:

import {
defaultSettings,
importSettings,
validateSettings,
POST_EFFECT_RANGES,
type ExperienceSettings
} from '@playcanvas/supersplat-viewer/settings';

// a complete settings object; pass 'object' to frame a subject from outside
const settings: ExperienceSettings = defaultSettings();

// throws on invalid input, naming the offending field
validateSettings(json);

// also check the authoring limits
validateSettings(json, { limits: true });

// migrates v1 settings to v2, without changing its argument
const migrated = importSettings(json);

// the bounds are data, so an editor UI can drive its sliders from them
const { min, max, step } = POST_EFFECT_RANGES.bloom.intensity;

CAMERA_FOV_RANGE, POST_EFFECT_RANGES, ANIM_TRACK_LIMITS and ANNOTATION_LIMITS export the limits above as data. defaultSettings() gives the camera an 85 degree field of view, at position [0, 2, 0] looking at [2, 2, 0], or with 'object', at [2, 2, -2] looking at [0, 0, 0].

Defaults​

A freshly-published splat is given a sensible default JSON:

  • Tonemapping linear, high precision off
  • Background [0, 0, 0] (black), no skybox
  • Post effects all disabled
  • One camera with FOV 75 — for environment-style scenes the default pose is position [0, 2, 0], target [2, 2, 0]; for object-style scenes it's position [2, 2, -2], target [0, 0, 0]
  • No animation tracks and no annotations
  • Start mode default

Studio surfaces these defaults the first time you open a scene; tweak as needed.

Schema versioning​

Older v1 settings are migrated to v2 automatically when loaded by Studio or the Viewer — you don't need to do anything special. If you're generating settings yourself, write v2 and you're current.

See also​