Szenendatei (JSON)

Eine Szenendatei enthält eine Szene und alle ihre Marker in einem JSON-Dokument. Nutzen Sie sie, um eine Szene zu sichern, zwei Versionen zu vergleichen, Inhalte zwischen Szenen zu übertragen oder eine Szene von einem KI-Assistenten bearbeiten zu lassen.

Die Datei wird gegen ein veröffentlichtes JSON Schema geprüft: https://voluma.ai/schemas/voluma-scene-v1.schema.json. Editoren wie VS Code nutzen es beim Bearbeiten für Vervollständigung und Fehlerprüfung.

Exportieren

1. Öffnen Sie die Szene im Studio und wählen Sie in der Menüleiste Erweitert.
2. Klicken Sie unten im Szenenbrowser auf Speichern unter und öffnen Sie den Tab Exportieren.
3. Klicken Sie auf Herunterladen. Die Datei heißt wie die Szene, zum Beispiel lobby.voluma-scene.json.

Der Export enthält auch nicht gespeicherte Änderungen und entspricht damit dem, was Sie im Studio sehen.

Importieren

1. Öffnen Sie im Studio die Szene, die Sie ändern möchten, im Modus Erweitert.
2. Klicken Sie unten im Szenenbrowser auf Zurücksetzen und öffnen Sie den Tab Importieren.
3. Klicken Sie auf Datei auswählen und wählen Sie eine .voluma-scene.json-Datei.
4. Prüfen Sie die Zusammenfassung: wie viele Marker aktualisiert, hinzugefügt und entfernt werden und ob sich der Haupt-Splat ändert.
5. Klicken Sie auf Importieren. Das Ergebnis öffnet sich als nicht gespeicherte Änderungen. Klicken Sie auf Speichern, um es zu behalten, oder auf Zurücksetzen, um es rückgängig zu machen.

Der Import ersetzt den Inhalt der Szene durch die Datei:

• Szeneneinstellungen, Titel und Haupt-Splat kommen aus der Datei. Adresse, Projekt und Eigentümer der Szene bleiben gleich.
• Marker dieser Szene, die in der Datei stehen, werden aktualisiert.
• Neue Marker oder Marker aus einer anderen Szene werden mit neuen IDs hinzugefügt. Verweise auf sie werden mitgeführt.
• Gespeicherte Marker, die in der Datei fehlen, werden beim Speichern gelöscht.
• Besuchermarker werden durch einen Import nie gelöscht.

Aufbau der Datei

{
  "$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>" } }]
          }
        ]
      }
    }
  ]
}

Feld	Inhalt
scene.properties	Szenenweite Einstellungen: Kamera und Steuerung, Ego-Perspektive (fpv), XR, Umgebung (bgColor, skyDome, fog, lights, groundPlane), Markergestaltung und Layout, Minikarte.
markers[].shape	Markertyp (geometry) und Platzierung. Positionen in Metern, y zeigt nach oben, Rotationen in Radiant.
markers[].properties.triggers	Wann der Marker reagiert (hover, click, approach, leave, focus, unfocus) und was er dann tut, in Reihenfolge.
markers[].properties.sound	Der eigene Klang des Markers. Die Trigger bestimmen, wann er spielt.

Das Schema beschreibt jedes Feld mit Bedeutung und Einheit.

Regeln für die Bearbeitung

Halten Sie sich an diese Regeln, wenn Sie eine Szenendatei selbst oder mit einem KI-Assistenten bearbeiten:

• Behalten Sie format und version bei. Andere Formate und Versionen werden abgelehnt.
• Behalten Sie die ID eines Markers, den Sie ändern. Dann aktualisiert der Import ihn, statt eine Kopie hinzuzufügen.
• Geben Sie einem neuen Marker eine ID, die kein anderer Marker in der Datei nutzt, zum Beispiel eine große Zahl. Der Import ersetzt sie durch eine echte ID.
• Verweisen Sie auf Marker über ihre ID. parentId, die marker_id einer Aktion und mediaTargetId müssen auf einen Marker in der Datei zeigen.
• Entfernen Sie einen Marker aus der Datei, um ihn zu löschen. Er verschwindet, wenn Sie nach dem Import speichern.
• Lassen Sie Felder, die Sie nicht kennen, unverändert. Der Import behält sie.
• Verwenden Sie Zahlen für numerische Einstellungen. Manche älteren Szenen speichern Zahlen als Text. Der Import akzeptiert beides, das Studio schreibt Zahlen.

Assets wie Haupt-Splat, Bilder, Video und Audio sind als URL enthalten. Eine Szenendatei enthält die Dateien selbst nicht.