modding:config_system_documentation

This is an old revision of the document!


The “configs” system is a key part of Dangerous Rays modding. A config is a XML file that contain a list of properties that can be read by the engine. The engine can then configure various things according to config properties values.
With the config system modders can modify a huge amount of things like UI elements colors or define/tweak gameplay components…
The engine will perform a sanity check of every config file at the game startup and will log any errors or warnings found in the dev console.

Here is the “life cycle” of the config system inside the DR engine:

1- All default configs (one for each config types) are loaded when the game is launched.
2- Once default configs are loaded, all regular configs files and their local properties are loaded in memory. This process can take some time depending on the amount of config files to load.
3- Once every configs are loaded in memory, the config inheritance process is done so when the process is finished, configs do have all their properties ready. Properties values are being read from their parent or default configs if necessary.
4- After everything is ready in the memory a error check pass is done on every configs.
5- Configs are ready to be used by the engine.

Important

Even if configs XML files can be directly edited by using some text editor like notepad, it's heavily recommended to use the Config Editor to deal with configs modification. Avoid manual XML modification as much as you can.

Here is what a config file syntax looks like:

<?xml version="1.0"?>
<config type="font">
    <property name="Font" type="resourcepath" value="Fonts/RobotoCondensed/RobotoCondensed-Bold.ttf" description="Font file to be used for this font" />
    <property name="Size" type="float" value="24.0" minvalue="0.0" maxvalue="64.0" description="Font size" />
</config>



Each config have a:

  • Name used as an identifier. The config name is simply defined by it's XML file name.
  • Type that define what config type it is and what it will configure.

In the above example, it's a “Font” config type (so it's used to define a font used by the UI) and this config is named “Button”.


Each config property have a:

  • Name used as a property identifier.
  • Type that define if the property is a integer or decimal number, a file path, a resource path…
  • Value.
  • Some other optional attributes like description to be used by the config editor, min/max values, metadata…

In the above example, we have two properties:

  • One “Font” property of “resourcepath” type that is used to define the resource path of the font.
  • One “Size” property of “float” (decimal number) type that is used to define the size of the font. Please note that the “minvalue” and “maxvalue” attributes are optional.

Each config has an assigned type, defining it's “purpose” in the game. Here is the list of config types that are handled within config system.

Type Name Description
Core Defines base properties of the game
MaterialPhysProperties Defines physical properties of a material surface
UIStyle Defines User Interface global look

As mentioned above each config property must have an assigned type. Here is the list of variable type that you can assign to your properties.

Type Description Example
int Integer number 46
bool true or false true
float Decimal number 11.07
vector2 2 dimensional vector 2.0, 4.0
vector3 3 dimensional vector 2.0, 4.0, 6.0
vector4 4 dimensional vector 2.0, 4.0, 6.0, 8.0
color R G B A normalized (from 0.0 to 1.0) color values 1.0, 0.0, 0.0, 1.0
string A text string hello world !
intvector2 2 dimensional vector of integer numbers 2, 4
intvector3 3 dimensional vector of integer numbers 2, 4, 8
enum Enumeration (string) MEDIUM
configname Config name myconfigname
filepath Complete file path C:/Folder/File.txt
resourcepath Resource path Core/Models/SM_Cube.mdl
soundevent FMOD Sound Event Name /AmbientMusic/AmbientMusic01

Each config properties can have some optional attributes defined. In the example below you can see that the “Size” property do have “minvalue” and “maxvalue” attributes defined. This is useful for limiting value in a certain range in the config editor.

<?xml version="1.0"?>
<config type="font">
    <property name="Size" type="float" value="24.0" minvalue="0.0" maxvalue="64.0" />
</config>


Here is the list of optional attributes:

Name Description Example
description Description of the property. This will be displayed in config editor description=“This set the font size”
minvalue Property minimum value (only work with “int” and “float” types) minvalue=“0.0”
maxvalue Property maximum value (only work with “int” and “float” types) maxvalue=“100.0”
metadata Additional data (may varies according to the attribute type) metadata=“LOW, MEDIUM, HIGH”

Each property can have a metadata string attributed to it (only declared in default/base configs). This metadata is mainly used by the config editor to properly display the config properties.

For example in the following default config example you can see that the “Texture” property do have the “texture” metadata. This means that only a texture resource type can be set for this property.


<?xml version="1.0"?>
<config type="terraintexturelayer" default="true">
    <property name="Texture" type="resourcepath" value="Nature_Terrain/Textures/T_Ground01_AD.dds" metadata="texture" description="Resource path of the texture to be used by this layer" />
    ...


Here is a table that shows what metadata needs to be specified according to each property types:

Property Type MetaData Usage Example
configname Config type metadata=“materialphysproperties”
resourcepath Resource type metadata=“texture”
enum Enum elements names metadata=“RED, GREEN, YELLOW”

Each registered config type must have one (and only one) default config. Here what a default config (for the “Font” config type) looks like:

<config type="font" default="true">
	<property name="Font" type="resourcepath" value="Fonts/Roboto/Roboto-Medium.ttf" />
	<property name="Size" type="float" value="18.0" />
	<property name="MergeIcons" type="bool" value="false" />
</config>

As you can see it is almost identical to a regular config. except that boolean attribute that is set to true:

default="true"

With that attribute we are specifying that this is the default config for the “Font” config type. In the default config you can see all properties that can be modified in any config of the same config type.
The main purpose of default configs is that they can be used as a fallback in case if some properties are missing from a config. Take this for example this default config:

<config type="font" default="true">
	<property name="Font" type="resourcepath" value="Fonts/Roboto/Roboto-Medium.ttf" />
	<property name="Size" type="float" value="18.0" />
	<property name="MergeIcons" type="bool" value="false" />
</config>

In the above default config there is 3 different properties that are declared. If we have another “MyFont01” font config that look like this:

<config type="font">
	<property name="Size" value="32.0" />
</config>

You can see that only 1 property is declared but the default config for the “Font” config type have 3 declared properties. Is it a problem ? No !

In this case when the “MyFont01” config will be loaded the config system is going to read the missing properties value from the default config. So the properties are going to have those assigned values when the “MyFont01” config will be loaded:

  • Font: Fonts/Roboto/Roboto-Medium.ttf (value from default config)
  • Size: 32 (value from “MyFont01” config)
  • MergeIcons: False (value from default config)

This concept might be difficult to understand at first (especially if you are not familiar with Object Oriented Programming/Inheritance concept for example) but you will understand it by trying to make new configs and explore the existing configs of the game.

  • modding/config_system_documentation.1601988627.txt.gz
  • Last modified: 06/10/2020 14:50
  • by admin