Skip to content

Scenes

A scene in Cognitive3D is the 3D environment your session data is drawn against. Session Replay, heatmaps, gaze paths, and event positions are all rendered on top of the scene geometry you upload, so every session you want to visualize must reference a scene the dashboard already knows about.

This page covers the scene lifecycle from the SDK's perspective — what the dashboard expects, how to tell the SDK which scene is active, and how to handle transitions between scenes during a session. The per-engine export commands live on the corresponding framework pages.

Scene Files

A scene upload is always the same four files, regardless of which engine produced them:

  • scene.gltf — JSON manifest describing nodes, materials, and references to the binary data.
  • scene.bin — raw vertex / normal / UV / index data referenced by the manifest.
  • settings.json — contains at minimum the sceneName, scale, and SDK version. The Upload Web App uses it to seed the scene record.
  • screenshot.png — a thumbnail image used by the dashboard. For best results, capture it from roughly the spawn point or a representative camera angle.

The SDK's engine adapters generate these for you. Not every adapter covers every field — the Wonderland exporter outputs geometry only (no materials/textures), and the PlayCanvas adapter has no built-in exporter at all. See each framework page for specifics.

Producing Scene Files

Where the files come from depends on the engine:

  • Three.js — c3dAdapter.exportScene(scene, sceneName, renderer, camera). Automatically excludes anything tagged as a dynamic object so the upload contains only static geometry. See Three.js Integration.
  • Wonderland Engine — c3dAdapter.exportScene(sceneName, scale, rootObject), triggered in the sample setup by pressing O. See Wonderland Integration.
  • Mattercraft — exported via the Mattercraft Editor / @cognitive3d/three-mattercraft helper. See Mattercraft Integration.
  • PlayCanvas, Plain JS — Currently not supported

Uploading the Scene

Once the four files are sitting in a single .zip folder, upload them through the Cognitive3D Upload Web App. The upload uses your Developer Key (distinct from the Application Key the SDK uses at runtime).

After a successful upload, the Web App returns a Scene ID and version:

✅ Scene uploaded successfully!
   Scene ID:      a1b2c3d4-e5f6-g7h8i9j0
   Version:       1
   Scene Name:    MyMainLevel

Update your SDK config so the runtime data you send is attributed to this scene:

// settings.js
export default {
  config: {
    APIKey: "YOUR_APPLICATION_API_KEY",
    allSceneData: [
      {
        sceneName: "MyMainLevel",
        sceneId: "a1b2c3d4-e5f6-g7h8i9j0",
        versionNumber: "1",
      },
    ],
  },
};

Warning

Data sent from the SDK is only attached to uploaded geometry when sceneName matches a scene that has been uploaded and has a real sceneId. If sceneId is blank, the session still records — it just won't have a 3D context on the dashboard.

Activating the Scene at Runtime

Tell the SDK which scene in allSceneData is currently active by name:

c3d.setScene("MyMainLevel");

This is typically done once during initialization, before c3d.startSession(...). The SDK looks up the matching entry in allSceneData and uses its sceneId and versionNumber for all data batches until setScene is called again.

Changing Scenes Mid-Session

When a participant moves between scenes inside a single continuous session — for example, leaving a main menu and loading the tutorial level — call c3d.setScene(...) with the new scene name at the transition.

function loadLevel(levelName) {
    // 1. Flush the previous scene's data and switch the active scene
    c3d.setScene(levelName);

    // 2. Your engine-specific level-loading logic
    //    (unload old assets, load new ones, etc.)
}

loadLevel("Level_01_Tutorial");

Calling setScene during an active session triggers two things under the hood:

  1. Batched data is flushed — all queued gaze, custom event, and sensor records for the previous scene are sent immediately, so they're attributed to the scene they came from.
  2. Dynamic object manifest is refreshed — if you're tracking dynamic objects, the SDK re-sends their registration information so the new scene has a valid object manifest for visualization in Session Replay.

You can list as many scenes as you need in allSceneData:

// settings.js
export default {
  config: {
    APIKey: "YOUR_APPLICATION_API_KEY",
    allSceneData: [
      { sceneName: "MainMenu",          sceneId: "a1b2c3d4-e5f6-g7h8-i9j0", versionNumber: "1" },
      { sceneName: "Level_01_Tutorial", sceneId: "k1l2m3n4-o5p6-q7r8-s9t0", versionNumber: "1" },
      { sceneName: "Level_02_Outdoor",  sceneId: "u1v2w3x4-y5z6-a7b8-c9d0", versionNumber: "1" },
    ],
  },
};

Iterating on a Scene

When the scene changes in your application — a new room layout, rearranged props, a new object that needs to show up with heatmaps — re-export and re-upload through the Upload Web App. The Web App returns an incremented versionNumber; the sceneId stays the same. Update your allSceneData entry to match.

intercom If you have a question or any feedback about our documentation please use the Intercom button (purple circle) in the lower right corner of any web page or join our Discord.