Ресурсы и шрифты

IcyUI загружает файлы разметки, словари ресурсов, шрифты и изображения через единый конвейер ресурсов: вы запрашиваете файл по пути и типу, и его читает импортёр для этого типа. Поверх него у шрифтов своя система: она находит шрифт по имени семейства, импортирует его при первой необходимости и подставляет резервный, если найти не удалось.

Загрузка файлов

Configuration.Assets.Load<T>(path) загружает файл и возвращает его как T:

// Loads a markup file from the game's folder without adding it anywhere yet.
public static UIElement LoadPauseMenu(IIcyHost ui) => ui.Configuration.Assets.Load<UIElement>("Menus/Pause.xml");

Откуда: пути отсчитываются от DefaultAssetContext конфигурации — папки сборки игры, если вы её не меняли. Установите для файла Copy to Output Directory в «Copy if newer», чтобы он оказался на месте во время работы.
Что: с настройками движка по умолчанию сразу загружаются UIElement (разметка), ResourceDictionary (файл словаря ресурсов) и шрифты, а интеграция с движком добавляет текстуры. LoadAsync<T> загружает без блокировки.
Короткий путь: Canvas.LoadMarkup(path, viewModel) загружает разметку, задаёт ей контекст данных и добавляет её на Canvas.

Отсутствующий файл приводит к исключению; файл разметки с ошибкой бросает MarkupException с указанием файла, строки и столбца.

Шрифты

Текст запрашивает шрифт по семейству, размеру и начертанию. FontSystem находит его так:

уже импортированный шрифт: векторный — в любом размере, растровый — только в своём;
системный шрифт из папки шрифтов Windows, если системные шрифты включены (с настройками движка по умолчанию они включены); папка индексируется один раз, когда семейство впервые не находится среди импортированных;
резервный шрифт, если ничего не подошло. IcyUI один раз пишет в журнал предупреждение об этом семействе (событие 1001), и текст с ним рисуется резервным шрифтом или не рисуется вовсе, если резервного нет.

Текст без FontFamily использует DefaultFontFamily: Segoe UI с настройками движка по умолчанию или семейство, заданное через WithDefaultFontFamily.

Векторные и растровые шрифты

IcyUI читает два вида файлов шрифтов:

	Векторные (`.ttf`, `.otf`)	Растровые (BMFont `.fnt`)
Размеры	Любые: один файл подходит для любого `FontSize`.	Один: тот, в котором шрифт создан. Другие размеры его не находят.
Масштабирование интерфейса	Перерисовываются в масштабированном размере, поэтому текст остаётся чётким.	Растягиваются из своего изображения, как картинка: чёткие только при масштабе 1.
Стоимость	Каждый символ рисуется в текстуру при первом использовании в каждом размере.	Рисовать нечего: символы уже есть в изображении.
Подходят для	Большинства интерфейсов: текста, который масштабируется вместе с дисплеем и настройками игрока.	Пиксельных игр, интерфейса с фиксированным разрешением, рисованного или стилизованного вида.

Растровый шрифт — это файл AngelCode BMFont (текстовый, XML или двоичный) вместе с изображениями страниц, созданный, например, в BMFont или Hiero. Импортируйте его так же, как векторный; изображения страниц загружаются из той же папки:

Game.UseIcyUI(ui => ui
    .ConfigureFonts()
    .ImportFont("Fonts/PixelFont.fnt"));       // its page images sit next to it

Текст, использующий его, должен запрашивать точно его размер — size из файла: <TextBlock FontFamily="Pixel" FontSize="16"/> для шрифта размером 16 пикселей.

Свой шрифт

Поставляйте файл шрифта вместе с игрой, импортируйте его при настройке и сделайте шрифтом по умолчанию:

Game.UseIcyUI(ui => ui
    .ConfigureFonts()
    .ImportFont("Fonts/MyFont.ttf")           // copied to the output folder
    .WithDefaultFontFamily("My Font"));        // the family name stored in the file

Имя семейства — то, что записано в самом файле шрифта, а не имя файла. Импортируйте файл один раз и используйте в любом размере.

Не копируйте шрифты Windows в свою игру: их лицензия запрещает распространение. Шрифты под лицензией SIL Open Font License, например Noto Sans или Inter, можно поставлять с любой игрой. В Linux и macOS нет Segoe UI, поэтому игра для этих платформ всегда должна импортировать собственный шрифт.

Только свои шрифты

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

Game.UseIcyUI(ui => ui
    .ConfigureFonts()
    .UseSystemFonts(false)                    // the engine defaults turned them on
    .ImportFont("Fonts/MyFont.ttf")
    .WithDefaultFontFamily("My Font"));        // Segoe UI is a system font

Сделайте одним из своих шрифтов и семейство по умолчанию: Segoe UI — системный шрифт. Ваша конфигурация выполняется после настроек движка, поэтому UseSystemFonts(false) в ней побеждает. Во время работы то же делает Configuration.Fonts.DisableSystemFonts(); уже найденные системные шрифты остаются загруженными.

Типичные ошибки

Текст не появляется. Проверьте журнал на предупреждение о шрифте (1001): имя семейства написано с ошибкой или шрифт не установлен и не импортирован. См. Журнал и диагностика.
Растровый шрифт не находится. Текст запрашивает размер, в котором шрифт не создавался. Используйте точно его размер или векторный шрифт.
Файлы отсутствуют во время работы. Файл, не скопированный в папку сборки, игра не найдёт; проверьте его настройку Copy to Output Directory.
Загрузка каждый кадр. Load каждый раз читает и разбирает файл (если вы не открыли кэш через AssetResolver.CreateScope); загрузите один раз и сохраните результат.

Table of Contents