Skip to content

General Debugging

In Edit->Project Settings->Cognitive3D, you make sure Enable Logging is enabled. If something isn't working, there will almost certainly be a message in the Output Log.

Updating SDK plugin

The Unreal SDK is constantly receiving new features and bug fixes. To upgrade the Cognitive3D SDK, close Unreal and delete the Plugins/Cognitive3D folder. Add the new SDK (you can download this from Github) and open Unreal Editor. You should be prompted to rebuild the plugin binary files.

Newer Versions

The SDK supports Unreal Engine 4.26.2 and newer. We also offer limited support of older Unreal Engine versions. There should be packages for each major engine versions on the Github page with some small changes. Make sure you are using the correct plugin version. If you are having trouble implementing the SDK into your version of the Unreal Engine, please get in touch!

Converting a Blueprint Project to C++

You should have Visual Studio set up to develop for C++. See the Unreal Docs to configure Visual Studio.

As described in the Unreal Docs, open the project and press New C++ Class which can be found in the Tools menu (this may be in the File menu in earlier versions of Unreal Engine). Complete this C++ Class Wizard and create any class. This class can safely be deleted later. This should create Binaries, Intermediate and Source in your project directory. Your project now has C++ enabled and can use plugins.

create cpp

create cpp

Config File Errors

Most errors are caused by unexpected access to ini config files. Examples include network errors during project setup or gameplay, or if you have recorded sessions that don't appear on the dashboard.

These two files hold the important settings:

Project/c3dlocal/Cognitive3DKeys.ini - your Developer Key

Project/Config/c3dlocal/Cognitive3DSettings.ini your Application Key and SceneData

Use the Reference section below to quickly verify that your Application Key, Developer Key and Scene Data are set.

Close the Unreal Editor before modifying these files. Afterwards, open Unreal and confirm the configuration is working by opening to the Cognitive3D section of the Project Settings.

Reference

//file contents of Cognitive3DKeys.ini

[Analytics]
DeveloperKey=XYZ321

Note

We strongly recommend excluding Cognitive3DKeys.ini from your version control, as it contains a unique personal key for your project.

//file contents of Cognitive3DSettings.ini

[Analytics]
ApiKey=ABCDEF123456
AttributionKey=
ExportPath=C:/Users/Name/Desktop/CognitiveTemp
ProviderModuleName=Cognitive3D

[/Script/Cognitive3D.Cognitive3DSettings]
Gateway=data.cognitive3d.com
GazeBatchSize=256
CustomEventBatchSize=256
CustomEventAutoTimer=10
DynamicDataLimit=512
DynamicAutoTimer=10
SensorDataLimit=512
SensorAutoTimer=10
EnableLocalCache=True
LocalCacheSize=100

[AnalyticsDebug]
ProviderModuleName=Cognitive3D

[AnalyticsTest]
ProviderModuleName=Cognitive3D

[AnalyticsDevelopment]
ProviderModuleName=Cognitive3D

[/Script/Cognitive3D.Cognitive3DSceneSettings]
SceneData=MySceneOne,/Game/Maps,asdf-1234-ghjk-5678,1,1234
SceneData=MySceneTwo,/Game/Maps,zxcv-2345-qwer-4567,2,1236

Sessions not appearing on the dashboard

A recorded session should appear on the dashboard in about a minute after the application exits. If you don't see this, there are a couple of common reasons:

No Cognitive3D Actor in the level

Make sure there is a Cognitive3D Actor in the level. This should be added automatically when using the Scene Setup Window, or can be found in Cognitive3D/Content/

The scene does not have a SceneId associated with it

The SceneId is used to send session data to the correct scene on the Cognitive3D platform. Without a SceneId, data is not collected and not uploaded. Make sure you have uploaded your scene using Window->Open Project Setup.

  • Open Cognitive3D Settings in Unreal Project Settings. You should see a list of one or more scene names with SceneId values
  • Open the Cognitive3DSettings.ini file to confirm that the SceneData exists for your scenes. See the section above for the expected format

If you need to modify the SceneData and you have already uploaded a scene successfully from Unreal, you can find the metadata on the Dashboard. Navigate to the Scenes tab, and use the Info hint next to the scene name to modify the Cognitive3DSettings.ini file

Scene Tab

SceneExplorer

GLTF Export crashes

In certain configurations, the GLTF export module we use may crash Unreal Editor with this error:

Fatal error:
[File:D:\build\++UE5\Sync\Engine\Source\Runtime\RHICore\Private\RHICoreShader.cpp]
[Line: 36] Shader requested a global uniform buffer of type 'VirtualShadowMap'
at static slot '[Name: VirtualShadowMapUbSlot, Slot: 6]', but it was null.
The uniform buffer should be bound using RHICmdList.SetStaticUniformBuffers()
or passed into an RDG pass using SHADER_PARAMETER_STRUCT_REF()
or SHADER_PARAMETER_RDG_UNIFORM_BUFFER().

To solve this, open the Engine - Rendering section of Project Settings. Set Forward Shading to False. You will need to restart the engine.

forward shading setting

This Forward Shading option only needs to be disabled during the GLTF export step. It can be re-enabled after the export is complete.

Some textures don't appear correctly on SceneExplorer

  • Complex materials in Unreal may not appear correctly in SceneExplorer. To avoid issues, the diffuse output from a material should adequately represent the object.

Some meshes are not exported

  • Some types of rendering components are not exported correctly. This includes TextRenderers. Skeletal Meshes will not correctly export materials in versions before 4.26.

Some meshes I don't want are exported

  • Try enabling Only Export Selected in the Cognitive Scene Setup window and Selecting the objects you want.

Exporting Metahumans

Exporting Metahumans to be displayed in a scene or as a Dynamic Object is supported. Hair rendering and skeletal animations are not supported. Use the following settings to export the high resolution LOD:

  • Level of Detail: 0

Eye Tracking

If you are using eye tracking hardware for your project, you can record Fixations to give you a detailed look at how your participants are focusing throughout your experience.

We use the 3rd party eye tracking plugins to record Fixations and Gaze using Eye Tracking. The plugin dependencies should be configured automatically if the plugin folder is present and the third party directory name hasn't been changed. If you are not recording eye tracking with any of these SDKs and Eye Tracking is enabled, you may need to open the Cognitive3D.Build.cs and manually include the modules.

These are the supported Eye Tracking SDKs:

  • TobiiEyeTracking
  • SRanipal (this includes version 1.2 and 1.3)
  • Varjo
  • PicoMobile
  • HPGlia

Varjo branch of Unreal Engine

If you are using the Varjo branch of the Unreal Engine, you need to add the following to the Cognitive3D.Build.cs file.

PublicDependencyModuleNames.Add("VarjoHMD");
PublicDependencyModuleNames.Add("VarjoEyeTracker");

Legacy Project Setup

If you are using an older version of the SDK, several of the project steps require manual changes. This is detailed below.

Configure Cognitive3D.Build.cs

Close the Unreal Editor (if it is open). There are additional platform configurations that can be enabled in the Cognitive3D.Build.cs file. You can find this file in the Plugin folder (YourProjectFolder/Plugins/Cognitive3D/Source/Cognitive3D/Cognitive3D.Build.cs). See Third Party SDK Features.

In most situations, this will be uncommenting a single function in this file to connect the Cognitive3D Plugin with other SDKs in your project.

Compile

Open your project through the Epic Games Launcher. When you launch the project from the Epic Games Launcher, you may be prompted to download the GLTF Exporter plugin from the marketplace. You will be prompted to recompile your project and the Cognitive3D Plugin. If the plugin is loaded correctly, it will be visible in the Plugins window.

Plugins Window

Open the Project Setup Window

From the Cognitive3D menu, open the Legacy / Project Setup Window

menu

Follow the instructions in the Project Setup Window to configure your project. You will need to have your Developer Key from the Dashboard.

project setup window

Complete the steps in this window and you will be prompted to export your Level Geometry and upload this to our dashboard.

When this process is complete, you will notice a new BP_Cognitive3DActor in your level. This Actor is configured to automatically start collecting basic data.

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.