DC Render API

DC Render API: Custom graphics API powering exclusive visual effects for Dragon Curse Chronicles.

Загрузки: 2K
Подписчики: 1
Обновлён: 8 августа 2026 г.
Лицензия: MIT

Опубликован 7 апреля 2026 г.

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: https://github.com/19136644525lxy/DC-Render-API
Distribution: CurseForge / Modrinth

DC Render API

Platform Support

Core Features

Main Capabilities

Animation Effects

Project Structure

Installation (Player Side)

Forge 1.20.1

Fabric 1.20.1

NeoForge 1.21.1

Quick Start (Integrate into a Custom Mod)

Requirements Matrix

Building Artifacts for All Three Loaders

Core Usage (Java Modders)

1. Create a Particle Group with Builder (Recommended)

2. Create a Controllable Particle (Server → Client Synced)

3. Circle & Spiral Orbit Animations

4. Particle Hit Event (Deal Damage)

5. Particle Style System

6. Timeline & Easing (Kotlin-friendly, Java works too)

7. Config File (config/dcrapi_config.properties)

Performance & Thread Safety

Performance Tips

Thread-Safety Guarantees (in code)

In-Game Debug Tool

Compatibility Matrix

Build Dependency Snippets (build.gradle)

Known Consumer / Real-World Usage

Migration Guide (0.1.x → 0.2.x)

License & Authors

Комментарии

7. Config File (`config/dcrapi_config.properties`)