Scenes

To visualize participant behavior and analytics data within the Cognitive3D dashboard, upload your scene's geometry. This provides the 3D context for heatmaps, gaze paths, and event locations in Session Replay.

Exporting a Three.js Scene

The C3DThreeAdapter provides a helper method, exportScene(), to simplify this process. This guide walks you through exporting your scene from a live Three.js application and uploading it to the Cognitive3D platform. The exportScene() method bundles your THREE.Scene object into the specific file format required by the platform. It generates a .gltf file, a .bin file for geometry, a settings.json configuration file, and a screenshot.png for use as a thumbnail.

Prerequisites

Before calling the export function, you must have the following objects available in your application:

• An initialized C3DThreeAdapter instance.
• The THREE.Scene object you wish to export.
• Your active THREE.WebGLRenderer instance.
• The THREE.Camera currently viewing the scene.

Usage

To trigger the export, call the exportScene() method on your adapter instance. This is typically done via a UI button or key press.

// Ensure you have access to your adapter, scene, renderer, and camera
const c3dthreejsAdapter = new C3DThreeAdapter(c3d);
const myScene = yourThreeJsScene;
const myRenderer = yourThreeJsRenderer;
const myCamera = yourThreeJsCamera;
const sceneNameForExport = "MyMainLevel"; // A descriptive name for your scene

c3dthreejsAdapter.exportScene(myScene, sceneNameForExport, myRenderer, myCamera);

How it works

When you call exportScene(), the following happens:

1. Dynamic Object Exclusion: The adapter first clones the scene and automatically removes all objects tagged for dynamic tracking (those with userData.c3dId). This ensures the exported GLTF contains only the static environment geometry.
2. Three.js's built-in GLTFExporter parses your static scene graph and creates files in memory.
3. File Generation: It generates four files:
   • scene.gltf: A JSON file describing the scene's structure, nodes, and materials.
   • scene.bin: A binary file containing the raw static geometry data (vertices, indices, etc.).
   • settings.json: A configuration file required by our backend, containing the sceneName and scale.
   • screenshot.png: A snapshot of the current view from the provided camera, rendered by the renderer.

The adapter then attempts to save these files. If your browser supports it (like modern Chrome or Edge), a dialog appears asking you to select a directory. The four files are saved into a sub-folder named scene inside your chosen directory, ready for upload.

Exporting a Wonderland Engine Scene

The C3DWonderlandAdapter includes optimized functionality to export your static scene geometry directly from the running application. This process generates the same four required files.

Limitations

The current Wonderland Engine scene export only provides geometry (position, normals, UVs). Material definitions and textures are not included.

Configuration

The export functionality is controlled entirely by properties on the C3DAnalyticsComponent in the Wonderland Editor.

1. Enable Scene Export (Toggle): Must be checked (true) to allow the O key to trigger the export.
2. Export Scale (Text Input): Defines the global scale for the exported geometry. (Default: 1.00)
3. Export Root Object (Drag & Drop): (Optional) Drag a scene object (e.g., a "World" or "Room" parent object) into this field. The exporter limits geometry collection to this object and its entire child hierarchy. If left empty, the entire scene is exported.

Usage

The export is designed to be triggered easily during development.

1. Run the Wonderland Engine project in the browser.
2. Press the O key on the keyboard (while the component toggle is enabled).
3. Your browser prompts you to select a folder where the files will be saved. (Cannot be a system folder.)

How it works

When triggered, the adapter performs the following actions:

1. Geometry Collection & Transformation: The script traverses the scene starting from the specified Export Root Object. It extracts all positions, normals, and UVs, transforming them to a single world coordinate system and applying the required left-handed coordinate system conversion for compatibility with Session Replay.
2. Screenshot Capture: The script hooks into the engine's onPostRender loop to capture a single frame from the WebGL canvas, ensuring the image is saved before the next frame is drawn.
3. File Generation: It generates four files in a new scene sub-folder:
   • scene.gltf: JSON manifest referencing the binary data.
   • scene.bin: Raw vertex, normal, and index data.
   • settings.json: Contains sceneName and exportScale.
   • screenshot.png: The captured thumbnail image.

Uploading the Scene Files (Engine independent)

Once you have the four scene files (scene.gltf, scene.bin, settings.json, and screenshot.png) collected in a single directory, you can upload them using the Upload Web App.

Getting Your Scene ID

After a successful upload, the web app displays a message containing the Scene ID and the new Scene Version.

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

Warning

Copy the Scene ID and Version and update your SDK configuration (usually settings.js) to match. Analytics data sent from your application must reference the correct Scene ID to be associated with the uploaded geometry.

// In your settings.js or equivalent configuration file
allSceneData: [
  {
    sceneName: "MyMainLevel",
    sceneId: "a1b2c3d4-e5f6-g7h8i9j0", // <-- Paste your new Scene ID here
    versionNumber: "1",                // <-- Update the version number
  },
  // ... other scenes
],

Scene Change

In your application, a participant may move between different levels or scenes within a single continuous session. The Cognitive3D SDK handles these transitions seamlessly, ensuring that analytics data is correctly associated with the specific scene in which it occurred.

When a participant transitions to a new scene, inform the SDK of this change by calling c3d.setScene().

Scene Change: How It Works

Calling c3d.setScene() triggers two actions:

1. Sends Batched Data: The SDK immediately sends all batched analytics data (such as gaze, custom events, and sensor data) that has been collected for the previous scene. This ensures that all data is correctly attributed to the scene it came from before the new scene is activated.

2. Refreshes Dynamic Objects: If you are tracking Dynamic Objects, the SDK refreshes the object manifest. This means it re-sends the registration information for all tracked objects to the backend, ensuring they are correctly visualized in the new scene context in Session Replay.

Scene change example

// settings.js
export default {
  config: {
    // ... other settings
    allSceneData: [
      {
        sceneName: "MainMenu",
        sceneId: "a1b2c3d4-e5f6-g7h8-i9j0",
        versionNumber: "1",
      },
      {
        sceneName: "Level_01_Tutorial",
        sceneId: "k1l2m3n4-o5p6-q7r8-s9t0",
        versionNumber: "1",
      },
    ],
  },
};

// In your application's scene loading logic...

function loadNewScene(sceneName) {
    console.log(`Loading scene: ${sceneName}`);

    // --- Cognitive3D Scene Change ---
    // Inform the SDK that the active scene is changing.
    c3d.setScene(sceneName);

    // ... your code to load the new scene's assets and logic ...
}

// Example usage:
// When the participant clicks the "Start Tutorial" button from the main menu:
loadNewScene("Level_01_Tutorial");

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.