ParticleDrawing
English | 简体中文
一个用于 NeoForge 的服务器端权威粒子效果库。它播放由 ParticleDrawing editor 导出的动画,并提供 Kotlin/Java API,允许直接从代码中绘制和动画化粒子。
粒子由服务器创建并拥有,而客户端在本地进行评估和渲染。像编排组、生命周期曲线和运行时发射器这样的声明式特性只需发送一次,并在客户端进行评估,因此运行中的效果几乎不消耗每刻带宽。
功能
- 通过命令播放位于
<gameDir>/animations/ 目录下的 .pdrawc 文件,或通过 ServerAnimationManager 从代码中播放,包括运行时变量更新。
- 使用
Draw 从代码中绘制线条、圆形、圆盘、曲线、折线、三角形、六角星、矩形、球体和立方体,支持渐变着色和每个粒子的入场延迟。
- 在
ParticleGroup 上记录移动、旋转、缩放、脉冲、颜色淡入淡出以及由表达式或实体驱动的运动的时间轴;客户端以渲染帧率回放这些内容。
- 将轨迹或光环声明为运行时发射器一次,让每个客户端根据锚点、行进距离或时间间隔进行发射,并具有确定性的每粒子抖动。
- 每个数据包最多生成 256 个粒子规格,自动对批量位置、速度、力和跟踪操作进行分块处理。
- 使用每粒子纹理、子矩形 UV、各向异性尺寸、固定方向、混合相加、内置软点/线形状以及自动同步到客户端的 PNG 注册功能,无需资源包。
- 注册带有可移动锚点的效果,控制其播放时钟,播放 OGG/WAV 音频并动态照亮粒子。
要求
| Minecraft |
Minimum NeoForge |
Java |
| 26.2 |
26.2.0.59 |
25 |
| 26.3 |
26.3.0.101 |
25 |
| 1.21.1 |
21.1.235 |
21 |
下载版本涵盖 26.2、26.3 和 1.21.1。
安装
玩家
- 为 Minecraft 26.2、26.3 或 1.21.1 安装 NeoForge。
- 将适用于您游戏版本的 JAR 文件安装到
mods/ 目录中。Modrinth · GitHub Releases
- 从 编辑器 导出动画,并将
.pdrawc 文件放入 <gameDir>/animations/ 中。
- 在游戏中使用
/pdraw 命令。动画按需加载,因此在添加或替换动画后无需重启游戏。
开发者
重构后的发布版本为每个游戏版本使用了独立的 Maven Central 坐标:
// build.gradle.kts
dependencies {
compileOnly("work.nekow:particledrawing-neoforge-26.3:<version>")
localRuntime("work.nekow:particledrawing-neoforge-26.3:<version>")
}
上述针对特定目标的坐标适用于从多版本布局构建的发布版本。
现有的旧版发布版本仍保留 work.nekow:particledrawing:<version>。
对于 Minecraft 26.2,请将 neoforge-26.3 替换为 neoforge-26.2。
在 Maven Central 上为您的目标选择一个已发布的 <version>。26.2 · 26.3
若要将库打包到您的模组 JAR 中,请使用
jarJar(implementation("work.nekow:particledrawing-neoforge-26.3:<version>"))。
同时在 META-INF/neoforge.mods.toml 中声明依赖项:
[[dependencies.${mod_id}]]
modId = "particledrawing"
type = "required"
ordering = "AFTER"
一个最小化的效果示例:
import net.minecraft.world.phys.Vec3
import work.nekow.particledrawing.api.Draw
import work.nekow.particledrawing.api.ParticleManager
val manager = ParticleManager.of(level)
Draw.circle(manager, Vec3(0.0, 70.0, 0.0), radius = 3.0, count = 80)
.fadeIn(15)
.spin(Vec3(0.0, 1.0, 0.0), Math.PI / 40)
.delay(100)
.stopContinuous()
.fadeOut(20)
更多内容请参阅 入门指南。
命令
| 命令 |
描述 |
/pdraw particle group ... |
创建和管理命名粒子组,供数据包和命令方块使用。 |
/pdraw particle add ... |
添加点、光束、螺旋线、魔法阵、球体和其他基本图元。 |
/pdraw particle emitter ... |
配置采样、图像、公式、锚点和分步粒子寿命。 |
/pdraw particle program ... |
编排锚点、实体跟随、移动、旋转、脉冲、变量和每粒子表达式。 |
/pdraw animation list |
列出 animations/ 中可用的动画。 |
/pdraw animation play <name> [pos] |
在 pos 处播放动画,或在玩家前方 3 格处播放。 |
/pdraw animation stop |
停止当前维度中正在播放的所有动画和效果。 |
| /pdraw animation camera <name\|stop> | 通过摄像机预览正在播放的动画。 |
| /pdraw animation var <name> <value> | 更新正在播放的动画中函数对象的变量。 |
| /pdraw animation debug | 打印评估时间、粒子数量和回放的时间线。 |
| /pdraw texture reload | 从磁盘重新加载粒子纹理(仅限客户端)。 |
使用 group → add → program 进行编排组设置。对于采样曲线、图像和连续发射器,
使用 emitter 配置每个步骤,然后使用 burst 或 start。两者均可在数据包函数和命令方块中使用。有关完整的语法和现成的魔法阵示例,请参阅 命令指南。
关于命令方块的简短示例,请参阅 带末影棒纹理的正弦曲线。
使用 texture=particle:minecraft:end_rod 可复用原版纹理,同时保留 PD 动画控制功能。
帧跟随粒子的年龄和生命周期。使用 field anchor 配合 expression local 共享组的锚点,
并使用 lifetime=80 设置四秒的生命周期。数据包设置与示例函数
文档
文档索引
从源码构建
git clone https://github.com/NekoWs/ParticleDrawing.git
cd ParticleDrawing
./gradlew build # 编译并运行测试套件
./gradlew runClient # 启动开发客户端
./gradlew runServer # 启动开发服务器
构建需要 JDK 25。根项目的构建目标版本为 26.3。使用 ./gradlew -p platforms/neoforge-26.2 build 或
./gradlew -p platforms/neoforge-26.3 build 构建任一适配器。共享核心部分针对 Java 21。架构、构件坐标、运行目录以及迁移说明请参见 多版本指南。
发布
gradle.properties 中的 mod_version 是唯一的真实来源。每当它发生变化时,相同的提交会打上匹配的标签(v<mod_version>)。推送此类标签会通过 publish.yml 使用 publishAndReleaseToMavenCentral 将构件发布到 Maven Central。Maven Central 在验证和同步后使构件可用。该标签还会触发 modrinth.yml 以发布各个目标并将此 README 同步到项目页面。Modrinth
release.yml 构建两个游戏目标版本,并创建一个 GitHub Release,其中包含运行时 JAR、源码 JAR、SHA-256 校验和以及自上一个标签以来的提交标题中的说明。ALPHA、BETA 和 RC 版本被标记为预发布版本。如果标签名称与 mod_version 不匹配,所有三个工作流都会失败;没有标签就没有发布。
要为现有标签发布 GitHub Release,请打开 Actions → Publish GitHub Release → Run workflow
并输入 v<version>。这将检出带标签的源代码并仅运行 GitHub Release 工作流。
它使用内置的 GITHUB_TOKEN 且权限为 contents: write;无需额外的密钥。重新运行会替换同名附件,同时保留现有的发布说明。
许可证
根据 Apache License 2.0 授权。
ParticleDrawing
English | 简体中文
A server-authoritative particle effects library for NeoForge. It plays the animations exported by the
ParticleDrawing editor and exposes a Kotlin/Java API for drawing and
animating particles directly from code.
Particles are created and owned by the server, while clients evaluate and render them locally.
Declarative features such as choreographed groups, life curves and runtime emitters are sent once and
evaluated on the client, so a running effect costs little to no per-tick bandwidth.
Features
- Play
.pdrawc files from <gameDir>/animations/ with a command, or from code through
ServerAnimationManager, including runtime variable updates.
- Draw lines, circles, discs, curves, polylines, triangles, hexagrams, rectangles, spheres and cuboids
from code with
Draw, with gradient coloring and per-particle entrance delays.
- Record a timeline of moves, rotations, scaling, pulses, color fades and expression- or entity-driven
motion on a
ParticleGroup; the client plays it back at render-frame rate.
- Declare a trail or an aura once as a runtime emitter and let each client emit along the anchor, per
distance travelled or per interval, with deterministic per-particle jitter.
- Spawn up to 256 particle specs per packet, with automatic chunking for the bulk position, velocity,
force and track operations.
- Use per-particle textures, sub-rectangle UVs, anisotropic sizes, fixed orientation, additive
blending, built-in soft-dot/line shapes and PNG registration that syncs itself to clients, without a
resource pack.
- Register effects with movable anchors, control their playback clock, play OGG/WAV audio and light
particles dynamically.
Requirements
| Minecraft |
Minimum NeoForge |
Java |
| 26.2 |
26.2.0.59 |
25 |
| 26.3 |
26.3.0.101 |
25 |
| 1.21.1 |
21.1.235 |
21 |
Downloads cover 26.2, 26.3 and 1.21.1.
Installation
Players
- Install NeoForge for Minecraft 26.2, 26.3 or 1.21.1.
- Install the JAR for your game version into
mods/. Modrinth · GitHub Releases
- Export an animation from the editor and place the
.pdrawc file into
<gameDir>/animations/.
- Use the
/pdraw command in game. Animations are loaded on demand, so the game does not have to be
restarted after adding or replacing one.
Developers
The refactored releases use a separate Maven Central coordinate for each game version:
// build.gradle.kts
dependencies {
compileOnly("work.nekow:particledrawing-neoforge-26.3:<version>")
localRuntime("work.nekow:particledrawing-neoforge-26.3:<version>")
}
The target-specific coordinates above apply to releases built from the multi-version layout.
Existing older releases retain work.nekow:particledrawing:<version>.
For Minecraft 26.2, replace neoforge-26.3 with neoforge-26.2.
Choose a published <version> for your target on Maven Central. 26.2 · 26.3
To bundle the library in your mod JAR, use
jarJar(implementation("work.nekow:particledrawing-neoforge-26.3:<version>")).
Declare the dependency in META-INF/neoforge.mods.toml as well:
[[dependencies.${mod_id}]]
modId = "particledrawing"
type = "required"
ordering = "AFTER"
A minimal effect:
import net.minecraft.world.phys.Vec3
import work.nekow.particledrawing.api.Draw
import work.nekow.particledrawing.api.ParticleManager
val manager = ParticleManager.of(level)
Draw.circle(manager, Vec3(0.0, 70.0, 0.0), radius = 3.0, count = 80)
.fadeIn(15)
.spin(Vec3(0.0, 1.0, 0.0), Math.PI / 40)
.delay(100)
.stopContinuous()
.fadeOut(20)
More in the getting started guide.
Commands
| Command |
Description |
/pdraw particle group ... |
Create and manage named particle groups for data packs and command blocks. |
/pdraw particle add ... |
Add dots, beams, helices, magic circles, spheres and other primitives. |
/pdraw particle emitter ... |
Configure sampling, images, formulas, anchors and particle lifetimes in steps. |
/pdraw particle program ... |
Choreograph anchors, entity following, movement, spin, pulses, variables and per-particle expressions. |
/pdraw animation list |
List the animations available in animations/. |
/pdraw animation play <name> [pos] |
Play an animation at pos, or 3 blocks in front of the player. |
/pdraw animation stop |
Stop every animation and effect playing in the current dimension. |
/pdraw animation camera <name|stop> |
Preview through a camera of a playing animation. |
/pdraw animation var <name> <value> |
Update a function object variable of the playing animations. |
/pdraw animation debug |
Print evaluation time, particle count and timeline of playback. |
/pdraw texture reload |
Reload particle textures from disk (client side only). |
Use group → add → program for choreographed groups. For sampled curves, images and continuous emitters,
configure each step with emitter, then use burst or start. Both work in data pack functions and command blocks. See the command guide for the full
syntax and a ready-to-use magic circle example.
For a short command block example, see the sin curve with the end rod texture.
Use texture=particle:minecraft:end_rod to reuse a vanilla texture while retaining PD animation controls.
Frames follow particle age and lifetime. Use field anchor with expression local to share the group anchor,
and lifetime=80 for a four-second lifetime. Data pack setup and example functions
Documentation
Documentation index
Building from source
git clone https://github.com/NekoWs/ParticleDrawing.git
cd ParticleDrawing
./gradlew build # compile and run the test suite
./gradlew runClient # start a development client
./gradlew runServer # start a development server
The build requires JDK 25. The root build targets 26.3. Build either adapter with ./gradlew -p platforms/neoforge-26.2 build or
./gradlew -p platforms/neoforge-26.3 build. The shared core targets Java 21. Architecture, artifact
coordinates, run directories, and migration notes are in the multi-version guide.
Releasing
mod_version in gradle.properties is the single source of truth. Whenever it changes, the same
commit gets a matching tag (v<mod_version>). Pushing such a tag publishes the artifact to Maven
Central through publish.yml using publishAndReleaseToMavenCentral. Central makes the artifacts
available after validation and synchronization. The tag also runs modrinth.yml to publish each target
and sync this README to the project page. Modrinth
release.yml builds both game targets and creates a
GitHub Release with their runtime JARs, sources JARs, SHA-256 checksums, and notes from commit titles since
the previous tag. ALPHA, BETA, and RC versions are marked as prereleases. All three workflows fail if
the tag name does not match mod_version; there is no release without a tag.
To publish a GitHub Release for an existing tag, open Actions → Publish GitHub Release → Run workflow
and enter v<version>. This checks out the tagged source and runs only the GitHub Release workflow.
It uses the built-in GITHUB_TOKEN with contents: write; no extra secret is required. Rerunning
replaces same-named attachments while preserving existing release notes.
License
Licensed under the Apache License 2.0.
评论 0
登录后参与评分
还没有评论,来抢沙发吧