DC Render API

模组

· 作者 Yifei061004

DC Render API:专为《Dragon Curse Chronicles》打造的自定义图形 API,提供独家视觉效果。

0 本站下载 0 关注 更新于 1 个月前

需要前置:Kotlin for Forge

最新 1.0.0 · 1.21.1 · NeoForge

一键开服(送7天)

DC Render API

DC Render API 是专为 Minecraft 模组打造的先进粒子渲染与动画库。它提供了一个完整、可直接投入生产环境的视觉系统,支持可控粒子、粒子组、发射器、样式、弹幕、显示实体、缓动时间轴以及轻量级事件总线——并内置了针对 Embeddium / Rubidium / Inventory Particles 等客户端优化模组激进 addParticle 剔除机制的缓解策略。该项目在 Forge 1.20.1 / Fabric 1.20.1 / NeoForge 1.21.1 上保持全功能一致。

跳转至中文文档: README.md


平台支持

加载器 Minecraft 版本 Mod 工件 JDK Kotlin 语言适配器
Minecraft Forge 1.20.1 0.2.0-1.20.1Forge JDK 17+ Kotlin-for-Forge-*-1.20.1.jar (by thedarkcolour)
Fabric 1.20.1 0.2.0-1.20.1Fabric JDK 17+ fabric-language-kotlin-* (by FabricMC)
NeoForge 1.21.1 1.0.0-1.21.1NeoForge JDK 21+ Kotlin-for-Forge-*-1.21.1-NeoForge.jar (by thedarkcolour)

⚠ 每种加载器都必须安装三个 jar 包:安装 Kotlin 语言适配器 + DC Render API jar + 使用该 API 的主模组(例如 Dragon Curse Chronicles)。缺少其中任何一个都会导致加载崩溃。


核心特性

主要能力

  • 可控粒子系统:通过稳定的 id 追踪粒子实例,具有明确的生命周期和死亡标记。
  • 粒子动画系统:圆形轨道、螺旋轨道、波浪运动、随机游走、缓动函数以及时间轴关键帧插值。
  • 服务端-客户端粒子同步:两个专用的网络数据包(ParticleGroupPacket, ParticleSyncPacket)确保跨客户端视图的一致性。
  • 粒子组管理:ServerParticleGroupManager / ClientParticleGroupManager 用于批量创建、更新和销毁。
  • 粒子发射器系统:ParticleEmitter 接口 + ParticleEmitterManager,支持速率和速度设置。
  • 粒子样式系统:ParticleStyle 用于定义大小、透明度、RGB 颜色、生命周期;提供 createStyle + applyStyleToParticle。
  • 弹幕系统:BarrageManager 支持复杂模式,包括圆形弹幕。
  • 显示实体系统:对 Minecraft 显示实体的轻量级封装:DisplayEntity + DisplayEntityManager。
  • 效果系统:Effect + EffectManager 将多个粒子与动画组合成一个可复用的单元。
  • 事件系统:轻量级 EventBus + ParticleEventBus;支持碰撞、命中、着地、入水等钩子。
  • 噪声系统:PerlinNoise 用于生成自然的随机性。
  • 智能粒子分发器(首创于 NeoForge 宿主模组):帧感知批处理 + LOD 衰减 + 对象池 + 渐进式发射 + 远距离数据包绕过;有效规避客户端粒子模组的激进剔除行为。

动画效果

  • 圆形轨道
  • 螺旋轨道
  • 波浪运动
  • 随机游走
  • 缓动函数(线性、二次、三次、四次、五次、正弦、指数、圆弧、回弹、弹性、弹跳……)
  • 时间轴插值(位置、缩放、旋转、颜色)
  • 组合 / 分层动画

项目结构

DC Render API/                                  # 独立单体仓库(本目录)
├── src/                                        # Forge 1.20.1 源代码
│   └── main/
│       ├── java/com/qituo/dcrapi/              # Java 层:模组入口、物品、网络、粒子、平台适配
│       │   ├── DcRenderApi.java                #   Forge @Mod 入口
│       │   ├── items/ParticleTesterItem.java   #   游戏内粒子调试器
│       │   ├── network/*                       #   服务器 → 客户端同步数据包
│       │   ├── particles/
│       │   │   ├── emitters/*                  #   Emitter 接口 + 管理器
│       │   │   ├── style/*                     #   Style 接口 + 管理器
│       │   │   ├── DcRenderApiParticleManager.java  # 线程安全的粒子注册表
│       │   │   ├── ControlableParticle.java
│       │   │   └── ServerParticleGroup*.java
│       │   └── platform/DcRenderApiServices.java
│       └── kotlin/com/qituo/dcrapi/            # Kotlin 层:动画、弹幕、颜色、配置、显示、效果、事件、数学、噪声、渲染、形状、命令、构建器、组合
│           ├── animation/timeline/             #   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/                        #   与 Forge 相同的 Kotlin 子系统布局
│   ├── 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
    • 依赖该 API 的模组(例如 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
    • 依赖该 API 的模组(例如 Dragon Curse Chronicles Fabric 版)
  3. 启动游戏。

NeoForge 1.21.1

  1. 为 Minecraft 1.21.1 安装 NeoForge 21.1.248+。
  2. 下载所有三个 jar 文件并将其放入 mods/ 文件夹:
    • Kotlin 适配器:Kotlin-for-Forge-*-1.21.1-NeoForge.jar (thedarkcolour)
    • DC Render API:dcrapi-1.0.0-1.21.1NeoForge.jar
    • 依赖该 API 的模组(例如 Dragon Curse Chronicles NeoForge 版)
  3. 启动游戏。

快速入门(集成到自定义模组中)

需求矩阵

加载器 需求
Forge 1.20.1 Forge 47.x / JDK 17+ / Kotlin for Forge
Fabric 1.20.1 Fabric Loader 0.16.13+ / Fabric API / fabric-language-kotlin / JDK 17+
NeoForge 1.21.1 NeoForge 21.1.248+ / Kotlin for Forge NeoForge / JDK 21+

为所有三个加载器构建制品

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

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

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

所有三个 build.gradle 脚本都注册了 sourcesJar 任务,因此每次构建时都会自动生成 -sources.jar。


核心用法(Java 模组开发者)

1. 使用构建器创建粒子组(推荐)

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);
});

事件类型:

事件类 触发条件
ParticleCollideEvent 粒子与方块碰撞
ParticleHitEntityEvent 粒子击中生物实体
ParticleOnGroundEvent 粒子落地
ParticleOnLiquidEvent 粒子进入液体

5. 粒子样式系统

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

int styleId = ParticleStyleManager.createStyle(
    1.0F,    // 大小
    0.5F,    // 透明度
    new Vec3(1, 0, 0), // 颜色 (RGB)
    2.0      // 生命周期(秒)
);
ParticleStyleManager.applyStyleToParticle(pid, styleId);

6. 时间轴与缓动(对 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)

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. 保持处理器轻量:切勿在 ParticleEventBus 回调中执行 I/O 或重型计算。

线程安全保证(代码层面)

  • ConcurrentHashMap<Integer, ControlableParticle> 作为 DcRenderApiParticleManager.PARTICLES 的后端存储。
  • AtomicInteger nextParticleId 用于避免 ID 分配期间的竞态条件。
  • CopyOnWriteArrayList 用于 ParticleEventBus 的处理程序列表;在注册时迭代是安全的。
  • 每刻批量移除模式:将死亡的粒子 ID 收集到列表中,然后一次性 removeAll —— 避免了 ConcurrentHashMap 迭代器的弱一致性陷阱。
  • 每个粒子的 try/catch:一个行为异常的粒子或数据包处理器绝不会导致整个刻的中断。

游戏内调试工具

三个加载器均注册了一个 粒子测试器 创造模式物品:

  • 右键点击:生成一个标准的演示粒子组(轨道 + 样式 + 事件挂钩)。
  • 潜行 + 右键点击:循环切换调试模式:Basic → Builder → Event → Basic …
  • 存储机制:当前测试模式的状态现在保存在物品堆栈本身(CustomData / NBT)中,而不是 JVM 静态字段 —— 修复了跨手持/跨玩家的状态污染问题。

兼容性矩阵

功能 Forge 1.20.1 Fabric 1.20.1 NeoForge 1.21.1
MC 版本 ✅ ✅ ✅
Java 版本 17 17 21
Kotlin 适配器 Kotlin-for-Forge fabric-language-kotlin Kotlin-for-Forge (NeoForge)
粒子组同步 ✅ ✅ ✅
粒子测试器物品 ✅ ✅ ✅
自动 sourcesJar 任务 ✅ ✅ ✅

构建依赖片段 (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 仓库,请将 jars 放入本地 libs/ 文件夹,并使用 files(...) 作为依赖。


已知消费者 / 实际使用案例

Dragon Curse Chronicles 是 DC Render API 的首方参考使用者:

  • 猪护身符激光 / 龙护身符火球 → 圆形轨道 + 波动粒子轨迹
  • 叔叔的干河豚鱼激光 → 约 1200 个粒子,带有两个反向旋转的渐变螺旋,通过 SmartParticleDispatcher 渐进式分发
  • 起源光环 / 护身符激活效果 → 粒子组 + 时间轴缓动

迁移指南 (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 许可证 发布 —— 请参阅 GitHub 上官方的独立许可证文件 LICENSE.md。

  • 当前版本:Forge 0.2.0 / Fabric 0.2.0-1.20.1Fabric / NeoForge 1.0.0(版本号因加载器而异)
  • 作者:QiTuo, Yifei
  • 源码仓库:
  • 分发平台:CurseForge / Modrinth

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源