[FAQ] Система настроек для модификаций (ModsPrefs)

[BattleFrame]

[FAQ] Система настроек для модификаций (ModsPrefs)
Начиная с версии 25.12 в клиент игры добавлена отдельная, изолированная система для хранения настроек модификаций.

---

Ранее  все модификации имеющие настройки, как правило, записывали их в файл preferences.xml в два блока: elementsGroupExpand и chatBoxWidth. В связи с этим после установки нескольких модов уже было сложно понять какой параметр к какому моду относится, а очистить настройки какого-либо мода вручную и вовсе становилось невыполнимой задачей, ведь малейшая проблема в файле приводила к полному сбросу всех настроек игры.
Отдельно стоит упомянуть про сохранение настроек из под модов и проблемы с правильным получением их из unbound2 вёрстки.

Система Mods Preferences:
Позволяет хранить настройки модификаций в отдельном файле, в отдельной коллекции DataHub и быстро обращаться к ним при помощи глобальных структур. Работает и управляется из Unbound2 вёрстки.

Состоит из:

• Файл mods_preferences.xml в корневом каталоге игры
• DataHub компонент CC.modsPrefs
• Структуры для получения данных (gui/unbound2/shared/mods.unbound)

Принцип работы:
На запуске игры считываются параметры, записанные в файле mods_preferences.xml и записываются в коллекцию DataHub. После чего становятся доступны для работы в вёрстке UB2.
При изменении параметров во время игры они изменяются только в DataHub, а обратно в файл mods_preferences.xml запишутся только при закрытии клиента.

Как работать с настройками:
Предположим мы решили добавить к нашей модификации настройки.

---

Инициализация мода (createModPrefs):

Скрытый текст

Первое, что нам необходимо сделать - это инициализировать мод в системе ModsPrefs.
Важно! Без инициализации система ничего не будет знать о вашем моде. Настройки не будут читаться и записываться.  
Выполняется инициализация при помощи внешнего вызова createModPrefs из вёрстки:

(bindcall externalCall 'inputMapping.onAction' "['createModPrefs',  MOD_SETTINGS_CONSTANT]" on='addedToStage')

MOD_SETTINGS_CONSTANT - это обыкновенная def constant с содержимым типа dict.

(def constant MOD_SETTINGS_CONSTANT "{
    modID: 'my_first_mod',
    prefs:{
        'minimap_size_x': 200,
        'minimap_size_y': 200,
        'draw_water': true,
        'minimap_title': 'Моя миникарта'
    }
}")

modID - Уникальный идентификатор вашего мода. Является обязательным параметром. Именно по нему вы будете обращаться к настройкам своего мода далее и именно так будет называться блок настроек вашего мода в mods_preferences.xml

prefs - dict с настройками вашего мода по-умолчанию. Может отсутствовать если таковые не требуются. При первой инициализации мода (когда его ещё нет в mods_preferences.xml) эти настройки запишутся как стандартные. Также эти настройки будут применены при использовании сброса настроек (подробнее про сброс дальше).

 

После выполнения createModPrefs данные записываются в компонент CC.modsPrefs, а также если мы закроем игру, то в файле mods_preferences.xml увидим следующее:

<mods_preferences.xml>
    <mod name="my_first_mod">
        <item name="draw_water" type="Boolean" value="true"/>
        <item name="minimap_size_x" type="Integer" value="200"/>
        <item name="minimap_size_y" type="Integer" value="200"/>
        <item name="minimap_title" type="String" value="Моя миникарта"/>
    </mod>
</mods_preferences.xml>

 

Установка значений настроек (setModPref):

Скрытый текст

 

Для установки нового значения настройки нам необходимо выполнить из вёрстки внешний вызов setModPref и передать ему dict с ключами: modID, name, value

(bindcall externalCall 'inputMapping.onAction' "['setModPref', {'modID': 'my_first_mod', 'name': 'mimimap_size_x', 'value': 1000}]" init=false watch=false (event "evMouseDown"))

modID - наш идентификатор мода, который мы указали при инициализации
name - имя настройки которую собираемся изменить
value - новое значение

(event "evMouseDown") - событие для срабатывания

 

При этом имя настройки может быть произвольным и не обязательно одним из указанных при инициализации.
Например, вы всё также можете создавать новые настройки из вёрстки или использовать id кораблей в настройках и все не существующие и заданные при помощи setModPref параметры будут созданы и сохранены.
При сохранении тип передаваемых данных определится автоматически.

 

Получение значений настроек:

Скрытый текст

 

Доступ к настройкам осуществляется путём получения таковых из коллекции DataHub.
Для упрощения данного этапа мы добавили 3 структуры. Находятся они в файле gui/unbound2/shared/mods.unbound.

• GET_MOD_PREF_BOOL - получить значение настройки с типом Boolean
• GET_MOD_PREF_NUMBER - получить значение настройки с типом Integer или Float
• GET_MOD_PREF_STRING - получить значение настройки с типом String

 

Тип значения с которым записана настройка можно узнать в файле в mods_preferences.xml

Пример:

(struct title = GET_MOD_PREF_STRING('my_first_mod' 'minimap_title'))
(struct sizeX = GET_MOD_PREF_NUMBER('my_first_mod' 'minimap_size_x'))
(struct sizeY = GET_MOD_PREF_NUMBER('my_first_mod' 'minimap_size_y'))

В данном случае мы получаем:

•  Сохранённое с типом String значение настройки minimap_title из модификации my_first_mod.
•  Сохранённые с типом Intriger значения настроек minimap_size_x и minimap_size_y из модификации my_first_mod.

Далее для вывода значений в вёрстке нам достаточно применять title.value, sizeX.value и sizeY.value соответственно.

 

Сложный путь для любителей добывать компоненты смостоятельно:

Скрытый текст

Получаем компонент самостоятельно из DataHub, передавая ID мода и имя переменной, разделённые символом _
В данном случае мы передаём my_first_mod_minimap_title, чтобы получить значение minimap_title из модификации my_first_mod

(var modsPrefsComponent:dhComponent = "getPrimaryComponent(CC.modsPrefs, 'my_first_mod_minimap_title')")
(var value:number = "toNumber(modsPrefsComponent.value.numValue)" (event "modsPrefsComponent.evValueChanged"))

 

 

Сброс значений настроек (clearModPref):

Скрытый текст

 

Вызов clearModPref позволит полностью удалить настройку из DataHub и файла настроек.
Важно! Стоит применять только для настроек, которые небыли указаны при инициализации т.к. при повторном выполнении createModPrefs они запишутся снова.  

Функция будет полезна в случае если, допустим, вы добавили в мод возможность настраивать что-то для каждого корабля индивидуально, и имя настройки содержит ID корабля (например, hide_ship_12345). Со временем таких уникальных настроек может накопиться очень много. Эта функция поможет вам подчищать их вместо установки false или пустого значения, тем самым не увеличивая размер файла пользователя.

 

Использование аналогично setModPref, за исключением того что value задавать не нужно:

(bindcall externalCall 'inputMapping.onAction' "['clearModPref', {'modID': 'my_first_mod', 'name': 'mimimap_size_x'}]" init=false watch=false (event "evMouseDown"))

 

Установка настроек мода по-умолчанию (resetModPrefs):

Скрытый текст

 

В случае если при инициализации был (createModPrefs) указан dict с настройками мода по-умолчанию, то вы можете использовать полный сброс настроек мода при помощи функции resetModPrefs.

(bindcall externalCall 'inputMapping.onAction' "['resetModPrefs',  MOD_SETTINGS_CONSTANT]" init=false watch=false (event "evMouseDown"))

Где MOD_SETTINGS_CONSTANT - это та же самая константа, что использовалась в вызове createModPrefs
При выполнении resetModPrefs все настройки модификации будут обнулены, а в DataHub и xml будут записаны исходные значения из MOD_SETTINGS_CONSTANT.prefs