📝 Added API documentation

This commit is contained in:
SBDeveloper 2022-07-01 12:54:19 +02:00
parent c6cf6c2c3b
commit e110f0afcc
13 changed files with 268 additions and 185 deletions

13
pom.xml
View file

@ -48,6 +48,13 @@
<version>3.9.0-SNAPSHOT</version>
<configuration>
<release>11</release>
<annotationProcessorPaths>
<path>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.18.24</version>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
<plugin>
@ -108,5 +115,11 @@
<version>4.8.0</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.18.24</version>
<scope>provided</scope>
</dependency>
</dependencies>
</project>

View file

@ -30,7 +30,7 @@ import org.bukkit.plugin.java.JavaPlugin;
import tech.sbdevelopment.mapreflectionapi.api.MapManager;
import tech.sbdevelopment.mapreflectionapi.listeners.MapListener;
import tech.sbdevelopment.mapreflectionapi.listeners.PacketListener;
import tech.sbdevelopment.mapreflectionapi.util.ReflectionUtils;
import tech.sbdevelopment.mapreflectionapi.utils.ReflectionUtils;
import java.util.logging.Level;
@ -38,11 +38,21 @@ public class MapReflectionAPI extends JavaPlugin {
private static MapReflectionAPI instance;
private static MapManager mapManager;
/**
* Get the plugin instance
*
* @return The {@link MapReflectionAPI} instance
*/
public static MapReflectionAPI getInstance() {
if (instance == null) throw new IllegalStateException("The plugin is not enabled yet!");
return instance;
}
/**
* Get the {@link MapManager}
*
* @return The manager
*/
public static MapManager getMapManager() {
if (mapManager == null) throw new IllegalStateException("The plugin is not enabled yet!");
return mapManager;
@ -74,18 +84,8 @@ public class MapReflectionAPI extends JavaPlugin {
return;
}
ProtocolLibrary.getProtocolManager().addPacketListener(new PacketListener(this));
try {
mapManager = new MapManager(this);
} catch (IllegalStateException e) {
getLogger().log(Level.SEVERE, e.getMessage(), e);
Bukkit.getPluginManager().disablePlugin(this);
return;
}
getLogger().info("Registering the events...");
Bukkit.getPluginManager().registerEvents(new MapListener(), this);
getLogger().info("Loading the map manager...");
mapManager = new MapManager();
getLogger().info("Discovering occupied Map IDs...");
for (int s = 0; s < Short.MAX_VALUE; s++) {
@ -99,6 +99,10 @@ public class MapReflectionAPI extends JavaPlugin {
}
}
getLogger().info("Registering the listeners...");
Bukkit.getPluginManager().registerEvents(new MapListener(), this);
ProtocolLibrary.getProtocolManager().addPacketListener(new PacketListener(this));
getLogger().info("MapReflectionAPI is enabled!");
getLogger().info("----------------");
}

View file

@ -24,14 +24,21 @@
package tech.sbdevelopment.mapreflectionapi.api;
import com.bergerkiller.bukkit.common.map.MapColorPalette;
import lombok.EqualsAndHashCode;
import lombok.RequiredArgsConstructor;
import lombok.ToString;
import java.awt.*;
import java.awt.image.BufferedImage;
import java.util.Arrays;
import java.util.Objects;
/**
* This class contains an image converted to a Minecraft byte array
*/
@RequiredArgsConstructor
@EqualsAndHashCode
@ToString
public class ArrayImage {
public byte[] array;
public final byte[] array;
public int minX = 0;
public int minY = 0;
public int maxX = 128;
@ -40,10 +47,6 @@ public class ArrayImage {
private int height;
private int imageType = BufferedImage.TYPE_4BYTE_ABGR;
public ArrayImage(byte[] data) {
this.array = data;
}
/**
* Convert a {@link BufferedImage} to an ArrayImage
*
@ -71,6 +74,11 @@ public class ArrayImage {
this.array = result;
}
/**
* Get the {@link BufferedImage} of this ArrayImage
*
* @return The converted image
*/
public BufferedImage toBuffered() {
BufferedImage img = new BufferedImage(width, height, this.imageType);
for (int x = 0; x < width; x++) {
@ -80,33 +88,4 @@ public class ArrayImage {
}
return img;
}
@Override
public boolean equals(Object o) {
if (this == o) return true;
if (!(o instanceof ArrayImage)) return false;
ArrayImage that = (ArrayImage) o;
return width == that.width && height == that.height && imageType == that.imageType && Arrays.equals(array, that.array);
}
@Override
public int hashCode() {
int result = Objects.hash(width, height, imageType);
result = 31 * result + Arrays.hashCode(array);
return result;
}
@Override
public String toString() {
return "ArrayImage{" +
"array=" + Arrays.toString(array) +
", minX=" + minX +
", minY=" + minY +
", maxX=" + maxX +
", maxY=" + maxY +
", width=" + width +
", height=" + height +
", imageType=" + imageType +
'}';
}
}

View file

@ -27,7 +27,7 @@ import org.bukkit.OfflinePlayer;
import org.bukkit.World;
import org.bukkit.entity.ItemFrame;
import org.bukkit.entity.Player;
import tech.sbdevelopment.mapreflectionapi.exceptions.MapLimitExceededException;
import tech.sbdevelopment.mapreflectionapi.api.exceptions.MapLimitExceededException;
public interface MapController {
/**
@ -72,6 +72,11 @@ public interface MapController {
*/
void update(ArrayImage content);
/**
* Get the content of the controller
*
* @return The {@link ArrayImage}
*/
ArrayImage getContent();
/**

View file

@ -23,12 +23,10 @@
package tech.sbdevelopment.mapreflectionapi.api;
import org.bukkit.Bukkit;
import org.bukkit.OfflinePlayer;
import org.bukkit.entity.Player;
import org.bukkit.plugin.java.JavaPlugin;
import org.jetbrains.annotations.Nullable;
import tech.sbdevelopment.mapreflectionapi.exceptions.MapLimitExceededException;
import tech.sbdevelopment.mapreflectionapi.api.exceptions.MapLimitExceededException;
import java.awt.image.BufferedImage;
import java.util.HashSet;
@ -40,19 +38,22 @@ public class MapManager {
protected final Set<Integer> OCCUPIED_IDS = new HashSet<>();
private final List<MapWrapper> MANAGED_MAPS = new CopyOnWriteArrayList<>();
public MapManager(JavaPlugin plugin) throws IllegalStateException {
String packageName = Bukkit.getServer().getClass().getPackage().getName();
String version = packageName.substring(packageName.lastIndexOf('.') + 1);
plugin.getLogger().info("Initializing the map manager for Minecraft version " + version + "...");
}
@Nullable
/**
* Wrap a {@link BufferedImage} in a {@link MapWrapper}
*
* @param image The image to wrap
* @return The wrapper
*/
public MapWrapper wrapImage(BufferedImage image) {
return wrapImage(new ArrayImage(image));
}
@Nullable
/**
* Wrap a {@link ArrayImage} in a {@link MapWrapper}
*
* @param image The image to wrap
* @return The wrapper
*/
public MapWrapper wrapImage(ArrayImage image) {
for (MapWrapper wrapper : MANAGED_MAPS) {
if (wrapper.getContent().equals(image)) return wrapper;
@ -60,12 +61,23 @@ public class MapManager {
return wrapNewImage(image);
}
/**
* Wrap a new image
*
* @param image The image to wrap
* @return The wrapper
*/
private MapWrapper wrapNewImage(ArrayImage image) {
MapWrapper wrapper = new MapWrapper(image);
MANAGED_MAPS.add(wrapper);
return wrapper;
}
/**
* Unwrap an image (will remove the wrapper)
*
* @param wrapper The {@link MapWrapper} to unwrap
*/
public void unwrapImage(MapWrapper wrapper) {
//TODO Cancel IDs
@ -73,6 +85,12 @@ public class MapManager {
MANAGED_MAPS.remove(wrapper);
}
/**
* Get the maps a player can see
*
* @param player The {@link Player} to check for
* @return A {@link Set} with the {@link MapWrapper}s
*/
public Set<MapWrapper> getMapsVisibleTo(OfflinePlayer player) {
Set<MapWrapper> visible = new HashSet<>();
for (MapWrapper wrapper : MANAGED_MAPS) {
@ -83,6 +101,14 @@ public class MapManager {
return visible;
}
/**
* Get the wrapper by a player and map id
*
* @param player The {@link OfflinePlayer} to check for
* @param id The ID of the map
* @return The {@link MapWrapper} for that map or null
*/
@Nullable
public MapWrapper getWrapperForId(OfflinePlayer player, int id) {
for (MapWrapper wrapper : getMapsVisibleTo(player)) {
if (wrapper.getController().getMapId(player) == id) {
@ -92,14 +118,30 @@ public class MapManager {
return null;
}
/**
* Register an occupied map ID
*
* @param id The map ID to register
*/
public void registerOccupiedID(int id) {
OCCUPIED_IDS.add(id);
}
/**
* Unregister an occupied map ID
*
* @param id The map ID to unregister
*/
public void unregisterOccupiedID(int id) {
OCCUPIED_IDS.remove(id);
}
/**
* Get the occupied IDs for a player
*
* @param player The {@link OfflinePlayer} to check for
* @return A {@link Set} with the found map IDs
*/
public Set<Integer> getOccupiedIdsFor(OfflinePlayer player) {
Set<Integer> ids = new HashSet<>();
for (MapWrapper wrapper : MANAGED_MAPS) {
@ -111,10 +153,24 @@ public class MapManager {
return ids;
}
/**
* Check if a player uses a map ID
*
* @param player The {@link OfflinePlayer} to check for
* @param id The map ID to check for
* @return true/false
*/
public boolean isIdUsedBy(OfflinePlayer player, int id) {
return id > 0 && getOccupiedIdsFor(player).contains(id);
}
/**
* Get the next ID that can be used for this player
*
* @param player The {@link Player} to check for
* @return The next ID
* @throws MapLimitExceededException If no IDs are available
*/
public int getNextFreeIdFor(Player player) throws MapLimitExceededException {
Set<Integer> occupied = getOccupiedIdsFor(player);
//Add the 'default' occupied IDs
@ -143,12 +199,26 @@ public class MapManager {
throw new MapLimitExceededException("'" + player + "' reached the maximum amount of available Map-IDs");
}
/**
* Clear all the maps of a player
* This makes them no longer viewable for this player
*
* @param player The {@link OfflinePlayer} to clear for
*/
public void clearAllMapsFor(OfflinePlayer player) {
for (MapWrapper wrapper : getMapsVisibleTo(player)) {
wrapper.getController().removeViewer(player);
}
}
/**
* Check if a MapWrapper exists for this image
* If so, the same MapWrapper can be used
*
* @param image The {@link ArrayImage} to check for
* @return A {@link MapWrapper} if duplicate, or null if not
*/
@Nullable
public MapWrapper getDuplicate(ArrayImage image) {
for (MapWrapper wrapper : MANAGED_MAPS) {
if (image.equals(wrapper.getContent())) {

View file

@ -26,8 +26,8 @@ package tech.sbdevelopment.mapreflectionapi.api;
import org.bukkit.Bukkit;
import org.bukkit.entity.Player;
import tech.sbdevelopment.mapreflectionapi.MapReflectionAPI;
import tech.sbdevelopment.mapreflectionapi.util.ReflectionUtil;
import tech.sbdevelopment.mapreflectionapi.util.ReflectionUtils;
import tech.sbdevelopment.mapreflectionapi.utils.ReflectionUtil;
import tech.sbdevelopment.mapreflectionapi.utils.ReflectionUtils;
import java.util.ArrayList;
import java.util.List;
@ -37,6 +37,13 @@ public class MapSender {
private static final List<QueuedMap> sendQueue = new ArrayList<>();
private static int senderID = -1;
/**
* Add a map to the send queue
*
* @param id The ID of the map
* @param content The {@link ArrayImage} to view on the map
* @param player The {@link Player} to view for
*/
public static void addToQueue(final int id, final ArrayImage content, final Player player) {
QueuedMap toSend = new QueuedMap(id, content, player);
if (sendQueue.contains(toSend)) return;
@ -45,6 +52,9 @@ public class MapSender {
runSender();
}
/**
* Run the sender task
*/
private static void runSender() {
if (Bukkit.getScheduler().isQueued(senderID) || Bukkit.getScheduler().isCurrentlyRunning(senderID) || sendQueue.isEmpty())
return;
@ -66,6 +76,13 @@ public class MapSender {
private static final Class<?> packetPlayOutMapClass = ReflectionUtils.getNMSClass("network.protocol.game", "PacketPlayOutMap");
private static final Class<?> worldMapData = ReflectionUtils.supports(17) ? ReflectionUtils.getNMSClass("world.level.saveddata.maps", "WorldMap") : null;
/**
* Send a map to a player
*
* @param id0 The ID of the map
* @param content The {@link ArrayImage} to view on the map
* @param player The {@link Player} to view for
*/
public static void sendMap(final int id0, final ArrayImage content, final Player player) {
if (player == null || !player.isOnline()) {
List<QueuedMap> toRemove = new ArrayList<>();

View file

@ -30,15 +30,20 @@ import org.bukkit.inventory.ItemStack;
import org.bukkit.inventory.meta.ItemMeta;
import org.bukkit.metadata.FixedMetadataValue;
import tech.sbdevelopment.mapreflectionapi.MapReflectionAPI;
import tech.sbdevelopment.mapreflectionapi.exceptions.MapLimitExceededException;
import tech.sbdevelopment.mapreflectionapi.util.ReflectionUtil;
import tech.sbdevelopment.mapreflectionapi.util.ReflectionUtils;
import tech.sbdevelopment.mapreflectionapi.api.exceptions.MapLimitExceededException;
import tech.sbdevelopment.mapreflectionapi.utils.ReflectionUtil;
import tech.sbdevelopment.mapreflectionapi.utils.ReflectionUtils;
import java.util.*;
public class MapWrapper {
protected ArrayImage content;
/**
* Construct a new {@link MapWrapper}
*
* @param image The {@link ArrayImage} to wrap
*/
public MapWrapper(ArrayImage image) {
this.content = image;
}
@ -274,13 +279,21 @@ public class MapWrapper {
}
};
/**
* Get the content that is wrapped
*
* @return The {@link ArrayImage}
*/
public ArrayImage getContent() {
return content;
}
/**
* Get the controller of this wrapper
*
* @return The {@link MapController}
*/
public MapController getController() {
return controller;
}
}

View file

@ -23,29 +23,42 @@
package tech.sbdevelopment.mapreflectionapi.api.events;
import lombok.Getter;
import lombok.RequiredArgsConstructor;
import lombok.Setter;
import org.bukkit.Material;
import org.bukkit.entity.Player;
import org.bukkit.event.Cancellable;
import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;
import org.bukkit.inventory.ItemStack;
import org.jetbrains.annotations.Nullable;
import tech.sbdevelopment.mapreflectionapi.MapReflectionAPI;
import tech.sbdevelopment.mapreflectionapi.api.MapWrapper;
/**
* This event gets fired when a map in the creative inventory gets updated
*/
@RequiredArgsConstructor
@Getter
public class CreateInventoryMapUpdateEvent extends Event implements Cancellable {
private static final HandlerList handlerList = new HandlerList();
@Setter
private boolean cancelled;
private final Player player;
private final int slot;
private final ItemStack item;
private MapWrapper mapWrapper;
private boolean cancelled;
public CreateInventoryMapUpdateEvent(Player player, int slot, ItemStack item) {
this.player = player;
this.slot = slot;
this.item = item;
}
/**
* Construct a new {@link CreateInventoryMapUpdateEvent}
*
* @param player The player whose inventory is updated
* @param slot The new slot
* @param item The item in the new slot
* @param isAsync Is this event called async?
*/
public CreateInventoryMapUpdateEvent(Player player, int slot, ItemStack item, boolean isAsync) {
super(isAsync);
this.player = player;
@ -53,44 +66,24 @@ public class CreateInventoryMapUpdateEvent extends Event implements Cancellable
this.item = item;
}
public static HandlerList getHandlerList() {
return handlerList;
}
public Player getPlayer() {
return player;
}
public int getSlot() {
return slot;
}
public ItemStack getItem() {
return item;
}
public MapWrapper getMapWrapper() {
if (mapWrapper == null) {
if (item == null) return null;
if (item.getType() != Material.MAP) return null;
MapReflectionAPI.getMapManager().getWrapperForId(player, item.getDurability());
}
return mapWrapper;
}
@Override
public HandlerList getHandlers() {
return handlerList;
}
@Override
public boolean isCancelled() {
return cancelled;
}
/**
* Get the {@link MapWrapper} of the map of this event
*
* @return The {@link MapWrapper}
*/
@Nullable
public MapWrapper getMapWrapper() {
if (mapWrapper == null) {
if (item == null) return null;
if (item.getType() != Material.MAP) return null;
mapWrapper = MapReflectionAPI.getMapManager().getWrapperForId(player, item.getDurability());
}
@Override
public void setCancelled(boolean b) {
this.cancelled = b;
return mapWrapper;
}
}

View file

@ -23,52 +23,42 @@
package tech.sbdevelopment.mapreflectionapi.api.events;
import lombok.Getter;
import lombok.RequiredArgsConstructor;
import lombok.Setter;
import org.bukkit.entity.Player;
import org.bukkit.event.Cancellable;
import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;
/**
* This event gets fired when a map creation is cancelled
*/
@RequiredArgsConstructor
@Getter
public class MapCancelEvent extends Event implements Cancellable {
private static final HandlerList handlerList = new HandlerList();
private final Player player;
private final int id;
@Setter
private boolean cancelled;
public MapCancelEvent(Player player, int id) {
this.player = player;
this.id = id;
}
private final Player player;
private final int id;
/**
* Construct a new {@link MapCancelEvent}
*
* @param player The player who tried to create the map
* @param id The ID of the map
* @param isAsync Is this event called async?
*/
public MapCancelEvent(Player player, int id, boolean isAsync) {
super(isAsync);
this.player = player;
this.id = id;
}
public static HandlerList getHandlerList() {
return handlerList;
}
public Player getPlayer() {
return player;
}
public int getId() {
return id;
}
@Override
public HandlerList getHandlers() {
return handlerList;
}
@Override
public boolean isCancelled() {
return cancelled;
}
@Override
public void setCancelled(boolean b) {
this.cancelled = b;
}
}

View file

@ -23,17 +23,29 @@
package tech.sbdevelopment.mapreflectionapi.api.events;
import lombok.Getter;
import lombok.RequiredArgsConstructor;
import lombok.Setter;
import org.bukkit.entity.ItemFrame;
import org.bukkit.entity.Player;
import org.bukkit.event.Cancellable;
import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;
import org.bukkit.util.Vector;
import org.jetbrains.annotations.Nullable;
import tech.sbdevelopment.mapreflectionapi.MapReflectionAPI;
import tech.sbdevelopment.mapreflectionapi.api.MapWrapper;
/**
* This event gets fired when a player interact with a map
*/
@RequiredArgsConstructor
@Getter
public class MapInteractEvent extends Event implements Cancellable {
private static final HandlerList handlerList = new HandlerList();
@Setter
private boolean cancelled;
private final Player player;
private final int entityID;
private final int action;
@ -41,16 +53,17 @@ public class MapInteractEvent extends Event implements Cancellable {
private final int hand;
private ItemFrame frame;
private MapWrapper mapWrapper;
private boolean cancelled;
public MapInteractEvent(Player player, int entityID, int action, Vector vector, int hand) {
this.player = player;
this.entityID = entityID;
this.action = action;
this.vector = vector;
this.hand = hand;
}
/**
* Construct a new {@link MapInteractEvent}
*
* @param player The player who interacted
* @param entityID The ID of the entity the map is in
* @param action The interact action
* @param vector The location of the entity
* @param hand The hand the player clicked with
* @param isAsync Is this event called async?
*/
public MapInteractEvent(Player player, int entityID, int action, Vector vector, int hand, boolean isAsync) {
super(isAsync);
this.player = player;
@ -60,30 +73,17 @@ public class MapInteractEvent extends Event implements Cancellable {
this.hand = hand;
}
public static HandlerList getHandlerList() {
@Override
public HandlerList getHandlers() {
return handlerList;
}
public Player getPlayer() {
return player;
}
public int getEntityID() {
return entityID;
}
public int getAction() {
return action;
}
public Vector getVector() {
return vector;
}
public int getHand() {
return hand;
}
/**
* Get the {@link ItemFrame} the map is in
*
* @return The frame the map is in, or null if it's not a map
*/
@Nullable
public ItemFrame getFrame() {
if (getMapWrapper() == null) return null;
@ -93,6 +93,12 @@ public class MapInteractEvent extends Event implements Cancellable {
return frame;
}
/**
* Get the {@link MapWrapper} of the map
*
* @return The wrapper
*/
@Nullable
public MapWrapper getMapWrapper() {
if (mapWrapper == null) {
mapWrapper = MapReflectionAPI.getMapManager().getWrapperForId(player, entityID);
@ -100,19 +106,4 @@ public class MapInteractEvent extends Event implements Cancellable {
return mapWrapper;
}
@Override
public boolean isCancelled() {
return cancelled;
}
@Override
public void setCancelled(boolean b) {
this.cancelled = b;
}
@Override
public HandlerList getHandlers() {
return handlerList;
}
}

View file

@ -21,9 +21,17 @@
* SOFTWARE.
*/
package tech.sbdevelopment.mapreflectionapi.exceptions;
package tech.sbdevelopment.mapreflectionapi.api.exceptions;
/**
* This exception gets thrown if no map IDs are available
*/
public class MapLimitExceededException extends Exception {
/**
* Construct a new {@link MapLimitExceededException}
*
* @param message The message in this exception
*/
public MapLimitExceededException(String message) {
super(message);
}

View file

@ -21,7 +21,7 @@
* SOFTWARE.
*/
package tech.sbdevelopment.mapreflectionapi.util;
package tech.sbdevelopment.mapreflectionapi.utils;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

View file

@ -20,7 +20,7 @@
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*/
package tech.sbdevelopment.mapreflectionapi.util;
package tech.sbdevelopment.mapreflectionapi.utils;
import org.bukkit.World;
import org.bukkit.entity.Player;