DC Render API

DC Render API

DC Render API — продвинутая библиотека рендеринга и анимации частиц для модов Minecraft. Она предоставляет полноценную, готовую к продакшену визуальную систему для управляемых частиц, групп частиц, эмиттеров, стилей, барражей, display-сущностей, таймлайнов с easing и лёгкой шины событий — и идёт в комплекте со встроенной стратегией обхода агрессивного отсечения addParticle со стороны клиентских оптимизационных модов вроде Embeddium / Rubidium / Inventory Particles. Проект поддерживает Forge 1.20.1 / Fabric 1.20.1 / NeoForge 1.21.1 с полным паритетом функций на всех трёх загрузчиках.

跳转至中文文档: README.md

Поддержка платформ

⚠ Обязательная установка трёх jar-файлов для каждого загрузчика: установите адаптер языка Kotlin + jar DC Render API + основной мод, который его использует (например, Dragon Curse Chronicles). Если чего-то из трёх не хватает, игра упадёт при загрузке.

Основные возможности

Главные функции

• Система управляемых частиц: экземпляры частиц отслеживаются по стабильному id с явным жизненным циклом и флагом dead.
• Система анимации частиц: движение по круговой орбите, спиральной орбите, волновое движение, случайное блуждание, easing-функции и интерполяция по ключевым кадрам таймлайна.
• Синхронизация частиц между сервером и клиентом: два выделенных сетевых пакета (ParticleGroupPacket, ParticleSyncPacket) гарантируют одинаковую картину у всех клиентов.
• Управление группами частиц: ServerParticleGroupManager / ClientParticleGroupManager для пакетного создания / тика / уничтожения.
• Система эмиттеров частиц: интерфейс ParticleEmitter + ParticleEmitterManager с настройками частоты и скорости.
• Система стилей частиц: ParticleStyle для размера / альфы / RGB / времени жизни; createStyle + applyStyleToParticle.
• Система барражей: BarrageManager поддерживает сложные паттерны, включая круговые барражи.
• Система display-сущностей: лёгкая обёртка вокруг Display Entities из Minecraft: DisplayEntity + DisplayEntityManager.
• Система эффектов: Effect + EffectManager объединяет несколько частиц + анимаций в один переиспользуемый блок.
• Система событий: лёгкие EventBus + ParticleEventBus; хуки на столкновение, попадание, нахождение на земле, вход в жидкость.
• Система шума: PerlinNoise для естественной случайности.
• Умный диспетчер частиц (впервые реализован в хост-моде для NeoForge): пакетная обработка с учётом кадров + затухание по LOD + пулинг объектов + прогрессивная эмиссия + обход пакетов на дальних дистанциях; обходит агрессивное отсечение со стороны клиентских модов для частиц.

Эффекты анимации

• Круговая орбита
• Спиральная орбита
• Волновое движение
• Случайное блуждание
• Функции плавности (Linear, Quad, Cubic, Quart, Quint, Sine, Expo, Circ, Back, Elastic, Bounce …)
• Интерполяция по таймлайну (позиция, масштаб, поворот, цвет)
• Композиция / слоёная анимация

Структура проекта

DC Render API/                                  # Отдельный монорепозиторий (этот каталог)
├── src/                                        # Исходники Forge 1.20.1
│   └── main/
│       ├── java/com/qituo/dcrapi/              # Java-слой: вход мода, предметы, сеть, частицы, платформа
│       │   ├── DcRenderApi.java                #   Точка входа Forge @Mod
│       │   ├── items/ParticleTesterItem.java   #   внутриигровой отладчик частиц
│       │   ├── network/*                       #   пакеты синхронизации сервер → клиент
│       │   ├── particles/
│       │   │   ├── emitters/*                  #   интерфейс эмиттера + менеджер
│       │   │   ├── style/*                     #   интерфейс стиля + менеджер
│       │   │   ├── DcRenderApiParticleManager.java  # потокобезопасный реестр частиц
│       │   │   ├── ControlableParticle.java
│       │   │   └── ServerParticleGroup*.java
│       │   └── platform/DcRenderApiServices.java
│       └── kotlin/com/qituo/dcrapi/            # Kotlin-слой: анимация, барражи, цвет, конфиг, отображение, эффекты, события, математика, шум, рендер, формы, команды, билдер, композиция
│           ├── animation/timeline/             #   Таймлайн: Eases.kt, Timeline.kt, DoubleConstTimeAnimator, ValueConstTimeAnimator
│           ├── barrages/ color/ config/ display/ effects/ event/ math/ noise/
│           ├── particles/builder/ParticleGroupBuilder.kt  # Рекомендуемый API-билдер
│           ├── particles/command/  particles/composition/  particles/emitters/  particles/style/
│           └── render/ shapes/
├── fabric/DC Render API/                       # Исходники Fabric 1.20.1 (паритет функций)
│   ├── src/main/java/                          #   частицы Fabric, сеть, предметы, mixin, клиентский инициализатор
│   ├── src/main/kotlin/                        #   та же структура Kotlin-подсистем, что и в Forge
│   ├── src/main/resources/fabric.mod.json      #   метаданные Fabric
│   └── build.gradle / gradle.properties
├── neoforge/                                   # Исходники NeoForge 1.21.1 (паритет функций)
│   ├── src/main/java + kotlin/                 #   портировано на 1.21.1 DataComponents / Holder / Codec / NeoForge.EVENT_BUS
│   └── build.gradle / gradle.properties
├── LICENSE.md                                  # Лицензия MIT (зеркало отдельного репозитория на GitHub)
├── build.gradle                                # сборка Forge 1.20.1; регистрирует задачу 'sourcesJar'
├── gradle.properties                           # mod_version=0.2.0, mod_id=dcrapi, mod_license=MIT
├── gradlew / gradlew.bat / gradle/             # Gradle Wrapper
└── settings.gradle

Установка (для игрока)

Forge 1.20.1

1. Установи Minecraft Forge 1.20.1 (47.x или новее).

2. Скачай все три jar-файла и положи их в папку mods/:

   • Адаптер Kotlin: Kotlin-for-Forge-*-1.20.1.jar (CurseForge / Modrinth)
   • DC Render API: dcrapi-0.2.0-1.20.1Forge.jar
   • Мод-потребитель (например, Dragon Curse Chronicles издание для Forge)
3. Запусти игру.

Fabric 1.20.1

1. Установи Fabric Loader 0.16.13+ и Fabric API 0.92.11+1.20.1.

2. Скачай все три jar-файла и положи их в папку mods/:

   • Адаптер Kotlin: fabric-language-kotlin-* (CurseForge / Modrinth)
   • DC Render API: dcrapi-0.2.0-1.20.1Fabric.jar
   • Мод-потребитель (например, Dragon Curse Chronicles издание для Fabric)
3. Запусти игру.

NeoForge 1.21.1

1. Установи NeoForge 21.1.248+ для Minecraft 1.21.1.

2. Скачай все три jar-файла и закинь их в папку mods/:

   • Адаптер Kotlin: Kotlin-for-Forge-*-1.21.1-NeoForge.jar (thedarkcolour)
   • DC Render API: dcrapi-1.0.0-1.21.1NeoForge.jar
   • Использующий мод (например, Dragon Curse Chronicles издание для NeoForge)
3. Запусти игру.

Быстрый старт (интеграция в собственный мод)

Матрица требований

Сборка артефактов для всех трёх загрузчиков

# ============ Forge 1.20.1 ============
cd "DC Render API"
./gradlew build               # outputs → build/libs/dcrapi-0.2.0-1.20.1Forge.jar and -sources.jar

# ============ Fabric 1.20.1 ============
cd "DC Render API/fabric/DC Render API"
./gradlew build               # outputs → build/libs/dcrapi-0.2.0-1.20.1Fabric.jar and -sources.jar

# ============ NeoForge 1.21.1 ============
cd "DC Render API/neoforge"
./gradlew build               # outputs → build/libs/dcrapi-1.0.0-1.21.1NeoForge.jar and -sources.jar

Все три скрипта build.gradle регистрируют задачу sourcesJar, так что -sources.jar создаётся автоматически при каждой сборке.

Основное использование (для Java-моддеров)

1. Создание группы частиц через Builder (рекомендуется)

import com.qituo.dcrapi.particles.builder.ParticleGroupBuilder;
import com.qituo.dcrapi.particles.ServerParticleGroup;
import net.minecraft.server.level.ServerLevel;
import net.minecraft.world.phys.Vec3;

ServerLevel level = ...;
Vec3 pos = player.position();

ServerParticleGroup group = new ParticleGroupBuilder()
    .position(pos)
    .world(level)
    .scale(2.0)
    .visibleRange(128.0)
    .maxTick(200)
    .buildAndRegister();

2. Создание управляемой частицы (синхронизация сервер → клиент)

import com.qituo.dcrapi.particles.DcRenderApiParticleManager;
import net.minecraft.core.particles.ParticleTypes;

int pid = DcRenderApiParticleManager.createParticle(
    ParticleTypes.FLAME,
    ParticleTypes.FLAME.get(),
    new Vec3(0, 64, 0)
);

3. Анимации круговой и спиральной орбиты

import com.qituo.dcrapi.particles.ParticleAnimation;
import net.minecraft.world.phys.Vec3;

Vec3 center = player.position();
Vec3 orbitPos  = ParticleAnimation.createCircleOrbit(center, 2.0, 0.1, tick);
Vec3 spiralPos = ParticleAnimation.createSpiralOrbit(center, 1.0, 3.0, 0.1, tick);

4. Событие попадания частицы (нанесение урона)

import com.qituo.dcrapi.event.ParticleEventBus;
import com.qituo.dcrapi.event.ParticleEvents.ParticleHitEntityEvent;

ParticleEventBus.INSTANCE.register(ParticleHitEntityEvent.class, ev -> {
    ev.getTarget().hurt(ev.getTarget().level().damageSources().magic(), 5.0F);
});

Типы событий:

5. Система стилей частиц

import com.qituo.dcrapi.particles.style.ParticleStyleManager;
import net.minecraft.world.phys.Vec3;

int styleId = ParticleStyleManager.createStyle(
    1.0F,    // size
    0.5F,    // alpha
    new Vec3(1, 0, 0), // color (RGB)
    2.0      // lifetime in seconds
);
ParticleStyleManager.applyStyleToParticle(pid, styleId);

6. Таймлайн и easing (удобно для Kotlin, но Java тоже работает)

import com.qituo.dcrapi.animation.timeline.Timeline;
import com.qituo.dcrapi.animation.timeline.Eases;

Timeline tl = new Timeline();
tl.addPositionAnimation(startPos, endPos, 200, Eases.INSTANCE.getEaseInOutCubic());
tl.addScaleAnimation(1.0F, 2.0F, 200, Eases.INSTANCE.getEaseOutBounce());
tl.start();

### 7. Файл конфигурации (`config/dcrapi_config.properties`)
```properties
maxParticleGroups=1000       # Верхняя граница активных групп частиц
defaultVisibleRange=64.0     # Резервная дальность видимости в блоках
particleTickRate=1            # Частота тиков
enableParticleEvents=true     # Включает рассылку ParticleEventBus
enableDebugLogging=false      # Подробный вывод логов

Производительность и потокобезопасность

Советы по производительности

1. Настройте visibleRange: держите значение между 32 и 128 блоками; большие значения быстро раздувают трафик и стоимость отрисовки.
2. Покадровая / постепенная эмиссия: для взрывных эффектов с >1000 частиц используйте паттерн очереди в стиле SmartParticleDispatcher (см. эталонную реализацию в NeoForge Dragon Curse Chronicles) вместо спавна всего за один тик.
3. Своевременно чистите: планируйте периодический вызов ServerParticleGroupManager.clear() для удаления мёртвых групп.
4. Держите обработчики лёгкими: никогда не выполняйте I/O или тяжёлые вычисления внутри колбэков ParticleEventBus.

Гарантии потокобезопасности (в коде)

• ConcurrentHashMap<Integer, ControlableParticle> лежит в основе DcRenderApiParticleManager.PARTICLES.
• AtomicInteger nextParticleId для избежания гонок при выделении id.
• CopyOnWriteArrayList для списков обработчиков ParticleEventBus; безопасно итерировать во время регистрации.
• Паттерн пакетного удаления на тике: соберите id мёртвых частиц в список, затем вызовите removeAll разом — это обходит подвох слабой согласованности итератора ConcurrentHashMap.
• try/catch на каждую частицу: одна сбойная частица или обработчик пакетов никогда не сможет прервать весь тик.

Инструмент отладки в игре

Все три загрузчика регистрируют креативный предмет Particle Tester:

• ПКМ: заспавнить стандартную демонстрационную группу частиц (орбита + стиль + хук события).
• Shift + ПКМ: переключить режим отладки: Basic → Builder → Event → Basic …
• Хранение: активный тестовый режим теперь сохраняется в самом стаке предмета (CustomData / NBT) вместо JVM-статического поля — исправляет загрязнение состояния между руками и игроками.

Матрица совместимости

Сниппеты зависимостей сборки (build.gradle)

// Forge 1.20.1:
dependencies {
    implementation fg.deobf("com.qituo:dcrapi:0.2.0-1.20.1Forge")
}

// Fabric 1.20.1:
dependencies {
    modImplementation("com.qituo:dcrapi:0.2.0-1.20.1Fabric")
}

// NeoForge 1.21.1:
dependencies {
    implementation("com.qituo:dcrapi:1.0.0-1.21.1NeoForge")
}

Координаты Maven — это целевой формат; если ещё не загружены в Maven-репозиторий, положите jar-файлы в локальную папку libs/ и используйте files(...) как зависимость.

Известные потребители / реальное использование

Dragon Curse Chronicles — эталонный потребитель DC Render API от самих авторов:

• Лазер Pig Talisman / фаербол Dragon Talisman → круглая орбита + волновые следы частиц
• Лазер Uncle's Dried Puffer Fish → ~1200 частиц с двумя контрвращающимися градиентными спиралями, отправляемых постепенно через SmartParticleDispatcher
• Эффекты Origin Aura / активации талисманов → группы частиц + таймлайн-сглаживание

Руководство по миграции (0.1.x → 0.2.x)

Было (0.1.x):

ServerParticleGroup group = new ServerParticleGroup();
group.initServerGroup(pos, world);
group.scale = 1.5;
ServerParticleGroupManager.addParticleGroup(group, pos, world);

Стало (0.2.x, Builder):

ServerParticleGroup group = new ParticleGroupBuilder()
    .position(pos).world(world).scale(1.5).visibleRange(64.0).maxTick(100)
    .buildAndRegister();

Основные изменения в релизе 0.2.0:
- `mod_version=0.2.0`, лицензия MIT явно указана в `gradle.properties` + отдельный файл `LICENSE.md`.
- Все три сборки под загрузчики регистрируют задачу `sourcesJar`; `-sources.jar` создаётся при каждой сборке.
- `ParticleTesterItem`: состояние тестового режима перенесено из статического поля JVM в `CustomData / NBT` стака предмета; устранено перетекание состояния между игроками.
- `DcRenderApiParticleManager`: `nextParticleId` изменён с обычного `int` → `AtomicInteger`; удаление по тику переведено на шаблон пакетного удаления для большей согласованности.

---

## Лицензия и авторы

Выпущено под **лицензией MIT** — см. официальный отдельный текст лицензии в [LICENSE.md на GitHub](https://github.com/19136644525lxy/DC-Render-API/blob/22c6b3a66ec7885f6eea4698329fe4129cd0766b/LICENSE.md).

- **Текущая версия**: Forge `0.2.0` / Fabric `0.2.0-1.20.1Fabric` / NeoForge `1.0.0` (номера версий независимы для каждого загрузчика)
- **Авторы**: QiTuo, Yifei
- **Репозиторий с исходным кодом**: https://github.com/19136644525lxy/DC-Render-API
- **Распространение**: [CurseForge](https://www.curseforge.com/minecraft/mc-mods/dc-render-api) / [Modrinth](https://modrinth.com/mod/dc-render-api)