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
- 安装 Minecraft Forge 1.20.1 (47.x 或更高版本)。
- 下载所有三个 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 版)
- 启动游戏。
Fabric 1.20.1
- 安装 Fabric Loader 0.16.13+ 和 Fabric API 0.92.11+1.20.1。
- 下载所有三个 jar 文件并将其放入
mods/ 文件夹:
- Kotlin 适配器:
fabric-language-kotlin-* (CurseForge / Modrinth)
- DC Render API:
dcrapi-0.2.0-1.20.1Fabric.jar
- 依赖该 API 的模组(例如 Dragon Curse Chronicles Fabric 版)
- 启动游戏。
NeoForge 1.21.1
- 为 Minecraft 1.21.1 安装 NeoForge 21.1.248+。
- 下载所有三个 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 版)
- 启动游戏。
快速入门(集成到自定义模组中)
需求矩阵
| 加载器 |
需求 |
| 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 # 详细日志输出
性能与线程安全
性能建议
- 调整
visibleRange:将其保持在 32 到 128 个方块之间;更大的值会迅速导致带宽和绘制成本激增。
- 帧批处理 / 渐进式发射:对于超过 1000 个粒子的爆发效果,请使用类似
SmartParticleDispatcher 的队列模式(参见 NeoForge Dragon Curse Chronicles 参考实现),而不是在一刻内生成所有粒子。
- 及时清理:安排定期执行
ServerParticleGroupManager.clear() 以回收已死亡的粒子组。
- 保持处理器轻量:切勿在 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
DC Render API
DC Render API is an advanced particle rendering & animation library for Minecraft mods. It exposes a complete, production-ready visual system for controllable particles, particle groups, emitters, styles, barrages, display entities, easing timelines and a lightweight event bus — and ships with a built-in mitigation strategy against aggressive addParticle culling from client-side optimization mods such as Embeddium / Rubidium / Inventory Particles. The project maintains Forge 1.20.1 / Fabric 1.20.1 / NeoForge 1.21.1 with full feature parity across all three loaders.
跳转至中文文档: README.md
Platform Support
| Loader |
Minecraft Version |
Mod Artifact |
JDK |
Kotlin Language Adapter |
| 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) |
⚠ Mandatory three-jar setup for every loader: install the Kotlin language adapter + DC Render API jar + the main mod that consumes it (e.g. Dragon Curse Chronicles). Missing any one of the three will crash at load.
Core Features
Main Capabilities
- Controllable Particle System: Particle instances tracked by stable
id with explicit lifecycle & dead flag.
- Particle Animation System: Circle orbit, spiral orbit, wave motion, random walk, easing functions, and timeline keyframe interpolation.
- Server-Client Particle Sync: Two dedicated network packets (
ParticleGroupPacket, ParticleSyncPacket) guarantee a consistent view across clients.
- Particle Group Management:
ServerParticleGroupManager / ClientParticleGroupManager for batched create / tick / destroy.
- Particle Emitter System:
ParticleEmitter interface + ParticleEmitterManager with rate & velocity settings.
- Particle Style System:
ParticleStyle for size / alpha / RGB / lifetime; createStyle + applyStyleToParticle.
- Barrage System:
BarrageManager supports complex patterns including circular barrages.
- Display Entity System: Lightweight wrapper around Minecraft Display Entities:
DisplayEntity + DisplayEntityManager.
- Effect System:
Effect + EffectManager combines multiple particles + animations into one reusable unit.
- Event System: Lightweight
EventBus + ParticleEventBus; hooks for collision, hit, on-ground, liquid-entry.
- Noise System:
PerlinNoise for natural-looking randomness.
- Smart Particle Dispatcher (pioneered in NeoForge host mod): Frame-aware batching + LOD falloff + object pooling + progressive emission + long-distance packet bypass; works around aggressive culling from client particle mods.
Animation Effects
- Circular Orbit
- Spiral Orbit
- Wave Motion
- Random Walk
- Easing functions (Linear, Quad, Cubic, Quart, Quint, Sine, Expo, Circ, Back, Elastic, Bounce …)
- Timeline interpolation (position, scale, rotation, color)
- Composition / layered animation
Project Structure
DC Render API/ # Standalone monorepo (this directory)
├── src/ # Forge 1.20.1 sources
│ └── main/
│ ├── java/com/qituo/dcrapi/ # Java layer: mod entry, items, network, particles, platform
│ │ ├── DcRenderApi.java # Forge @Mod entry
│ │ ├── items/ParticleTesterItem.java # in-game particle debugger
│ │ ├── network/* # server → client sync packets
│ │ ├── particles/
│ │ │ ├── emitters/* # Emitter interface + manager
│ │ │ ├── style/* # Style interface + manager
│ │ │ ├── DcRenderApiParticleManager.java # Thread-safe particle registry
│ │ │ ├── ControlableParticle.java
│ │ │ └── ServerParticleGroup*.java
│ │ └── platform/DcRenderApiServices.java
│ └── kotlin/com/qituo/dcrapi/ # Kotlin layer: animation, barrage, color, config, display, effect, event, math, noise, render, shape, commands, builder, composition
│ ├── animation/timeline/ # Timeline: Eases.kt, Timeline.kt, DoubleConstTimeAnimator, ValueConstTimeAnimator
│ ├── barrages/ color/ config/ display/ effects/ event/ math/ noise/
│ ├── particles/builder/ParticleGroupBuilder.kt # Recommended builder API
│ ├── particles/command/ particles/composition/ particles/emitters/ particles/style/
│ └── render/ shapes/
├── fabric/DC Render API/ # Fabric 1.20.1 sources (feature parity)
│ ├── src/main/java/ # Fabric particles, network, items, mixin, client initializer
│ ├── src/main/kotlin/ # Same Kotlin subsystem layout as Forge
│ ├── src/main/resources/fabric.mod.json # Fabric metadata
│ └── build.gradle / gradle.properties
├── neoforge/ # NeoForge 1.21.1 sources (feature parity)
│ ├── src/main/java + kotlin/ # Ported to 1.21.1 DataComponents / Holder / Codec / NeoForge.EVENT_BUS
│ └── build.gradle / gradle.properties
├── LICENSE.md # MIT License (mirrors the standalone GitHub repo)
├── build.gradle # Forge 1.20.1 build; registers 'sourcesJar' task
├── gradle.properties # mod_version=0.2.0, mod_id=dcrapi, mod_license=MIT
├── gradlew / gradlew.bat / gradle/ # Gradle Wrapper
└── settings.gradle
Installation (Player Side)
Forge 1.20.1
- Install Minecraft Forge 1.20.1 (47.x or newer).
- Download all three jars and drop them into your
mods/ folder:
- Kotlin adapter:
Kotlin-for-Forge-*-1.20.1.jar (CurseForge / Modrinth)
- DC Render API:
dcrapi-0.2.0-1.20.1Forge.jar
- The consuming mod (e.g. Dragon Curse Chronicles Forge edition)
- Launch the game.
Fabric 1.20.1
- Install Fabric Loader 0.16.13+ and Fabric API 0.92.11+1.20.1.
- Download all three jars and drop them into your
mods/ folder:
- Kotlin adapter:
fabric-language-kotlin-* (CurseForge / Modrinth)
- DC Render API:
dcrapi-0.2.0-1.20.1Fabric.jar
- The consuming mod (e.g. Dragon Curse Chronicles Fabric edition)
- Launch the game.
NeoForge 1.21.1
- Install NeoForge 21.1.248+ for Minecraft 1.21.1.
- Download all three jars and drop them into your
mods/ folder:
- Kotlin adapter:
Kotlin-for-Forge-*-1.21.1-NeoForge.jar (thedarkcolour)
- DC Render API:
dcrapi-1.0.0-1.21.1NeoForge.jar
- The consuming mod (e.g. Dragon Curse Chronicles NeoForge edition)
- Launch the game.
Quick Start (Integrate into a Custom Mod)
Requirements Matrix
| Loader |
Requirements |
| 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+ |
Building Artifacts for All Three Loaders
# ============ 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
All three build.gradle scripts register a sourcesJar task, so a -sources.jar is produced automatically on every build.
Core Usage (Java Modders)
1. Create a Particle Group with Builder (Recommended)
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. Create a Controllable Particle (Server → Client Synced)
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. Circle & Spiral Orbit Animations
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. Particle Hit Event (Deal Damage)
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);
});
Event Types:
| Event Class |
Trigger |
ParticleCollideEvent |
Particle collides with a block |
ParticleHitEntityEvent |
Particle hits a living entity |
ParticleOnGroundEvent |
Particle lands on the ground |
ParticleOnLiquidEvent |
Particle enters a liquid |
5. Particle Style System
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. Timeline & Easing (Kotlin-friendly, Java works too)
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 File (config/dcrapi_config.properties)
maxParticleGroups=1000 # Upper bound on active particle groups
defaultVisibleRange=64.0 # Fallback visible range in blocks
particleTickRate=1 # Tick frequency
enableParticleEvents=true # Enables ParticleEventBus dispatching
enableDebugLogging=false # Verbose log output
Performance & Thread Safety
Performance Tips
- Tune
visibleRange: keep it between 32 and 128 blocks; larger values blow up bandwidth and draw cost quickly.
- Frame-batched / progressive emission: for burst effects with >1000 particles, use a
SmartParticleDispatcher-style queue pattern (see NeoForge Dragon Curse Chronicles reference implementation) instead of spawning everything in one tick.
- Clean up promptly: schedule periodic
ServerParticleGroupManager.clear() to reap dead groups.
- Keep handlers light: never do I/O or heavy computation inside ParticleEventBus callbacks.
Thread-Safety Guarantees (in code)
ConcurrentHashMap<Integer, ControlableParticle> backing DcRenderApiParticleManager.PARTICLES.
AtomicInteger nextParticleId to avoid races during id allocation.
CopyOnWriteArrayList for ParticleEventBus handler lists; safe to iterate while registering.
- Batch-remove pattern on tick: collect dead particle ids to a list, then
removeAll at once — avoids the ConcurrentHashMap iterator weak-consistency gotcha.
- Per-particle try/catch: one misbehaving particle or packet handler can never abort an entire tick.
In-Game Debug Tool
All three loaders register a Particle Tester creative item:
- Right-click: Spawn a standard demo particle group (orbit + style + event hook).
- Sneak + Right-click: Cycle debug mode:
Basic → Builder → Event → Basic …
- Storage: the active test mode is now saved on the item stack itself (
CustomData / NBT) instead of a JVM-static field — fixes cross-hand / cross-player state pollution.
Compatibility Matrix
| Feature |
Forge 1.20.1 |
Fabric 1.20.1 |
NeoForge 1.21.1 |
| MC Version |
✅ |
✅ |
✅ |
| Java |
17 |
17 |
21 |
| Kotlin Adapter |
Kotlin-for-Forge |
fabric-language-kotlin |
Kotlin-for-Forge (NeoForge) |
| Particle Group Sync |
✅ |
✅ |
✅ |
| Particle Tester Item |
✅ |
✅ |
✅ |
| Auto sourcesJar Task |
✅ |
✅ |
✅ |
Build Dependency Snippets (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 coordinates are the target format; if not yet uploaded to a Maven repo, drop the jars into a local libs/ folder and use files(...) as a dependency.
Known Consumer / Real-World Usage
Dragon Curse Chronicles is the first-party reference consumer of DC Render API:
- Pig Talisman laser / Dragon Talisman fireball → circular orbit + wave particle trails
- Uncle's Dried Puffer Fish laser → ~1200 particles with two counter-rotating gradient helices, dispatched progressively via
SmartParticleDispatcher
- Origin Aura / Talisman activation effects → particle groups + timeline easing
Migration Guide (0.1.x → 0.2.x)
Before (0.1.x):
ServerParticleGroup group = new ServerParticleGroup();
group.initServerGroup(pos, world);
group.scale = 1.5;
ServerParticleGroupManager.addParticleGroup(group, pos, world);
After (0.2.x, Builder):
ServerParticleGroup group = new ParticleGroupBuilder()
.position(pos).world(world).scale(1.5).visibleRange(64.0).maxTick(100)
.buildAndRegister();
Highlights of the 0.2.0 release:
mod_version=0.2.0, MIT license explicitly declared in gradle.properties + standalone LICENSE.md.
- All three loader builds register a
sourcesJar task; -sources.jar is produced on every build.
ParticleTesterItem: test-mode state moved from a static JVM field into item stack CustomData / NBT; eliminates cross-player state pollution.
DcRenderApiParticleManager: nextParticleId changed from plain int → AtomicInteger; tick removal switched to batch-remove pattern for stronger consistency.
License & Authors
Released under the MIT License — see the official standalone license blob at LICENSE.md on GitHub.
- Current version: Forge
0.2.0 / Fabric 0.2.0-1.20.1Fabric / NeoForge 1.0.0 (version numbers are independent per loader)
- Authors: QiTuo, Yifei
- Source repo:
- Distribution: CurseForge / Modrinth
评论 0
登录后参与评分
还没有评论,来抢沙发吧