Feat: Добавлена документация по основным методам DungeonUtility

i18n/ru/docusaurus-plugin-content-pages/libraries/index.md → docs/libraries/DungeonUtility/generations/ItemGeneration.md

@@ -1,4 +1,6 @@
-# Библиотеки
+---
+hide_title: true
+---
 
 ```mdx-code-block
 import NotImplemented from "@site/src/components/NotImplemented"

docs/libraries/DungeonUtility/generations/StructurePiece.md

@@ -0,0 +1,9 @@
+---
+hide_title: true
+---
+
+```mdx-code-block
+import NotImplemented from "@site/src/components/NotImplemented"
+
+<NotImplemented />
+```

src/pages/libraries/index.md → docs/libraries/DungeonUtility/getting-started.md

@@ -1,4 +1,4 @@
-# Libraries
+# Intro
 
 ```mdx-code-block
 import NotImplemented from "@site/src/components/NotImplemented"

docs/libraries/DungeonUtility/loaders/StructureFormats.md

@@ -0,0 +1,9 @@
+---
+hide_title: true
+---
+
+```mdx-code-block
+import NotImplemented from "@site/src/components/NotImplemented"
+
+<NotImplemented />
+```

docs/libraries/DungeonUtility/loaders/StructureLoader.md

@@ -0,0 +1,9 @@
+---
+hide_title: true
+---
+
+```mdx-code-block
+import NotImplemented from "@site/src/components/NotImplemented"
+
+<NotImplemented />
+```

docs/libraries/readme.md

@@ -0,0 +1,34 @@
+---
+displayed_sidebar: librariesSidebar
+slug: /libraries
+---
+
+# Libraries
+
+<!--
+
+    Inner Core Docs: Inner Core, Core Engine and Horizon documentation
+    Copyright (C) 2022  Nernar (https://github.com/nernar)
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+	Maintained and distributed by MaXFeeD ([email protected])
+
+-->
+
+```mdx-code-block
+import DocMap from "@site/src/components/DocMap"
+
+<DocMap exploreCategories={ true } />
+```

docusaurus.config.js

@@ -112,7 +112,7 @@ const config = /** @type {import('@docusaurus/types').Config} */ ({
 				},
 				{
 					position: 'left',
-					to: 'libraries',
+					to: 'docs/libraries',
 					label: 'Libraries'
 				},
 				{

i18n/ru/docusaurus-plugin-content-docs/current.json

@@ -62,5 +62,18 @@
   "sidebar.tutorialSidebar.category.Publishing": {
     "message": "Публикация",
     "description": "The label for category Publishing in sidebar tutorialSidebar"
+  },
+
+  "sidebar.librariesSidebar.category.Upload Structure": {
+    "message": "Загрузка структур",
+    "description": "The label for category Upload Structure in sidebar librariesSidebar"
+  },
+  "sidebar.librariesSidebar.category.Structure Generation": {
+    "message": "Генерация структур",
+    "description": "The label for category Structure Generation in sidebar librariesSidebar"
+  },
+  "sidebar.librariesSidebar.category.Advanced": {
+    "message": "Продвинутые возможности",
+    "description": "The label for category Advanced in sidebar librariesSidebar"
   }
 }

i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/generations/ItemGeneration.md

@@ -0,0 +1,104 @@
+# Генерация предметов
+
+ItemGeneration - класс для создания генераторов предметов и взаимодействия с ними.
+Данный класс может работать только с ванильными контейнерами!
+
+:::info Какие проблемы решает генератор предметов?
+
+1. Известная раньше проблема, это пустые сундуки в структурах,  DungeonUtility будет по умолчанию генерировать предметы до тех-пор пока не сгенерирует, что очень удобно.
+2. Интеграция между модами
+3. Просмотр игроком, что ему может выпасть в сундуке
+:::
+
+Разберем базовые методы данного класса, в отдельности разберем создание генератора, на данный момент содержится даже проблема, чтто и в StructureLoader!
+**Поэтому очень важно позаботиться об уникальности имени генератора!**
+
+## Генерация предметов
+
+```ts
+// Создаем генератор по имени example_name, для использования генератора всегда будет необходимо использовать его
+ItemGeneration.newGenerator("example_name");
+```
+
+Теперь разберем данный метод:
+
+```ts
+ItemGeneration.addItem("example_name", VanillaItemID.diamond, .1, {min: 1, max: 5});
+```
+
+Мы обращаемся к генератору по имени example_name и добавляем предмет с идентификатором VanillaItemID.diamond, шансом спавна .1 (это 10%), а последним параметром мы устанавливаем количество падающих предметов (от 1 до 5).
+:::tip
+Помните, что метод использует [**вероятность**](https://ru.wikipedia.org/wiki/Вероятность) спавна, коротко говоря это шанс спавнв деленный на 100(например 1/100 = 1%)
+:::
+
+Теперь разберем метод заполнения сундука:
+
+```ts
+ItemGeneration.fill("example_name", x, y, z, region);
+```
+
+Данный метод заполняет сундук на координатах x, y, z, [region](https://nernar.github.io/ru/docs/environment/modifying-region)
+
+## Интеграция с другими модами
+
+Для того, чтобы не добавлять свои предметы вручную в каждый мод на структуры был добавлен метод:
+
+```ts
+ItemGeneration.setItemIntegration(VanillaItemID.diamond_axe, .1, {min: 1, max: 1});
+```
+
+Тут мы добавляем предмет с идентификатором VanillaItemID.diamond_axe, шансом спавна .1 (это 10%) и следующим параметром мы устанавливаем количество падающих предметов (от 1 до 1).
+
+## Recipe Viewer
+
+Данный метод создаст интеграцию с Recipe Viewer за вас.
+
+```ts
+ItemGeneration.registerRecipeViewer("example_generator", "Title generator");
+```
+
+Данный метод позволит игроку просматрировать предметы в Recipe Viewer, которые он сможет получить с данжей.
+
+## Как заставить генерироваться лут в своей структуре?
+
+```ts
+examplePool.setGlobalPrototype("test_structure", Structure.getPrototypeDefault("example_generator"));
+```
+
+Мы обращаемся к экземпляру StructurePool и устанавливаем ему генерацию предметов `example_generator`.
+
+## Примеры
+
+```ts
+// Помните, что имя генератора должно быть уникально!!!
+ItemGeneration.newGenerator("example_generator");
+
+// Добавляем предметы
+ItemGeneration.addItem("example_generator", VanillaItemID.iron_ingot, .5, {min: 1, max: 3});
+ItemGeneration.addItem("example_generator", VanillaItemID.diamond, .1, {min: 1, max: 1});
+
+// Создаем событие нажатия палкой, теперь палка будет заполнять сундуки
+Item.registerUseFunction(VanillaItemID.stick, (coords, item, block, player) => {
+    // Заполняем сундук на координатах coords в измерении в котором находится игрок player
+    ItemGeneration.fill("example_generator", coords.x, coords.y, coords.z, BlockSource.getDefaultForActor(player));
+});
+
+// Добавляем предмет во все другие моды
+ItemGeneration.setItemIntegration(VanillaItemID.diamond_axe, .1, {min: 1, max: 1});
+
+// Создаем интеграцию с Recipe Viewer
+ItemGeneration.registerRecipeViewer("example_generator", "Title generator");
+
+
+// Создаем StructurePool, ОБРАТИТЕ ВНИМАНИЕ, что у каждого мода должно быть свое уникальное имя!
+let examplePool = new StructurePool("example_pool");
+
+// Устанавливаем путь к папке со структурами, в данном случае папка structures в главной директории мода
+examplePool.setPathStructures(__dir__+"structures");
+
+// Загружаем структуру 'test_structure.struct' из папки указаной выше, структура будет доступна по имени test_structure
+examplePool.upload("test_structure");
+
+// Устанавливаем генерацию предметов в структуре test_structure
+examplePool.setGlobalPrototype("test_structure", Structure.getPrototypeDefault("example_generator"));
+```

i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/generations/StructurePiece.md

@@ -0,0 +1,108 @@
+# Генерация структуры
+
+DefaultGenerationDescription - класс обеспечит качественную генерацию, которая создается очень просто
+
+::info Какие проблемы решает генератор структур DungeonUtility?
+
+1. Частые появления структуры, раньше могло запсавнится несколько структур в одном месте, что выглидит очень не очень
+2. Половинчитые структуры, структуры могли половинчиться из разных причин, DungeonUtility также предлагает исправление данной проблемы
+:::
+
+## Генерация структур
+
+Начнем, пожалуй, сразу с примера:
+
+```ts
+let examplePool = new StructurePool("example_pool");
+
+// Устанавливаем путь к папке со структурами, в данном случае папка structures в главной директории мода
+examplePool.setPathStructures(__dir__+"structures");
+
+// Загружаем структуру 'test_structure.struct' из папки указаной выше, структура будет доступна по имени test_structure
+examplePool.upload("test_structure");
+
+// Добавляем событие StructureLoadOne, чтобы работать со структурой
+Callback.addCallback("StructureLoadOne", () => {
+    // Создаем DefaultGenerationDescription, даем ему структуру, которую будем генерировать с шансом 1 к 80 (примерно 1 структура на 80 чанков)
+    let example_generation = new DefaultGenerationDescription(examplePool.get("test_structure"), 80);
+
+    example_generation.setIdentifier("my_mod:test_structure");// Задаем уникальный индитификатор, для структуры
+    example_generation.setSurface(true, [VanillaBlockID.grass]);// Задаем блоки на которых будет спавниться структура
+    example_generation.setDistance(90, "my_mod_group");// Задаем минимальное расстояния между структурами my_mod_group
+
+    // Регистрируем генерацию структур, по выше описаным параметрам
+    example_generation.register();
+});
+```
+
+### Разберем код
+
+Для регистрации генерации структуры используется класс DefaultGenerationDescription
+Он принимает структуру, которая будет генерироваться и шанс
+
+:::info
+В шансе спана указывается делитель для получения [**вероятности**](https://ru.wikipedia.org/wiki/Вероятность) спавна структуры
+:::
+Дальше мы устанавливаем уникальный индитификатор мода, это требуется для исправления половинчитых структур
+:::info
+Если ваша структура генерируется очень часто, не рекомендуется это делать
+:::
+
+```ts
+example_generation.setIdentifier("my_mod:test_structure");
+```
+
+Затем мы установили поверхности на которых будет генерироваться структура, в где true - это переключатель между белым списком и черным, в примере белый список
+```ts
+example_generation.setSurface(true, [VanillaBlockID.grass]);
+```
+
+Дальше мы задали групу к которой принадлежит структура и минимальное растояние до ближайшей структуры данной группы(что-бы структуры не спавнились слишком часто)
+
+```ts
+example_generation.setDistance(90, "my_mod_group");
+```
+
+Ну и на последок мы зарегистрировали генерацию структуры
+
+```ts
+example_generation.register();
+```
+
+## Пример с генерацией предметов
+
+```ts
+// Помните, что имя генератора должно быть уникально!!!
+ItemGeneration.newGenerator("example_generator");
+
+// Добавляем предметы
+ItemGeneration.addItem("example_generator", VanillaItemID.iron_ingot, .5, {min: 1, max: 3});
+ItemGeneration.addItem("example_generator", VanillaItemID.diamond, .1, {min: 1, max: 1});
+
+// Создаем интеграцию с Recipe Viewer
+ItemGeneration.registerRecipeViewer("example_generator", "Title generator");
+
+
+// Создаем StructurePool, ОБРАТИТЕ ВНИМАНИЕ, что у каждого мода должно быть свое уникальное имя StructurePool!
+let examplePool = new StructurePool("example_pool");
+// Устанавливаем путь к папке со структурами, в данном случае папка structures в главной директории мода
+examplePool.setPathStructures(__dir__+"structures");
+// Загружаем структуру 'test_structure.struct' из папки указаной выше, структура будет доступна по имени test_structure
+examplePool.upload("test_structure");
+
+// Устанавливаем генерацию предметов в структуре test_structure
+examplePool.setGlobalPrototype("test_structure", Structure.getPrototypeDefault("example_generator"));
+
+// Добавляем событие StructureLoadOne, чтобы работать со структурой
+Callback.addCallback("StructureLoadOne", () => {
+    // Создаем DefaultGenerationDescription, даем ему структуру которую будем генерировать, с шансом 1 к 80(примерно 1 структура на 80 чанков)
+    let example_generation = new DefaultGenerationDescription(examplePool.get("test_structure"), 80);
+
+    example_generation.setIdentifier("my_mod:test_structure");// Задаем уникальный индитификатор, для структуры
+    example_generation.setSurface(true, [VanillaBlockID.grass]);// Задаем блоки на которых будет спавниться структура
+    example_generation.setDistance(90, "my_mod_group");// Задаем минимальное расстояния между структурами my_mod_group
+
+    //  Регистрируем генерацию структур, по раннее описанным параметрам
+    example_generation.register();
+});
+```