Wonderland Engine Integration

The Wonderland Engine integration is straightforward using NPM. It supports automatic gaze tracking and scene export.

Installation

Open a terminal inside your Wonderland Engine project's root folder and run:

npm install @cognitive3d/analytics

Create an Analytics Component

Create a new JavaScript file in your Wonderland project (e.g., js/c3d-analytics-component.js) and use the following code. This component handles the entire lifecycle of the SDK.

import { Component, Type } from "@wonderlandengine/api";
import C3D from "@cognitive3d/analytics";
import C3DWonderlandAdapter from "@cognitive3d/analytics/adapters/wonderland";

let c3d;

export class C3DAnalyticsComponent extends Component {
    static TypeName = "c3d-analytics-component";
    static Properties = {
        apiKey: { type: Type.String, default: "YOUR_APPLICATION_API_KEY" },
        sceneName: { type: Type.String, default: "Your_Scene_Name" },
        sceneId: { type: Type.String, default: "YOUR_SCENE_ID" },
        versionNumber: { type: Type.String, default: "1" },
        exportScale: { type: Type.String, default: "1.0" },
        exportRootObject: { type: Type.Object },

        // In-editor Boolean toggle to enable the scene export feature
        enableSceneExport: { type: Type.Bool, default: true },
    };

    adapter = null;

    start() {
        if (c3d) return;

        // Initialize SDK
        c3d = new C3D({
            config: {
                APIKey: this.apiKey,
                allSceneData: [{
                    sceneName: this.sceneName,
                    sceneId: this.sceneId,
                    versionNumber: this.versionNumber
                }]
            }
        });

        this.adapter = new C3DWonderlandAdapter(c3d, this.engine);

        c3d.setScene(this.sceneName);
        c3d.setDeviceProperty("AppName", "Wonderland_WebXR_SDK_Test_App");
        c3d.setUserProperty("c3d.app.version", "1.0");

        this.engine.onXRSessionStart.add(this.onXRSessionStart.bind(this));
        this.engine.onXRSessionEnd.add(this.onXRSessionEnd.bind(this));

        this._setupSceneExportInput();
    }

    // LOGIC IS TIED TO c3d-sdk-webxr scene export (Press O on keyboard at Runtime to initiate scene export)
    _setupSceneExportInput() {
        if (!this.adapter) return;

        window.addEventListener("keyup", async (event) => {
            // Check if the key is 'O' AND the toggle is enabled
            if (event.key.toUpperCase() === "O" && this.enableSceneExport) {
                console.log('Key "O" detected. Initiating static scene export...');

                // Parse the string to a float
                const numericScale = parseFloat(this.exportScale) || 1.0;

                await this.adapter.exportScene(
                    this.sceneName,
                    numericScale,
                    this.exportRootObject
                );
            } else if (event.key.toUpperCase() === "O" && !this.enableSceneExport) {
                console.log('Key "O" pressed, but Scene Export is currently disabled in the component properties.');
            }
        });

        console.log('Cognitive3D: Scene Export listener active.');
    }

    async onXRSessionStart(session) {
        console.log('Cognitive3D: VR Session Started');
        const success = await c3d.startSession(session);
        if (success) console.log('Cognitive3D SDK session successfully started.');
    }

    onXRSessionEnd() {
        console.log('Cognitive3D: VR Session Ended');
        if (c3d) c3d.endSession().then(status => console.log('Cognitive3D SDK session ended with status:', status));
    }
}

Register the Component

Make sure your new C3DAnalyticsComponent is registered with the engine in your main js/index.js file.

Import the component (add this line within the wle:auto-imports block):

import {C3DAnalyticsComponent} from './c3d-analytics-component.js';

Register the component with the engine (add this line within the wle:auto-register block). This is the crucial step that makes the component appear in the editor's UI, allowing you to add it to objects in your scene:

engine.registerComponent(C3DAnalyticsComponent);

Usage

The c3d-analytics-component will be fully integrated and ready to use in your Wonderland project.

1. Within the Wonderland Engine, select an object or create a new object in the hierarchy.
2. Add the component c3d-analytics-component to the object and enter your Cognitive3D project information: API Key, sceneName, sceneID and versionNumber.

The following screenshot is of a Wonderland Engine project illustrating the total integration of Cognitive3D WebXR SDK:

Scene Export

The Wonderland Engine adapter supports scene export with the following configuration properties:

• Enable Scene Export (Toggle): Must be checked (true) to allow the O key to trigger the export.
• Export Scale (Text Input): Defines the global scale for the exported geometry. (Default: 1.00)
• Export Root Object (Drag & Drop): (Optional) Drag a scene object into this field to limit the export to that object and its children. If left empty, the entire scene is exported.

To export: run the project in the browser and press the O key. Your browser will prompt you to select a save folder.

For full details on the export process and file format, see the Scenes page.

Limitations

The following features are not currently supported with the Wonderland Engine adapter:

• Automatic Performance Sensors (Profiler)
• Dynamic Objects
• Scene export does not include material definitions or textures (geometry only)

Note: The WebXR SDK is currently in development and we are working on new features. Support for the above may come later.

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.