From 3846834c1a82b8cff4abad7bc7af6c22ddcb0822 Mon Sep 17 00:00:00 2001 From: Reider745 <70357814+Reider745@users.noreply.github.com> Date: Fri, 23 Aug 2024 18:56:23 +0300 Subject: [PATCH 1/2] =?UTF-8?q?Feat:=20=D0=94=D0=BE=D0=B1=D0=B0=D0=B2?= =?UTF-8?q?=D0=BB=D0=B5=D0=BD=D0=B0=20=D0=B4=D0=BE=D0=BA=D1=83=D0=BC=D0=B5?= =?UTF-8?q?=D0=BD=D1=82=D0=B0=D1=86=D0=B8=D1=8F=20=D0=BF=D0=BE=20=D0=BE?= =?UTF-8?q?=D1=81=D0=BD=D0=BE=D0=B2=D0=BD=D1=8B=D0=BC=20=D0=BC=D0=B5=D1=82?= =?UTF-8?q?=D0=BE=D0=B4=D0=BE=D0=BC=20DungeonUtility?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../generations/ItemGeneration.md | 6 +- .../generations/StructurePiece.md | 9 ++ .../DungeonUtility/getting-started.md | 2 +- .../loaders/StructureFormats.md | 0 .../DungeonUtility/loaders/StructureLoader.md | 9 ++ docs/libraries/readme.md | 34 +++++ docusaurus.config.js | 3 +- .../current.json | 13 ++ .../generations/ItemGeneration.md | 101 +++++++++++++++ .../generations/StructurePiece.md | 96 ++++++++++++++ .../DungeonUtility/getting-started.md | 87 +++++++++++++ .../loaders/StructureFormats.md | 117 ++++++++++++++++++ .../DungeonUtility/loaders/StructureLoader.md | 74 +++++++++++ .../current/libraries/readme.md | 34 +++++ sidebars.js | 34 +++++ 15 files changed, 615 insertions(+), 4 deletions(-) rename i18n/ru/docusaurus-plugin-content-pages/libraries/index.md => docs/libraries/DungeonUtility/generations/ItemGeneration.md (78%) create mode 100644 docs/libraries/DungeonUtility/generations/StructurePiece.md rename src/pages/libraries/index.md => docs/libraries/DungeonUtility/getting-started.md (90%) create mode 100644 docs/libraries/DungeonUtility/loaders/StructureFormats.md create mode 100644 docs/libraries/DungeonUtility/loaders/StructureLoader.md create mode 100644 docs/libraries/readme.md create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/generations/ItemGeneration.md create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/generations/StructurePiece.md create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/getting-started.md create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/loaders/StructureFormats.md create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/loaders/StructureLoader.md create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/libraries/readme.md diff --git a/i18n/ru/docusaurus-plugin-content-pages/libraries/index.md b/docs/libraries/DungeonUtility/generations/ItemGeneration.md similarity index 78% rename from i18n/ru/docusaurus-plugin-content-pages/libraries/index.md rename to docs/libraries/DungeonUtility/generations/ItemGeneration.md index a06984cde..86ee1363b 100644 --- a/i18n/ru/docusaurus-plugin-content-pages/libraries/index.md +++ b/docs/libraries/DungeonUtility/generations/ItemGeneration.md @@ -1,7 +1,9 @@ -# Библиотеки +--- +hide_title: true +--- ```mdx-code-block import NotImplemented from "@site/src/components/NotImplemented" -``` +``` \ No newline at end of file diff --git a/docs/libraries/DungeonUtility/generations/StructurePiece.md b/docs/libraries/DungeonUtility/generations/StructurePiece.md new file mode 100644 index 000000000..86ee1363b --- /dev/null +++ b/docs/libraries/DungeonUtility/generations/StructurePiece.md @@ -0,0 +1,9 @@ +--- +hide_title: true +--- + +```mdx-code-block +import NotImplemented from "@site/src/components/NotImplemented" + + +``` \ No newline at end of file diff --git a/src/pages/libraries/index.md b/docs/libraries/DungeonUtility/getting-started.md similarity index 90% rename from src/pages/libraries/index.md rename to docs/libraries/DungeonUtility/getting-started.md index 0aa1be748..3e3e895c3 100644 --- a/src/pages/libraries/index.md +++ b/docs/libraries/DungeonUtility/getting-started.md @@ -1,4 +1,4 @@ -# Libraries +# Intro ```mdx-code-block import NotImplemented from "@site/src/components/NotImplemented" diff --git a/docs/libraries/DungeonUtility/loaders/StructureFormats.md b/docs/libraries/DungeonUtility/loaders/StructureFormats.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/libraries/DungeonUtility/loaders/StructureLoader.md b/docs/libraries/DungeonUtility/loaders/StructureLoader.md new file mode 100644 index 000000000..86ee1363b --- /dev/null +++ b/docs/libraries/DungeonUtility/loaders/StructureLoader.md @@ -0,0 +1,9 @@ +--- +hide_title: true +--- + +```mdx-code-block +import NotImplemented from "@site/src/components/NotImplemented" + + +``` \ No newline at end of file diff --git a/docs/libraries/readme.md b/docs/libraries/readme.md new file mode 100644 index 000000000..f35fdb57d --- /dev/null +++ b/docs/libraries/readme.md @@ -0,0 +1,34 @@ +--- +displayed_sidebar: librariesSidebar +slug: /libraries +--- + +# Libraries + + + +```mdx-code-block +import DocMap from "@site/src/components/DocMap" + + +``` diff --git a/docusaurus.config.js b/docusaurus.config.js index 387c44d11..66a46a8a9 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -26,6 +26,7 @@ const darkCodeTheme = require('prism-react-renderer/themes/vsDark'); const logger = require('@docusaurus/logger'); const path = require('path'); const fs = require('fs'); +const sidebars = require('./sidebars'); const baseUrl = process.env.BASE_URL ?? '/'; @@ -112,7 +113,7 @@ const config = /** @type {import('@docusaurus/types').Config} */ ({ }, { position: 'left', - to: 'libraries', + to: 'docs/libraries', label: 'Libraries' }, { diff --git a/i18n/ru/docusaurus-plugin-content-docs/current.json b/i18n/ru/docusaurus-plugin-content-docs/current.json index a16dc3a22..b5700c517 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current.json +++ b/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" } } diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/generations/ItemGeneration.md b/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/generations/ItemGeneration.md new file mode 100644 index 000000000..a11f86264 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/generations/ItemGeneration.md @@ -0,0 +1,101 @@ +--- +title: Генерация предметов +--- + +ItemGeneration - класс для создания генераторов предметов и взаимодействия с ними. +Данный класс может работать только с ванильными контейнерами! + +## Какие проблемы решает генератор предметов? + +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 и добавляем предмет с id из VanillaItemID.diamond, с шансом спавна .1(это 10%) и следующим параметром мы устанавливаем количество падающих предметов, а именно от 1 до 5. +> Помните, что метод использует [**вероятность**](https://ru.wikipedia.org/wiki/Вероятность) спавна, коротко говоря это шанс спавнв деленный на 100(например 1/100 = 1%) + +Теперь разберем метод заполнения сундука + +```ts +ItemGeneration.fill("example_name", x, y, z, region); +``` + +Данный метод заполняет сундук на координатах x, y, z и в измерении region(BlockSource) + +## Интеграция с другими модами + +Для того, чтобы не добавлять свои предметы в ручную в каждый мод на структуры был добавлен метод +```ts +ItemGeneration.setItemIntegration(VanillaItemID.diamond_axe, .1, {min: 1, max: 1}); +``` +Тут мы добавляем предмет с id из VanillaItemID.diamond_axe, с шансом спавна .1(это 10%) и следующим параметром мы устанавливаем количество падающих предметов, а именно от 1 до 1. + +## Recipe Viewer + +Данный метод создаст интеграцию с RecipeViewer за вас! + +```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}); + +// Создаем интеграцию с RecipeViewer +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")); +``` diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/generations/StructurePiece.md b/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/generations/StructurePiece.md new file mode 100644 index 000000000..baa4182ad --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/generations/StructurePiece.md @@ -0,0 +1,96 @@ +--- +title: Генерация структуры +--- + +DefaultGenerationDescription - класс обеспечит качественную генерацию, которая создается очень просто + +## Какие проблемы решает генератор структур 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 +Он принимает структуру, которая будет генерироваться и шанс + +> В шансе спана указывается делитель для получения [**вероятности**](https://ru.wikipedia.org/wiki/Вероятность) спавна структуры + +Дальше мы устанавливаем уникальный индитификатор мода, это требуется для исправления половинчитых структур +> **Если ваша структура генерируется очень часто, не рекомендую это делать** +> example_generation.setIdentifier("my_mod:test_structure"); + +Затем мы установили поверхности на которых будет генерироваться структура, в где true - это переключатель между белым списком и черным, в примере белый список +> example_generation.setSurface(true, [VanillaBlockID.grass]); + +Дальше мы задали групу к которой принадлежит структура и минимальное растояние до ближайшей структуры данной группы(что-бы структуры не спавнились слишком часто) +> example_generation.setDistance(90, "my_mod_group"); + +Ну и на последок мы зарегистрировали генерацию структуры + +> 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}); + +// Создаем интеграцию с RecipeViewer +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(); +}); +``` diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/getting-started.md b/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/getting-started.md new file mode 100644 index 000000000..a52567c2f --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/getting-started.md @@ -0,0 +1,87 @@ +# Начало + +Dungeon Utility - это мод-библиотека, для создания структур и работы со структурами. +Библитоека позволяет создавать структуры и устанавливать их в мире с более хорошей производительностью, чем аналоги в виде Structures и предшеественников мода + +[TypeScript декларации](https://github.com/Reider745/Dungeon-Utility/tree/main/declarations) - требуются для подсказок в [toolchain](https://github.com/zheka2304/innercore-mod-toolchain) + +Данная документация содержит только основные методы, без дополнительных усложнений, для простоты понимания, документация расчитана на тех кто уже [JavaScript](https://learn.javascript.ru/) + +[Старая документация DungeonUtility](https://github.com/Reider745/libs/blob/main/mod_documentation_api/DungeonUtility.md) + +**Какие возможности включает данная мод-библиотека?** + ++ Загрузка структур от всех существующих на inner core библиотек ++ Полный контроль над установкой структуры ++ Возможность создавать лут в сундуки ++ Создание качественной генерации структур + +## Примущества и недостатки DungeonUtility + ++ Плюсы + + Проработанное api + + Хорошая производительность + + Поддержка серверного ядра [ZoteCoreLoader](https://github.com/Reider745/ZoteCoreLoader) + + Поддержка разных форматов структур + + Открытый [исходный код](https://github.com/Reider745/Dungeon-Utility) + + Поддержка BlockState, extra, CompoundTag + ++ Минусы + + Поддержка только inner core 1.16 + + Необходимость делать зависимость от мода + +## Сохранение структур + +Сохранение структур происходит в несколько этапов: + +1. Вызов команды du (включает возможность использовать ванильный деревянный топор для выбора точек!). +2. Выбирите две крайние точки структуры. +3. Выбирите центр структуры, нажав на шифте (желательно). +4. Вызовите команду struct. + +### Команда struct + +Сохраняет структуру в файл(в папку output, которая находится в папке мода) + +``` +/struct save name:string saveAir:bool specialSeparator:bool type:string compression:bool +``` + ++ Параметры команды: + + name - имя структуры, без пробелов! + + saveAir - сохранять вместе со структурой блоки воздуха, true или false (указывать не обязательно, по умолчанию false). + + specialSeparator - красивое оформление JSON, true или false (указывать не обязательно, по умолчанию false). + + type - тип формата, в который будет сохранена структура (указывать не обязательно, по умолчанию DungeonUtility). + + compression - сжимать ли структуру с помощью алгоритма Хаффмана, true или false (указывать не обязательно, по умолчанию false). + +Вывводит список загруженных структур + +``` +/struct list +``` + +Устанавливает структуру, на место где стоит игрок + +``` +/struct set name:string pool:string +``` + ++ Параметры команды: + + name - имя структуры, без пробелов! + + pool - в котором находится структура, без пробелов! + +Переводит струтктуру формата DungeonUtility_V2 в текстовый формат(что-бы можно было понять как сохранилось структура), берет структуру из папки output + +``` +/struct du2 name:string +``` + +# Моды которые используют DungeonUtility + ++ [Desolation](https://icmods.mineprogramming.org/mod?id=784) ++ [Schematic](https://icmods.mineprogramming.org/mod?id=786) ++ [AppliedEnergistics 2](https://icmods.mineprogramming.org/mod?id=906) ++ [Example Structure](https://icmods.mineprogramming.org/mod?id=992) ++ [Galacticraft 4 PE](https://icmods.mineprogramming.org/mod?id=8556) ++ [Ancient wonders](https://icmods.mineprogramming.org/mod?id=682) ++ [Aether 2 BE](https://icmods.mineprogramming.org/mod?id=195) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/loaders/StructureFormats.md b/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/loaders/StructureFormats.md new file mode 100644 index 000000000..3f9305a1f --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/loaders/StructureFormats.md @@ -0,0 +1,117 @@ +--- +title: Форматы структур +--- + +Формат структуры - это способ чтения/записи структуры из/в файл + +| Формат | Поддержка BlockState | Поддержка дополнительного блока | Поддержка CompountNBT | Актуаленный формат? | +|-------------------|----------------------|---------------------------------|-----------------------|---------------------| +| DungeonUtility_V2 | + | + | + | + | +| DungeonUtility | + | + | + | + | +| DungeonCore | + | + | - | - | +| Structures | - | - | - | + | +| DungeonUtility | - | - | - | - | +| DungeonAPI | - | - | - | - | +| DungeonAPI_V2 | - | - | - | - | + +## Зачем существуют различные форматы структур? + +Dungeon Utility изначально писался как часть модификации Ancient Wonders/Dungeon craft. +В случае Ancient wonders, данный мод имел 3 различные библиотеки для структур, что было весьма не красиво с точки зрения истеки и поддержки мода. +В случае Dungeon craft, мод всегда использовал только одну библиотеку структур, они использовали разные форматы структур, переход был пусть и простым делом, но в один момент при конвертации форматов произошла ошибка, которая была замечена уже после. + +DungeonUtility предлагает быстрый переход с разных библиотек, без проблем с форматом структур! +Примером данного перехода является мод Aether 2 BE, Ancient wonders + +## Какой формат лучше использовать? + +Формат DungeonUtility - является форматом, **который используется везде по умолчанию**, имеет один жирный минус, большой вес файла. + +Формат DungeonUtility_V2 - является новым форматом, который имеет достаточно компакнтый размер, при этом обладает неплохой скоростью загрузки. +Особенностью данного формата являются: что он [бинарный файл](https://en.wikipedia.org/wiki/Binary_file), хорошая безопасноть - иногда происходит повреждение части информации на носителе(увы и ах от этого не кто не застрохован) в случае если часть файла все-же повредилась, есть шанс что хотя-бы половина структуры загрузиться нормально. +Также в формат была заложена такая структура из которой его легко поддерживать и развивать дальше! + +Исходя из выше сказаного рекомендую использовать формат DungeonUtility_V2, об устройстве формата можете почитать внизу(не требуется для обычных пользователей библиотеки) + +## Спецификация формата DungeonUtility_V2 + +### Типы данных которые используются + +| Тип | Размер | +|-------|--------| +| byte | 1 | +| short | 2 | +| int | 4 | + +## Структура файла DungeonUtility_V2 + +Самый первый byte - версия формата + +| Версии | +|----------| +| -128 | + +### Версия DungeonUtility_V2 -128 + +После версии индут заголовки зоны +Зоны - это некоторое количесва байтов, которое определяется в заголовке зоны +Заголовок зоны - содержат: byte, int. byte - тут это id зоны, int - место где зона заканчивается, в случае не поддержки зоны, чтение зоны пропускается! В случае повреждения int - шансов на чтение файла нет, к счастью это очень маленькая часть файла, шанс на повреждение маленький. + +| Зоны | Имя | Предназначение | Приоритет чтения | +|------|--------------|--------------------------------------|------------------| +| -1 | EMPTY | Скипующая зона | 0 | +| - | MAP | Хранение информации по байту | - | +| 0 | DESCRIPTION | Описание | 10 | +| 1 | STATES | Описание блоков которые используются | 5 | +| 2 | PLANE_BLOCKS | Разрез структуры | -5 | + +Чем больше приоритет, чем раньше читается зона + +### EMPTY + +Зона которая скипает чтение информации внутри себя, может использоваться, в случае повреждения байта, отвечающего за id зоны, также может использовать в случае не поддержки зоны + +### MAP + +Абстракнтая зона, представляющая собой своего рода HashMap. +Первый byte количество полей, дальше идут поля, каждое поле представляет собой: два byte, первый котороый хранит тип информации, второй байт используется как ключ, по которому, дальше количество байтов и значение зависят от типа + +| Тип | Имя | Размер | +|-----|--------|-----------------------------------------------------------------------| +| -1 | EMPTY | Не имеет | +| 0 | BYTE | 1 | +| 1 | SHORT | 2 | +| 2 | INT | 4 | +| 3 | STRING | 2 байта(short) + плюс прочитанный short + минимальное значение short | + +#### Чтения строки + +Читается short, прибавляется минимальное значение short, получаем последовательность байтов строки + +### DESCRIPTION + +Наследуется от зоны MAP + +| Ключ | Имя | +|------|----------| +| 1 | X_OFFSET | +| 2 | Y_OFFSET | + +### STATES + +Содержит описание стейтов +Перый байт, тип данных, который используется для обозначения состояния блока(1 - byte, 2 - short), данный байт очень важен для чтения и используется в PLANE_BLOCKS, дальше этот параметр будет называться как **id состояния**! +Следующие 2 байта(short) количетсво состояний + +Описания состояния: первые байты **id состояния** дальше идет 3 байта, которые обозначают boolean, есть-ли у блока state, есть-ли у блока extra, есть-ли у tag +Первым читается state, если он есть, вторыи extra, затем tag +Способ записи BlockState, если id блока больше 8000, то первый байт 1 иначе 0, если равен 1 то дальше идет текстовое id блока, если нет то short id блока, после идет BlockState в виде json +tag также записывается в виде строки + +### PLANE_BLOCKS + +Представляет собой двух мерный массив **id состояний**! +Первый short - это позиция разреза по координате z +второй и третий short - размеры двух мерного массива + +Двух мерный массив содержит **id состояния**, каждая позиция в массиве это кордината блока в структурк, также необходимо вычесть X_OFFSET и Y_OFFSET из DESCRIPTION diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/loaders/StructureLoader.md b/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/loaders/StructureLoader.md new file mode 100644 index 000000000..8ce15a162 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/loaders/StructureLoader.md @@ -0,0 +1,74 @@ +--- +title: Загрузка структур +--- + +Данный класс StrcutureLoader использовался раньше для загрузки структур, сейчас эти методы устарели, но они все еще поддерживаются. +Класс используетя для манипуляции структрами в файлах. +Актуальный классом является StructurePool + +## Что делает StrcuturePool? + +Данный класс просто хранит структуры по их имени, в дальнейшем их можно будет использовать по имени + +## Почему StructureLoader Устарел? + +Все мы любим назвать свое единственное дерево в моде wood, что будет если в двух разных модах будет структура wood? +Очень просто, выживит сильнейший! + +Чтобы не было подобных ситуаций был создан StructurePool, он имеет свое имя по которому его можно получить в других модификациях, для простоты понимания мы это тоже упустим. + +**Важно что-бы ваше StructurePool имя не совпало с чужими! Нес используйте сокращение от имени мода, используете все имя мода!** + +Для начала создаим StructurePool, который в дальнейшем будем использовать + +```ts +let poolInstance = new StructurePool("test_pool"); +``` + +Для простоты и сокращения кода установим путь к папке со структурами(отсюда они в дальнейшем будут браться) + +```ts +poolInstance.setPathStructures(/*ПОЛНЫЙ путь к папке со структурами*/); +``` + +Загрузка структуры +Важно дополнительный раз уточнить, что формат структуры указывать не обезательно, **по умолчанию везде используется DungeonUtility** + +```ts +poolInstance.upload(/*имя файла*/, /*Формат структуры, по умолчанию DungeonUtility*/); +``` + +Получение структуры, используется везде где нужна структура +> ВНИМАНИЕ! Загрзука структур не происходит сразу как вы используется upload + +Событие StructureLoadOne вызывается после загрузки структур, работаете со структурами тут! + +```ts +poolInstance.get(/*имя структуры*/); +``` + +### Пример использования + +```ts +// Создаем StructurePool, обратите внимание, что у каждого мода должен быть свое уникальное имя StructurePool!!!!!!!!! +let examplePool = new StructurePool("example_pool"); + +// Устанавливаем путь к папке со структурами, в данном случае папка structures в главное директории мода +examplePool.setPathStructures(__dir__+"structures"); + +// Загружаем структуру test_structure.struct из папки указаной выше, структура будет доступна по имени test_structure +examplePool.upload("test_structure"); +// Загружаем структуру test_structure.struct из папки указаной выше, структура будет доступна по имени legacy_structure +// Обратите внимание, что в данном примере используется формат файла Structures +examplePool.upload("legacy_structure", "Structures"); +// Загружаем структуру test_structure_folder.struct из папки указаной выше + папка указанае тут внизу, структура будет доступна по имени test_structure_folder +examplePool.upload("folder/test_structure_folder"); + + +Callback.addCallback("StructureLoadOne", () => { + // Примеры получения структур загруженных выше! + examplePool.get("test_structure"); + examplePool.get("legacy_structure"); + examplePool.get("test_structure_folder"); +}); +``` diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/libraries/readme.md b/i18n/ru/docusaurus-plugin-content-docs/current/libraries/readme.md new file mode 100644 index 000000000..4cf3d6c17 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/libraries/readme.md @@ -0,0 +1,34 @@ +--- +displayed_sidebar: librariesSidebar +slug: /libraries +--- + +# Start your Journey + + + +```mdx-code-block +import DocMap from "@site/src/components/DocMap" + + +``` diff --git a/sidebars.js b/sidebars.js index 334037173..85d4ddaee 100644 --- a/sidebars.js +++ b/sidebars.js @@ -240,5 +240,39 @@ module.exports = { type: 'doc', id: 'future-steps' } + ], + librariesSidebar: [ + { + type: 'category', + label: 'Dungeon Utility', + link: { + type: 'generated-index' + }, + items: [ + 'libraries/DungeonUtility/getting-started', + { + type: 'category', + label: 'Upload Structure', + link: { + type: 'generated-index' + }, + items: [ + 'libraries/DungeonUtility/loaders/StructureFormats', + 'libraries/DungeonUtility/loaders/StructureLoader', + ] + }, + { + type: 'category', + label: 'Structure Generation', + link: { + type: 'generated-index' + }, + items: [ + 'libraries/DungeonUtility/generations/ItemGeneration', + 'libraries/DungeonUtility/generations/StructurePiece' + ] + } + ] + } ] }; From 34c15c7b612091aa2d700befcd040c6d2701ff68 Mon Sep 17 00:00:00 2001 From: Reider745 <70357814+Reider745@users.noreply.github.com> Date: Fri, 23 Aug 2024 23:03:45 +0300 Subject: [PATCH 2/2] Preview hot fix --- .../generations/ItemGeneration.md | 2 +- .../generations/StructurePiece.md | 2 +- .../loaders/StructureFormats.md | 9 ++++ .../DungeonUtility/loaders/StructureLoader.md | 2 +- docusaurus.config.js | 1 - .../generations/ItemGeneration.md | 43 ++++++++------- .../generations/StructurePiece.md | 52 +++++++++++------- .../DungeonUtility/getting-started.md | 53 ++++++++++--------- .../loaders/StructureFormats.md | 15 +++--- .../DungeonUtility/loaders/StructureLoader.md | 42 ++++++++------- 10 files changed, 125 insertions(+), 96 deletions(-) diff --git a/docs/libraries/DungeonUtility/generations/ItemGeneration.md b/docs/libraries/DungeonUtility/generations/ItemGeneration.md index 86ee1363b..e4f110f1a 100644 --- a/docs/libraries/DungeonUtility/generations/ItemGeneration.md +++ b/docs/libraries/DungeonUtility/generations/ItemGeneration.md @@ -6,4 +6,4 @@ hide_title: true import NotImplemented from "@site/src/components/NotImplemented" -``` \ No newline at end of file +``` diff --git a/docs/libraries/DungeonUtility/generations/StructurePiece.md b/docs/libraries/DungeonUtility/generations/StructurePiece.md index 86ee1363b..e4f110f1a 100644 --- a/docs/libraries/DungeonUtility/generations/StructurePiece.md +++ b/docs/libraries/DungeonUtility/generations/StructurePiece.md @@ -6,4 +6,4 @@ hide_title: true import NotImplemented from "@site/src/components/NotImplemented" -``` \ No newline at end of file +``` diff --git a/docs/libraries/DungeonUtility/loaders/StructureFormats.md b/docs/libraries/DungeonUtility/loaders/StructureFormats.md index e69de29bb..e4f110f1a 100644 --- a/docs/libraries/DungeonUtility/loaders/StructureFormats.md +++ b/docs/libraries/DungeonUtility/loaders/StructureFormats.md @@ -0,0 +1,9 @@ +--- +hide_title: true +--- + +```mdx-code-block +import NotImplemented from "@site/src/components/NotImplemented" + + +``` diff --git a/docs/libraries/DungeonUtility/loaders/StructureLoader.md b/docs/libraries/DungeonUtility/loaders/StructureLoader.md index 86ee1363b..e4f110f1a 100644 --- a/docs/libraries/DungeonUtility/loaders/StructureLoader.md +++ b/docs/libraries/DungeonUtility/loaders/StructureLoader.md @@ -6,4 +6,4 @@ hide_title: true import NotImplemented from "@site/src/components/NotImplemented" -``` \ No newline at end of file +``` diff --git a/docusaurus.config.js b/docusaurus.config.js index 66a46a8a9..83974356b 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -26,7 +26,6 @@ const darkCodeTheme = require('prism-react-renderer/themes/vsDark'); const logger = require('@docusaurus/logger'); const path = require('path'); const fs = require('fs'); -const sidebars = require('./sidebars'); const baseUrl = process.env.BASE_URL ?? '/'; diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/generations/ItemGeneration.md b/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/generations/ItemGeneration.md index a11f86264..3468d95e7 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/generations/ItemGeneration.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/generations/ItemGeneration.md @@ -1,15 +1,14 @@ ---- -title: Генерация предметов ---- +# Генерация предметов ItemGeneration - класс для создания генераторов предметов и взаимодействия с ними. Данный класс может работать только с ванильными контейнерами! -## Какие проблемы решает генератор предметов? +:::info Какие проблемы решает генератор предметов? 1. Известная раньше проблема, это пустые сундуки в структурах, DungeonUtility будет по умолчанию генерировать предметы до тех-пор пока не сгенерирует, что очень удобно. 2. Интеграция между модами 3. Просмотр игроком, что ему может выпасть в сундуке +::: Разберем базовые методы данного класса, в отдельности разберем создание генератора, на данный момент содержится даже проблема, чтто и в StructureLoader! **Поэтому очень важно позаботиться об уникальности имени генератора!** @@ -21,40 +20,44 @@ ItemGeneration - класс для создания генераторов пр ItemGeneration.newGenerator("example_name"); ``` -Теперь разберем данный метод +Теперь разберем данный метод: ```ts -ItemGeneration.addItem("example_name", VanillaItemID.diamond, .1, {min: 1, max:5}); +ItemGeneration.addItem("example_name", VanillaItemID.diamond, .1, {min: 1, max: 5}); ``` -Мы обращаемся к генератору по имени example_name и добавляем предмет с id из VanillaItemID.diamond, с шансом спавна .1(это 10%) и следующим параметром мы устанавливаем количество падающих предметов, а именно от 1 до 5. -> Помните, что метод использует [**вероятность**](https://ru.wikipedia.org/wiki/Вероятность) спавна, коротко говоря это шанс спавнв деленный на 100(например 1/100 = 1%) +Мы обращаемся к генератору по имени 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(BlockSource) +Данный метод заполняет сундук на координатах x, y, z, [region](https://nernar.github.io/ru/docs/environment/modifying-region) ## Интеграция с другими модами -Для того, чтобы не добавлять свои предметы в ручную в каждый мод на структуры был добавлен метод +Для того, чтобы не добавлять свои предметы вручную в каждый мод на структуры был добавлен метод: + ```ts ItemGeneration.setItemIntegration(VanillaItemID.diamond_axe, .1, {min: 1, max: 1}); ``` -Тут мы добавляем предмет с id из VanillaItemID.diamond_axe, с шансом спавна .1(это 10%) и следующим параметром мы устанавливаем количество падающих предметов, а именно от 1 до 1. + +Тут мы добавляем предмет с идентификатором VanillaItemID.diamond_axe, шансом спавна .1 (это 10%) и следующим параметром мы устанавливаем количество падающих предметов (от 1 до 1). ## Recipe Viewer -Данный метод создаст интеграцию с RecipeViewer за вас! +Данный метод создаст интеграцию с Recipe Viewer за вас. ```ts ItemGeneration.registerRecipeViewer("example_generator", "Title generator"); ``` -Разберем данный метод, данный метод позводит просматрировать игроку предметы в Recipe Viewer которые он может получить с данжей. +Данный метод позволит игроку просматрировать предметы в Recipe Viewer, которые он сможет получить с данжей. ## Как заставить генерироваться лут в своей структуре? @@ -62,7 +65,7 @@ ItemGeneration.registerRecipeViewer("example_generator", "Title generator"); examplePool.setGlobalPrototype("test_structure", Structure.getPrototypeDefault("example_generator")); ``` -Разберем данный код, мы обращаемся к экземпляру StructurePool и устанавливаем ей генерацию предметов example_generator +Мы обращаемся к экземпляру StructurePool и устанавливаем ему генерацию предметов `example_generator`. ## Примеры @@ -80,20 +83,20 @@ Item.registerUseFunction(VanillaItemID.stick, (coords, item, block, player) => { ItemGeneration.fill("example_generator", coords.x, coords.y, coords.z, BlockSource.getDefaultForActor(player)); }); -// Добавляем предмет вовсе другие моды +// Добавляем предмет во все другие моды ItemGeneration.setItemIntegration(VanillaItemID.diamond_axe, .1, {min: 1, max: 1}); -// Создаем интеграцию с RecipeViewer +// Создаем интеграцию с Recipe Viewer ItemGeneration.registerRecipeViewer("example_generator", "Title generator"); -// Создаем StructurePool, обратите внимание, что у каждого мода должен быть свое уникальное имя StructurePool!!!!!!!!! +// Создаем StructurePool, ОБРАТИТЕ ВНИМАНИЕ, что у каждого мода должно быть свое уникальное имя! let examplePool = new StructurePool("example_pool"); -// Устанавливаем путь к папке со структурами, в данном случае папка structures в главное директории мода +// Устанавливаем путь к папке со структурами, в данном случае папка structures в главной директории мода examplePool.setPathStructures(__dir__+"structures"); -// Загружаем структуру test_structure.struct из папки указаной выше, структура будет доступна по имени test_structure +// Загружаем структуру 'test_structure.struct' из папки указаной выше, структура будет доступна по имени test_structure examplePool.upload("test_structure"); // Устанавливаем генерацию предметов в структуре test_structure diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/generations/StructurePiece.md b/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/generations/StructurePiece.md index baa4182ad..d4d2bb408 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/generations/StructurePiece.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/generations/StructurePiece.md @@ -1,30 +1,29 @@ ---- -title: Генерация структуры ---- +# Генерация структуры DefaultGenerationDescription - класс обеспечит качественную генерацию, которая создается очень просто -## Какие проблемы решает генератор структур DungeonUtility? +::info Какие проблемы решает генератор структур DungeonUtility? 1. Частые появления структуры, раньше могло запсавнится несколько структур в одном месте, что выглидит очень не очень 2. Половинчитые структуры, структуры могли половинчиться из разных причин, DungeonUtility также предлагает исправление данной проблемы +::: ## Генерация структур -Начнем пожалуй сразу с примера +Начнем, пожалуй, сразу с примера: ```ts let examplePool = new StructurePool("example_pool"); -// Устанавливаем путь к папке со структурами, в данном случае папка structures в главное директории мода +// Устанавливаем путь к папке со структурами, в данном случае папка structures в главной директории мода examplePool.setPathStructures(__dir__+"structures"); -// Загружаем структуру test_structure.struct из папки указаной выше, структура будет доступна по имени test_structure +// Загружаем структуру 'test_structure.struct' из папки указаной выше, структура будет доступна по имени test_structure examplePool.upload("test_structure"); // Добавляем событие StructureLoadOne, чтобы работать со структурой Callback.addCallback("StructureLoadOne", () => { - // Создаем DefaultGenerationDescription, даем ему структуру которую будем генерировать, с шансом 1 к 80(примерно 1 структура на 80 чанков) + // Создаем DefaultGenerationDescription, даем ему структуру, которую будем генерировать с шансом 1 к 80 (примерно 1 структура на 80 чанков) let example_generation = new DefaultGenerationDescription(examplePool.get("test_structure"), 80); example_generation.setIdentifier("my_mod:test_structure");// Задаем уникальный индитификатор, для структуры @@ -41,21 +40,34 @@ Callback.addCallback("StructureLoadOne", () => { Для регистрации генерации структуры используется класс DefaultGenerationDescription Он принимает структуру, которая будет генерироваться и шанс -> В шансе спана указывается делитель для получения [**вероятности**](https://ru.wikipedia.org/wiki/Вероятность) спавна структуры - +:::info +В шансе спана указывается делитель для получения [**вероятности**](https://ru.wikipedia.org/wiki/Вероятность) спавна структуры +::: Дальше мы устанавливаем уникальный индитификатор мода, это требуется для исправления половинчитых структур -> **Если ваша структура генерируется очень часто, не рекомендую это делать** -> example_generation.setIdentifier("my_mod:test_structure"); +:::info +Если ваша структура генерируется очень часто, не рекомендуется это делать +::: + +```ts +example_generation.setIdentifier("my_mod:test_structure"); +``` Затем мы установили поверхности на которых будет генерироваться структура, в где true - это переключатель между белым списком и черным, в примере белый список -> example_generation.setSurface(true, [VanillaBlockID.grass]); +```ts +example_generation.setSurface(true, [VanillaBlockID.grass]); +``` Дальше мы задали групу к которой принадлежит структура и минимальное растояние до ближайшей структуры данной группы(что-бы структуры не спавнились слишком часто) -> example_generation.setDistance(90, "my_mod_group"); + +```ts +example_generation.setDistance(90, "my_mod_group"); +``` Ну и на последок мы зарегистрировали генерацию структуры -> example_generation.register(); +```ts +example_generation.register(); +``` ## Пример с генерацией предметов @@ -67,15 +79,15 @@ 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}); -// Создаем интеграцию с RecipeViewer +// Создаем интеграцию с Recipe Viewer ItemGeneration.registerRecipeViewer("example_generator", "Title generator"); -// Создаем StructurePool, обратите внимание, что у каждого мода должен быть свое уникальное имя StructurePool!!!!!!!!! +// Создаем StructurePool, ОБРАТИТЕ ВНИМАНИЕ, что у каждого мода должно быть свое уникальное имя StructurePool! let examplePool = new StructurePool("example_pool"); -// Устанавливаем путь к папке со структурами, в данном случае папка structures в главное директории мода +// Устанавливаем путь к папке со структурами, в данном случае папка structures в главной директории мода examplePool.setPathStructures(__dir__+"structures"); -// Загружаем структуру test_structure.struct из папки указаной выше, структура будет доступна по имени test_structure +// Загружаем структуру 'test_structure.struct' из папки указаной выше, структура будет доступна по имени test_structure examplePool.upload("test_structure"); // Устанавливаем генерацию предметов в структуре test_structure @@ -90,7 +102,7 @@ Callback.addCallback("StructureLoadOne", () => { example_generation.setSurface(true, [VanillaBlockID.grass]);// Задаем блоки на которых будет спавниться структура example_generation.setDistance(90, "my_mod_group");// Задаем минимальное расстояния между структурами my_mod_group - // Регистрируем генерацию структур, по выше описаным параметрам + // Регистрируем генерацию структур, по раннее описанным параметрам example_generation.register(); }); ``` diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/getting-started.md b/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/getting-started.md index a52567c2f..924ce294b 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/getting-started.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/getting-started.md @@ -1,47 +1,50 @@ # Начало -Dungeon Utility - это мод-библиотека, для создания структур и работы со структурами. -Библитоека позволяет создавать структуры и устанавливать их в мире с более хорошей производительностью, чем аналоги в виде Structures и предшеественников мода +Dungeon Utility — это мод-библиотека, для создания структур и работы со структурами. +Библиотека позволяет создавать структуры и устанавливать их в мире с лучшей производительностью, чем аналоги в виде Structures и предшественников мода. -[TypeScript декларации](https://github.com/Reider745/Dungeon-Utility/tree/main/declarations) - требуются для подсказок в [toolchain](https://github.com/zheka2304/innercore-mod-toolchain) +[Декларации TypeScript](https://github.com/Reider745/Dungeon-Utility/tree/main/declarations) — требуются для подсказок в различных средах Данная документация содержит только основные методы, без дополнительных усложнений, для простоты понимания, документация расчитана на тех кто уже [JavaScript](https://learn.javascript.ru/) [Старая документация DungeonUtility](https://github.com/Reider745/libs/blob/main/mod_documentation_api/DungeonUtility.md) -**Какие возможности включает данная мод-библиотека?** +:::info Какие возможности включает данная мод-библиотека?** + Загрузка структур от всех существующих на inner core библиотек + Полный контроль над установкой структуры + Возможность создавать лут в сундуки + Создание качественной генерации структур +::: -## Примущества и недостатки DungeonUtility +## Преимущества и недостатки DungeonUtility -+ Плюсы - + Проработанное api - + Хорошая производительность - + Поддержка серверного ядра [ZoteCoreLoader](https://github.com/Reider745/ZoteCoreLoader) - + Поддержка разных форматов структур - + Открытый [исходный код](https://github.com/Reider745/Dungeon-Utility) - + Поддержка BlockState, extra, CompoundTag - -+ Минусы - + Поддержка только inner core 1.16 - + Необходимость делать зависимость от мода +### Плюсы + ++ **Проработанное API**: Удобный интерфейс для разработчиков. ++ **Хорошая производительность**: Эффективная работа даже при больших нагрузках. ++ **Поддержка серверного ядра**: Совместимость с [ZoteCoreLoader](https://github.com/Reider745/ZoteCoreLoader). ++ **Разнообразие форматов структур**: Гибкость в использовании различных структур данных. ++ **Открытый исходный код**: Доступный для изучения и модификации [репозиторий](https://github.com/Reider745/Dungeon-Utility). ++ **Поддержка BlockState, extra, CompoundTag**: Широкий функционал для работы с данными. + +### Минусы + ++ **Поддержка только inner core 1.16**: Ограниченная совместимость с другими версиями. ++ **Необходимость делать зависимость от мода**: Дополнительные требования для интеграции. ## Сохранение структур Сохранение структур происходит в несколько этапов: -1. Вызов команды du (включает возможность использовать ванильный деревянный топор для выбора точек!). -2. Выбирите две крайние точки структуры. -3. Выбирите центр структуры, нажав на шифте (желательно). -4. Вызовите команду struct. +1. Вызовите команду `/du` (включает возможность использовать ванильный деревянный топор для выбора точек) +2. Выберите две крайние точки структуры +3. Выберите центр структуры, нажав на нужный блок с шифтом (желательно) +4. Вызовите команду `/struct` ### Команда struct -Сохраняет структуру в файл(в папку output, которая находится в папке мода) +Сохраняет структуру в файл (в папку output, которая находится в папке мода). ``` /struct save name:string saveAir:bool specialSeparator:bool type:string compression:bool @@ -49,18 +52,18 @@ Dungeon Utility - это мод-библиотека, для создания с + Параметры команды: + name - имя структуры, без пробелов! - + saveAir - сохранять вместе со структурой блоки воздуха, true или false (указывать не обязательно, по умолчанию false). + + saveAir - сохранять ли вместе со структурой блоки воздуха, true или false (указывать необязательно, по умолчанию false). + specialSeparator - красивое оформление JSON, true или false (указывать не обязательно, по умолчанию false). + type - тип формата, в который будет сохранена структура (указывать не обязательно, по умолчанию DungeonUtility). + compression - сжимать ли структуру с помощью алгоритма Хаффмана, true или false (указывать не обязательно, по умолчанию false). -Вывводит список загруженных структур +Отображает список загруженных структур: ``` /struct list ``` -Устанавливает структуру, на место где стоит игрок +Устанавливает структуру на место, где стоит игрок: ``` /struct set name:string pool:string @@ -70,7 +73,7 @@ Dungeon Utility - это мод-библиотека, для создания с + name - имя структуры, без пробелов! + pool - в котором находится структура, без пробелов! -Переводит струтктуру формата DungeonUtility_V2 в текстовый формат(что-бы можно было понять как сохранилось структура), берет структуру из папки output +Переводит струтктуру формата DungeonUtility_V2 в текстовый формат (чтобы можно было разобрать содержимое структуры ), берет структуру из папки output. ``` /struct du2 name:string diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/loaders/StructureFormats.md b/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/loaders/StructureFormats.md index 3f9305a1f..4ed2236a6 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/loaders/StructureFormats.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/loaders/StructureFormats.md @@ -1,8 +1,6 @@ ---- -title: Форматы структур ---- +# Форматы структур -Формат структуры - это способ чтения/записи структуры из/в файл +Формат структуры — это способ хранения и загрузки структуры из файла или любого другого источника. | Формат | Поддержка BlockState | Поддержка дополнительного блока | Поддержка CompountNBT | Актуаленный формат? | |-------------------|----------------------|---------------------------------|-----------------------|---------------------| @@ -17,7 +15,7 @@ title: Форматы структур ## Зачем существуют различные форматы структур? Dungeon Utility изначально писался как часть модификации Ancient Wonders/Dungeon craft. -В случае Ancient wonders, данный мод имел 3 различные библиотеки для структур, что было весьма не красиво с точки зрения истеки и поддержки мода. +В случае Ancient wonders, данный мод использовал несколько различных библиотек для структур, что было неприемлемо с точки зрения поддержания работы мода. В случае Dungeon craft, мод всегда использовал только одну библиотеку структур, они использовали разные форматы структур, переход был пусть и простым делом, но в один момент при конвертации форматов произошла ошибка, которая была замечена уже после. DungeonUtility предлагает быстрый переход с разных библиотек, без проблем с форматом структур! @@ -25,11 +23,10 @@ DungeonUtility предлагает быстрый переход с разны ## Какой формат лучше использовать? -Формат DungeonUtility - является форматом, **который используется везде по умолчанию**, имеет один жирный минус, большой вес файла. +Формат DungeonUtility является форматом, который используется **по умолчанию**, однако имеет один жирный минус — большой размер файла. Формат DungeonUtility_V2 - является новым форматом, который имеет достаточно компакнтый размер, при этом обладает неплохой скоростью загрузки. -Особенностью данного формата являются: что он [бинарный файл](https://en.wikipedia.org/wiki/Binary_file), хорошая безопасноть - иногда происходит повреждение части информации на носителе(увы и ах от этого не кто не застрохован) в случае если часть файла все-же повредилась, есть шанс что хотя-бы половина структуры загрузиться нормально. -Также в формат была заложена такая структура из которой его легко поддерживать и развивать дальше! +Данный формат представляет собой [бинарный файл](https://en.wikipedia.org/wiki/Binary_file) Исходя из выше сказаного рекомендую использовать формат DungeonUtility_V2, об устройстве формата можете почитать внизу(не требуется для обычных пользователей библиотеки) @@ -114,4 +111,4 @@ tag также записывается в виде строки Первый short - это позиция разреза по координате z второй и третий short - размеры двух мерного массива -Двух мерный массив содержит **id состояния**, каждая позиция в массиве это кордината блока в структурк, также необходимо вычесть X_OFFSET и Y_OFFSET из DESCRIPTION +Двухмерный массив содержит **идентификатор состояния**, каждая позиция в массиве это координата блока в структуре, также необходимо вычесть X_OFFSET и Y_OFFSET из DESCRIPTION diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/loaders/StructureLoader.md b/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/loaders/StructureLoader.md index 8ce15a162..0f8a5d4cb 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/loaders/StructureLoader.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/libraries/DungeonUtility/loaders/StructureLoader.md @@ -1,45 +1,51 @@ ---- -title: Загрузка структур ---- +# Загрузка структур -Данный класс StrcutureLoader использовался раньше для загрузки структур, сейчас эти методы устарели, но они все еще поддерживаются. +StrcutureLoader — класс который использовался раньше для загрузки структур, сейчас эти методы устарели, но они все еще поддерживаются. Класс используетя для манипуляции структрами в файлах. -Актуальный классом является StructurePool +Актуальный классом является StructurePool, Данный класс просто хранит структуры по их имени, в дальнейшем их можно будет использовать по имени. -## Что делает StrcuturePool? -Данный класс просто хранит структуры по их имени, в дальнейшем их можно будет использовать по имени ## Почему StructureLoader Устарел? -Все мы любим назвать свое единственное дерево в моде wood, что будет если в двух разных модах будет структура wood? +Все мы любим назвать свое единственное дерево в моде 'бревно265', что будет если в двух разных модах будет структура 'бревно265'? Очень просто, выживит сильнейший! Чтобы не было подобных ситуаций был создан StructurePool, он имеет свое имя по которому его можно получить в других модификациях, для простоты понимания мы это тоже упустим. -**Важно что-бы ваше StructurePool имя не совпало с чужими! Нес используйте сокращение от имени мода, используете все имя мода!** +:::info -Для начала создаим StructurePool, который в дальнейшем будем использовать +**Важно чтобы ваше имя StructurePool не совпадало с другими модами! Указывайте имя мода полностью, не сокращая его.** +::: + +Для начала создадим StructurePool, который в дальнейшем будем использовать: ```ts let poolInstance = new StructurePool("test_pool"); ``` -Для простоты и сокращения кода установим путь к папке со структурами(отсюда они в дальнейшем будут браться) +Для простоты и сокращения кода установим путь к папке со структурами (отсюда они в дальнейшем будут загружаться): ```ts poolInstance.setPathStructures(/*ПОЛНЫЙ путь к папке со структурами*/); ``` Загрузка структуры -Важно дополнительный раз уточнить, что формат структуры указывать не обезательно, **по умолчанию везде используется DungeonUtility** ```ts poolInstance.upload(/*имя файла*/, /*Формат структуры, по умолчанию DungeonUtility*/); ``` +:::info + +Формат структуры указывать не обезательно, **по умолчанию используется DungeonUtility** +::: + Получение структуры, используется везде где нужна структура -> ВНИМАНИЕ! Загрзука структур не происходит сразу как вы используется upload +:::info + +ВНИМАНИЕ! Загрузка структур НЕ происходит сразу, как только используется `upload`. +::: Событие StructureLoadOne вызывается после загрузки структур, работаете со структурами тут! @@ -50,18 +56,18 @@ poolInstance.get(/*имя структуры*/); ### Пример использования ```ts -// Создаем StructurePool, обратите внимание, что у каждого мода должен быть свое уникальное имя StructurePool!!!!!!!!! +// Создаем StructurePool, ОБРАТИТЕ ВНИМАНИЕ, что у каждого мода должно быть свое уникальное имя StructurePool! let examplePool = new StructurePool("example_pool"); -// Устанавливаем путь к папке со структурами, в данном случае папка structures в главное директории мода +// Устанавливаем путь к папке со структурами, в данном случае папка structures в главной директории мода examplePool.setPathStructures(__dir__+"structures"); -// Загружаем структуру test_structure.struct из папки указаной выше, структура будет доступна по имени test_structure +// Загружаем структуру 'test_structure.struct' из папки указанной выше, структура будет доступна по имени test_structure examplePool.upload("test_structure"); -// Загружаем структуру test_structure.struct из папки указаной выше, структура будет доступна по имени legacy_structure +// Загружаем структуру 'legacy_structure.struct' из папки указанной выше, структура будет доступна по имени legacy_structure // Обратите внимание, что в данном примере используется формат файла Structures examplePool.upload("legacy_structure", "Structures"); -// Загружаем структуру test_structure_folder.struct из папки указаной выше + папка указанае тут внизу, структура будет доступна по имени test_structure_folder +// Загружаем структуру 'test_structure_folder.struct' из папки указанной выше и папки указанной тут, структура будет доступна по имени test_structure_folder examplePool.upload("folder/test_structure_folder");