com.github.fierioziy.api.ServerConnection Maven / Gradle / Ivy
Show all versions of ParticleNativeAPI Show documentation
package com.github.fierioziy.api;
import com.github.fierioziy.ParticleNativeAPI;
import org.bukkit.Location;
import org.bukkit.entity.Player;
import java.util.Collection;
/**
* Interface used to handle packet sending.
*
* It provides a non-reflective methods that uses NMS PlayerConnection
* to send Minecraft packets.
*
* It is dynamically generated by ParticleNativeAPI instance and should
* only be obtained from there.
* @see ParticleNativeAPI
*/
public interface ServerConnection {
/**
* Creates a non-reflective wrapper of
* parameter player's NMS PlayerConnection instance.
*
* A generated code for this method looks roughly like this:
* {@code
* PlayerConnection createPlayerConnection(Player player) {
* return new PlayerConnection_Impl(player);
* }
* }
*
* If you plan to send more than 4-5 packets to one
* of Players somewhere, then using this wrapper will be
* more beneficial (faster) than using ServerConnection due
* to caching NMS PlayerConnection directly in field.
*
* It is better not to cache it long-term (for ex.
* in HashMap/ArrayList etc.) and any complications to do it
* anyways will be significantly slower than ServerConnection.
*
* Obtaining PlayerConnection from ServerConnection is fast, really.
*
* @param player a player from which PlayerConnection should be obtained.
* @return a non-reflective PlayerConnection wrapper of
* this player's NMS PlayerConnection.
* @see PlayerConnection
*/
PlayerConnection createPlayerConnection(Player player);
/**
* Sends packet to a Player using its NMS PlayerConnection.
*
* A generated code for this method looks roughly like this:
* {@code
* void sendPacket(Player player, Object packet) {
* ((CraftPlayer) player).getHandle().playerConnection
* .sendPacket((Packet) packet);
* }
* }
*
* A packet parameter must be an instance of Minecraft packet interface.
* Otherwise, you might get ClassCastException on packet parameter.
*
* You can use this method to send other packet than instances created using
* this API. Any valid Minecraft packet can be used by this method.
*
* @param player a player to which send a packet object.
* @param packet a valid Minecraft packet created either by this API or
* via reflections.
* @throws ClassCastException when provided packet object is not
* an instance of Minecraft packet interface.
*/
void sendPacket(Player player, Object packet);
/**
* Sends packet to each Player using their NMS PlayerConnection.
*
* A generated code for this method looks roughly like this:
* {@code
* void sendPacket(Collection players, Object packet) {
* Packet nmsPacket = (Packet) packet;
*
* int length = players.size();
* Iterator it = players.iterator();
*
* for (int i = 0; i < length; ++i) {
* ((CraftPlayer) it.next()).getHandle().playerConnection
* .sendPacket(nmsPacket);
* }
* }
* }
*
* A packet parameter must be an instance of Minecraft packet interface.
* Otherwise, you might get ClassCastException on packet parameter.
*
* You can use this method to send other packet than instances created using
* this API. Any valid Minecraft packet can be used by this method.
*
* @param players a Collection of players to which send a packet object.
* @param packet a valid Minecraft packet created either by this API or
* via reflections.
* @throws ClassCastException when provided packet object is not
* an instance of Minecraft packet interface.
*/
void sendPacket(Collection players, Object packet);
/**
* Send a packet to every player in given radius.
*
* Technically speaking, gets all players around loc parameter
* in given radius and send packet to every player in radius
* using its NMS PlayerConnection.
*
* A generated code for this method looks (roughly) like this:
* {@code
* void sendPacket(Location loc, double radius, Object packet) {
* radius *= radius;
* Packet nmsPacket = (Packet) packet;
*
* double x = loc.getX();
* double y = loc.getY();
* double z = loc.getZ();
*
* // this initializations are optimized
* int length = loc.getWorld().getPlayers().size();
* Iterator it = loc.getWorld().getPlayers().iterator();
*
* for (int i = 0; i < length; ++i) {
* CraftPlayer p = (CraftPlayer) it.next();
* Location pLoc = p.getLocation();
*
* // pseudo code if statement is optimized
* if (( (pLoc.getX() - x)^2
* + (pLoc.getY() - y)^2
* + (pLoc.getZ() - z)^2) <= radius) {
* p.getHandle().playerConnection.sendPacket(nmsPacket);
* }
* }
* }
* }
*
* This method should be a little faster than normal for-each loop
* with radius check due to few bytecode optimizations:
*
* - one packet cast per entire loop,
* - duplicating list reference around
*
length and it variables,
* - duplicating subtraction results around radius check,
* - using traditional
for loop with
* cached list size instead of hasNext interface
* method check on each iteration.
*
*
* A packet parameter must be an instance of Minecraft packet interface.
* Otherwise, you might get ClassCastException on packet parameter.
*
* You can use this method to send other packet than instances created using
* this API. Any valid Minecraft packet can be used by this method.
*
* @param loc a Location containing position.
* @param radius a spherical radius around which send packet to
* nearby players.
* @param packet a valid Minecraft packet created either by this API or
* via reflections.
* @throws ClassCastException when provided packet object is not
* an instance of Minecraft packet interface.
*/
void sendPacket(Location loc, double radius, Object packet);
}