Basic knowledge about configuration files

This section contains the basic principles for describing game components.

SDL files

SDL (structure definition language) - a common format for configuration files used by the Gem RTS game engine. SDL files of Gem RTS have nothing in common with the graphic modeling language and SDL files from Microsoft Visual Studio.

SDL files are used to describe most of the game's components.

Examples of use:

descriptions of game objects;
descriptions of interface elements;
unit settings;
game mode settings;
game level files (maps);
descriptions of mission logic;
descriptions of special effects (VFX) and sound effects (SFX);
descriptions of units' properties and behavior;
descriptions of animations; ...

SDL files are text documents that are saved in UTF-8 encoding. These files can be viewed and edited with any standard text editor, including Sublime, Notepad++, Vim, among others.

For certain SDL files, specialized editors are available within the Editor application (refer to the EDITOR section of the documentation for more details). If the editor features a built-in game component editor, it is advised to utilize this tool for creating and editing the corresponding SDL files. Using the integrated component editor ensures optimal compatibility and functionality for these files. Use of generic text editors should be limited to scenarios where it is absolutely necessary.

Rules for naming SDL files

SDL files can have different extensions, but they always share the same syntax. The most common extensions of SDL files are presented in the table.

Extension	Description of File Contents
.def	Descriptions of game objects
.ext	Additional descriptions of objects
.set	Descriptions of game components and settings parameters
.inc	Used for structuring descriptions and extracting common descriptions for groups of components. The content of .inc files is inserted by the engine parser into the final SDL at the places from which the .inc file is called
.info	Game component settings
.mi	Descriptions of mission logic

Extension

Description of File Contents

.def

Descriptions of game objects

.ext

Additional descriptions of objects

.set

Descriptions of game components and settings parameters

.inc

Used for structuring descriptions and extracting common descriptions for groups of components. The content of .inc files is inserted by the engine parser into the final SDL at the places from which the .inc file is called

.info

Game component settings

.mi

Descriptions of mission logic

Location of SDL files

The location of SDL files depends on which game component is described in them. The location of the file affects the format and structure of the description.

Most files must be located in a strictly defined folder or have a specific name.

More details on the principle of file placement are discussed in the article Game Resource Architecture.

Contents of SDL files

The content of an SDL file depends on which game component it describes.

Files	Explanation
...\scene\set\interaction_entity\human.inc ...\scene\set\target\human.inc ...\scene\properties\selection\human.inc	SDL files have the same name and extension, but contain different description formats depending on the location of the file in the game resource structure.
..\scene\set\environment	SDL files from the environment folder describe the same game component: weather and visual environmental effects. They have the same format for describing parameters and settings of effects. The content of files from the environment folder differs only in the values of weather parameters, names of effects, and textures.

Files

Explanation

...\scene\set\interaction_entity\human.inc ...\scene\set\target\human.inc ...\scene\properties\selection\human.inc

SDL files have the same name and extension, but contain different description formats depending on the location of the file in the game resource structure.

..\scene\set\environment

SDL files from the environment folder describe the same game component: weather and visual environmental effects. They have the same format for describing parameters and settings of effects. The content of files from the environment folder differs only in the values of weather parameters, names of effects, and textures.

Syntax

An SDL file structure consists of blocks. The smallest unit of a block is a line enclosed in curly braces and contains the parameter name.

Each SDL block must have an opening and closing curly brace. Missing a brace causes critical errors in the game.

Optionally, a block can contain one or more parameter values. A parameter value can be a number or a variable name. Variable names containing space are enclosed in double quotes.

SDL block template
{parameter [data]}

Example

{actor}
{health 1000}
{tag "oficer t34"}

If there are multiple values, they are listed separated by spaces.

Example

{actor m2 m3 “oficer t34”}

The parameter actor has three values: m2, m3, and "officer t34"

Blocks can be nested. Tabs and line breaks are optional but recommended for easier understanding of descriptions.

Example

{rules
    {“vehicle”
       {“actor” “m2”
          {“icon” “m2_icon”}
       }
    }
}

Conditions

SDL files that set game component settings can contain conditions for calling or setting parameters.

Condition Format
{if condition [data]}
[data] - optional the parameter value (if required)

Conditions can also be nested. Conditions are evaluated in sequence. The parameter value from the first condition that triggers is selected.

Example

{vision 1
    {if human 0.2
        {if mp_team "a" 0.5}
    }
    {if tags “xxx” 0.8}
}

The parameter vision defaults to a value of 1. If the unit is of type human, the vision parameter is set to 0.2. If multiplayer mode is enabled and the human unit belongs to team "a", the vision parameter is set to 0.5. If the "human" condition does not apply and the unit has the tag "xxx", the vision parameter is set to 0.8

Comments

You can make a single-line comment with a semicolon. Anything written on the line after the semicolon is ignored by the engine during loading.

Example

{armor ; unit defence 
    ; {value 17} 
    {value 5} 
}

The phrase "unit defence" is a single-line comment for the armor parameter, and it will be ignored during loading.

The block {value 17} will be ignored during loading.

All single-line comments are removed during loading. Do not use single-line comments in SDL files created and edited with game Editors.

With a double hash symbol ##, the game Editor creates marks in the SDL file for disabled blocks. During loading, blocks marked with a double hash are not ignored or deleted. They appear in the editor marked as disabled.

Example

{##health
   {max 17}
}

The commented-out block named health will appear as disabled in the Editor. The game will not consider the parameter values described in it. If necessary, you can enable the health block in the Editor, and the double hash symbol will be removed from the SDL file.

SDL assembly

Loading SDL files supports staged assembly of the final file. Using the package system, you can completely "override" the base file or supplement it.

Example

core\global\set\difficulty\normal.dl
main\global\set\difficulty\normal.dl

When the main package is connected, the content of the normal.dl file from the core package will be completely replaced by the content of the normal.dl from the main package.

Example

main\global\set\difficulty\mk10.def
special\global\set\difficulty\mk10+.def

When the special package is connected, the content of the mk10.def file from the main package will be supplemented by the content of the mk10+.def file from the special package.

A SDL file located on the wrong path can lead to a loading error or be ignored.

Debugging assembly

The game editor allows you to assemble the final version of the processed SDL file using the console command preprocess_sdl “path_to_file” for debugging purposes. The result of this command is available in the folder “...\Users<user>\AppData\Local\Men of War II\preprocess\”

Example

preprocess_sdl “/set/damage_report.set”

If you type the specified line in the Editor's Console, the SDL parser will compile a complete description for the damage_report.set file considering all its components and place it in the folder: <user>\AppData\Local\Men of War II\preprocess\

Instructions

An instruction is a repeating part of an SDL description, which is moved to a separate file or fragment for further calling in needed places of descriptions and settings.

Instructions are used for:

avoiding repetitions in descriptions of game components;
structuring descriptions;
globally modifying parameters and settings of game components depending on the game mode.

Instruction syntax

Instructions are called at the needed places in an SDL file. You can call the same instruction multiple times in needed places.

An instruction is indicated by a SDL fragment enclosed in parentheses.

The format for describing and calling an instruction depends on its type.

The instruction description contains the type name and name. The instruction name is enclosed in double quotes. Optionally, the instruction description can contain an SDL fragment. An instruction is called by its name.

Example

(define “example” [...])
...
("example")

The first line contains a description of a define-type instruction named "example". An SDL description fragment can be included as [...]. In empty instructions, the SDL fragment is absent. The third line contains a call to the instruction by its name

Example

(include "file.inc")

The instruction name corresponds to the name of the file whose content needs to be included at the instruction call site during the assembly of the final SDL

Instructions can be nested.

Example

(define "event3" 
    ("event1") 
    ("event2")
)

The instruction event3 calls the instructions event1 and event2.

Types of instructions

Name	Description
include	The instruction includes content of an SDL file in other files where needed. This allows structuring descriptions by topics and avoiding duplication of descriptions.
define	The instruction is used to create macros, which helps avoid duplication of descriptions or similar pieces of descriptions that only differ by parameter values.
mod	The instruction allows including/excluding part of the code or changing parameter values depending on the game mode.

Name

Description

include

The instruction includes content of an SDL file in other files where needed. This allows structuring descriptions by topics and avoiding duplication of descriptions.

define

The instruction is used to create macros, which helps avoid duplication of descriptions or similar pieces of descriptions that only differ by parameter values.

mod

The instruction allows including/excluding part of the code or changing parameter values depending on the game mode.

Arguments

Arguments are used to call the same instruction but with different parameter values. In the instruction description, an argument is indicated by the percent symbol %.

Arguments can be specified in two ways:

by ordinal number;
by variable name

Argument values can be numbers or sets of characters, such as variable names.

Arguments by ordinal number

When describing an instruction, you can use integers, starting from zero. When calling the instruction, use the word args and list the argument values strictly from 0 and in order.

Template for specifying arguments by ordinal number
%0 %1 %2

Template for specifying argument values by their ordinal number
args data%0 data%1 data%2

Example

(define "seismic" 
    {damage blast 
        {energy %1}
        {radius %0}
        {light %2}
    }
)
...
("seismic" args 10 8 3000)
...
("seismic" args 45 300 3000)

At the first call of the "seismic" instruction, the arguments take the following values: %0=10, %1=8, %2=3000 At the second call of the "seismic" instruction, the arguments take the values: %0=45, %1=300, %2=3000 The result of the "seismic" instruction call will be SDL, containing at the call sites the lines:

...
{damage blast 
     {energy 8}
     {radius 10} 
     {light 3000}
}
...
{damage blast 
     {energy 300}
     {radius 45} 
     {light 3000}
}

When calling an instruction with arguments specified by ordinal number, you must strictly observe the order of listing the arguments. Failing to follow the order leads to errors.

Named arguments

Variable names are used to describe named arguments.

Template for specifying named arguments
%name

Template for calling named arguments
name(data)

When calling an instruction with named arguments, the order of listing the arguments is not important.

Example

(define "seismic" 
    {damage blast 
        {energy %energy} 
        {radius %radius}
    }
)
...
("seismic" energy(10) radius(8))
...
("seismic" radius(300) energy(45))

The result of the "seismic" instruction call will be SDL, containing at the call sites the lines:

...
{damage blast 
     {energy 10}
     {radius 8} 
}
...
{damage blast 
     {energy 45}
     {radius 300}
}

It is important to ensure that arguments do not contain the names of other arguments passed above unless this is your intention.

Example

(instruction "example" sx(1) sy(3))

If there was a reference to the argument s before the call to the instruction example, then at the places of parameters sx and sy, the value of the parameter s will be set with the prefixes x and y. For example, if s=5, the arguments will take the values 5x and 5y.

PreviousPackage file structure NextInclude instruction

Last updated 5 months ago