Библиотеки

Библиотеки

Библиотеки — это дополнительные исполняемые файлы, нужные, чтобы дополнить и расширить существующий API и упростить выполнение каких-либо задач.  

Добавление библиотек в моды

Библиотеки представлены одиночным файлом с кодом. Чтобы добавить библиотеку в мод, ее нужно переместить в директорию библиотек мода (обычно она называется lib, название директории задается параметром libraryDir в разделе defaultConfig файла построения).

Принцип работы библиотек

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

Чтобы импортировать библиотеку используется команда IMPORT:

IMPORT ("имя библиотеки") - импортирует все объекты API из указанной библиотеки

IMPORT ("имя библиотеки", "имя объекта API") - импортирует конкретный объект API из указанной библиотеки

Область видимости библиотек

Библиотеки бывают двух типов - локальные и глобальные.  

Локальные могут быть импортированы только в пределах одного мода, и, если одна и та же библиотека присутствует в двух разных модах, она будет загружена для каждого из них отдельно. Локальные библиотеки используются в случае, когда API, которое она добавляет не нуждается в совместимости. К примеру, библиотека ToolType просто добавляет упрощенные типы инструментов.

Глобальные библиотеки загружаются один раз для всех модов и могут быть импортированы откуда угодно. Они используются для создания глобальных модулей регистрации, которым нужно взаимодействие со всеми модами. Как пример можно привести библиотеку energylib, позволяющую регистрировать различные типы энергии и использовать их в разных модах.

Версии библиотек

Каждая библиотека имеет свой собственный код версии, он нужен для определения самой новой версии библиотеки, если одновременно используется несколько одинаковых библиотек. Особенно это касается глобальных.

Если при импорте библиотеки в целевом пространстве находится более одной библиотеки с одинаковыми именами, будет загружена только одна и при этом с наибольшей версией.

Обратная совместимость

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

Для этого в команде импорта существует возможность импортировать библиотеку с указанием целевой версии. Формат команды импорта с указанием целевой версии:

IMPORT ("имя библиотеки:целевая версия", ...) - в первом параметре указывается через двоеточие код целевой версии библиотеки, второй параметр остается неизменным.

Советуется использовать именно этот вариант импорта, чтобы минимизировать шанс того, что полученный API не будет соответствовать ожидаемому (Произойдет это только в том случае, если разработчик библиотеки не позаботился об обратной совместимости).

Разработка библиотек

Как было сказано выше библиотека — это одиночный файл с кодом. Далее будут рассмотрены особенности разработки библиотек.

Заголовок

Заголовок библиотеки полностью описывает ее параметры и представлен вызовом команды LIBRARY перед всем остальным кодом. 

Использование команды LIBRARY:

LIBRARY({
    name: "имя библиотеки", // по этому имени библиотека будет импортирована
    version: код версии, // код версии должен быть целым числом больше 0, при каждом обновлении библиотеки его надо увеличивать и указывать в документации к ней
    shared: false, // если true, то библиотека будет глобальной
    api: "CoreEngine", // название API, которое использует библиотека
    dependencies: [  "name1:version1",
        //...
    ] 
    /* список зависимостей от других библиотек в том же формате, что и первый параметр команды IMPORT (Импортировать эти библиотеки надо отдельно, этот параметр гарантирует их загрузку до загрузки этой библиотеки)*/
});

Импорт библиотек

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

Экспорт объектов API

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

Использование команды EXPORT:

EXPORT("имя объекта API", объект API) - делает данный объект доступным для экспорта под данным именем

Обратная совместимость экспортируемых объектов

При изменении объекта API и его несовместимости с прошлыми версиями (к примеру при удалении или изменении названия метода) стоит сделать дополнительный экспорт для обратной совместимости.

Использование команды EXPORT для добавления объекта обратной совместимости:

EXPORT("имя объекта API:код версии", объект API) - экспортирует данный объект для версий <код версии> и ниже, может присутствовать экспорт с таким же именем и без версии, а так же другие импорты для совместимости с более низкими версиями.

Пример (Версия библиотеки, в которой это происходит больше 3):

EXPORT("print", function() {
    alert("new version print");
}); 

EXPORT("print:3", function() {
    alert("older print");
});

EXPORT("print:1", function() {
    alert("first version print");
});

При импорте библиотеки с указанием разных версий, всегда будет присутствовать print, однако для новых версий это будет первый вариант, для версии 3 и ниже - второй, а для версии 1 - третий.