Skip to content

General Debugging

In Edit->Project Settings->CognitiveVR, you make sure Mute Info Messages and Mute Error Messages are disabled. If something isn't working, there will almost certainly be a message in the Output Log!

debug toggles

Newer Versions

Unreal Engine 4.14.3 is supported with the SDK. There should be packages for major engine versions on the github release page. If you are having trouble implementing the SDK into your version of the Unreal Engine, please get in touch! The versions we support are:

  • 4.15.3
  • 4.16.3
  • 4.17.2
  • 4.18.3
  • 4.19.2
  • 4.20.3
  • 4.21.2

Converting a Blueprint Project to C++

This assumes you have Visual Studio set up to develop for C++. From the Unreal Docs:


It's important to note that Visual Studio 2015 (VS2015) doesn't install C++ tooling support by default. When installing VS2015, choose Custom installation and then choose the C++ components that you'll need for your workflow. If you've already installed Visual Studio 2015, choose File > New > Project > C++ to install C++.

This is an example of how the root folder should look when the project has C++ enabled. Notice the Binaries, Intermediate and Source folders.


To enable C++ in the project, open the project. In the Content Browser, press 'Add New' and select 'New C++ Class...'


In this example, the parent class 'None' is fine. Press Next.


Name your class whatever you would like. This class can safely be deleted later. Press Create Class.


This should create the Binaries, Intermediate and Source folders in your project root. Your project now has C++ enabled and can use plugins!

Scene Explorer

Some textures don't appear correctly on

Special Characters

  • This is a known bug. It is related to special characters in the names of texture and/or materials in Unreal.
  • ä, á â, ã and other special characters may not correctly keep their references when using Blender to decimate your scene.
  • Replacing these characters in these texture/materials names in Unreal with ascii characters should fix this issue. After replacing these characters, make sure to export your scene again.
  • Alternatively, modifying the exported .mtl and .obj files can fix the references to these textures and/or materials. Only try this if you are familiar with the .mtl and .obj file formats.


  • Really complex materials in Unreal may not correctly find the diffuse texture required to display in SceneExplorer.

Why is my camera so slow?

  • The camera might not be slow - the Unreal scene might be giant!
  • Due to the scale used in Unreal, you must include the settings.json file that is created when running Blender to reduce scene geometry. This should be generated by default. The contents of this file are {"scale":100,"sceneName":"YourSceneName","sdkVersion":"0.5.0"}

Do I really need Blender?

  • Technically no, but it drastically simplifies a lot of processes. Python scripts that run in Blender will convert image files to the correct format, create a settings.json file and move all required files into the correct directory for uploading. This would have to be done manually otherwise.

Some meshes are not exported

  • Some types of rendering components are not exported correctly. This includes TextRenderers and Skeletal Meshes

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.

  • In some cases, it can be convenient to simply modify the exported scene.obj file in a 3d modeling program.

Player Tracker

No data uploaded to Scene Explorer

There are three common reasons data from your play session might not display on

No PlayerTracker Component

Make sure there is a PlayerTracker component parented to your player's camera.

Missing Start Session Blueprint

Add an Analytics->Start Session blueprint in your level blueprints, connected to Event Begin Play. There are also other ways to start a session, including C++.

start session

The scene does not have a SceneKey associated with it

The SceneId is used by the PlayerTracker component to send data to the correct scene on SceneExplorer. Without a SceneId, data is not collected and not uploaded. Make sure you have uploaded your scene using Window->Cognitive Scene Setup.

Fixation Recorder

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

Simply attach a Fixation Recorder component to your Player Actor. There are several parameters on the component to configure how fixation points are recorded. The default values are taken from several academic papers and should be suitable for most projects.

Installing Tobii VR Eye Tracker

Follow the instructions for adding the TobiiVR Unreal package to your project. Note that this requires Unreal Engine 4.21 or newer.

Then, add the following code to the CognitiveVR.Build.cs file and start the Unreal Editor. It should prompt you to recompile your project.

    new string[] {


Installing Vive Pro Eye Tracker

Follow the instructions for adding the Vive Pro Eye Unreal package to your project. Note that this requires Unreal Engine 4.20 or newer.

Add the following code to the CognitiveVR.Build.cs file and start the Unreal Editor. It should prompt you to recompile your project.

    new string[] {


string BaseDirectory = System.IO.Path.GetFullPath(System.IO.Path.Combine(ModuleDirectory, "..", "..", ".."));
string SRanipalDir = System.IO.Path.Combine(BaseDirectory,"SRanipal","Binaries",Target.Platform.ToString());

Installing Varjo VR-1 Eye Tracker

Follow the instructions for installing the Varjo plugin into your project. The plugin requires 4.21 or newer.

Add the following code to the CognitiveVR.Build.cs file and start the Unreal Editor. It should prompt you to recompile your project.

If you are using the Varjo branch of the Unreal Engine, you need to add this:


If you are using the Varjo Plugin, add this:

new string[] {


Debug Canvas

The Debug Canvas provides an overview of recorded session data while the session is playing. You can disable this canvas from ProjectSettings/CognitiveVR.


The DebugCanvasHolder actor is added to the level automatically after the the level is exported using the Cognitive3D Scene Setup window. Alternatively, you can add the actor to the level from this path: "CognitiveVR C++ Classes/CognitiveVR/Public/DebugCanvasHolder"

Display Values


  • Session Name - The session name as it will appear on the dashboard
  • Scene Name - The friendly name of the currently loaded level
  • Scene Id - The Id of the current level. Used internally to identify which level is loaded
  • Session Active - True if StartSession has been called and is running correctly
  • Has Player Tracker - True if there is a Player Tracker component in the level
  • Has Fixation Recorder - True if there is a Fixation Recorder component in the level
  • Session Duration - The time in real seconds since StartSession has been called
  • Session Data
    • Data Type - What kind of data is described in this row. For Dynamics, the prefixed number is the total number of dynamic objects in the level that have been recorded
    • Count - The number of oustanding data points. This value resets when a batch of data is sent to the dashboard. For Fixations, this is the number of fixations that have ended
    • Part - How many batches of data have been sent to the dashboard
    • Send Time - The last time a batch of events was sent (in seconds since session start)
  • Sensor Values - Each Sensor listing its name and most recently recorded value
  • ExitPoll - Each ExitPoll question in the current question set and the player's answers

Known Issues

References to Dynamic Object not saved in Blueprint

In a rare case, it appears that Blueprint (both components on Blueprint Classes and nodes in the Event Graph) will not save references to Dynamic Object components. This occurs in 4.14 but may be fixed in newer versions.

get component

A reference may reset if: a class is defined in C++ AND implements a Blueprint Event Graph. If this broken class references a Dynamic Object component OR any other Blueprint class which references a Dynamic Object component, the reference may reset.

The solution is: add GetOwner()->GetComponentByClass(UDynamicObject::StaticClass()); in a non-constructor function in the broken class's C++ definition. It may also require that you add #include "DynamicObject.h" to the header of your broken class.