Scene file (JSON)

A scene file holds one scene and all of its markers in a single JSON document. Use it to back up a scene, compare two versions, move content between scenes, or let an AI assistant edit a scene and hand it back.

The file is validated against a published JSON Schema: https://voluma.ai/schemas/voluma-scene-v1.schema.json. Editors such as VS Code use it for completion and error checking while you edit.

Export

1. Open the scene in Studio and switch to Advanced in the menu bar.
2. Click Save as at the bottom of the scene browser, then open the Export tab.
3. Click Download. The file is named after the scene, for example lobby.voluma-scene.json.

The export includes unsaved changes, so it matches what you see in Studio.

Import

1. Open the scene you want to change in Studio, in Advanced mode.
2. Click Revert at the bottom of the scene browser, then open the Import tab.
3. Click Choose file and select a .voluma-scene.json file.
4. Check the summary: how many markers are updated, added and removed, and whether the main splat changes.
5. Click Import. The result opens as unsaved changes. Click Save to keep it, or Revert to undo it.

Import replaces the scene's content with the file:

• Scene settings, title and main splat come from the file. The scene's address, project and owner stay the same.
• Markers of this scene that are in the file are updated.
• Markers that are new, or come from another scene, are added with new ids. References to them move along.
• Saved markers missing from the file are deleted when you save.
• Visitor markers are never deleted by an import.

File structure

{
  "$schema": "https://voluma.ai/schemas/voluma-scene-v1.schema.json",
  "format": "voluma.scene",
  "version": 1,
  "exportedAt": "2026-10-16T12:00:00.000Z",
  "generator": { "name": "voluma-web-app", "version": "1.32.0" },
  "scene": {
    "title": "Lobby",
    "mainSplat": { "url": "https://assets.example.com/lobby.sog" },
    "properties": {
      "controls": { "autoRotate": true, "autoRotateSpeed": 0.5 },
      "skyDome": { "image": "https://assets.example.com/sky.jpg" }
    }
  },
  "markers": [
    {
      "id": 101,
      "parentId": null,
      "order": 0,
      "title": "Reception",
      "private": false,
      "shape": {
        "geometry": "sphere",
        "position": { "x": 0, "y": 1.2, "z": -2 },
        "rotation": { "x": 0, "y": 0, "z": 0 },
        "scale": { "x": 0.3, "y": 0.3, "z": 0.3 },
        "color": "#ffffff"
      },
      "properties": {
        "schemaVersion": 2,
        "triggers": [
          {
            "on": "click",
            "sources": { "scene": true, "menu": true },
            "responses": [{ "type": "action", "action": { "type": "overlay", "html": "<h2>Reception</h2><p>Open 9:00 to 17:00.</p>" } }]
          }
        ]
      }
    }
  ]
}

Field	Contents
scene.properties	Scene-wide settings: camera and controls, first person (fpv), XR, environment (bgColor, skyDome, fog, lights, groundPlane), marker styling and layout, mini-map.
markers[].shape	Marker type (geometry) and placement. Positions are in metres, y points up, rotations are in radians.
markers[].properties.triggers	When the marker reacts (hover, click, approach, leave, focus, unfocus) and what it does, in order.
markers[].properties.sound	The marker's own sound. Triggers decide when it plays.

The schema describes every field with its meaning and unit.

Editing rules

Follow these rules when you edit a scene file by hand or with an AI assistant:

• Keep format and version. Import refuses other formats and versions.
• Keep the id of a marker you change. That makes import update it instead of adding a copy.
• Give a new marker an id that no other marker in the file uses, for example a large number. Import replaces it with a real id.
• Refer to markers by id. parentId, an action's marker_id and mediaTargetId must point to a marker in the file.
• Remove a marker from the file to delete it. It disappears when you save after importing.
• Leave fields you do not understand as they are. Import keeps them.
• Use numbers for numeric settings. Some older scenes store numbers as text. Import accepts both, but Studio writes numbers.

Assets such as the main splat, images, video and audio are referenced by URL. A scene file does not contain the files themselves.