Skip to content
GameDriver GameDriver Knowledge Base

GameDriver Configuration File Reference

Overview

Section titled “Overview”

GameDriver for Unity uses an XML configuration file located at Resources/config/gdio.unity_agent.config.txt. This document describes the XML structure and available configuration options.

File Location

Section titled “File Location”
  • The configuration file should be placed at: Resources/config/gdio.unity_agent.config.txt

XML Structure

Section titled “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

Section titled “Configuration Options Reference”

Object Resolvers

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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.

Recorder Settings

Section titled “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

Section titled “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

Section titled “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%”).

Unicode Settings

Section titled “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

Section titled “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.

Emulation

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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.

Lua Configuration

Section titled “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

Section titled “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.

Licensing

Section titled “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.

Notes on Configuration File Format

Section titled “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

Section titled “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>