bbub

ДОКУМЕНТАЦИЯ МОДА EXAMPLE MOD
==============================

Документ описывает фактическое состояние проекта и реализованные изменения.
Основной язык проекта — Java, платформа — NeoForge.


1. ОБЩАЯ ИНФОРМАЦИЯ
--------------------

Мод предназначен для Minecraft 1.21.1 и NeoForge 21.1.235.

Идентификаторы и версия:

- mod id: examplemod
- отображаемое имя: Example Mod
- версия мода: 1.0.0
- основной пакет: com.example.examplemod
- Java: 21

Основная идея мода — добавить набор специальных зачарований для добычи:

- Drill — массовое разрушение блоков в направлении взгляда;
- Orebot — автоматическая добыча связанной жилы руды;
- Auto Smelting — автоматическая переплавка дропа;
- Lumberjack — массовая рубка связанных брёвен;
- Efficiency Plus — дополнительное ускорение инструментов;
- Magnet — притягивание выпавших предметов.

Зачарования работают на обычных инструментах Minecraft. Отдельные предметы
«спец-кирка» для основной механики не используются. Классы DrillItem и
OrebotItem сохранены только как старый legacy-код и не являются главным
путём работы текущей системы.


2. ЧТО БЫЛО СДЕЛАНО
--------------------

В проекте реализована единая система кастомных зачарований на базе
компонентов предметов Minecraft 1.21.1:

1. Зарегистрированы шесть зачарований и их JSON-описания.
2. Логика добычи перенесена на события NeoForge.
3. Добавлены книги зачарований в отдельную творческую вкладку.
4. Добавлена обработка объединения книг и наложения зачарований через
   наковальню.
5. Добавлены команды для выдачи зачарований на предмет в главной руке.
6. Добавлен случайный бонус кастомного зачарования при зачаровании книги
   в обычном столе зачарований.
7. Реализованы частицы при массовой добыче и автоплавке.
8. Для зачарований настроены ограничения по типам инструментов.
9. Добавлена несовместимость Efficiency Plus с обычной Efficiency.
10. Реализована работа Magnet одновременно с главной и дополнительной рукой.
11. Добавлены русские названия и творческая вкладка «Инструменты шахтёра».

Главные файлы:

- ExampleMod.java — регистрация мода, зачарований, вкладки и книг;
- OrebotEvents.java — вся основная игровая логика и обработчики событий;
- CustomEnchantCommand.java — команды /customenchant и /givecustomenchant;
- CustomEnchantmentBookItem.java — вспомогательная логика зачарованных книг;
- ExampleModClient.java — клиентский экран конфигурации;
- Config.java — шаблон общей конфигурации NeoForge.


3. ЗАЧАРОВАНИЯ
---------------

3.1. Drill

Предназначено только для кирок.

- Drill I ломает область 3x3x1.
- Drill II ломает область 3x3x2.
- Область ориентируется по направлению взгляда игрока.
- Для взгляда по горизонтали область строится поперёк направления взгляда.
- Для взгляда вверх или вниз учитывается вертикальная ориентация.
- Обрабатываются только непустые блоки с допустимой скоростью разрушения.
- Каждый успешно разрушенный блок учитывается в износе инструмента.
- При разрушении появляются фиолетовые частицы PORTAL.

Область строится относительно исходной позиции. При Drill II второй слой
располагается в направлении взгляда, поэтому зачарование не просто расширяет
площадь, а добавляет глубину.

Drill и Orebot взаимно несовместимы в JSON-описаниях зачарований.


3.2. Orebot

Предназначено только для кирок.

- Срабатывает только при разрушении руды.
- Рудой считается блок, путь идентификатора которого заканчивается на _ore.
- Дополнительно распознаётся ancient_debris.
- Для поиска соседей используется полный объём 3x3x3, то есть до 26 соседних
  позиций вокруг каждого блока.
- Используется обход связной компоненты в ширину.
- Обход продолжается, пока находятся соседние распознаваемые руды.
- Нерудные блоки обычным способом не отменяются и не ломаются Orebot.
- За успешную массовую добычу инструмент получает износ не менее 2 единиц
  и далее по формуле 2 единицы за каждый добытый блок.
- При добыче появляются фиолетовые частицы PORTAL.

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


3.3. Auto Smelting

Предназначено только для кирок.

При разрушении подходящего блока обработчик:

1. Получает стандартный список дропа блока.
2. Для каждого предмета ищет рецепт типа SMELTING.
3. Если рецепт найден, заменяет дроп результатом плавки.
4. Если рецепта нет, оставляет исходный предмет.
5. Выбрасывает получившийся предмет около разрушенного блока.

Количество результата учитывает количество исходных предметов и количество
предметов, выдаваемых рецептом. За блок списывается 1 единица прочности.
При работе появляются:

- PORTAL — общая фиолетовая частица;
- FLAME — визуальная частица автоплавки.

Автоплавка использует обычные рецепты печи Minecraft, поэтому отдельная
таблица рецептов для мода не создаётся.


3.4. Lumberjack

Предназначено только для топоров.

- Lumberjack I ломает до 16 связанных брёвен.
- Lumberjack II ломает до 48 связанных брёвен.
- Проверяются шесть соседних направлений: вверх, вниз, север, юг, восток,
  запад.
- Целевыми блоками считаются блоки тега minecraft:logs.
- Листья сами по себе не являются целью и не ломаются.
- За каждое успешно разрушенное бревно списывается 1 единица прочности.

Поиск идёт в ширину и останавливается после достижения лимита уровня.
Зачарование не пытается удалять всю крону дерева.


3.5. Efficiency Plus

Работает на кирках, топорах, лопатах и инструментах из тега
examplemod:efficiency_tools.

- Максимальный уровень: VIII.
- Ускорение добавляется через событие PlayerEvent.BreakSpeed.
- Формула:

  новая скорость = текущая скорость + уровень * уровень + 1

Примеры добавки к скорости:

- уровень I: +2;
- уровень II: +5;
- уровень VI: +37;
- уровень VII: +50;
- уровень VIII: +65.

Efficiency Plus несовместимо с обычным ванильным Efficiency. Ограничение
задано и в JSON зачарования, и дополнительно проверяется:

- в обработчике наковальни;
- в командах;
- при выборе применимых зачарований.


3.6. Magnet

Работает на инструментах добычи и мечах:

- кирка;
- топор;
- лопата;
- мотыга;
- меч.

Механика запускается в PlayerTickEvent.Post на сервере, один раз в два тика.
Magnet не использует событие разрушения блока и не отменяет обычную добычу.

Параметры:

- Magnet I: радиус 6 блоков, скорость притягивания 0.22;
- Magnet II: радиус 12 блоков, скорость притягивания 0.35.

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

Magnet II игнорирует распространённый строительный и шахтёрский мусор:

stone, cobblestone, gravel, diorite, andesite, granite, netherrack, dirt,
sand, red_sand, soul_sand, tuff, basalt, blackstone, end_stone,
cobbled_deepslate и deepslate.

Magnet II можно получить объединением двух книг Magnet I в наковальне.
В творческой вкладке сразу доступны книги обоих уровней. Получение Magnet II
через обычный стол зачарований отдельно не гарантируется.


4. ОГРАНИЧЕНИЯ ПО ПРЕДМЕТАМ
----------------------------

Ограничения заданы в JSON-файлах и дополнительно проверяются в Java-коде.

Зачарование       Допустимые предметы
---------------------------------------------------------------
Drill             кирки
Orebot            кирки
Auto Smelting     кирки
Lumberjack        топоры
Efficiency Plus   кирки, топоры, лопаты, мотыги
Magnet            кирки, топоры, лопаты, мотыги, мечи

Теги предметов:

- data/examplemod/tags/item/efficiency_tools.json;
- data/examplemod/tags/item/magnet_tools.json.

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


5. КНИГИ И КРЕАТИВНАЯ ВКЛАДКА
------------------------------

Творческая вкладка мода называется «Инструменты шахтёра».
В ней создаются обычные ItemStack зачарованных книг с компонентами
Minecraft 1.21.1:

- STORED_ENCHANTMENTS — хранимые зачарования книги;
- ENCHANTMENT_GLINT_OVERRIDE — принудительное свечение книги.

Вкладка содержит:

- Drill I;
- Drill II;
- Orebot I;
- Auto Smelting I;
- Lumberjack I;
- Lumberjack II;
- Efficiency Plus VI;
- Efficiency Plus VII;
- Efficiency Plus VIII;
- Magnet I;
- Magnet II.

Книги создаются методом ExampleMod.createBookFor(...). Отдельная регистрация
каждой книги как нового предмета не требуется: это обычные ItemStack
minecraft:enchanted_book с нужным компонентом.

CustomEnchantmentBookItem оставлен как вспомогательный/legacy-класс. Текущая
творческая вкладка создаёт стандартный enchanted_book напрямую.


6. СТОЛ ЗАЧАРОВАНИЙ
--------------------

Обработчик PlayerEnchantItemEvent добавляет дополнительное поведение:

- если зачаровывается книга или зачарованная книга, есть шанс 12.5% добавить
  одно кастомное зачарование уровня I;
- случайный выбор идёт среди Drill, Orebot, Auto Smelting, Lumberjack и
  Magnet;
- зачарование добавляется в STORED_ENCHANTMENTS;
- книге принудительно включается свечение;
- если зачаровывается не книга, кастомные зачарования из обычного компонента
  предмета удаляются.

Это именно дополнительный шанс после обычной логики стола, а не замена
ванильного списка зачарований. Поэтому наличие зачарования на книге зависит
от случайности. Гарантированные источники — творческая вкладка, команда и
наковальня.


7. НАКОВАЛЬНЯ
-------------

Обработчик AnvilUpdateEvent читает кастомные зачарования из правого предмета,
обычно из книги, и переносит их на левый предмет.

Поддерживаются:

- применение книги к подходящему инструменту;
- объединение двух одинаковых уровней;
- повышение уровня при одинаковом уровне;
- объединение разных уровней с выбором большего;
- ограничение результата максимальным уровнем;
- объединение Magnet I + Magnet I в Magnet II;
- установка стоимости операции;
- расход одного правого предмета.

Правила повышения уровня:

- одинаковые уровни дают следующий уровень;
- разные уровни дают больший из уровней;
- результат не превышает максимум из JSON/игровой логики.

Максимальные уровни:

- Drill: II;
- Orebot: I;
- Auto Smelting: I;
- Lumberjack: II;
- Efficiency Plus: VIII;
- Magnet: II.

Наковальня не применяет:

- Lumberjack к предмету, который не является топором;
- Drill, Orebot и Auto Smelting к предмету, который не является киркой;
- Efficiency Plus к предмету с обычной Efficiency;
- неизвестные или некастомные зачарования через этот обработчик.

Обычные ванильные правила наковальни могут дополнительно влиять на итоговый
результат.


8. КОМАНДЫ
----------

Зарегистрированы две команды с одинаковой логикой:

  /customenchant <enchant> <level>
  /givecustomenchant <enchant> <level>

Требуется уровень разрешений 2. Команда работает с предметом в главной руке.
Диапазон аргумента level: от 1 до 10. Реальный игровой максимум всё равно
ограничивается обработчиками и JSON.

Примеры:

  /customenchant drill 1
  /customenchant drill 2
  /customenchant orebot 1
  /customenchant auto_smelting 1
  /customenchant lumberjack 2
  /customenchant efficiency_plus 8
  /customenchant magnet 1

Можно использовать полный идентификатор:

  /customenchant examplemod:magnet 1

Если namespace не указан, автоматически используется examplemod.
Команда выдаёт понятную ошибку, если:

- выполнена не игроком;
- зачарование неизвестно или не зарегистрировано;
- главная рука пуста;
- Efficiency Plus добавляется на предмет с обычной Efficiency.

Команда записывает зачарование в компонент ENCHANTMENTS предмета.


9. ОБРАБОТКА РАЗРУШЕНИЯ
------------------------

Главное событие — BlockEvent.BreakEvent.
Проверки выполняются в следующем порядке:

1. Обрабатывается только серверная сторона.
2. Проверяется предмет в главной руке.
3. Повторная обработка активной позиции блокируется.
4. Magnet пропускается отдельно: он не вмешивается в добычу.
5. Проверяется Orebot, если предмет — кирка и исходный блок является рудой.
6. Проверяется Drill, если предмет — кирка и блок можно разрушить.
7. Проверяется Lumberjack, если предмет — топор.
8. Проверяется Auto Smelting, если предмет — кирка и блок можно разрушить.
9. Если ни одно условие не выполнено, Minecraft использует обычную добычу.

Для дополнительных блоков используется tryBreak(...).
Набор ACTIVE_BREAKS защищает от повторного входа и рекурсивной обработки
одной и той же позиции при массовом разрушении.

Обычный блок не отменяется только из-за наличия кастомного зачарования.
Событие отменяется лишь тогда, когда конкретная механика действительно
перехватывает разрушение и сама обрабатывает блок.


10. ИЗНОС И ЧАСТИЦЫ
--------------------

Фактический износ инструмента:

- Drill: максимум 1 единица за каждый успешно разрушенный блок, минимум 1;
- Orebot: минимум 2 единицы, затем 2 единицы за каждый добытый блок;
- Lumberjack: 1 единица за каждое бревно;
- Auto Smelting: 1 единица за блок.

Для уменьшения прочности используется стандартный hurtAndBreak Minecraft.
Поэтому итог зависит также от текущей прочности инструмента и ванильных
механик.

Используемые частицы:

- PORTAL — фиолетовый эффект массовой добычи;
- FLAME — эффект Auto Smelting.


11. СТРУКТУРА РЕСУРСОВ
-----------------------

JSON зачарований:

  src/main/resources/data/examplemod/enchantment/

Файлы:

- drill.json;
- orebot.json;
- auto_smelting.json;
- lumberjack.json;
- efficiency_plus.json;
- magnet.json.

Теги предметов:

  src/main/resources/data/examplemod/tags/item/

Локализация:

  src/main/resources/assets/examplemod/lang/ru_ru.json
  src/main/resources/assets/examplemod/lang/en_us.json

Модели предметов:

  src/main/resources/assets/examplemod/models/item/

Основная Java-логика:

  src/main/java/com/example/examplemod/


12. КОНФИГУРАЦИЯ
-----------------

Config.java подключается как общая конфигурация NeoForge:

  run/client/config/examplemod-common.toml

В конфигурации шаблона присутствуют:

- logDirtBlock;
- magicNumber;
- magicNumberIntroduction;
- список items.

Эти параметры являются стандартным шаблонным конфигом MDK и не управляют
балансом кастомных зачарований. Радиус Magnet, лимиты Lumberjack и формулы
прочности сейчас задаются в Java-коде.

На клиенте зарегистрирован экран конфигурации через Mods -> Example Mod ->
Config. Класс ExampleModClient не загружается на dedicated server.


13. СБОРКА И УСТАНОВКА
----------------------

Сборка из корня проекта:

  gradlew.bat build

Главный результат:

  build/libs/examplemod-1.0.0.jar

JAR нужно скопировать в папку mods соответствующего клиента или сервера.
После замены JAR требуется полностью перезапустить игру/сервер.
Команда /reload не перезагружает Java-код мода.

Если проверяется поведение и оно не изменилось, нужно убедиться, что:

- запущен новый JAR;
- старый JAR не лежит рядом в папке mods;
- версия Minecraft — 1.21.1;
- версия NeoForge совместима с 21.1.235;
- зачарование находится на предмете в главной руке, кроме Magnet, который
  дополнительно проверяет вторую руку.


14. ИЗВЕСТНЫЕ НЮАНСЫ И ОГРАНИЧЕНИЯ
-----------------------------------

1. Система использует современные компоненты Minecraft 1.21.1, а не старый
   NBT-подход. Зачарования книги хранятся в STORED_ENCHANTMENTS, а
   зачарования инструмента — в ENCHANTMENTS.

2. Команда принимает уровни от 1 до 10, но фактический максимум каждого
   зачарования ниже и контролируется отдельно.

3. Запись кастомного зачарования командой на неподходящий предмет возможна на
   уровне компонента, но игровой эффект на таком предмете не активируется.
   Наковальня дополнительно запрещает такое применение.

4. Drill и Orebot взаимоисключающие зачарования. Efficiency Plus
   взаимоисключимо с ванильным Efficiency.

5. Orebot распознаёт руды по имени блока, а не по универсальному тегу руд.
   Поэтому нестандартная руда другого мода будет обработана только в случае,
   если её registry path заканчивается на _ore.

6. Auto Smelting работает только для рецептов типа SMELTING. Рецепты
   blast furnace, smoker и сторонние типы рецептов отдельно не используются.

7. Lumberjack распознаёт только minecraft:logs. Специальные блоки дерева,
   не входящие в этот тег, не будут обработаны.

8. Magnet притягивает уже выпавшие ItemEntity. Он не создаёт дополнительные
   предметы и не меняет лут сам по себе.

9. Magnet II фильтрует только явно перечисленные предметы. Другой мусор,
   отсутствующий в списке, может притягиваться.

10. Класс CustomEnchantmentBookItem существует, но книги текущей творческой
    вкладки создаются как обычные minecraft:enchanted_book. Это сделано для
    совместимости с компонентами и стандартной логикой Minecraft.

11. Классы DrillItem и OrebotItem относятся к старой архитектуре с отдельными
    предметами. Для текущей механики их изменять не нужно, если не планируется
    возвращение отдельных специальных инструментов.

12. Обычный стол зачарований не обязан показывать кастомные зачарования среди
    своих стандартных вариантов. Кастомное зачарование для книги добавляется
    отдельным случайным событием с шансом 12.5%.


15. КРАТКАЯ СХЕМА РАБОТЫ
-------------------------

Регистрация:

  ExampleMod
      -> ResourceKey зачарований
      -> творческая вкладка
      -> команды
      -> общая конфигурация

Игровые события:

  OrebotEvents
      -> BreakEvent: Drill / Orebot / Lumberjack / Auto Smelting
      -> BreakSpeed: Efficiency Plus
      -> PlayerTickEvent: Magnet
      -> PlayerEnchantItemEvent: бонус для книг
      -> AnvilUpdateEvent: книги и объединение уровней

Ресурсы:

  enchantment/*.json
      -> ограничения, максимальные уровни, стоимость, совместимость

  tags/item/*.json
      -> группы инструментов для Efficiency Plus и Magnet

Таким образом, текущий проект является функциональным модом для ускоренной
добычи и обработки ресурсов, где все основные эффекты реализованы через
обычные инструменты, серверные события NeoForge и компоненты предметов
Minecraft 1.21.1.