Skip to main content

Scene Description File (JSON)

A world's scene description file is one JSON object with two parts:

  • entities: the objects placed in the world (models, media, scripts, ...). The world stores them in its glbmodelsattr attribute.
  • settings: the world-wide settings described below. The world stores them in its roomsattr attribute.

The scene editor in VR and the export also add "version": 1. When you save the file, entities and settings replace the world's stored values.

Global Settings​

The settings object holds the global settings that affect how the world behaves and looks. Fields you leave out use the defaults listed here.

General​

  • title (String): Display title of the world.
  • description (String): Human-readable description of the world.
  • passwordProtected (Boolean): When true, visitors must enter the world's password. Default false.
  • maxUsers (Number): Maximum number of concurrent visitors. Default 25.
  • instanceSize (Number): Runs the world as automatic copies of this many visitors each (for example 6 for a six-seat table). Each copy has its own voice, chat, player list and game, and keeps one extra place for the owner or an admin. ?session=<id> links join a given copy. 0 (default) is one shared world.
  • firstPersonOnly (Boolean): When true, visitors stay in first-person view and cannot switch to third person. Default false.
  • sessionOnlyChat (Boolean): When true, chat messages are not saved: visitors only see what is sent while they are in the world. Only the world owner or an admin can change it. Default false.
  • useWelcome (Object): { "use": false } skips the welcome screen. Default { "use": true }.
  • useMultiUser (Object): { "use": false } gives every visitor a private copy of the world. Default { "use": true }.

Voice and media​

  • micShare (Boolean): Shares visitors' microphone audio with others. Default true.
  • joinMuted (Boolean): Visitors enter with their microphone muted and can unmute from the HUD. Default false.
  • webcamShare (Boolean): Shows the webcam share button in the HUD. Default true.
  • screenShare (Boolean): Shows the screen share button in the HUD. Default false.

Spawning​

  • spawnPoint (Object): Default spawn position { "x", "y", "z" } in metres. Default { "x": 0, "y": 0, "z": 0 }.
  • spawnRotation (Object): Default spawn rotation { "x", "y", "z" } in degrees. Default all 0.
  • randomRadius (Number): Radius in metres around spawnPoint in which visitors spawn at random. Default 0.
  • autoSpawn (Boolean): When true, visitors who fall below autoSpawnPoint.y are respawned. Default false.
  • autoSpawnPoint (Object): { "x", "y", "z" }. Only y is used: the height below which visitors respawn.

Rendering and lighting​

  • toneMapping (String): Renderer tone mapping. One of "Custom" (default), "No", "Linear", "Reinhard", "Cineon", "ACESFilmic", "AgX", "Neutral".
    • "Custom" applies exposure only, with no highlight compression: bright skin blows out and blacks turn grey.
    • "Neutral" (Khronos PBR Neutral) keeps colors true and handles highlights. Use it for worlds with avatars, skin or dark fabrics.
    • "ACESFilmic" and "AgX" desaturate skin.
  • lightIntensity (Number): Renderer exposure (toneMappingExposure). Default 1.
  • lighting (Object): Sun, ambient and hemisphere light. Fields you leave out use these defaults:
    • shadows (Boolean): Real-time sun shadows. Default false.
    • sunIntensity (Number): Default 2.6.
    • sunColor (String): Hex color. Default "#fff4d8".
    • sunPosition (Object): Sun position { "x", "y", "z" } relative to the point it lights. Only the direction changes the lighting; the length also sets the shadow camera distance. Default { "x": -120, "y": 465, "z": 100 }.
    • ambientIntensity (Number): Flat ambient fill. Default 0.15.
    • ambientColor (String): Default "#fff8f0".
    • hemisphereIntensity (Number): Sky and ground bounce light. Default 0.95.
    • hemisphereSkyColor (String): Default "#b5e0ff".
    • hemisphereGroundColor (String): Default "#e2cca4".
    • shadowMapSize (Number): Shadow map resolution. Default 2048.
    • shadowArea (Number): Half-size in metres of the shadowed area around the player. Default 100.

Sky​

  • useSky (Object): The sky dome.
    • use (Boolean): Show the sky. Default true.
    • mode (String): "color" for a two-color gradient, "material" for a panorama texture. Used by the Studio settings panel.
    • colorTop (String): Zenith color. Default "#53b9fb".
    • colorBottom (String): Horizon color. Default "#bfe9f7".
    • textureSrc (String): Panorama URL (.ktx2, .webp, .jpg or .avif). A name without https:// loads from the bundled /assets/sky/ folder.
    • prefixId (String): The library material (material_...) the panorama comes from.
    • useEnvironment (Boolean): Show the environment map (useEnvironment.textureSrc) as the sky instead. New worlds save false.
    • toneMapped (Boolean): Apply tone mapping to the sky. Default true.
    • useGrounded (Boolean): Ground-projected sky dome. Default false.
    • radius (Number): Grounded dome radius. Default 500.
    • height (Number): Grounded dome height. Default 15.
    • resolution (Number): Dome segments. Default 32.

Ground​

  • useGround (Object): The ground plane.
    • use (Boolean): Show the ground. Default true.
    • teleport (Boolean): Allow teleporting onto the ground. Default true.
    • runtimeNavmesh (Boolean): Build the navigation mesh in the browser from the live scene. Default true. Set false to use each entity's baked navigation mesh.
    • mode (String): "grid" (procedural grid, default), "color" (flat material.color) or "material" (PBR material).
    • chunkColor (String): Grid fill color.
    • voxelsColor (String): Grid line color.
    • groundColor (String): Base color of the ground surface. Empty uses material.color in "color" mode, else the fog color.
    • useFog (Boolean): Fade the ground into the horizon. Default true. This is separate from the scene fog.
    • fogDensity (Number): How fast the ground fades: about 63% faded at 1 / fogDensity metres. Default 0.025 (about 40 m). Keep it above about 0.003, or the edge of the ground shows.
    • fogColor (String): Color the ground fades into. Empty means the sky's colorBottom.
    • material (Object): Used when mode is "material":
      • manifest (String): A library material's manifest link (https://<cdn>/m/<material_id>.json). The ground then uses the full material and follows edits made in the library. See PBR Materials.
      • prefixId (String): The library material (material_...).
      • colorMap, normalMap, roughnessMap, metalnessMap (String): Texture URLs, as saved by older worlds.
      • color (String): Tint color. Default "#ffffff".
      • roughness (Number): 0 to 1. Default 1.
      • metalness (Number): 0 to 1. Default 0.
      • bumpScale (Number): Default 1.
      • normalScaleX, normalScaleY (Number): Default 1.
      • repeat (Number): How often the texture tiles across the ground. Default 4.

Environment map​

  • useEnvironment (Object): Image-based lighting. Every PBR material reflects the environment map, and a light probe made from it adds soft fill light. It is not shown as the background unless useSky.useEnvironment is true.
    • use (Boolean): Enable the environment map.
    • textureSrc (String): A bundled map name or an https:// URL to a .hdr, UltraHDR .jpg or .ktx2 panorama. Default "industrial_sunset_puresky_1k.jpg". The .jpg files are UltraHDR (a JPEG with a gain map) and are much smaller than the .hdr files. Bundled maps:
      • Studios and interiors: "studio_small_01_1k.jpg", "neutral.hdr", "hotel_room_1k.jpg", "small_empty_room_4_1k.jpg", "courtyard_1k.jpg", "paul_lobe_haus_1k.jpg"
      • Skies: "industrial_sunset_puresky_1k.jpg", "citrus_orchard_puresky_1k.jpg", "citrus_orchard_road_puresky_1k.jpg", "kloofendal_43d_clear_puresky_1k.jpg", "kloofendal_48d_partly_cloudy_puresky_1k.jpg", "sunflowers_puresky_1k.jpg", "sky.hdr", "sky_1.hdr"
      • Landscapes and city: "dam_wall_1k.jpg", "ninomaru_teien_1k.jpg", "pizzo_pernice_1k.jpg", "spruit_sunrise_1k.jpg", "venice_sunset_1k.jpg", "portland_landing_pad_1k.jpg"
      • Night: "moonless_golf_1k.jpg"
      • Test only: "white_furnace.hdr"
    • environmentIntensity (Number): Strength of reflections and fill light. Default 1. Dark interiors 0.3–0.6, bright interiors 0.6–1, outdoors 0.8–1.2.
    • environmentRotation (Object): Rotation { "x", "y", "z" } in degrees, to place the map's key light where you want it.
Match the environment map to the world

Use an interior or studio map for interiors: a blue sky map indoors gives dark glossy materials a blue cast. For dark interiors such as clubs and lounges, studio_small_01_1k.jpg or neutral.hdr at an intensity of 0.3–0.6 keeps black materials black.

Fog​

  • fog (Object): Scene fog. When fog is present, the world uses the built-in fog: exponential with density 0.0075 and color #DFE9F3 on desktop, linear up to 300 m on mobile.
Fog fields are not applied yet

The fog object also takes enabled, color and density, but the renderer does not read them yet: any fog object turns the built-in fog on, even { "enabled": false }. Leave fog out to keep fog off.

Complete Scene JSON Example​

{
  "version": 1,
  "entities": [],
  "settings": {
    "title": "Main Plaza",
    "description": "Metropolitan gathering space",
    "maxUsers": 50,
    "instanceSize": 0,
    "passwordProtected": false,
    "firstPersonOnly": false,
    "sessionOnlyChat": false,

    "screenShare": true,
    "webcamShare": true,
    "micShare": true,
    "joinMuted": false,

    "spawnPoint": { "x": 0, "y": 1.6, "z": 12 },
    "spawnRotation": { "x": 0, "y": 180, "z": 0 },
    "randomRadius": 2,
    "autoSpawn": true,
    "autoSpawnPoint": { "x": 0, "y": -8, "z": 0 },

    "lightIntensity": 1,
    "toneMapping": "Neutral",
    "lighting": {
      "shadows": true,
      "sunIntensity": 2.5,
      "sunColor": "#fff2d6",
      "sunPosition": { "x": -120, "y": 465, "z": 100 },
      "ambientIntensity": 0.2,
      "ambientColor": "#ffffff",
      "hemisphereIntensity": 0.85,
      "hemisphereSkyColor": "#dcecff",
      "hemisphereGroundColor": "#918b7c"
    },

    "useSky": {
      "use": true,
      "mode": "color",
      "colorTop": "#53b9fb",
      "colorBottom": "#bfe9f7",
      "toneMapped": true,
      "useEnvironment": false
    },

    "useGround": {
      "use": true,
      "teleport": true,
      "mode": "grid",
      "chunkColor": "#ffffff",
      "voxelsColor": "#777777",
      "useFog": true,
      "fogDensity": 0.025
    },

    "useEnvironment": {
      "use": true,
      "textureSrc": "industrial_sunset_puresky_1k.jpg",
      "environmentIntensity": 1,
      "environmentRotation": { "x": 0, "y": 0, "z": 0 }
    }
  }
}