GameDriver Features
      Back to home
      1. GameDriver Knowledge Base
      2. General
      3. GameDriver Features

      GameDriver Configuration File Reference

      Learn how to configure the GameDriver agent using different options in the config settings file.

      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

      • The configuration file should be placed at: Resources/config/gdio.unity_agent.config.txt

      XML Structure

      The configuration file uses a standard XML format with a root <config> 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.

      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%").

      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.

      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.

      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.

      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

      • 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>