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

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

SDL файлы

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

SDL-файлы Gem RTS не имеют ничего общего с языком графического моделирования и файлами SDL из Visual Studio от Microsoft

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

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

  • описания игровых объектов;

  • описания элементов интерфейса;

  • настройки юнитов;

  • настройки режимов игры;

  • файлы игровых уровней (карт);

  • описания логики миссий;

  • описания спецэффектов (VFX) и звуковых эффектов (SFX);

  • описания свойств и поведения юнитов;

  • описания анимаций;

  • ...

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

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

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

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

Расширение
Описание содержимого файла

.def

Описания игровых объектов

.ext

Дополнительные описания объектов

.set

Описания компонент игры и настройки параметров

.inc

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

.info

Настройки компонент игры

.mi

Описания логики миссии

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

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

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

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

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

Файлы
Пояснение

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

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

Любой файл из папки ...\scene\set\environment

SDL-файлы из папки environment описывают один и тот же компонент игры: погоду и визуальные эффекты окружения. Имеют одинаковый формат описания параметров и настроек эффектов. Содержимое файлов из папки environment отличается лишь значениями параметров погоды, названиями эффектов и текстур

Синтаксис

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

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

Формат записи блока SDL:

{parameter [data]}

Примеры блоков SDL
{actor}
{health 1000}
{tag "oficer t34"}

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

Пример блока SDL c несколькими значениями параметра
{actor m2 m3 “oficer t34”}

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

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

Пример вложенных блоков
{rules
    {“vehicle”
       {“actor” “m2”
          {“icon” “m2_icon”}
       }
    }
}

Условия

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

Формат записи условия

{if condition [data]}

condition - условие; [data] - значение параметра, если требуется

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

Пример вложенных условий
{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.

Комментарии

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

Пример однострочного комментария
{armor ; unit defence
;    {value 17}
     {value 5}
}

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

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

Пример закомментированного блока
{##health
   {max 17}
}

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

Сборка SDL

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

Пример замены файла
  • core\global\set\difficulty\normal.dl

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

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

Пример дополнения файл
  • main\global\set\difficulty\mk10.def

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

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

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

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

Пример использования команды
preprocess_sdl “/set/damage_report.set”

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

Инструкции

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

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

  • избежания повторений в описаниях компонентов игры;

  • структурирования описаний;

  • глобальной модификации параметров и настроек компонент игры в зависимости от режима игры

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

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

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

Формат описания и вызова инструкции зависит от ее вида.

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

Пример описания и вызова инструкции
(define “example” [...])
...
("example")

Первая строка содержит описание инструкции вида define с именем "example". В качестве [...] может быть фрагмент SDL описания. В пустых инструкциях фрагмент SDL отсутствует. Третья строка содержит вызов инструкции по ее имени

Пример вызова инструкции
(include "file.inc")

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

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

Пример описания вложенной инструкции
(define "event3" ("event1") ("event2"))

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

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

Название
Описание

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

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

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

Аргументы

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

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

  • порядковым номером;

  • именем переменной

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

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

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

Формат задания аргументов с порядковым номером

%0 %1 %2

Формат задания значений аргументов с порядковым номером

args data%0 data%1 data%2

Пример аргументов с порядковым номером
(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}
}

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

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

Формат задания именных аргументов

%name

Формат вызова именных переменных

name(data)

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

Пример инструкции c именными аргументами
(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}
}
Пример использования составных имен аргументов
(instruction "example" sx(1) sy(3))

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


Заключение

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

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

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

Cover

Создание модов: руководство и советы

Этот раздел поможет разобраться с основами и продвинутыми аспектами создания модов для Gem RTS. Следование пошаговым инструкциям поможет настроить рабочие пакеты, активировать их в игре, портировать карты из других игр серии Men of War, а также осуществить расширенную настройку мода и внедрить новые правила игры.

Cover

Редактор карт: основы и возможности.

Раздел поможет освоить основные и продвинутые аспекты работы с Редактором Gem RTS. Подробные инструкции помогут изучить создание и настройку различных элементов игровых уровней, открывая возможности для воплощения новых игровых сюжетов и событий.

Cover

Настройка игровых параметров: руководство и советы

Раздел поможет понять основы и углубиться в настройку игровых параметров Gem RTS. Вооружившись знаниями раздела, можно настроить режимы передвижения юнитов, бронепробиваемость, модификаторы сложности и другие важные аспекты игры, создавая возможности для нового игрового опыта.

Last updated