Введение
Текстурный атлас - изображение, содержащее набор (или «атлас») под-изображений (спрайтов), каждое из которых является текстурой для некоторого 2D или 3D объекта), которые в основном используются в пользовательском интерфейсе игры. 

Эта документация пройдет следующие этапы:

• Добавление новых спрайтов (sprites).
• Создание текстурных атласов (sprite sheets) из добавленных вами спрайтов.
• Импорт текстурных атласов в ваш модуль.
• Использование спрайтов в XML-файлах пользовательского интерфейса.
• Загрузка и выгрузка категорий спрайтов.

Предпосылки

• Создайте модуль в ПУТЬ УСТАНОВКИ\Mount & Blade II Bannerlord\Modules
• Знание того, как создать свой проект в интегрированной среде разработки (IDE), такой как Visual Studio.
• Mount & Blade II: Bannerlord - Modding Kit - загружается из Steam.

Добавление спрайтов

• Создайте новую папку с именем GUI в разделе Modules\ИМЯ_ВАШЕГО_МОДА.
• Создайте новую папку с именем SpriteParts во вновь созданной папке GUI.
• Создайте новую папку с именем ui_{ИМЯ_ВАШЕЙ_КАТЕГОРИИ} во вновь созданной папке SpriteParts. В этой документации он будет называться ui_mycategory.
• Примечание. Контент внутри ui_{ИМЯ_ВАШЕЙ_КАТЕГОРИИ} будет помещен в одну категорию с названием "ИМЯ_ВАШЕЙ_КАТЕГОРИИ". Все спрайты в категории загружаются и выгружаются вместе. Рекомендуется разделить спрайты на категории (вместо того, чтобы иметь только одну категорию), чтобы избежать загрузки ненужных спрайтов. Например, вы можете создать новый экран в игре, который требует загрузки определенных спрайтов. Эти спрайты можно объединить в категорию, и после открытия экрана загрузить только соответствующие спрайты, а после закрытия экрана выгрузить их (см. раздел «Загрузка и выгрузка категорий спрайтов»).
• Поместите свои спрайты в папку ui_{ИМЯ_ВАШЕЙ_КАТЕГОРИИ}. Например, этот спрайт добавлен и назван mysprite.png:
• Для лаунчера новые спрайты должны быть добавлены в категорию под MODULE_NAME\LauncherGUI\SpriteParts.

Создание текстурных атласов 
Чтобы сгенерировать текстурный атлас, запустите исполняемый файл TaleWorlds.TwoDimension.SpriteSheetGenerator.exe, расположенный по адресу ПУТЬ_УСТАНОВКИ\Mount & Blade II Bannerlord\bin\Win64_Shipping_wEditor. Если вы выполнили описанные выше шаги, после запуска SpriteSheetGenerator.exe вы должны увидеть следующее окно:

SpriteSheetGenerator.exe создаст две папки с именами Assets и AssetSources в папке Modules\ИМЯ_ВАШЕГО_МОДА. Он также создаст файл SpriteData.xml (с префиксом имени вашего модуля) в папке Modules\ИМЯ_ВАШЕГО_МОДА\GUI.

• Если вы создаете текстурный атлас для программы запуска, используйте сценарий Update Launcher SpriteSheets.bat в папке LauncherGUI.

Импорт созданных текстурных атласов 
Чтобы использовать спрайты в своих текстурных атласах, необходимо также импортировать их из браузера ресурсов. Обратите внимание, что этот шаг можно пропустить, если вы добавляете спрайты только для Launcher.
Выполните следующие действия, чтобы импортировать текстурный атлас:

• Убедитесь, что вы встроили свой проект в Modules\ИМЯ_ВАШЕГО_МОДА\bin\Win64_Shipping_wEditor (в дополнение к Win64_Shipping_Client). Если ваш проект построен неправильно, вы получите сбой при запуске.
• Запустите Mount & Blade II: Bannerlord - Modding Kite из Steam.
• Убедитесь, что ваш мод выбран в разделе «Моды» панели запуска, затем нажмите «Играть».
• В главном меню нажмите "Alt + `", чтобы открыть консоль.
• Введите resource.show_resource_browser и нажмите Enter.

Это должно открыть браузер ресурсов:

Сверните папку Native слева от браузера ресурсов, чтобы легко увидеть свой модуль. Затем выберите свой модуль.

Откройте папку GauntletUI в вашем модуле. Затем нажмите кнопку «Сканировать новые файлы ресурсов», на которую указывает красная стрелка внизу (стрелка справа).

Это должно открыть новое окно:

Убедитесь, что выбрана ваша категория (в примере это ui_mycategory), затем нажмите кнопку «Импорт». Затем вы должны увидеть что-то похожее на это:

Закройте браузер ресурсов и игру. Теперь вы должны увидеть новый файл с именем ui_{ИМЯ_ВАШЕЙ_КАТЕГОРИИ}_1_tex.tpac в разделе Modules\ИМЯ_ВАШЕГО_МОДА\Assets\GauntletUI.

Использование спрайтов в XML-файлах пользовательского интерфейса
Теперь вы можете использовать спрайты в созданных вами текстурных атласах (вам также необходимо загрузить соответствующую категорию, которая описана ниже, в разделе «Загрузка и выгрузка категорий спрайтов»). Спрайты используются в XML-файлах пользовательского интерфейса. Вы можете обращаться к своим спрайтам по их именам. Вы можете найти имена ваших спрайтов в файле SpriteData.xml (с префиксом имени вашего модуля), который находится в Modules\ИМЯ_ВАШЕГО_МОДА\GUI. В качестве примера мы создадим новый XML-файл пользовательского интерфейса. Для этого вернитесь в папку с именем GUI в разделе Modules\ИМЯ_ВАШЕГО_МОДА\ и создайте новую папку с именем Prefabs. Создайте новый файл с именем MyXml.xml в папке Prefabs. Теперь вы можете обращаться к своим спрайтам в этом файле как Sprite="mysprite". Например, содержимое файла MyXml.xml может быть следующим:

<Prefab>
    <Window>
        <Widget DoNotAcceptEvents="true" DoNotPassEventsToChildren="true" WidthSizePolicy="StretchToParent" HeightSizePolicy="StretchToParent">
            <Children>
                <ImageWidget WidthSizePolicy="Fixed" HeightSizePolicy="Fixed" SuggestedWidth="128" SuggestedHeight="128" HorizontalAlignment="Center" VerticalAlignment="Center" Sprite="mysprite"/>
            </Children>
        </Widget>
    </Window>
</Prefab>

Загрузка и выгрузка категорий спрайтов
Чтобы использовать добавленные вами спрайты, вам необходимо их загрузить. Тут у вас есть два варианта:¸

1. Загрузка и выгрузка вручную
   • У разработчика больше контроля. Они могут выбирать, когда категории спрайтов загружаются и выгружаются. Таким образом, они могут управлять использованием памяти и производительностью.
   • Требует написания кода. Таким образом, более сложный, чем вариант AlwaysLoad.
2. Использование опции AlwaysLoad
   • Категории спрайтов загружаются при запуске автоматически.
   • Категории сохраняются в памяти до закрытия игры. Таким образом, нет необходимости вручную загружать их каждый раз, когда они используются.
   • Уменьшено время загрузки пользовательского интерфейса за счет увеличения использования памяти.
   • Легко использовать.

1. Загрузка и выгрузка вручную
Здесь мы покажем, как загружать и выгружать категории спрайтов вручную. В приведенном ниже примере мы переопределяем методы OnGameStart и OnGameEnd класса MBSubModuleBase для добавления и удаления глобального слоя MyScreen соответственно. Обратите внимание, что конструктор MyScreen загружает категорию спрайтов и XML пользовательского интерфейса, которые мы создали в предыдущих разделах. Мы также выгружаем категорию спрайтов внутри метода OnFinalize.
Если вы собираетесь скопировать приведенный ниже код, не забудьте изменить пространство имен и имя функции Main. Они должны совпадать с полями в вашем SubModule.xml. Другими словами, вы должны изменить SpritesheetDocumentation (пространство имен) на ИМЯ_ВАШЕГО_МОДА и Main (имя функции Main) на YOUR_MAIN_FUNCTION_NAME в этом поле SubModule.xml:

<SubModuleClassType value="YOUR_MODULE_NAME.YOUR_MAIN_FUNCTION_NAME"/>

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

using TaleWorlds.Core;
using TaleWorlds.MountAndBlade;
using TaleWorlds.Engine.Screens;
using TaleWorlds.Engine.GauntletUI;
using TaleWorlds.GauntletUI.Data;
using TaleWorlds.TwoDimension;

namespace SpritesheetDocumentation
{
    public class Main : MBSubModuleBase
    {
        private MyScreen _myScreen;

        protected override void OnSubModuleLoad()
        {

        }

        protected override void OnGameStart(Game game, IGameStarter gameStarterObject)
        {
            base.OnGameStart(game, gameStarterObject);
            _myScreen = new MyScreen();
            ScreenManager.AddGlobalLayer(_myScreen, true); // add MyScreen on game start
        }

        public override void OnGameEnd(Game game)
        {
            base.OnGameEnd(game);
            _myScreen.OnFinalize();
            ScreenManager.RemoveGlobalLayer(_myScreen); // remove MyScreen on game end
        }
    }

    public class MyScreen : GlobalLayer
    {
        private GauntletLayer _gauntletLayer;
        private IGauntletMovie _gauntletMovie;
        private SpriteCategory _category;

        public MyScreen()
        {
            var spriteData = UIResourceManager.SpriteData;
            var resourceContext = UIResourceManager.ResourceContext;
            var resourceDepot = UIResourceManager.UIResourceDepot;

            _category = spriteData.SpriteCategories["ui_mycategory"]; // select which category to load, put your category name here
            _category.Load(resourceContext, resourceDepot); // load the selected category

            _gauntletLayer = new GauntletLayer(2);
            Layer = (ScreenLayer)_gauntletLayer;

            _gauntletMovie = _gauntletLayer.LoadMovie("MyXml", null); // load the ui xml in Prefabs folder
        }

        public void OnFinalize()
        {
            // unload ui xml, sprite category, layer, etc.
            _gauntletMovie = null;
            _category.Unload();
            _gauntletLayer = null;
        }
    }
}

2. Использование опции AlwaysLoad (Всегда загружать)
Вместо ручной загрузки категорий спрайтов, как в разделе «Загрузка и выгрузка вручную», вы можете выбрать, какие категории спрайтов должны загружаться автоматически при запуске, включив параметр «Всегда загружать» (AlwaysLoad) для этих категорий. Если разработчик не выгружает их вручную, категории с включенной опцией AlwaysLoad будут храниться в памяти до тех пор, пока игра не будет закрыта, чтобы вам не приходилось загружать их вручную каждый раз, когда они используются. Включение параметра AlwaysLoad уменьшает время загрузки пользовательского интерфейса (поскольку эти категории загружаются только один раз при запуске), но увеличивает использование памяти (поскольку эти категории будут храниться в памяти, даже если они не используются). Эта опция очень полезна для категорий, которые часто загружаются и выгружаются (например, категория, которая используется на экране, который часто открывается и закрывается).
Примечание. Эта функция появилась в версии e1.6.2. Если вы используете более раннюю версию и все еще хотите использовать опцию AlwaysLoad, переключите игру и инструменты моддинга на e1.6.2 или более новую версию.
Чтобы включить параметр AlwaysLoad для категории, выполните следующие действия:
Создайте новый файл XML с именем Config.xml в папке Modules\ИМЯ_ВАШЕГО_МОДУЛЯ\GUI\SpriteParts. Скопируйте и вставьте следующее в Config.xml:

<Config>
    <SpriteCategory Name="ui_{ИМЯ_ВАШЕЙ_КАТЕГОРИИ}">
        <AlwaysLoad/>
    </SpriteCategory>
</Config>

Замените ui_{ИМЯ_ВАШЕЙ_КАТЕГОРИИ} своей категорией. Затем создайте текстурные атласы, выполнив действия, описанные в разделе «Создание текстурных атласов» выше. Чтобы проверить, все ли в порядке, откройте файл с именем {ИМЯ_МОДУЛЯ_ВАШЕГО}SpriteData.xml, который находится в папке Modules\ИМЯ_МОДУЛЯ_ВАШЕГО\GUI. Там вы должны увидеть, что опция AlwaysLoad включена для категорий, которые вы выбрали в Config.xml:

<SpriteData>
    <SpriteCategories>
        <SpriteCategory>
            <Name>ui_{ИМЯ_ВАШЕЙ_КАТЕГОРИИ}</Name>
            <AlwaysLoad />
            <SpriteSheetCount>1</SpriteSheetCount>
            <SpriteSheetSize ID="1" Width="512" Height="512" />
        </SpriteCategory>
    </SpriteCategories>
    ...
</SpriteData>

Вам не нужно изменять/добавлять какой-либо код для загрузки новой категории текстурных атласов.

Вывод
Убедитесь, что вы создали экран и загрузили XML-файл пользовательского интерфейса, который вы создали в разделе «Использование спрайтов в XML-файлах пользовательского интерфейса», чтобы увидеть результат ниже.
Примечание. Если вы добавили категорию спрайтов с помощью параметра «Всегда загружать» и не использовали код, представленный в разделе «Загрузка и выгрузка вручную», вы можете написать собственный код для создания экрана и загрузки XML-кода пользовательского интерфейса. Если вы не знаете, как это сделать, вы можете скопировать код из раздела «Загрузка и выгрузка вручную» (пожалуйста, также прочитайте подробности в этом разделе) и удалить следующие строки, так как вы использовали опцию «Всегда загружать» и вам не нужно это чтобы загрузить категорию вручную:

var spriteData = UIResourceManager.SpriteData;
var resourceContext = UIResourceManager.ResourceContext;
var resourceDepot = UIResourceManager.UIResourceDepot;

_category = spriteData.SpriteCategories["ui_mycategory"]; // select which category to load, put your category name here
_category.Load(resourceContext, resourceDepot); // load the selected category

Вы также можете удалить поле _category и удалить его ссылки.

• Убедитесь, что вы встроили свой проект в Modules\ИМЯ_ВАШЕГО_МОДА\bin\Win64_Shipping_Client.
• Запустите игру (не инструменты моддинга) из Steam и убедитесь, что ваш модуль выбран в разделе «Моды» в программе запуска, затем нажмите «Играть».
• Создайте новую кампанию или загрузите совместимый файл сохранения, чтобы открыть карту кампании. Оба они начнут игру. Обратите внимание, что написанный нами код добавляет экран после запуска игры (проверьте метод OnGameStart).
• После того, как вы запустите игру, создав новую кампанию, вы должны увидеть этот экран: