> For the complete documentation index, see [llms.txt](https://docs.bestway.com.ua/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bestway.com.ua/gem-rts-v1-ru/bazovaya-informaciya-o-resursakh-v-gem-rts/obshaya-informaciya-o-konfiguracionnykh-failakh.md).

# Общая информация о конфигурационных файлах

Раздел содержит основные принципы описания игровых компонентов

## SDL файлы

SDL (structure definition language) - общий формат конфигурационных файлов, используемых игровым движком Gem RTS.

{% hint style="info" %}
SDL-файлы Gem RTS не имеют ничего общего с языком графического моделирования и файлами SDL из Visual Studio от Microsoft
{% endhint %}

SDL-файлы применяются для описания большинства компонентов игры.

Примеры использования:

* описания игровых объектов;
* описания элементов интерфейса;
* настройки юнитов;
* настройки режимов игры;
* файлы игровых уровней (карт);
* описания логики миссий;
* описания спецэффектов (VFX) и звуковых эффектов (SFX);
* описания свойств и поведения юнитов;
* описания анимаций;
* ...

SDL-файлы - текстовые документы, сохраненные в кодировке utf-8.\
Файлы можно просматривать и редактировать с помощью любого текстового редактора, такого как Sublime, Notepad++, Vim и другие.

Для ряда SDL-файлов в приложении Editor предусмотрены отдельные редакторы (смотрите раздел документации [РЕДАКТОР](/gem-rts-v1-ru/redaktor.md)). Такие файлы необходимо создавать и редактировать с помощью соответствующего редактора, а прибегать к использованию текстового редактора в случае крайней необходимости.

## Правила именования SDL-файлов

SDL-файлы могут иметь разные расширения, но при этом всегда имеют общий синтаксис.\
Наиболее распространненые расширения SDL файлов представлены в таблице.

<table><thead><tr><th width="153">Расширение</th><th>Описание содержимого файла</th></tr></thead><tbody><tr><td><strong>.def</strong></td><td>Описания игровых объектов</td></tr><tr><td><strong>.ext</strong></td><td>Дополнительные описания объектов</td></tr><tr><td><strong>.set</strong></td><td>Описания компонент игры и настройки параметров</td></tr><tr><td><strong>.inc</strong></td><td>Используются для структурирования описаний и выноса общих описаний для групп компонентов. Содержимое .inc файлов вставляется парсером движка в итоговый SDL в тех местах, откуда вызывается файл .inc</td></tr><tr><td><strong>.info</strong></td><td>Настройки компонент игры</td></tr><tr><td><strong>.mi</strong></td><td>Описания логики миссии</td></tr></tbody></table>

## Расположение SDL-файлов

Расположение SDL-файлов зависит от того, какой компонент игры в нем описан.\
От расположения файла зависит формат и структура описания.

{% hint style="warning" %}
Большинство файлов должны находиться в строго определенной папке или иметь конкретное название
{% endhint %}

{% hint style="info" %}
Более подробно принцип размещения файлов рассматривается в статье [Архитектура ресурсов игры](/gem-rts-v1-ru/modeli/nastroika-modeli-doma/opisanie-ierarkhii-struktury-modeli-doma.md)
{% endhint %}

## Содержимое SDL-файлов

Содержимое SDL-файла зависит от того, какой компонент игры в нем описывается.

<table><thead><tr><th width="364">Файлы</th><th>Пояснение</th></tr></thead><tbody><tr><td>...\scene\<strong>set\interaction_entity</strong>\<mark style="color:green;">human.inc</mark><br><br>...\scene\<strong>set\target</strong><mark style="color:green;">\human.inc</mark><br><br>...\scene\<strong>properties\selection</strong>\<mark style="color:green;">human.inc</mark></td><td>SDL-файлы имеют одинаковое имя и расширение, но содержат разный формат описания, зависящий от расположения файла в структуре ресурсов игры</td></tr><tr><td>Любой файл из папки<br>...\scene\set\environment</td><td>SDL-файлы из папки environment описывают один и тот же компонент игры: погоду и визуальные эффекты окружения.<br>Имеют одинаковый формат описания параметров и настроек эффектов. Содержимое файлов из папки environment отличается лишь значениями параметров погоды, названиями эффектов и текстур</td></tr></tbody></table>

## Синтаксис

Структура SDL-файла формируется из блоков.\
Минимальная единица блока - строка, которая заключена в **фигурные скобки** и содержит **имя** **параметра**.

{% hint style="danger" %}
Каждый блок SDL должен иметь открывающую и закрывающую **фигурную скобку**. Потеря скобки влечет за собой критические ошибки в работе игры.
{% endhint %}

Опционально блок может содержать одно или несколько значений параметра.\
В качестве значения параметра может быть число или имя переменной. Имена переменных, содержащие пробел, записываются в двойных кавычках.

> **Формат записи блока SDL:**
>
> `{parameter [data]}`

<details>

<summary>Примеры блоков SDL</summary>

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

</details>

Если значений несколько, то они перечисляются через пробелы.

<details>

<summary>Пример блока SDL c несколькими значениями параметра</summary>

```
{actor m2 m3 “oficer t34”}
```

*Параметр **actor** имеет три значения: m2, m3 и "oficer t34"*

</details>

Блоки могут быть вложенными.\
Табуляции и переводы строк необязательны, но рекомендуются для облегчения восприятия описаний.

<details>

<summary>Пример вложенных блоков</summary>

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

</details>

### Условия

SDL-файлы, в которых прописываются настройки компонент игры, могут содержать условия для вызова или установки параметров.

> **Формат записи условия**
>
> ```
> {if condition [data]}
> ```
>
> *condition - условие;*\
> *\[data] - значение параметра, если требуется*

Условия также могут быть вложенными.\
Условия перебираются последовательно. Будет выбрано значение параметра из первого сработавшего условия.

<details>

<summary>Пример вложенных условий</summary>

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

*Параметр **vision** по умолчанию имеет значение **1**.*\
*Если юнит типа human, то параметру **vision** будет установлено значение **0.2**.*\
*Если включен режим мультиплеера и юнит типа human принадлежит команде "а", то параметр **vision** примет значение **0.5**.*\
*Если условие "human" не сработало и юнит имеет тег "xxx", то параметр **vision** примет значение **0.8**.*

</details>

### Комментарии

С помощью символа точки с запятой можно сделать однострочный комментарий.\
Все, что написано в строке после точки с запятой будет проигнорировано движком при загрузке.

<details>

<summary>Пример однострочного комментария</summary>

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

*Фраза "unit defence" является однострочным комментарием к параметру armor,*\
*и будет проигнорирована при загрузке*\
\&#xNAN;*Блок* `{value 17}` *будет проигнорирован при загрузке*

</details>

{% hint style="warning" %}
Все однострочные комментарии удаляются при загрузке.\
Не используйте однострочные комментарии в SDL-файлах, которые создаются и редактируются с помощью Редакторов игры
{% endhint %}

С помощью символа двойной решетки **##** Редактор игры создает в файле SDL пометки отключенных блоков. При загрузке блоки, отмеченные двойной решеткой, не игнорируются и не удаляются. Отображаются в редакторе с пометкой, что блок отключен.

<details>

<summary>Пример закомментированного блока</summary>

```
{##health
   {max 17}
}
```

*Закомментированный блок с именем **health** будет отображаться в Редакторе как отключенный. Игра не будет учитывать значения параметров, которые в нем описаны.*\
*При необходимости блок **health** можно включить в Редакторе, при этом в SDL файле символ двойной решетки будет удален*

</details>

## Сборка SDL

Загрузка SDL-файлов поддерживает поэтапную сборку итогового файла.\
С помощью системы пакетов можно как полностью “перекрыть” базовый файл, так и дополнить его.

<details>

<summary>Пример замены файла</summary>

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

*При подключении Пакета **main** содержимое файла **normal.dl** из Пакета **core** будет полностью заменено на содержимое **normal.dl** из Пакета **main***

</details>

<details>

<summary>Пример дополнения файл</summary>

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

*При подключении Пакета **special** содержимое файла **mk10.def** из Пакета **main** будет дополнено содержимым файла **mk10+.def** из Пакета **special***

</details>

{% hint style="danger" %}
SDL-файл расположенный по неправильному пути может привести к ошибке при загрузке или быть проигнорированным
{% endhint %}

### Отладка сборки

В редакторе игры предусмотрена возможность собрать финальный вариант обработанного SDL-файла с помощью консольной команды **preprocess\_sdl “path\_to\_file”** для целей отладки.\
Результат выполнения данной команды будет доступен в папке\
“...**\Users\\\<user>\AppData\Local\Men of War II\preprocess\\**”

<details>

<summary>Пример использования команды</summary>

```
preprocess_sdl “/set/damage_report.set”
```

*Если в Консоли Редактора набрать указанную строчку, то парсер SDL соберет целостное описание для файла damage\_report.set с учетом всех его составляющих и поместит его в папку:*\
*...\\\<user>\AppData\Local\Men of War II\preprocess\\*

</details>

## Инструкции

**Инструкция** - повторяющаяся часть SDL описания, которая выносится в отдельный файл или фрагмент для дальнейшего вызова в нужных местах описаний и настроек.

Инструкции используются для:

* избежания повторений в описаниях компонентов игры;
* структурирования описаний;
* глобальной модификации параметров и настроек компонент игры в зависимости от режима игры

### Синтаксис инструкций

Вызов инструкций происходит в нужных местах SDL файла.\
Вызов одной и той же инструкции можно осуществлять многократно в нужных местах.

Признаком инструкции является фрагмент SDL, заключенный в **круглые скобки**.

{% hint style="info" %}
Формат описания и вызова инструкции зависит от ее [вида](#vidy-instrukcii).
{% endhint %}

Описание инструкции содержит название ее вида и имя.\
Имя инструкции заключается в двойные кавычки.\
Опционально описание инструкции может содержать фрагмент SDL.\
Вызов инструкции происходит по ее имени.

<details>

<summary>Пример описания и вызова инструкции</summary>

{% code lineNumbers="true" %}

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

{% endcode %}

*Первая строка содержит описание инструкции вида define с именем "*&#x65;xample"*.*\
*В качестве* `[...]` *может быть фрагмент SDL описания. В пустых инструкциях фрагмент SDL отсутствует.*\
*Третья строка содержит вызов инструкции по ее имени*

</details>

<details>

<summary>Пример вызова инструкции</summary>

```
(include "file.inc")
```

*Имя инструкции соответствует имени файла, содержимое которого необходимо включить в месте вызова инструкции при сборке итогового SDL .*

</details>

Инструкции могут быть вложенными.

<details>

<summary>Пример описания вложенной инструкции</summary>

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

*Инструкция **event3** вызывает инструкции **event1** и **event2***

</details>

### Виды Инструкций

<table><thead><tr><th width="179">Название</th><th>Описание</th></tr></thead><tbody><tr><td><a href="/gem-rts-v1-ru/bazovaya-informaciya-o-resursakh-v-gem-rts/obshaya-informaciya-o-konfiguracionnykh-failakh/instrukciya-include.md">include</a></td><td>Инструкция включает содержимое SDL файла в другие файлы, где это нужно. Это позволяет структурировать описания по темам и избегать дублирования описаний</td></tr><tr><td><a href="/gem-rts-v1-ru/bazovaya-informaciya-o-resursakh-v-gem-rts/obshaya-informaciya-o-konfiguracionnykh-failakh/instrukciya-define.md">define</a></td><td>Инструкция используется для создания макросов, что позволяет избежать дублирования описаний или однотипных кусков описаний, которые отличаются только значениями параметров</td></tr><tr><td><a href="/gem-rts-v1-ru/bazovaya-informaciya-o-resursakh-v-gem-rts/obshaya-informaciya-o-konfiguracionnykh-failakh/instrukciya-mod.md">mod</a></td><td>Инструкция позволяет включать/исключать часть кода или менять значения параметров в зависимости от режима игры</td></tr></tbody></table>

### Аргументы

Аргументы используются для вызова одной и той же инструкции, но с разными значениями параметров. При описании инструкции признаком аргумента является символ процент **%.**

Аргументы можно задавать двумя способами:

* порядковым номером;
* именем переменной

В качестве значений аргументов могут быть как числа, так и наборы символов, например, имена переменных.

#### Аргументы в виде порядковых номеров

При описании инструкции в качестве аргументов можно использовать целые числа, начиная с нуля.\
При вызове инструкции используется слово args и перечисление значений аргументов строго от 0 и по порядку.

> **Формат задания аргументов с порядковым номером**
>
> `%0 %1 %2`

> **Формат задания значений аргументов с порядковым номером**
>
> `args data%0 data%1 data%2`

<details>

<summary>Пример аргументов с порядковым номером</summary>

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

*При первом вызове Инструкции "seismic" аргументы принимают следующие значения:*\
*%0=10, %1=8, %2=3000*

*При втором вызове Инструкции "seismic" аргументы принимают значения:*\
*%0=45, %1=300, %2=3000*\
\
*Итогом вызова Инструкции "seismic" будет SDL, содержащий в местах вызова строки:*

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

</details>

{% hint style="danger" %}
При вызове инструкции с аргументами, заданными порядковым номером, необходимо строго соблюдать порядок перечисления аргументов.\
Несоблюдение порядка приведет к ошибкам.
{% endhint %}

#### Именные аргументы

Для описания именных аргументов используются имена переменных.

> **Формат задания именных аргументов**
>
> `%name`

> **Формат вызова именных переменных**
>
> `name(data)`

При вызове Инструкции с именными аргументами порядок перечисления аргументов не важен.

<details>

<summary>Пример инструкции c именными аргументами</summary>

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

*Итогом вызова инструкции "seismic" будет SDL, содержащий в местах вызова строки:*

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

</details>

{% hint style="warning" %}
Важно следить за тем, чтобы аргументы не содержали названия других аргументов, передаваемых выше, если только это не является вашей задумкой.
{% endhint %}

<details>

<summary>Пример использования составных имен аргументов</summary>

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

*Если до вызова инструкции* **example** *было обращение к аргументу **s**, то на месте параметров **sx** и **sy** будет заданное значение параметра **s** c приставками **x** и **y.***\
\
\&#xNAN;*Например, если s=5, то аргументы примут значение 5x и 5y*

</details>

***

## Заключение

Овладение структурой и синтаксисом SDL-файлов открывает широкие возможности для кастомизации и улучшения игрового опыта. Понимание аспектов написания конфигурационных файлов позволяет вносить уникальные изменения, делая игру более интересной и отвечающей новым вызовам. Творчество и внимание к деталям станут основой для создания качественных и инновационных изменений игрового процесса и правил, приводя к созданию новых незабываемых сюжетов.

Подробнее узнать о работе с Инструкциями:

<table data-view="cards"><thead><tr><th data-type="content-ref"></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><a href="/gem-rts-v1-ru/bazovaya-informaciya-o-resursakh-v-gem-rts/obshaya-informaciya-o-konfiguracionnykh-failakh/instrukciya-include.md">Инструкция include</a></td><td><a href="https://2052154247-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx2fkAZ6oKGGdByFhKPpa%2Fuploads%2FrCk1dAvSKKe04Fp9WkP4%2Fsplash_editor_3.jpg?alt=media&amp;token=a89d5e03-56d3-401d-b04b-8da366458bd9">cover picture default</a></td></tr><tr><td><a href="/gem-rts-v1-ru/bazovaya-informaciya-o-resursakh-v-gem-rts/obshaya-informaciya-o-konfiguracionnykh-failakh/instrukciya-define.md">Инструкция define</a></td><td><a href="https://2052154247-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx2fkAZ6oKGGdByFhKPpa%2Fuploads%2FrCk1dAvSKKe04Fp9WkP4%2Fsplash_editor_3.jpg?alt=media&amp;token=a89d5e03-56d3-401d-b04b-8da366458bd9">cover picture default</a></td></tr><tr><td><a href="/gem-rts-v1-ru/bazovaya-informaciya-o-resursakh-v-gem-rts/obshaya-informaciya-o-konfiguracionnykh-failakh/instrukciya-mod.md">Инструкция mod</a></td><td><a href="https://2052154247-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx2fkAZ6oKGGdByFhKPpa%2Fuploads%2FrCk1dAvSKKe04Fp9WkP4%2Fsplash_editor_3.jpg?alt=media&amp;token=a89d5e03-56d3-401d-b04b-8da366458bd9">cover picture default</a></td></tr></tbody></table>

Более подробную информацию о работе с конфигурационными файлами можно найти в следующих разделах.

<table data-view="cards"><thead><tr><th data-type="content-ref"></th><th></th><th></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><a href="/gem-rts-v1-ru/sozdanie-modov-k-igre.md">РАЗРАБОТКА МОДОВ</a></td><td>Создание модов: руководство и советы</td><td>Этот раздел поможет разобраться с основами и продвинутыми аспектами создания модов для Gem RTS.<br>Следование пошаговым инструкциям поможет настроить рабочие пакеты, активировать их в игре, портировать карты из других игр серии Men of War, а также осуществить расширенную настройку мода и внедрить новые правила игры.</td><td><a href="https://2052154247-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx2fkAZ6oKGGdByFhKPpa%2Fuploads%2FrCk1dAvSKKe04Fp9WkP4%2Fsplash_editor_3.jpg?alt=media&amp;token=a89d5e03-56d3-401d-b04b-8da366458bd9">cover picture default</a></td></tr><tr><td><a href="/gem-rts-v1-ru/redaktor.md">РЕДАКТОР</a></td><td>Редактор карт: основы и возможности.</td><td>Раздел поможет освоить основные и продвинутые аспекты работы с Редактором Gem RTS.<br>Подробные инструкции помогут изучить создание и настройку различных элементов игровых уровней, открывая возможности для воплощения новых игровых сюжетов и событий.</td><td><a href="https://2052154247-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx2fkAZ6oKGGdByFhKPpa%2Fuploads%2FrCk1dAvSKKe04Fp9WkP4%2Fsplash_editor_3.jpg?alt=media&amp;token=a89d5e03-56d3-401d-b04b-8da366458bd9">cover picture default</a></td></tr><tr><td><a href="/gem-rts-v1-ru/nastroiki-igrovykh-parametrov.md">Работа с конфигурационными файлами</a></td><td>Настройка игровых параметров: руководство и советы</td><td>Раздел поможет понять основы и углубиться в настройку игровых параметров Gem RTS. Вооружившись знаниями раздела, можно настроить режимы передвижения юнитов, бронепробиваемость, модификаторы сложности и другие важные аспекты игры, создавая возможности для нового игрового опыта.</td><td><a href="https://2052154247-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx2fkAZ6oKGGdByFhKPpa%2Fuploads%2FrCk1dAvSKKe04Fp9WkP4%2Fsplash_editor_3.jpg?alt=media&amp;token=a89d5e03-56d3-401d-b04b-8da366458bd9">cover picture default</a></td></tr></tbody></table>