Files
gods-eye-view/docs/SCENE-DOCUMENT.md
T
Sameh KhamisandManjunath Paparaju 71f40c9655 Keep phone and clean-view credits as they were, and lift narrow corners over the World Timeline
The Cesium credit box's width cap and right-to-left placement apply from
1200px as before, and in the Omnibar layout at every width, so the phone
shell, clean view, recording and scene playback keep their own layout.
Narrower than 1120px the coordinates and the Tactical readout sit above
the World Timeline while it shows. The scene format notes that a build
from before `sonar` refuses a project that has it.

Co-authored-by: Manjunath Paparaju <[email protected]>
2026-11-18 19:45:47 -08:00

6.4 KiB
Raw Blame History

Scene document format

Authoring exports a UTF-8 JSON project. Version 7 records Stories metadata. Versions 1 through 6 and unversioned legacy files migrate on import, including version 6 projects written by early Stories builds. Existing shots keep their camera behavior. Unknown versions or unsupported fields are rejected with a field path before the current project, selection or saved bytes change.

{
  "version": 7,
  "scenes": [{
    "id": "my-scene",
    "title": "My scene",
    "shots": [{
      "id": "my-shot",
      "title": "Arrival",
      "durationSec": 4,
      "holdSec": 1,
      "camera": { "lat": 51.5, "lon": -0.12, "alt": 800,
        "heading": 0, "pitch": -35, "roll": 0 },
      "visual": { "style": "normal" },
      "layers": { "traffic": { "enabled": true } }
    }]
  }]
}

Fields and migration

The root requires scenes (an array, which may be empty). Optional root fields are version, createdAt, updatedAt and installedBuiltInSceneIds (string IDs). Each scene requires a shots array; optional fields are id, title, releaseLayerIds, appliedShotPacks and version-4 anchors. A pack marker has id, optional numeric version and shotBindings (original shot title to saved shot ID). These markers retain the editor's existing pack-update and rename behavior. From version 6 (written by early Stories builds), scenes may include stories (true when saved to Stories), storyThumb (a JPEG or PNG data URL of at most 300,000 characters) and storyTags (up to five supported topic keys).

Shots accept id, title, durationSec, holdSec, camera, visual, layers, sourcePackId, sourcePackVersion and version-4 move. Scene IDs are unique within the project; shot IDs are unique within their scene. Existing IDs and pack bindings survive migration. Missing IDs are generated once and persisted by the next save/export. Missing titles and optional camera/visual fields receive the editor's defaults. Empty scenes and intentionally empty projects remain empty.

Camera latitude/longitude and heading/pitch/roll use degrees. Altitude uses meters above the WGS84 ellipsoid. Import preserves finite heights below 100 meters and zero pitch, which previously fell through to defaults. Anchors and explicit moves require the ellipsoid altitude reference; terrain-relative inputs are rejected. See the camera contract for exact semantics. Flight durations retain the editor's minimum of 0.2 seconds and its 4-second fallback for zero; holds may be zero.

Visual fields are style, mapStack, styleParams, bloom, sharpen, hud, and detection, and scope. Bloom has enabled, intensity, version; sharpen has enabled, intensity; HUD has visible, variant and an optional sonar; detection has mode, density, allocation, fadePct and outsideOpacityPct. Scope has enabled, featherPct. HUD sonar: true is Sonar on beside a layout that cannot say it (Minimal); it is written only then, so Tactical with Sonar stays the variant cyber and a shot without Sonar has no sonar. A shot without it opens with Sonar on only when its variant is cyber. A build from before sonar refuses a project that has it, as it refuses any field it does not know; every other project still opens there. The latter settings were written by Update Shot but previously lost during normalization; they now survive import and capture. Version-1/2 bloom without an explicit scale version uses the original inverted scale and migrates once to scale 2. The scene document and bloom scale versions are separate. Legacy numeric strings are accepted for numeric fields.

Layer entries accept a boolean shorthand or { "enabled": true, "params": {} }. Parameters and style parameters retain nested JSON data. They are interpreted by already registered components; importing a file does not fetch its URLs, register modules, evaluate code or apply its layers. Unsupported structural fields are rejected instead of silently dropping potential edits. Map-stack selection retains the existing registered-stack behavior.

Validation limits

gods-eye-view/director exports parseSceneDocument(text), validateSceneDocument(project), stringifySceneDocument(project), SceneDocumentError, SCENE_DOCUMENT_VERSION and SCENE_DOCUMENT_LIMITS. Validation is independent of the renderer, storage and recipes. Parsing checks UTF-8 size before JSON decoding; the file importer also checks file size before reading it. Migration/defaults live separately in src/scenes/project.js.

Limits are 5 MiB, 256 scenes, 10,000 total shots, 10,000 entries per collection, 24 levels of nesting, 200,000 visited values, 65,536 characters per JSON string (300,000 for a Stories thumbnail), 256 characters per field/ID, and 4,096 characters per title. Numeric values must be finite. Camera limits are latitude ±90, longitude ±180, altitude −12,000 to 1 billion meters, heading/roll ±360 and pitch ±90; durations/holds are at most 86,400 seconds. Post-processing values are bounded and normalized to the existing slider ranges. Object prototype keys are refused at every depth.

An invalid import leaves the current project and playback untouched. A valid import cancels and settles pending playback before replacing the project. If multiple files are read concurrently, only the newest request can replace it. Disposal prevents a pending import from publishing.

The browser storage key remains godsEyeView.sceneProject.v2 for compatibility; that key's suffix is not the document version. An unreadable saved project stays in storage. The app supplies temporary defaults and a visible warning, but blocks saving over the original bytes until a valid file is explicitly imported. Export can preserve temporary edits. Storage writes use the same validation before replacing saved bytes; invalid edits and storage write failures surface an unsaved toast.

Only authored project fields belong in this file. Runtime clocks, camera flights, loading progress and run diagnostics remain separate. Camera anchors and authored moves arrived in version 4; data packs follow in version 5. Declarative interactions remain a planned extension. No scene assets, source links, licenses or contributor attribution change with this document boundary.

Version 5 additionally accepts scene dataPacks and shot dataPackIds, as defined in data packs. Version-4 camera documents continue to import without adding any packs.