Редактирование:Библиотеки

<div class="mw-parser-output"><h1> Библиотеки </h1>
<p>Библиотеки — это дополнительные исполняемые файлы, нужные, чтобы дополнить и расширить существующий API и упростить выполнение каких-либо задач. &#160;
</p>
<h2> Добавление библиотек в моды </h2>
<p>Библиотеки представлены одиночным файлом с кодом. Чтобы добавить библиотеку в мод, ее нужно переместить в директорию библиотек мода (обычно она называется lib, название директории задается параметром libraryDir в разделе defaultConfig файла построения).
</p>
<h2> Принцип работы библиотек </h2>
<p>Библиотека регистрирует новые объекты API, которые можно импортировать в пространство имен любого исполняемого файла для их последующего использования. Имя библиотеки и имена объектов API, которые она добавляет можно посмотреть в документации к ней.
</p><p><u>Чтобы импортировать библиотеку используется команда IMPORT:</u>
</p><p><i>IMPORT</i> (<i>"имя библиотеки") - импортирует все объекты API из указанной библиотеки</i>
</p><p><i>IMPORT ("имя библиотеки", "имя объекта API") - импортирует конкретный объект API из указанной библиотеки</i>
</p>
<h2> Область видимости библиотек </h2>
<p>Библиотеки бывают двух типов - локальные и глобальные. &#160;
</p><p>Локальные могут быть импортированы только в пределах одного мода, и, если одна и та же библиотека присутствует в двух разных модах, она будет загружена для каждого из них отдельно. Локальные библиотеки используются в случае, когда API, которое она добавляет не нуждается в совместимости. К примеру, библиотека ToolType просто добавляет упрощенные типы инструментов.
</p><p>Глобальные библиотеки загружаются один раз для всех модов и могут быть импортированы откуда угодно. Они используются для создания глобальных модулей регистрации, которым нужно взаимодействие со всеми модами. Как пример можно привести библиотеку energylib, позволяющую регистрировать различные типы энергии и использовать их в разных модах.
</p>
<h2> Версии библиотек </h2>
<p>Каждая библиотека имеет свой собственный код версии, он нужен для определения самой новой версии библиотеки, если одновременно используется несколько одинаковых библиотек. Особенно это касается глобальных.
</p><p>Если при импорте библиотеки в целевом пространстве находится более одной библиотеки с одинаковыми именами, будет загружена только одна и при этом с наибольшей версией.
</p>
<h2> Обратная совместимость </h2>
<p>Новые версии библиотек могут изменять старый API, при этом правило с загрузкой максимальной версии может вызвать некорректную работу какого-то мода, использующего старую версию библиотеки.
</p><p>Для этого в команде импорта существует возможность импортировать библиотеку с указанием <u>целевой версии</u>. Формат команды импорта с указанием целевой версии:
</p><p><i>IMPORT ("имя библиотеки:целевая версия", ...) - в первом параметре указывается через двоеточие код целевой версии библиотеки, второй параметр остается неизменным.</i>
</p><p>Советуется использовать именно этот вариант импорта, чтобы минимизировать шанс того, что полученный API не будет соответствовать ожидаемому (Произойдет это только в том случае, если разработчик библиотеки не позаботился об обратной совместимости).
</p>
<h1> Разработка библиотек </h1>
<p>Как было сказано выше библиотека — это одиночный файл с кодом. Далее будут рассмотрены особенности разработки библиотек.
</p>
<h2> Заголовок </h2>
<p>Заголовок библиотеки полностью описывает ее параметры и представлен вызовом команды LIBRARY <u>перед всем остальным кодом</u>.&#160;
</p><p>Использование команды LIBRARY:
<pre class="fck_mw_syntaxhighlight"><syntaxhighlight lang="Javascript">LIBRARY({
    name: &quot;имя библиотеки&quot;, // по этому имени библиотека будет импортирована
    version: код версии, // код версии должен быть целым числом больше 0, при каждом обновлении библиотеки его надо увеличивать и указывать в документации к ней
    shared: false, // если true, то библиотека будет глобальной api: &quot;CoreEngine&quot;, // название API, которое использует библиотека
    dependencies: [  &quot;name1:version1&quot;,
        //...
    ] 
    /* список зависимостей от других библиотек в том же формате, что и первый параметр команды IMPORT (Импортировать эти библиотеки надо отдельно, этот параметр гарантирует их загрузку до загрузки этой библиотеки)*/
});
</syntaxhighlight></pre>
</p>
<h2> Импорт библиотек </h2>
<p>Импорт других библиотек происходит по тем же принципам, что и в обычных файлах модов, однако все импортируемые библиотеки нужно задекларировать в загловке в параметре dependencies с учетом версий.
</p>
<h2> Экспорт объектов API </h2>
<p>Экспорт объектов API является самой важной частью библиотек, без которой они теряют свой смысл. Экспорт позволяет передать какой-либо объект под данным именем для его последующего импорта из этой библиотеки.
</p><p><u>Использование команды EXPORT:</u>
</p><p><i>EXPORT("имя объекта API", объект API) - делает данный объект доступным для экспорта под данным именем</i>
</p>
<h2> Обратная совместимость экспортируемых объектов </h2>
<p>При изменении объекта API и его несовместимости с прошлыми версиями (к примеру при удалении или изменении названия метода) стоит сделать дополнительный экспорт для обратной совместимости.
</p><p><u>Использование команды EXPORT для добавления объекта обратной совместимости:</u>
</p><p><i>EXPORT("имя объекта API:код версии", объект API) - экспортирует данный объект для версий &lt;код версии&gt; и ниже, может присутствовать экспорт с таким же именем и без версии, а так же другие импорты для совместимости с более низкими версиями.</i>
</p><p><u>Пример (Версия библиотеки, в которой это происходит больше 3):</u>
<pre class="fck_mw_syntaxhighlight"><syntaxhighlight lang="Javascript">EXPORT(&quot;print&quot;, function() {
    alert(&quot;new version print&quot;);
}); 

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

EXPORT(&quot;print:1&quot;, function() {
    alert(&quot;first version print&quot;);
});</syntaxhighlight></pre>
</p><p>При импорте библиотеки с указанием разных версий, всегда будет присутствовать print, однако для новых версий это будет первый вариант, для версии 3 и ниже - второй, а для версии 1 - третий.
</p></div>
@@ Строка 46: / Строка 46: @@
 Как было сказано выше библиотека — это одиночный файл с кодом. Далее будут рассмотрены особенности разработки библиотек.
-<div class="mw-parser-output">
 == Заголовок ==
@@ Строка 55: / Строка 54: @@
      name: "имя библиотеки", // по этому имени библиотека будет импортирована
      version: код версии, // код версии должен быть целым числом больше 0, при каждом обновлении библиотеки его надо увеличивать и указывать в документации к ней
-     shared: false, // если true, то библиотека будет глобальной
+     shared: false, // если true, то библиотека будет глобальной api: "CoreEngine", // название API, которое использует библиотека
-    api: "CoreEngine", // название API, которое использует библиотека
      dependencies: [  "name1:version1",
          //...
@@ Строка 63: / Строка 61: @@
 });
 </syntaxhighlight>
-</div>
 == Импорт библиотек ==