关于 3.x.x 版本的详细信息,请查看 从 3.x.x 迁移到 4.x.x 部分。
ParticleNativeAPI
ParticleNativeAPI 是一个专为 Spigot 和 Bukkit 服务器设计的粒子生成 API,旨在:
- 快速(性能可与原生 Java 代码相媲美!),
- 跨版本兼容,支持至 MC 1.7(包含已移除的粒子!),
- 使用灵活,
- 相对简单且易于使用。
此外,该粒子 API 支持生成特定类型的粒子:
- 方块粒子,
- 物品粒子,
- 带颜色(每个数据包仅 1 个粒子),
- 带颜色和大小,
- 带过渡颜色和大小,
- 带特定运动轨迹(每个数据包仅 1 个粒子)
- 带角度
- 带延迟
……同时保持高速以及在 Minecraft 更新之间的跨版本兼容性。

整个 API 结构旨在反映 Minecraft 发送数据包的方式,但它采用强类型设计且不依赖反射(Reflection)来实现这一目标!
使用方法
生成粒子的过程通过非常简单的链式方法完成:
- 从 API -> 获取粒子列表 -> 获取粒子
- 选择粒子的属性
- 生成粒子数据包
- 使用粒子列表发送数据包。
就这么简单。
// 从插件实例获取 API
ParticleNativeAPI api = ParticleNativePlugin.getAPI();
// ... 或者使用核心模块生成它(“this” 是你的插件实例)
particleApi = ParticleNativeCore.loadAPI(this);
Player player = ...;
Location loc = player.getLocation();
// 如此简单即可
particleApi.LIST_1_8.FLAME // 从所需列表中获取粒子
.packet(true, loc) // 生成粒子数据包
.sendTo(player); // 发送给特定的玩家
将数据包发送给谁或在什么条件下发送由你决定。如需了解更多关于上述粒子列表的信息,我鼓励你阅读我 GitHub 仓库中的详细教程 此处。
为什么它很快
它在内部使用 ObjectWeb 的 ASM 库来生成与版本相关的 Java 代码,而不是使用反射。
反射仅用于识别在服务器启动阶段应生成哪个 Minecraft 版本的 API。
简易基准测试
我在本地主机上进行了测试,以测量在我的角色周围随机位置生成 400,000 个粒子的执行时间。
notable 环境配置:
- 本地主机服务器 MC 1.17
- JDK 17
- Intel i5-12600
- 32 GB RAM DDR4
所有测试均在经过广泛的预热后执行,即多次运行以允许 JVM 优化频繁使用的代码。
然而,这仍然是一个简单的基准测试(并非 JMH 或其他专业工具),因此结果仅供参考,请谨慎看待。
用于测试的所有代码均可在我的仓库中找到 此处。
测试包含 4 种发送粒子的方法:
- nms - 直接使用 NMS 和 OBC 发送数据包,
- particle_native_api - 使用本 API 通过简单方法发送粒子,
- spigot_api - 使用 Spigot API 的 spawnParticle 方法(针对玩家)发送效果,
- reflection - 使用具有可访问性设置为 true 的 NMS 和 OBC 反射类来发送粒子。这些类/方法/字段会被缓存以供多次使用。

正如你所见,至少在我的机器上,ParticleNativeAPI 的性能与 Spigot API 相当,并且非常接近特定版本实现的速度。
最小化使用示例概述
public class PluginName extends JavaPlugin {
// 加载的粒子 API
private ParticleNativeAPI particleApi;
@Override
public void onEnable() {
// 加载 API 并存储以备后用
particleApi = ParticleNativeCore.loadAPI(this);
// 或者从正在运行的插件 API 实例中获取它
// 检查其状态是否正常
// if (ParticelNativePlugin.isValid()) {
// particleApi = ParticleNativePlugin.getAPI();
// }
// else {
// getLogger().log(Level.SEVERE, "加载依赖时发生错误。");
// this.setEnabled(false);
// return;
// }
}
// 使用示例
@Override
public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
if (!command.getName().equalsIgnoreCase("somecmd")) return true;
if (!(sender instanceof Player)) {
sender.sendMessage(ChatColor.RED + "你必须是一名玩家才能使用此命令!");
return true;
}
Player pSender = (Player) sender;
Location loc = pSender.getLocation();
// 粒子生成
particleApi.LIST_1_8.FLAME // 从列表中选择粒子
.packet(true, loc) // 创建粒子数据包
.sendInRadiusTo(player, 30D); // 如果玩家在 30 格半径内,则向其发送
return true;
}
}
服务器管理员须知
如果您是通过其他插件被重定向到此页面,只需将该插件的 jar 文件放入 plugins 文件夹即可。
除了启动阶段外,该库本身不会执行任何操作。它可以作为其他插件的依赖项使用。
插件开发者须知
详细的教程和各种示例可以在我的 GitHub 仓库中找到:这里。
核心 API 的 Maven 配置及示例设置(官方仓库):
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.2.0</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
<configuration>
<!-- 用主构件替换阴影版本 -->
<shadedArtifactAttached>false</shadedArtifactAttached>
<!-- 重定位 API 类以避免与使用此核心 API 的其他插件产生相同类路径冲突 -->
<relocations>
<relocation>
<pattern>com.github.fierioziy.particlenativeapi</pattern>
<shadedPattern>me.yourpluginpackage.particleapi</shadedPattern>
</relocation>
</relocations>
</configuration>
</execution>
</executions>
</plugin>
<!-- 其他插件 ... -->
</plugins>
<!-- 其他构建配置 ... -->
</build>
<dependencies>
<dependency>
<groupId>com.github.fierioziy.particlenativeapi</groupId>
<artifactId>ParticleNativeAPI-core</artifactId>
<version>4.5.0</version>
<scope>compile</scope>
</dependency>
<!-- 其他依赖 -->
</dependencies></pre>
插件引用设置的 Maven 配置(官方仓库):
<dependencies>
<dependency>
<groupId>com.github.fierioziy.particlenativeapi</groupId>
<artifactId>ParticleNativeAPI-plugin</artifactId>
<version>4.5.0</version>
<scope>provided</scope>
</dependency>
<!-- 其他依赖 -->
</dependencies></pre>
请求功能或报告问题
如果您发现了错误或想要请求新功能,请使用我 GitHub 上的 Issue 追踪器:这里。
源代码
所有插件的源代码都在我的 GitHub 仓库中:这里。
对于 3.x.x 版本,当前源代码位于 master-v3 分支:这里。
兼容性
已测试的 Spigot 版本:1.7.10, 1.8.8, 1.12, 1.14.3, 1.15.2, 1.16.5, 1.17, 1.18, 1.19, 1.19.3, 1.20.2, 1.20.6, 1.21.1, 1.21.3, 1.21.4, 1.21.10.
已测试的 Paper-Spigot 版本(自 1.20.6 起内部存在与 Spigot 的差异):1.20.6, 1.21.3, 1.21.4, 1.21.10.
目前,插件应至少兼容 MC 1.7 到 MC 1.21.10 之间的版本。
它也应该能在 Bukkit (CraftBukkit) 上运行。
只有在添加新功能/修复错误,或者未来版本的 Minecraft 在数据包处理方面发生变化时,才需要更新。
请注意,本 API 将优先考虑向后兼容性
即优先支持 MC 版本范围内的向后兼容,而非自身的前向兼容。
通常情况下,这将以新主要版本的形式发布(例如从 3.x.x 到 4.x.x)
话虽如此,接下来的 API 更新有时可能会迫使您修改代码
以再次与新版本的 API 保持兼容。
For version 3.x.x details of this lib check Migration from 3.x.x to 4.x.x section.
ParticleNativeAPI
ParticleNativeAPI is a particle spawning API for Spigot and Bukkit server designed to be:
- fast (comparable to native Java written code!),
- cross-version compatible down to MC 1.7 (includes removed particles!),
- flexible in use,
- relatively easy and convenient to use.
On top of that, this particle API supports spawning certain particles:
- of blocks,
- of items,
- with color (only 1 particle per packet),
- with color and size,
- with transition color and size,
- with certain motion (only 1 particle per packet)
- with angle
- with delay
... and still be fast and cross version compatible between Minecraft updates.

Entire API structure targets to reflect how Minecraft handles sending packets, however it strongly typed and uses no Reflection to do so!
How to use
Spawning particle is made in very simple method chain:
- from API -> get particles list -> get particle
- select properties of particle
- make particle packet
- send it, using particles lists.
That's it.
// get API from plugin instance
ParticleNativeAPI api = ParticleNativePlugin.getAPI();
// ... or generate it using core module ("this" is Your plugin instance)
particleApi = ParticleNativeCore.loadAPI(this);
Player player = ...;
Location loc = player.getLocation();
// as simple as that
particleApi.LIST_1_8.FLAME // from desired list get particle
.packet(true, loc) // make particle packet
.sendTo(player); // send it to certain player(s)
To whoever you want to send this packet or on what conditions is up to You. To read more about particle lists above, I encourage you to read detailed tutorial on my github repository here.
Why is it fast
It internally uses ObjectWeb's ASM library to generate version-dependent Java code instead of using Reflection.
Reflection is only used to recognize on which Minecraft version should API be generated, at server start-up phase.
Simple benchmark
I've made test on localhost to measure execution time of 400 000 particles in random locations around my character.
Notable environment:
- localhost server MC 1.17
- JDK 17
- Intel i5-12600
- 32 GB RAM DDR4
All tests were made after an extensive warmup of executing them several times to allow JVM to optimize frequently used code.
However, it is still simple benchmark (not JMH or something), so results should be taken with a little pinch of salt.
All code used to test is found on my repository here.
Tests consist of 4 methods to send particle:
- nms - uses directly NMS and OBC to send packet,
- particle_native_api - uses this api to send particle with simple method,
- spigot_api - uses Spigot API's spawnParticle method (to player) to send effect,
- reflection - uses NMS and OBC reflected classes (with accessibility set to true) to send particle. Those classes/methods/fields are cached for multiple use.

As you can see, at least on my machine, ParticleNativeAPI is comparable to Spigot API and very close in speed to version specific implementation.
Minimal usage example overview
public class PluginName extends JavaPlugin {
// loaded particle API
private ParticleNativeAPI particleApi;
@Override
public void onEnable() {
// load API and store it for later use
particleApi = ParticleNativeCore.loadAPI(this);
// or get it from running plugin api instance
// check if everything is fine with it
// if (ParticelNativePlugin.isValid()) {
// particleApi = ParticleNativePlugin.getAPI();
// }
// else {
// getLogger().log(Level.SEVERE, "Error occurred while loading dependency.");
// this.setEnabled(false);
// return;
// }
}
// example usage
@Override
public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
if (!command.getName().equalsIgnoreCase("somecmd")) return true;
if (!(sender instanceof Player)) {
sender.sendMessage(ChatColor.RED + "You must be player to use this command!");
return true;
}
Player pSender = (Player) sender;
Location loc = pSender.getLocation();
// particle spawning
particleApi.LIST_1_8.FLAME // select particle from list
.packet(true, loc) // create particle packet
.sendInRadiusTo(player, 30D); // send it to player if in 30 block radius
return true;
}
}
For server owners
If you were redirected here by other plugin, just include plugin's jar in plugins folder.
This library doesn't do anything on it's own besides startup phase. It may be used as a dependency by other plugins.
For plugin developers
A detailed tutorial with various examples can be found on my github repository here.
Maven for core API with example setup (official repository):
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.2.0</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
<configuration>
<!-- replace shaded version with main artifact -->
<shadedArtifactAttached>false</shadedArtifactAttached>
<!-- relocate API classes to avoid same-classpath-conflicts -->
<!-- with other plugins using this core API -->
<relocations>
<relocation>
<pattern>com.github.fierioziy.particlenativeapi</pattern>
<shadedPattern>me.yourpluginpackage.particleapi</shadedPattern>
</relocation>
</relocations>
</configuration>
</execution>
</executions>
</plugin>
<!-- other plugins ... -->
</plugins>
<!-- other build config ... -->
</build>
<dependencies>
<dependency>
<groupId>com.github.fierioziy.particlenativeapi</groupId>
<artifactId>ParticleNativeAPI-core</artifactId>
<version>4.5.0</version>
<scope>compile</scope>
</dependency>
<!-- other dependencies -->
</dependencies></pre>
Maven for plugin reference setup (official repository):
<dependencies>
<dependency>
<groupId>com.github.fierioziy.particlenativeapi</groupId>
<artifactId>ParticleNativeAPI-plugin</artifactId>
<version>4.5.0</version>
<scope>provided</scope>
</dependency>
<!-- other dependencies -->
</dependencies></pre>
Request feature or report an issue
If you found a bug or just want to request a feature, use an issue tracker on my github here.
Source code
All plugin's source code is present on my github repository here.
For version 3.x.x current source is on branch master-v3 here.
Compatibility
Tested Spigot versions: 1.7.10, 1.8.8, 1.12, 1.14.3, 1.15.2, 1.16.5, 1.17, 1.18, 1.19, 1.19.3, 1.20.2, 1.20.6, 1.21.1, 1.21.3, 1.21.4, 1.21.10.
Tested Paper-Spigot versions (since 1.20.6 internal discrepancies with Spigot): 1.20.6, 1.21.3, 1.21.4, 1.21.10.
Plugin should be compatible at least between MC 1.7 and MC 1.21.10 for now.
It should work on Bukkit (CraftBukkit) as well.
It will only needs update if new feature/bugfix were added or there were Minecraft changes in packet handling in future versions.
Keep in mind, that this API will favor backward compatibility
with supported MC versions range instead of forward compatibility of itself.
Most of the time it will be announced as new major version (for ex. from 3.x.x to 4.x.x)
That said, next API updates might sometimes force some changes
in Your code to again be compatible with newer API version.
评论 0
登录后参与评分
还没有评论,来抢沙发吧