Dasik Library

🧠 Dasik Library

"Универсальная основа Hive Mind, обеспечивающая работу автономной генетики животных, динамических GameRules и высокопроизводительного стайного поведения в Minecraft."

📖 Введение

Разработка современных модов для Minecraft Fabric часто упирается в одни и те же архитектурные препятствия: регистрация динамических GameRules на лету без блокировки неизменяемых реестров, синхронизация генетики и масштаба животных между сохранениями мира, организация ИИ стай и скоплений без просадки тикрейта сервера и интеграция опциональных клиентских GUI настроек без фатальных крашей ClassNotFoundException на headless выделенных серверах.

Dasik Library — это универсальная самостоятельная основа, созданная для решения этих задач. Она предоставляет высокопроизводительный архитектурный каркас, на котором работают все моды из коллекций Vanilla Outsider, Delayed Gratification и Instant Gratification. Спроектированная с упором на строго zero-allocation горячие пути, изоляцию через Knot ClassLoader и модульные API, она даёт разработчикам и игрокам фреймворк корпоративного уровня для современного Minecraft.

[!IMPORTANT] Это самостоятельная универсальная библиотека / API.

• Универсальный единый JAR: Dasik Library собирается в один универсальный кросс-версионный JAR (>=26.1.2-, сейчас v1.8.35) с чистым SemVer. Он без проблем загружается на Minecraft 26.1.2, 26.2, 26.3 и будущих снапшотах.
• Готовность и для клиента, и для выделенного сервера: Полностью совместима с одиночными клиентами и многопользовательскими выделенными серверами.
• Никакого лишнего геймплея: Сама по себе не добавляет произвольных игровых предметов или генерации мира. Она тихо работает в фоне, предоставляя общую инфраструктуру ИИ, генетики и реестров для зависимых модов.

✨ Возможности

🧬 API автономной генетики и разведения животных

• Постоянная генетика сущностей: Прикрепляет не зависящую от типа сущности модель генетических данных к живым сущностям через постоянные attachment'ы Fabric (dasik-library:genetics), сохраняя родословную, UUID и поколенческие признаки между сохранениями мира.
• Треугольные мутации и восстановление через ауткроссинг: Реализует естественную биологическую математику разведения, включая треугольное распределение мутаций, усреднение признаков родителей, многоуровневые штрафы за инбридинг и генетическое восстановление через ауткроссинг.
• Конструктор размеров и связанные атрибуты: Позволяет легко привязать физический масштаб сущности (minecraft:scale, настраивается от 0.1f до 3.0f) к вторичным атрибутам (максимальное здоровье, скорость передвижения, урон атаки) через LinkedAttributeRegistry с линейным, обратным или квадратичным масштабированием.
• Изменение лута на основе генетики: Использует GeneticsLootRegistry и хуки лута для динамического масштабирования дропа, выхода мяса и ресурсов в зависимости от размера сущности и генетической жизнеспособности.

⚙️ Динамическая регистрация GameRule и движок авто-перевода

• Разморозка реестра по требованию: Безопасно размораживает BuiltInRegistries.GAME_RULE во время выполнения через MappedRegistryAccessor, позволяя модам-потребителям и аддонам регистрировать собственные GameRules без гонок при запуске и блокировок реестра.
• Автоматическая инъекция переводов: Динамически генерирует человекочитаемые ключи переводов и внедряет их напрямую в ванильную карту Language (dasik$injectDynamicGameRuleTranslations), устраняя отсутствующие заполнители строк (включая жирное форматирование категорий §l).
• Сохранение в файле мира: Незаметно перехватывает сериализацию SavedData (GameRuleMapMixin), гарантируя, что динамические изменения GameRule через /gamerule надёжно сохраняются в level.dat и game_rules.dat.
• Автоматическая очистка осиротевших правил: Подключается к ServerLifecycleEvents.SERVER_STARTING, чтобы обнаруживать и аккуратно удалять осиротевшие динамические GameRules, оставшиеся после удаления модов, сохраняя файлы мира в чистоте.
• Помощники математических преобразований: Встроенные утилиты расчёта процентов, промилле и децилей (getPct, getChance, getProb, getDecileFloat).

🦅 Высокопроизводительный ИИ стай и стайного движения (кэшированные Boids)

• Паттерн лидер-последователи $O(N)$: Устраняет дорогостоящие попарные проверки расстояний $O(N^2)$, вычисляя и кэшируя метрики группы (FlockState) исключительно на лидере стаи, что обеспечивает плавные стаи из 100+ сущностей при стабильных 20 TPS.
• Биомеханическое рулевое управление: Полные расчёты векторного управления выравниванием, сплочённостью и разделением для реалистичных воздушных мурмураций (AerialFlockingStrategy) и наземного движения стай (TerrestrialFlockingStrategy).
• Устойчивое следование: Встроенный обход штрафа за навигацию в воде и пороги телепортации для догона, чтобы члены стаи никогда не терялись на границах чанков.

📡 Коллективный разум и развязанная шина сигналов

• Развязанные социальные сигналы: Высокопроизводительная SignalBus позволяет мобам отправлять и получать оповещения, предупреждения и обновления настроения между видами без жёстко прописанных связей классов.
• Изоляция областей: Адресная доставка сигналов (Scope.SAME_SPECIES, Scope.HERD, Scope.GLOBAL) с безопасными проверками экземпляров.
• Архитектура ленивой заморозки: Решает гонки при инициализации модов, позволяя модулям регистрировать социальные события во время инициализации мода, при этом безопасно блокируя реестр на тике сервера.

🖥️ Опциональная интеграция GUI и безопасность ClassLoader сервера

• Изолированный ClassLoader-ом резолвер экрана конфигурации: GuiHelper динамически обнаруживает и вызывает YetAnotherConfigLib (YACL) и Cloth Config через рефлексию и изоляцию Knot ClassLoader.
• 100% защита от крашей на выделенном сервере: Полностью предотвращает загрузку клиентских классов GUI на выделенных серверах, устраняя краши при запуске сервера.
• Стандартизированная поддержка создателей: Предоставляет DasikSupportHelper для встраивания стандартизированных кнопок поддержки создателей под индексом 0 на страницах категорий экрана конфигурации.

🛡️ Корпоративная стабильность и горячие пути с нулевым выделением памяти

• Независимая от зависимостей защита версий: ModVersionGuard проверяет совместимость среды выполнения Minecraft при запуске и отображает человекочитаемые диагностические рекомендации, если обнаружена несовместимая версия API.
• Атомарное сохранение файлов: ConfigHelper управляет операциями чтения/записи JSON с использованием атомарной замены временных файлов и автоматической генерации резервных копий.
• Рендеринг с нулевым выделением: Архитектура с нулевым выделением байтов в куче на высокочастотных путях тиков и рендеринга.

📊 Краткий справочник и матрица механик

🚀 Быстрый старт для разработчиков и руководство по внедрению

Интеграция Dasik Library в ваш собственный мод на Fabric занимает всего несколько строк кода:

1. Настройка Gradle

Добавьте репозиторий Modrinth Maven и объявите зависимость в вашем build.gradle:

repositories {
    maven {
        name = "Modrinth"
        url = "https://api.modrinth.com/maven"
    }
}

dependencies {
    modImplementation "maven.modrinth:dasik-library:1.8.35"
}

2. Регистрация динамического GameRule

Зарегистрируйте GameRule с автоматическим переводом на английский и выделением категории жирным:

import net.dasik.social.api.gamerule.DynamicGameRuleManager;

// Registers 'my_mod:drop_multiplier' with a default value of 2 under the 'Gameplay' category
DynamicGameRuleManager.registerIntegerRule(
    "my_mod:drop_multiplier",
    2,
    "Drop Multiplier",
    "Gameplay"
);

3. Привязка размера животного к здоровью и скорости

Свяжите физический размер с боевыми характеристиками и подвижностью:

import net.dasik.social.api.genetics.SizeStatsBuilder;
import net.dasik.social.api.genetics.LinkMode;
import net.minecraft.world.entity.ai.attributes.Attributes;

SizeStatsBuilder.create("my_mod:beast_genetics")
    .linkAttribute(Attributes.MAX_HEALTH, LinkMode.PROPORTIONAL, 2.0f)
    .linkAttribute(Attributes.MOVEMENT_SPEED, LinkMode.INVERSE, 0.5f)
    .register();

4. Динамическое сканирование реестров

Безопасно отслеживайте и обрабатывайте новые записи реестра, добавленные другими модами:

import net.dasik.social.api.registry.DynamicRegistryScanner;
import net.minecraft.core.registries.BuiltInRegistries;

DynamicRegistryScanner.subscribe(BuiltInRegistries.ITEM, item -> {
    // Process new modded items dynamically on startup and live reload
});

⚙️ Основная конфигурация и архитектура сохранений

[!IMPORTANT] 💡 Конфиг vs. GameRules в игре: Глобальный файл конфигурации задаёт значения по умолчанию только для новых миров. В существующих мирах меняйте настройки прямо в игре через экран Edit Game Rules или команду /gamerule.

Dasik Library управляет состояниями динамических GameRule прямо в файлах сохранения вашего мира:

• Хранение в мире: Хранится в <world_save>/data/game_rules.dat и level.dat.
• Никакого мусора: Когда вы удаляете мод, регистрировавший динамические правила, движок очистки при запуске Dasik Library обнаруживает отсутствующий namespace и снимает с регистрации осиротевшие записи, предотвращая спам в консоли и раздувание файлов сохранения.

📖 Подробное руководство и плейбук по интеграции

1. Для выживальщиков и администраторов серверов

1. Скачайте dasik-library-1.8.35.jar (или последний релиз).
2. Поместите JAR прямо в папку .minecraft/mods вместе с Fabric API.
3. Запустите Minecraft. Dasik Library работает тихо и эффективно в фоне, предоставляя базовые сервисы для ваших установленных модов.
4. При настройке GameRules в игре через экран Edit Game Rules или /gamerule все правила, зарегистрированные модами на базе Dasik, автоматически переводятся, организуются по категориям и сохраняются прямо в файл мира.

2. Для создателей модпаков

1. Универсальная поддержка нескольких версий: Вам не нужны отдельные сборки Dasik Library для минорных патчей Minecraft — одна сборка работает с MC 26.1.2, 26.2 и 26.3+.
2. Безопасно для серверов: Включайте Dasik Library и в клиентские, и в серверные модпаки, не боясь крашей клиентского GUI.
3. Чистое обновление миров: При обновлении модпаков и удалении устаревших модов библиотека автоматически вычищает осиротевшие GameRules при следующем запуске сервера.

3. Для разработчиков модов

1. Объявите dasik-library в вашем fabric.mod.json:

   "depends": {
    "fabricloader": ">=0.16.10",
    "minecraft": ">=26.1.2-",
    "fabric-api": "*",
    "dasik-library": ">=1.8.15"
   }

2. Используйте DynamicGameRuleManager, чтобы не писать повторяющийся шаблонный код GameRule и файлы переводов.
3. Используйте GuiHelper, чтобы предоставить опциональные GUI для YACL или Cloth Config, которые бесшовно открываются через ModMenu, сохраняя 100% безопасность на сервере.

🧩 Рекомендуемые моды-компаньоны и проекты на движке

Dasik Library служит движком для множества популярных модов. Ознакомьтесь с этими проектами, работающими напрямую на этой библиотеке:

• 📜 Collapsible Game Rules: Превращает экран редактирования игровых правил в сворачиваемые категории с поиском в реальном времени, используя динамические метаданные Dasik Library.
• 🐕 Better Dogs: Полная переработка поведения собак с интеллектом личности, стайным взаимодействием и ездой на транспорте на базе ИИ-движка стайности Dasik Library.
• 🌿 Natural Reproduction: Автономный движок размножения и генетики 27 видов диких животных, построенный непосредственно на Dasik Animal Genetics.

🌟 Загляните в мой профиль — там больше улучшений ванильной игры, утилит для производительности и переработок геймдизайна.

💬 Присоединяйтесь к сообществу и получайте поддержку

☕ Поддержка

Если вам нравится эта экосистема, поддержите будущие обновления!

[!NOTE] 🇮🇩 Пользователям из Индонезии: SocioBuzz и Saweria поддерживают местные способы оплаты (Gopay, OVO, Dana и т.д.), если вы хотите поддержать меня без использования PayPal/Ko-fi!

📜 Благодарности и разрешения для модпаков

[!IMPORTANT] 📦 Разрешения для модпаков и распространение:
Вы можете свободно включать этот мод в любой модпак на любой платформе! Однако файл мода должен загружаться напрямую через официальные каналы распространения (Modrinth или CurseForge). Перезагрузка, зеркалирование или распространение оригинального JAR-файла мода на сторонних зеркалах, сайтах-скраперах или несанкционированных лаунчерах строго запрещено.

⚖️ Лицензия и правила форков (без перезагрузок без изменений):
Этот проект с открытым исходным кодом под GNU GPLv3. Мы полностью приветствуем изучение кода, обучение на нём и форк репозитория для создания настоящих модификаций, существенных расширений функционала или портов для сообщества — при условии, что ваш проект остаётся открытым под GPLv3 с надлежащей атрибуцией.
Однако прямые перезагрузки 1:1, форки-клоны без значимых функциональных изменений или повторная публикация идентичных сборок под другими названиями проектов (например, ради накрутки загрузок или наград) строго запрещены.