体验设置

Experience Settings 定义观看体验，包括色调映射、后期效果、背景、相机、动画、标注和起始模式，是两个产品的共同约定：

• 写入方：Studio 每次 Save 保存。
• 读取方：Viewer 在场景页、嵌入和自托管运行时加载。

通常通过 Studio 制作，不手改 JSON。若自有应用嵌入、构建生成或直接消费设置，应遵循以下结构。

当前结构 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
    };

    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<{
        initial: {
            position: [number, number, number];
            target:   [number, number, number];
            fov:      number; // degrees
        };
    }>;

    animTracks: Array<{
        name: string;
        duration: number;       // seconds
        frameRate: number;
        loopMode: 'none' | 'repeat' | 'pingpong';
        interpolation: 'step' | 'spline';
        smoothness: number;     // 0-1
        keyframes: {
            times: number[];
            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;                          // sanitized HTML
        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' — start positioned at the first annotation's camera pose
    startMode: 'default' | 'animTrack' | 'annotation';

    hasStartPose?: boolean;
};

多数由 Studio 面板制作，animTracks 来自编辑器时间轴，发布时烘焙。详情见链接。

字段	制作位置
tonemapping, highPrecisionRendering	后期效果
background.color, background.skyboxUrl	天空盒与背景
postEffectSettings	后期效果
cameras	相机
animTracks	时间轴，发布烘焙
annotations	标注
startMode, hasStartPose	发布时初始值，可经 Studio 顶部或启动配置调整
碰撞体素	独立场景资源，不在此 JSON

默认值

新发布默认：

• 色调映射 linear，高精度关闭。
• 背景黑色 [0, 0, 0]，无天空盒。
• 后期效果全部关闭。
• 单相机 FOV 75：环境位置 [0, 2, 0]、目标 [2, 2, 0]；对象位置 [2, 2, -2]、目标 [0, 0, 0]。
• 无动画、无标注。
• 起始模式 default。

首次打开 Studio 显示默认，可按需调整。

版本

Studio 和 Viewer 自动迁移 v1 到 v2，无需操作。自行生成时写 v2。

另请参见

• 嵌入：设置 settings.json URL。
• 自托管：打包设置副本。
• 发布 API：编程发布与更新。