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

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

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 должен иметь открывающую и закрывающую фигурную скобку. Потеря скобки влечет за собой критические ошибки в работе игры.

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

Формат записи блока 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-файлах, которые создаются и редактируются с помощью Редакторов игры

С помощью символа двойной решетки ## Редактор игры создает в файле 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-файл расположенный по неправильному пути может привести к ошибке при загрузке или быть проигнорированным

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

В редакторе игры предусмотрена возможность собрать финальный вариант обработанного 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

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

Название

Описание

include

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

define

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

mod

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

Аргументы

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

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

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

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

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

При описании инструкции в качестве аргументов можно использовать целые числа, начиная с нуля. При вызове инструкции используется слово 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-файлов открывает широкие возможности для кастомизации и улучшения игрового опыта. Понимание аспектов написания конфигурационных файлов позволяет вносить уникальные изменения, делая игру более интересной и отвечающей новым вызовам. Творчество и внимание к деталям станут основой для создания качественных и инновационных изменений игрового процесса и правил, приводя к созданию новых незабываемых сюжетов.

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

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

Last updated 6 months ago

SDL файлы

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

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

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

Синтаксис

Условия

Комментарии

Сборка SDL

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

Инструкции

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

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

Аргументы

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

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

Заключение