Built-In Components

Components represent standalone scripts designed to capture data in various commonly sought-after categories. They're crafted for effortless integration and are minimally reliant on specific project configurations. Most of them are added by default to the Cognitive3D_Manager prefab, additional components may be included based on your selections in the scene setup window.

You can find all of these within the Cognitive 3D SDK/Runtime/Components directory. These components are configured such that only one instance of each can be added to a game object. Unless otherwise stated, components record data at a default of 10Hz.

Default Components

HMD Height

Samples the height of a participant's HMD. Average is assumed to be participant's eye height.

Room Size

Sends custom events and sensor data related to when users exit their specified boundaries, modify those boundaries, or recenter within them.

Boundary

Note

The user boundary feature is supported in the Cognitive3D Unity SDK version 1.6.5 and above, with support limited to Meta and OpenXR platforms.

Records the user's boundary setup, including any updates or changes, and monitors the user's movement within that boundary. When a user moves or re-centers within the boundary, the SDK records relevant data such as the boundary points and interactions with the environment.

Note

Known Issue: On Meta headset devices, when users create a new boundary during a session, there is a operating system bug where the previous boundary data is cached and used, causing an offset between the displayed boundary in Scene Explorer and the actual boundary. We’ve shared this problem with Meta and will provide an update as soon as the issue is resolved.

Arm Length

Collects distances from the HMD to the participant's controller. The maximum is assumed to be roughly the participant's arm length.

Frame Rate

Records a sensor for the average, 1% low, and 5% low for framerate over time.

In cases where you are using Meta's Asynchronous Space Warp (ASW), the Meta SDK will cap the framerate to half of the device's refresh rate and inject a synthetic frame for every frame rendered by the engine. As a result, the framerate perceived by the user will be twice that is reported by the engine. To correct for this, our SDK will double the value written to the framerate sensor. In addition, for all frames ASW is enabled and active, the c3d.app.meta.spaceWarp sensor value will be set to 1.

To identify sessions where ASW was used, you can search for all sessions where the session property c3d.app.meta.wasSpaceWarpUsed == true.

HMD Present Event

Sends Custom Events when a participant removes or wears their HMD.

Battery Level

Send the battery level of an Android device after initialization and on quit. This requires building the project to an Android device. This component records data at 0.1Hz.

Controller Tracking

Note

In Unity SDK version 1.8.0 and above, the controllers are tracked using this component. If you're using version 1.8.0 or later and have selected or plan to use the automatic controller/hand setup in the Scene Setup window, make sure there are no Dynamic Object components attached to the controller game objects.

This component tracks the position and rotation of the controllers, sends custom events when controllers lose tracking and record controller height relative to HMD position. The controller position and rotation are recorded at the default rate of 10Hz, while the controller height relative to the HMD position is recorded at 1Hz.

Hand Tracking

Note

In Unity SDK version 1.8.0 and above, this component is the default on the Cognitive3D_Manager prefab. It supports hand tracking for Meta, PicoXR, HTC Wave, and OpenXR SDKs.

Records Custom Events when the participant switches from using controllers to using hands or vice versa.

Controller Input Tracker

Records a Dynamic Object property when common controller inputs occur. This is visible in Scene Explorer.

Oculus Hardware

Sends sensor data representing the following data points. Please note that this will only report data if you are building for the Oculus platform and have Oculus Integration selected in the project setup window.

• Battery Temperature
• CPU Level
• GPU Level
• Power Saving Mode

HMD Orientation

Sends sensor data representing the pitch and yaw of the HMD.

Profiler Sensor

Sends sensor data representing the following Unity profiler metrics. Please note that this only works on Unity versions >= 2020.2. This component records data at 1Hz.

• Number of draw calls
• System memory usage in MB
• Main thread time in ms

Optional Components

These components can be added by drag-and-drop or by the Add Component option in the inspector window.

HMD Collision Event

Sends Custom Events if the HMD collides with something in the game world. Collision LayerMask can be set on the component.

Controller Collision Event

Sends Custom Events when either controller collides in the game world. Collision LayerMask can be set on the component.

Teleport Event

Sends a Custom Event when a player's HMD root transform changes positions. This is not triggered when the player walks while using roomscale. If the player moves without an immediate teleport, do not use this component!

In the inspector window, drag and drop the GameObject that moves when user teleports.

Multiplayer Components

If you are building a multiplayer app, you can get additional analytics from one of the following components. These components are designed to be dropped into a project that already implements a specific multiplayer framework. See the Multiplayer page for more technical details.

Photon Multiplayer

This supports Photon PUN 2. This component provides:

• Custom Events when players create, join, leave, or are disconnected from rooms.
• Sensor values recording Round-Trip Time (RTT/ping) and Round-Trip Time Variance over time.
• Session Properties using the Photon RoomId to automatically associate multiple player sessions together.

When the checkbox is pressed in the Project Setup Window, it will automatically add a Photon Multiplayer and Photon View component to the Cognitive3D_Manager prefab. The below image shows the expected final setup on the Cognitive3D_Manager.

Note

Please ensure that there is only one Cognitive3D_Manager with a Photon View component across all your multiplayer scenes.

Unity Netcode for Gameobjects Multiplayer

Note

The Unity Netcode feature is supported in the Cognitive3D Unity SDK version 1.6.0 and above.

This component adds support for Unity Netcode and provides:

• Custom events when players connect or disconnect as a host or client, as well as when the server starts or stops.
• Session properties such as local client id, server address, and port.
• A sensor value recording Round-Trip Time (RTT/ping).

When the checkbox is pressed in the Project Setup Window, it will automatically add a Netcode Multiplayer and Network Object component to the Cognitive3D_Manager prefab. The below image shows the expected final setup on the Cognitive3D_Manager.

Normcore Multiplayer

Note

The Normcore Multiplayer feature is supported in the Cognitive3D Unity SDK version 1.6.0 and above.

This component adds support for Normcore and provides:

• Custom events for when players connect to or disconnect from a room, and when the avatars are created or destroyed.
• Session properties such as client id, room name, and matcher URL.
• A sensor value recording Round-Trip Time (RTT/ping).

When the checkbox is selected in the Project Setup Window, it will automatically add a Normcore Multiplayer component to the Cognitive3D_Manager prefab. The image below shows the expected final setup on the Cognitive3D_Manager.

Oculus-specific components

If you have enabled the Oculus Integration / Meta XR sdk from the Project Setup Window, there will be an extra page in the Scene Setup Window. From here you can enable analytics for several additional features for Oculus.

Oculus Social Data

Select the Oculus Social Data option in the Additional Oculus Setup page of the Scene Setup window to add this component.

This component performs an entitlement check with the Oculus platform to record the following data:

• A Session Property for the Oculus AppID.
• A Session Property for the user's Oculus ID. This Oculus Id can also be used with the Participant System if you enable the Record Oculus User Data option on the component.
• A Session Property for the user's Display Name.

Developer should ensure their app has permissions to access this information. This includes enabling permissions on the Oculus Dashboard and including the Application ID in the Oculus Platform Settings. See the Oculus documentation for more details.

If you already use the Oculus Platform in your app, you may need to configure the Initialize Type on the component:

• Automatic : This is the default choice. This will automatically complete an entitlement check and associated callbacks when the session begins.
• Delayed : Waits until you call Oculus.Platform.Core.Initialize() elsewhere in your code to perform the entitlement check.
• Manual : If you select this option, you need to execute the code below to record data from this component.

  var oculusSocial = FindObjectOfType<Cognitive3D.Components.OculusSocial>();
  if (oculusSocial != null)
  {
    oculusSocial.BeginOculusEntitlementCheck(Cognitive3D.Components.OculusSocial.GetAppIDFromConfig())
  }

Oculus Passthrough

Select the Mixed Reality option in the Additional Oculus Setup page of the Scene Setup window to add this component.

Records a Sensor value representing whether passthrough is enabled and Custom Events when passthrough state changes. For more information on enabling passthrough on Oculus devices, please visit the Get Started with Passthrough page.

Quest Pro Eye Tracking

This option will not add a component. Instead, it modifies the OVRManager to enable settings required for Quest Pro eye tracking support.

Internal Components

Room Tracking Space

This is added to the user's tracking space identified in the scene setup window to help find the game object in the scene. This doesn't send any events or sensor data.

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.