MoParticles

MoParticles 是一个 Paper 插件,它读取 MoLang 粒子定义(基岩版粒子语言),将其烘焙为动画,生成带有正确纹理的资源包,并使用客户端的 Item Display 实体播放这些动画。
支持的服务器
Paper 和 Purpur,Minecraft 1.21.5 至 26.3。所有数据包均使用 PacketEvents 2.14.0 按玩家进行编码,因此任何受支持的客户端都可以同时观看。需要 Java 21+。
渲染方式
效果完全通过数据包渲染。服务器上永远不会生成真实实体。
对于每个粒子:
- Spawn Entity 和 Set Entity Data 在粒子出现时创建 Item Display。
- Teleport Entity 每刻移动粒子。客户端在显示实体的位置/旋转插值持续时间内对移动进行插值,因此 20 TPS 下的帧看起来非常平滑。
- Set Entity Data 仅在粒子的缩放或色调实际更改时触发。
- Remove Entities(一个批处理数据包)清理消失的粒子或离开的观察者。
单个观察者的所有数据包都会写入其通道,并每刻使用 User#writePacket 和 User#flushPackets 刷新一次。每个观察者的 PacketEvents 用户只解析并缓存一次,因此数百个粒子在每个玩家每刻只需单次网络刷新。
元数据索引与 Minecraft Wiki 协议文档(Java Edition protocol/Entity metadata)匹配,从 1.21.5 到 26.3 版本完全相同。确切的索引记录在 DisplayEntityPackets.java 中。
资源包
该插件为每个支持的服务器版本生成一个资源包。打包中的每个效果都包含:
- 物品定义 (
assets/<namespace>/items/particles/<name>.json)
- 平面模型 (
assets/<namespace>/models/item/particles/<name>.json)
- 纹理 (
assets/<namespace>/textures/item/particles/<name>.png)
客户端从物品的 minecraft:item_model 组件解析此链:
<ns>:particles/<name> (item_model component)
-> assets/<ns>/items/particles/<name>.json (item definition)
-> assets/<ns>/models/item/particles/<name>.json (plane model)
-> assets/<ns>/textures/item/particles/<name>.png
颜色通过索引 0 处的 minecraft:custom_model_data 颜色列表传递。资源包声明格式 46(在 1.21.4 中引入),支持最高至 999,因此一个资源包适用于所有受支持的客户端。
纹理
纹理按以下顺序查找:
- 效果声明的纹理路径,完全按照书写内容。
textures/particle/<lastSegment>.png(例如,textures/particle/moparticles/circle 解析为 textures/particle/circle.png)。
textures/particle/<effectName>.png。
插件首先检查 plugins/MoParticles/,然后检查捆绑的 jar 文件。捆绑的默认值(circle.png 和 cube.png)是清晰的像素艺术,没有抗锯齿,并且每次启动时都会刷新,以便纹理修复传播到现有安装。每个纹理都在运行时根据效果颜色进行着色。如果未找到任何内容,代码中将生成一个清晰的圆圈作为最终回退方案。
资源包包含一个像素艺术风格的 pack.png 图标。
构建
运行:
./gradlew shadowJar
输出为 build/libs/MoParticles-2.0.0-all.jar。PacketEvents 和命令框架已阴影化,因此不需要额外的插件。
将 jar 文件放入服务器的 plugins 文件夹,然后从 plugins/MoParticles/generated/resourcepack.zip 安装生成的资源包。
命令
/moparticles list
/moparticles play <effect> <location> [radius]
/moparticles playhere <effect> [radius]
/moparticles stop <id>
/moparticles stopall
/moparticles reload
/moparticles info <effect>
命令描述
- list - 显示所有加载的效果
- play <effect> <location> [radius] - 在指定位置为半径内的玩家播放效果
- playhere <effect> [radius] - 在你所在的位置播放效果
- stop <id> - 通过 ID 停止正在运行的动画
- stopall - 停止所有正在运行的动画
- reload - 从磁盘重新加载效果和资源包
- info <effect> - 显示效果元数据
示例粒子
插件捆绑了来自 Snowstorm 的三个效果,位于 src/main/resources/particles/ 下:
- snowstorm:fire - 自定义 Snowstorm 火焰粒子
- snowstorm:loading - Snowstorm 的加载圆圈粒子
- snowstorm:rainbow - Snowstorm 的彩虹粒子动画
通过将 .json 文件放入 plugins/MoParticles/particles/ 并运行 /moparticles reload 来添加你自己的效果。
在你的插件中使用 MoParticles
1. 添加依赖
Gradle
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
compileOnly 'com.github.Chest-Solutions:MoParticles:2.0.0'
}
Maven
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>com.github.Chest-Solutions</groupId>
<artifactId>MoParticles</artifactId>
<version>2.0.0</version>
<scope>provided</scope>
</dependency>
</dependencies>
2. 标记为硬依赖
在你的 plugin.yml 中:
name: MyPlugin
version: 1.0
main: com.example.plugin.MyPlugin
depend: [MoParticles]
3. 播放效果
MoParticleAPI api = MoParticleAPI.get();
String effectName = "fire";
Location targetLocation = player.getLocation();
if (api.hasEffect(effectName)) {
UUID animationId = api.play(effectName, targetLocation, 10.0);
api.stop(animationId);
}
MoParticles

MoParticles is a Paper plugin that reads MoLang particle definitions (the Bedrock
particle language), bakes them into animations, generates a resource pack with
the right textures, and plays the animations using client-side Item Display
entities.
Supported servers
Paper and Purpur, Minecraft 1.21.5 through 26.3. All packets are encoded per
player using PacketEvents 2.14.0, so any supported client can watch at the same
time. Requires Java 21+.
How it renders
Effects render entirely with packets. No real entities are ever spawned on the
server.
For each particle:
- Spawn Entity and Set Entity Data create the Item Display when the particle
appears.
- Teleport Entity moves the particle every tick. The client interpolates the
move over the display's position/rotation interpolation duration, so frames
at 20 TPS look perfectly smooth.
- Set Entity Data only fires when a particle's scale or tint actually changes.
- Remove Entities (one batched packet) cleans up particles that disappear or
viewers who leave.
All packets for one viewer are written to their channel and flushed once per
tick using User#writePacket and User#flushPackets. Each viewer's PacketEvents
user is resolved once and cached, so hundreds of particles cost a single
network flush per player per tick.
The metadata indexes match the Minecraft wiki protocol documentation (Java
Edition protocol/Entity metadata), which is identical from 1.21.5 through 26.3.
The exact indexes are documented in
DisplayEntityPackets.java.
Resource pack
The plugin generates one resource pack per supported server version. Every
effect in the pack gets:
- An item definition (assets/<namespace>/items/particles/<name>.json)
- A plane model (assets/<namespace>/models/item/particles/<name>.json)
- A texture (assets/<namespace>/textures/item/particles/<name>.png)
The client resolves this chain from the item's minecraft:item_model
component:
<ns>:particles/<name> (item_model component)
-> assets/<ns>/items/particles/<name>.json (item definition)
-> assets/<ns>/models/item/particles/<name>.json (plane model)
-> assets/<ns>/textures/item/particles/<name>.png
Colors travel through the minecraft:custom_model_data color list at index 0.
The pack declares format 46 (introduced in 1.21.4) with support up to 999, so
one pack works for every supported client.
Textures
Textures are looked up in this order:
- The effect's declared texture path exactly as written.
- textures/particle/<lastSegment>.png (for example,
textures/particle/moparticles/circle resolves to textures/particle/circle.png).
- textures/particle/<effectName>.png.
The plugin checks plugins/MoParticles/ first, then the bundled jar. The
bundled defaults (circle.png and cube.png) are crisp pixel art with no
anti-aliasing and are refreshed on every startup so texture fixes propagate to
existing installs. Each one is tinted at runtime by the effect color. If
nothing is found, a crisp circle is generated in code as a final fallback.
The pack includes a pixel-art pack.png icon.
Build
Run:
./gradlew shadowJar
The output is build/libs/MoParticles-2.0.0-all.jar. PacketEvents and the
command framework are shaded in, so no extra plugins are required.
Drop the jar into your server's plugins folder, then install the generated
resource pack from plugins/MoParticles/generated/resourcepack.zip.
Commands
/moparticles list
/moparticles play <effect> <location> [radius]
/moparticles playhere <effect> [radius]
/moparticles stop <id>
/moparticles stopall
/moparticles reload
/moparticles info <effect>
Command descriptions
- list - shows all loaded effects
- play <effect> <location> [radius] - plays an effect at a location for
players within radius blocks
- playhere <effect> [radius] - plays an effect at your position
- stop <id> - stops a running animation by its id
- stopall - stops every running animation
- reload - reloads effects and the resource pack from disk
- info <effect> - shows effect metadata
Example particles
The plugin bundles three effects from Snowstorm in
src/main/resources/particles/:
- snowstorm:fire - custom snowstorm fire particle
- snowstorm:loading - Snowstorm's loading circle particle
- snowstorm:rainbow - Snowstorm's rainbow particle animation
Add your own by dropping .json files into plugins/MoParticles/particles/
and running /moparticles reload.
Using MoParticles in your plugin
1. Add the dependency
Gradle
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
compileOnly 'com.github.Chest-Solutions:MoParticles:2.0.0'
}
Maven
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>com.github.Chest-Solutions</groupId>
<artifactId>MoParticles</artifactId>
<version>2.0.0</version>
<scope>provided</scope>
</dependency>
</dependencies>
2. Mark it as a hard dependency
In your plugin.yml:
name: MyPlugin
version: 1.0
main: com.example.plugin.MyPlugin
depend: [MoParticles]
3. Play an effect
MoParticleAPI api = MoParticleAPI.get();
String effectName = "fire";
Location targetLocation = player.getLocation();
if (api.hasEffect(effectName)) {
UUID animationId = api.play(effectName, targetLocation, 10.0);
api.stop(animationId);
}
评论 0
登录后参与评分
还没有评论,来抢沙发吧