GameDriver Configuration File Reference

Overview

GameDriver’s agent for both Unity and Unreal Engine is configured through an XML file with the same overall structure. Most options are Unity-specific — Unreal’s agent reads far fewer config elements, and a handful of names it does share with Unity (like infobox or websockets) use a different, smaller set of attributes. This document covers the full Unity reference first, then a dedicated Unreal Engine Configuration Options section at the end. Where an option’s name is shared between engines but its schema differs, that’s called out inline.

File Location

• Unity: Resources/config/gdio.unity_agent.config.txt
• Unreal Engine: Content/GameDriver/gdio.unreal_agent.config.txt (see Getting Started with GameDriver and Unreal Engine)

The sections below (through Unreal Engine Configuration Options) describe the Unity config file specifically.

XML Structure

The configuration file uses a standard XML format with a root element. The file should begin with an XML declaration and include a version attribute for the config element:

<?xml version="1.0" encoding="utf-8"?>
<config version="0.2">
  <!-- Configuration elements go here -->
</config>

Configuration Options Reference

Object Resolvers

Defines the resolvers used to locate objects in the game hierarchy.

XML Path	Attribute	Description	Default
/config/objectresolvers/resolver	@class	The resolver class name	"gdio.unity_agent.HierarchyPathObjectResolver"
/config/objectresolvers/resolver	@priority	Priority level (lower numbers have higher priority)	0

Example:

<objectresolvers>
  <resolver class="gdio.unity_agent.HierarchyPathObjectResolver" priority="0" />
</objectresolvers>

This example sets the default HierarchyPathObjectResolver with the highest priority.

Build Flags

Defines build-specific flags for the GameDriver agent.

XML Path	Attribute	Description	Default
/config/buildflags/flag	@name	Build flag name	"" (empty)

Example:

<buildflags>
  <flag name="" />
</buildflags>

This example includes an empty build flag setting.

Hierarchy Path

Configures how the hierarchy path resolver works.

XML Path	Attribute	Description	Default
/config/hierarchypath	@primaryattribute	The primary attribute to use when resolving objects	"tag"

Example:

<hierarchypath primaryattribute="tag" />

This example configures the hierarchy path resolver to use the “tag” attribute as the primary identifier.

Mouse Click Highlight

XML Path	Attribute	Description	Default
/config/mouseclickhighlight	@radius	Size of mouse click highlight	3
/config/mouseclickhighlight	@frames	Number of frames to display the highlight	15
/config/mouseclickhighlight	@style	Style of highlight (e.g., "circle")	"circle"
/config/mouseclickhighlight	@color	Color of highlight (RGB format)	"1.0,0.0,0.0" (red)

Example:

<mouseclickhighlight radius="3" frames="15" style="circle" color="1.0,0.0,0.0" />

This example sets a red circle highlight with radius 3 that displays for 15 frames.

XR Settings

XML Path	Attribute	Description	Default
/config/xrsettings	@lefthand_model_offset	Left hand model offset (6 values)	0.0,0.0,0.0,0.0,0.0,0.0
/config/xrsettings	@lefthand_pointer_offset	Left hand pointer offset (6 values)	0.0,0.0,0.0,0.0,0.0,0.0
/config/xrsettings	@righthand_model_offset	Right hand model offset (6 values)	0.0,0.0,0.0,0.0,0.0,0.0
/config/xrsettings	@righthand_pointer_offset	Right hand pointer offset (6 values)	0.0,0.0,0.0,0.0,0.0,0.0

Example:

<xrsettings lefthand_model_offset="0.0,0.0,0.0,0.0,0.0,0.0" lefthand_pointer_offset="0.0,0.0,0.0,0.0,0.0,0.0" righthand_model_offset="0.0,0.0,0.0,0.0,0.0,0.0" righthand_pointer_offset="0.0,0.0,0.0,0.0,0.0,0.0" />

This example uses default offset values for XR hand tracking.

XR Thresholds

XML Path	Attribute	Description	Default
/config/xrthresholds	@frames	Frame threshold for XR	1
/config/xrthresholds	@axis_mag_thres	Axis magnitude threshold	0.5
/config/xrthresholds	@axis_angle_thres	Axis angle threshold	10
/config/xrthresholds	@pos_thres	Position threshold	0.1
/config/xrthresholds	@rot_thres	Rotation threshold	0.05

Example:

<xrthresholds frames="1" axis_mag_thres="0.5" axis_angle_thres="10" pos_thres="0.1" rot_thres="0.05" />

This example sets thresholds for XR input detection with default values.

Unreal Engine: xrthresholds is also supported, but only the frames attribute is read — axis_mag_thres, axis_angle_thres, pos_thres, and rot_thres have no Unreal equivalent. Example: <xrthresholds frames="1" />.

Recorder Settings

These settings are used when recording XR events. For more information, see the Recorder documentation here.

XML Path	Attribute	Description	Default
/config/recorder	@agg_buttons	Aggregate buttons in recording	false
/config/recorder	@agg_vec2	Aggregate Vector2 inputs	true
/config/recorder	@rem_vec2_time	Vector2 removal time	0.0
/config/recorder	@frames_or_time	Use frames or time for recording	"time"
/config/recorder	@rec_physics	Record physics	false
/config/recorder	@rec_all_eyes	Record all eye-tracking data	false
/config/recorder	@use_action_callback	Use action callback	false
/config/recorder	@world_refs	World reference objects (comma-separated)	"XR Origin"
/config/recorder	@local_refs	Local reference objects (comma-separated)	"Camera Offset,LeftHand,RightHand"

Example:

<recorder agg_buttons="false" agg_vec2="true" rem_vec2_time="0.0" rec_physics="false" rec_all_eyes="false" use_action_callback="false" frames_or_time="time" world_refs="XR Origin" local_refs="Camera Offset,LeftHand,RightHand" />

This example configures the recorder with VR-specific reference objects and default behavior for input aggregation.

OnGUI Events

XML Path	Attribute	Description	Default
/config/ongui_events	@enabled	Enable OnGUI events	true
/config/ongui_events	@show_mouse	Show mouse in OnGUI events	true
/config/ongui_events	@hide_on_screenshot	Hide the pointer in screenshots	false

Example:

<ongui_events enabled="true" show_mouse="true" hide_on_screenshot="false"/>

This example enables OnGUI events and shows the mouse cursor during these events.

Info Box

XML Path	Attribute	Description	Default
/config/infobox	@enabled	Display info box	true
/config/infobox	@x	Info box X position	10.0
/config/infobox	@y	Info box Y position	10.0
/config/infobox	@font_size	Info box font size	11
/config/infobox	@font_type	Info box font type	"" (empty)
/config/infobox	@font_color	Info box font color (RGBA)	"1.0,1.0,1.0,1.0" (white)
/config/infobox	@background_size	Info box background size (width,height)	"300.0,70.0"
/config/infobox	@background_color	Info box background color (RGBA)	"0.0,0.0,0.0,0.15" (transparent black)
/config/infobox	@hide_on_screenshot	Hide infobox in screenshots	false

Example:

<infobox enabled="true" x="10.0" y="10.0" font_size="11" font_type="" font_color="1.0,1.0,1.0,1.0" background_size="300.0,70.0" background_color="0.0,0.0,0.0,0.15" hide_on_screenshot="false"/>

This example shows a standard info box configuration with default settings. Note that you can use percentage values for x and y by adding a ”%” suffix (e.g., “10.0%”).

Unreal Engine: infobox is also supported, but only the enabled, x, and y attributes are read — there is no font_size, font_type, font_color, background_size, background_color, or hide_on_screenshot equivalent. Example: <infobox enabled="true" x="400.0" y="100.0" />.

Unicode Settings

XML Path	Attribute	Description	Default
/config/unicode/ignoreZeroWidthSpace	@enabled	Ignore zero-width space	true

Example:

<unicode>
  <ignoreZeroWidthSpace enabled="true" />
</unicode>

This example enables ignoring zero-width space characters (U+200B), which is useful when comparing strings in text input fields.

Object Resolution

XML Path	Attribute	Description	Default
/config/resolver/useCache	@enabled	Use object resolver cache	false

Example:

<resolver>
  <useCache enabled="true" />
</resolver>

This example enables the object resolver cache, which may improve performance when repeatedly accessing the same objects.

Unreal Engine: the same <resolver><useCache enabled="..."/></resolver> element is accepted in Unreal’s config file, but it is currently a pre-existing stub that isn’t read or acted on by the agent. See HPath Engine Selector below for Unreal’s actual resolver-related option, newengine, which lives on the same <resolver> element.

Emulation

XML Path	Attribute	Description	Default
/config/emulation/clickevent	@enabled	Emulate click events	false

Example:

<emulation>
  <clickevent enabled="true" />
</emulation>

This example enables click event emulation.

Hooking

XML Path	Attribute	Description	Default
/config/hooking/initialize	@enabled	Initialize hooking	true
/config/hooking/initialize/mouse	@enabled	Initialize mouse hooking	true
/config/hooking/initialize/keyboard	@enabled	Initialize keyboard hooking	true
/config/hooking/initialize/gamepad	@enabled	Initialize gamepad hooking	true
/config/hooking/initialize/touch	@enabled	Initialize touch hooking	true
/config/hooking/initialize/unityxr	@enabled	Initialize Unity XR hooking	true
/config/hooking/initialize/ovr	@enabled	Initialize OVR hooking	true

Example:

<hooking>
  <initialize enabled="true">
    <mouse enabled="true" />
    <keyboard enabled="true" />
    <gamepad enabled="true" />
    <touch enabled="true" />
    <unityxr enabled="true" />
    <ovr enabled="true" />
  </initialize>
</hooking>

This example enables hooking for all input types.

Wait Operations

XML Path	Attribute	Description	Default
/config/waitfordelay	@object	Default delay for WaitForObject operations (ms)	0
/config/waitfordelay	@value	Default delay for WaitForObjectValue operations (ms)	0

Example:

<waitfordelay object="0" value="0" />

This example configures no delay for wait operations.

Unity Analytics

XML Path	Attribute	Description	Default
/config/unityanalytics	@enabled	Enable Unity Analytics	false

Example:

<unityanalytics enabled="false" />

This example disables Unity Analytics integration.

Activation

XML Path	Attribute	Description	Default
/config/activateonstart	@enabled	Activate on start	true

Example:

<activateonstart enabled="true" />

This example enables automatic activation at startup.

Unity Message Filter

XML Path	Attribute	Description	Default
/config/unitymessagefilter	@include	Unity message filter codes (comma-separated) Values: 0 - Error, 1 - Assert, 4 - Exception, 3 - Log, 2 - Warning	"0,1,4"

Example:

<unitymessagefilter include="0,1,4" />

This example sets default message filter values.

Unreal Engine: the equivalent element is named unrealmessagefilter rather than unitymessagefilter, and its include values are named log-severity strings rather than numeric codes: Error, Warning, Display (comma-separated). Example: <unrealmessagefilter include="Display" />. See also Diagnostic Log Category Filter below for a separate, per-category diagnostic filter unique to Unreal.

Lua Configuration

XML Path	Attribute	Description	Default
/config/luaEnvironment	@enabled	Enable Lua environment	true
/config/luaDebugging	@enabled	Enable Lua debugging	false
/config/luaDebugging	@port	Lua debug server port	41912
/config/luaCustomTypes/customType	@namespace	Custom type namespace	varies
/config/luaCustomTypes/customType	@type	Custom type name	varies

Example:

<luaEnvironment enabled="true" />
<luaDebugging enabled="false" port="41912" />
<luaCustomTypes>
  <customType namespace="MyGame.Entities" type="Player" />
</luaCustomTypes>

This example enables the Lua environment without debugging and defines a custom Lua type.

WebSockets

XML Path	Attribute	Description	Default
/config/websockets	@enabled	Enable WebSockets	true (from code)
/config/websockets	@host	WebSocket host	"localhost" (from code)
/config/websockets	@port	WebSocket port	19734 (from code)
/config/websockets	@maxConnectionAttempts	Maximum connection attempts	5
/config/websockets	@connectionAttemptDelay	Delay between connection attempts	5

Example:

<websockets enabled="true" host="localhost" port="19734" maxConnectionAttempts="5" connectionAttemptDelay="5" />

This example configures WebSocket connections with default settings.

Unreal Engine: websockets is also supported, but with a different attribute set: enabled, url (not host), port, retryTime, and retryCount (not maxConnectionAttempts/connectionAttemptDelay). Example: <websockets enabled="false" port="7071" url="127.0.0.1" retryTime="5" retryCount="3" />. Unreal also has a separate <listening port="15505" /> element (or a bare <port>...</port>) for its raw TCP port, independent of the optional WebSockets transport.

Licensing

XML Path	Attribute	Description	Default
/config/license/server	@url	License server URL	null
/config/license/node	(element value)	License node identifier	"" (empty)
/config/license/token	(element value)	License token	"" (empty)

Example:

<license>
  <server url="https://licensing.gamedriver.io" />
  <node>MyGameProject</node>
  <token>abcd1234-ef56-7890-ab12-3456cdef7890</token>
</license>

This example configures GameDriver to use a specific license server, node identifier, and token.

Unreal Engine: the concept is the same, but the schema is flatter — server, node, and token are all attributes directly on a single <license> element, not nested child elements. Example: <license server="https://licensing.gamedriver.io" node="MyGameProject" token="abcd1234-ef56-7890-ab12-3456cdef7890" />.

Notes on Configuration File Format

• All paths in the configuration file use XPath syntax
• Some elements (like license/node and license/token) store values as element content rather than attributes
• When providing comma-separated values for arrays (like in unitymessagefilter), do not include spaces between values
• Float values use period (.) as the decimal separator and follow en-US culture formatting
• XR offset values are specified as 6-value arrays (likely representing position and rotation)
• Color values are specified as comma-separated RGB or RGBA values ranging from 0.0 to 1.0
• For position attributes like infobox x and y, you can use percentage values by adding a ”%” suffix (e.g., “10.0%“)

Complete Configuration Example

<?xml version="1.0" encoding="utf-8"?>
<config version="0.2">

  <!-- Object Resolvers Configuration -->
  <objectresolvers>
    <resolver class="gdio.unity_agent.HierarchyPathObjectResolver" priority="0" />
  </objectresolvers>

  <!-- Build Flags Configuration -->
  <buildflags>
    <flag name="" />
  </buildflags>

  <!-- Mouse Click Highlight Configuration -->
  <mouseclickhighlight radius="3" frames="15" style="circle" color="1.0,0.0,0.0" />

  <!-- XR Settings -->
  <xrsettings lefthand_model_offset="0.0,0.0,0.0,0.0,0.0,0.0" lefthand_pointer_offset="0.0,0.0,0.0,0.0,0.0,0.0" righthand_model_offset="0.0,0.0,0.0,0.0,0.0,0.0" righthand_pointer_offset="0.0,0.0,0.0,0.0,0.0,0.0" />
  <xrthresholds frames="1" axis_mag_thres="0.5" axis_angle_thres="10" pos_thres="0.1" rot_thres="0.05" />

  <!-- Recorder Configuration -->
  <recorder agg_buttons="false" agg_vec2="true" rem_vec2_time="0.0" rec_physics="false" rec_all_eyes="false" use_action_callback="false" frames_or_time="time" world_refs="XR Origin" local_refs="Camera Offset,LeftHand,RightHand" />

  <!-- OnGUI Events Configuration -->
  <ongui_events enabled="true" show_mouse="true" />

  <!-- Hierarchy Path Configuration -->
  <hierarchypath primaryattribute="tag" />

  <!-- Information Box Configuration -->
  <infobox enabled="true" x="10.0" y="10.0" font_size="11" font_type="" font_color="1.0,1.0,1.0,1.0" background_size="300.0,70.0" background_color="0.0,0.0,0.0,0.15" />

  <!-- Unicode Configuration -->
  <unicode>
    <ignoreZeroWidthSpace enabled="true" />
  </unicode>

  <!-- Resolver Configuration -->
  <resolver>
    <useCache enabled="false" />
  </resolver>

  <!-- Emulation Configuration -->
  <emulation>
    <clickevent enabled="false" />
  </emulation>

  <!-- Hooking Configuration -->
  <hooking>
    <initialize enabled="true">
      <mouse enabled="true" />
      <keyboard enabled="true" />
      <gamepad enabled="true" />
      <touch enabled="true" />
      <unityxr enabled="true" />
      <ovr enabled="true" />
    </initialize>
  </hooking>

  <!-- Wait For Delay Configuration -->
  <waitfordelay object="0" value="0" />

  <!-- Unity Analytics Configuration -->
  <unityanalytics enabled="false" />

  <!-- Activation Configuration -->
  <activateonstart enabled="true" />

  <!-- Unity Message Filter Configuration -->
  <unitymessagefilter include="0,1,4" />

  <!-- Lua Configuration -->
  <luaEnvironment enabled="true" />
  <luaDebugging enabled="false" port="41912" />

  <!-- WebSockets Configuration -->
  <websockets enabled="true" host="localhost" port="19734" maxConnectionAttempts="5" connectionAttemptDelay="5" />

  <!-- License Configuration -->
  <license>
    <server url="" />
    <node></node>
    <token></token>
  </license>
</config>

Unreal Engine Configuration Options

Unreal’s agent config file (Content/GameDriver/gdio.unreal_agent.config.txt) uses the same <config version="0.2"> XML root as Unity, but reads far fewer elements overall. Options it shares by name with Unity but with a different or narrower schema (infobox, websockets/listening, xrthresholds, resolver/useCache, and the message filter) are noted inline in their respective sections above. This section covers the options that are unique to Unreal.

HPath Engine Selector

Selects which HPath query-resolution engine the agent uses. Lives on the same <resolver> element as the (currently inert) useCache option described above.

XML Path	Attribute	Description	Default
/config/resolver	@newengine	Use the optimized stack-machine HPath engine (true) or the legacy evaluator (false)	true

Example:

<resolver newengine="false">
  <useCache enabled="false" />
</resolver>

This example opts a project back into the legacy HPath evaluator. Omitting newengine entirely (or the whole <resolver> element) also defaults to the new engine — only an explicit false opts out. This can also be toggled live at runtime without relaunching, via the gdio.HPath.Engine console variable.

Slate Explorer

Controls how deep the Slate Explorer tool recurses when building its widget tree.

XML Path	Attribute	Description	Default
/config/slateExplorer	@recursionLimit	Maximum recursion depth when building the Slate/UMG widget tree	40

Example:

<slateExplorer recursionLimit="50"/>

Diagnostic Log Category Filter

A named, hierarchical set of diagnostic log categories, each off by default. Unlike unrealmessagefilter (a severity filter), this turns on verbose diagnostic logging for a specific internal subsystem without needing a code change — useful when asked by GameDriver support to enable a specific category while troubleshooting. Enabling a parent category (e.g. Input) also enables all of its _-prefixed child categories (e.g. Input_MouseMove).

XML Path	Attribute	Description	Default
/config/logfilter/log	@enabled	Enable this named diagnostic log category	false
/config/logfilter/log	(element value)	The category name	—

Example:

<logfilter>
  <log enabled="true">Input_MouseMove</log>
</logfilter>

TCP Listening Port

Sets the agent’s raw TCP listening port, independent of the optional WebSockets transport described above.

XML Path	Attribute	Description	Default
/config/listening	@port	TCP listening port	15505

Example:

<listening port="15505" />

Complete Unreal Configuration Example

<?xml version="1.0" encoding="utf-8"?>
<config version="0.2">
  <resolver>
      <useCache enabled="false" />
  </resolver>
  <infobox enabled="true" x="400.0" y="100.0" />
  <listening port="15505" />
  <websockets enabled="false" port="7071" url="127.0.0.1" retryTime="5" retryCount="3"/>
  <xrthresholds frames="1" />
  <logging><trace enabled="true" modules=""/></logging>
  <logfilter>
    <log enabled="false">Input_MouseMove</log>
  </logfilter>
  <slateExplorer recursionLimit="50"/>
    <unrealmessagefilter include="Display" />
</config>