Skip to content

Sensors

Tracking Custom and Performance Sensors

The Cognitive3D SDK allows you to record continuous streams of numerical data throughout a user's session. This is a powerful feature for correlating in-experience events with user biometrics, application performance, or any custom state you want to track over time.

All recorded sensor data is displayed as interactive graphs on the session timeline in SceneExplorer, providing a detailed, moment-by-moment snapshot of the user's state and the application's health.

Built-in Performance Sensors (Profiler)

The SDK includes a built-in profiler that can automatically track key performance metrics from your application. This is the easiest way to get immediate, valuable insight into your application's performance without any extra code.

Enabling the Profiler

To enable automatic performance tracking, simply pass your graphics engine's primary renderer or application object as the second argument when initializing the SDK.

For Three.js

Pass the THREE.WebGLRenderer instance.

import C3D from '@cognitive3d/analytics';
import settings from './settings';

// Pass the renderer to the C3D constructor
const c3d = new C3D(settings, myThreeJsRenderer);

For PlayCanvas

Pass the pc.Application instance (this.app).

import C3D from '@cognitive3d/analytics';
import settings from './settings';

// In your PlayCanvas script, 'this.app' is the application instance
const c3d = new C3D(settings, this.app);

Standard Sensors

Once enabled, the following performance sensors will be recorded automatically every second and will be viewable in SceneExplorer:

Profiler Sensors (Profiler.js)

  • Draw Calls Count: This sensor counts the number of rendering commands sent to the GPU for each frame, helping to measure rendering complexity.

  • System Memory In MB: This sensor measures your application's total memory usage in megabytes to monitor for potential memory leaks.

  • Main Thread Time In Ms: This sensor records the time in milliseconds it took to process and render the last frame, indicating overall performance.

Framerate Sensors (FPSTracker.js)

  • Average FPS: This sensor tracks the average number of frames rendered per second over a one-second interval, showing the application's general smoothness.

  • 1% Low FPS: This sensor measures the framerate during the most demanding moments to help identify instances of stuttering or performance drops.

Controller Sensors (ControllerTracker.js)

  • Controller height from HMD: This sensor tracks the vertical distance of the left or right controller relative to the headset, which is useful for analyzing hand position and gestures.

Adding Your Own Custom Sensors

Beyond the standard sensors, you can define and record any arbitrary numerical data you wish. This allows you to track application-specific states or data from external hardware, like biometric sensors.

How to Add a Custom Sensor

Adding and recording a custom sensor is a single function call. You provide a custom name (string) for the sensor and the numerical value you want to record.

// The sensor name can be any string you choose.
// The value must be a number.

c3d.sensor.recordSensor('heartRate', 85);
c3d.sensor.recordSensor('playerStamina', 92.5);

How to Record Data at a Fixed Interval

For many types of data, such as biometrics or periodic state checks, you may want to record a value at a consistent interval rather than on every frame. You can easily achieve this by using setInterval.

The following example shows how to record the user's current heart rate and the number of active enemies once every second.

// Example of recording sensor data every 1000 milliseconds (1 second)
setInterval(() => {
    // This code will execute every second

    // Get the current heart rate from your biometric device
    const currentHeartRate = getHeartRateFromDevice();
    c3d.sensor.recordSensor('heartRate', currentHeartRate);

    // Get the current enemy count from your game logic
    const activeEnemies = enemyManager.getActiveCount();
    c3d.sensor.recordSensor('activeEnemies', activeEnemies);

}, 1000);

Configuration and Batching

To optimize network performance, sensor data is collected locally and sent to the server in batches. You can control the size of these batches.

You can configure the batch size in your initial settings file or change it at runtime.

// settings.js
export default {
  config: {
    // ... other settings
    // Number of Sensor snapshots to store before sending
    sensorDataLimit: 64,
  },
};

At Runtime

// Change the batch size to 32 during the session
c3d.config('sensorDataLimit', 32);

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.