![ParticleNativeAPI [1.7+]](https://www.spigotmc.org/data/resource_icons/76/76480.jpg?1585129467){kind=icon}
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:
Entire API structure targets to reflect how Minecraft handles sending packets, however it is strongly typed and uses no Reflection to do so!
How to use
Spawning particle is made in very simple method chain:
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
Minimal usage example overview
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):
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, 1.21.11.
Tested Paper-Spigot versions (since 1.20.6 internal discrepancies with Spigot): 1.20.6, 1.21.3, 1.21.4, 1.21.10, 1.21.11.
It should work on Bukkit (CraftBukkit) as well.
Plugin should be compatible at least between MC 1.7 and MC 1.21.11 for now.
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.
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.
- 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
Entire API structure targets to reflect how Minecraft handles sending packets, however it is 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
Code (Java):
// 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)
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)
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
Spoiler: Simple benchmark
I've made test on localhost to measure execution time of 400 000 particles in random locations around my character.
Notable environment:
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:
As you can see, at least on my machine, ParticleNativeAPI is comparable to Spigot API and very close in speed to version specific implementation.
Notable environment:
- localhost server MC 1.17
- JDK 17
- Intel i5-12600
- 32 GB RAM DDR4
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
Spoiler: A minimal plugin example
For server owners
Code (Java):
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 ;
}
}
// 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 ;
}
}
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):
Spoiler: Core API
Maven for plugin reference setup (official repository):
HTML:
<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>
<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>
Spoiler: Plugin API
HTML:
<dependencies>
<dependency>
<groupId>com.github.fierioziy.particlenativeapi </groupId>
<artifactId>ParticleNativeAPI-plugin </artifactId>
<version>4.5.0 </version>
<scope>provided </scope>
</dependency>
<!-- other dependencies -->
</dependencies>
<dependency>
<groupId>com.github.fierioziy.particlenativeapi </groupId>
<artifactId>ParticleNativeAPI-plugin </artifactId>
<version>4.5.0 </version>
<scope>provided </scope>
</dependency>
<!-- other dependencies -->
</dependencies>
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, 1.21.11.
Tested Paper-Spigot versions (since 1.20.6 internal discrepancies with Spigot): 1.20.6, 1.21.3, 1.21.4, 1.21.10, 1.21.11.
It should work on Bukkit (CraftBukkit) as well.
Plugin should be compatible at least between MC 1.7 and MC 1.21.11 for now.
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.
Quick facts
- Edition: Minecraft Java
- File type: .jar
- Minecraft versions listed: 1.7, 1.8, 1.9
- How to install: Install the matching mod loader (Forge, Fabric or NeoForge) for your Minecraft version. → Download the .jar. → Put it in the .minecraft/mods folder and launch that loader profile.
- Where to get it: Opens on Spigot — not every file is mirrored on our own servers.
Install steps are the general flow for this file type — How to install Minecraft Java mods & modpacks walks through it step by step.
ParticleNativeAPI [1.7+] is a free Minecraft Java mod. Compatible with Minecraft 1.7, 1.8, 1.9, 1.10 and newer. Downloaded 4,015 times (via Spigot). Download it and open it directly in the game.