From 81592d8b562fdb5e3e513f58c58f8391dcac1d0b Mon Sep 17 00:00:00 2001 From: R0bbyYT Date: Sat, 19 Dec 2020 16:32:42 +0100 Subject: [PATCH] More documentation for the FakePlayer, Small improvement for the FakePlayerController --- .../server/entity/fakeplayer/FakePlayer.java | 19 +++- .../fakeplayer/FakePlayerController.java | 104 ++++++++++++++++-- .../entity/fakeplayer/FakePlayerOption.java | 3 + 3 files changed, 117 insertions(+), 9 deletions(-) diff --git a/src/main/java/net/minestom/server/entity/fakeplayer/FakePlayer.java b/src/main/java/net/minestom/server/entity/fakeplayer/FakePlayer.java index 952222b9c..a003e5da5 100644 --- a/src/main/java/net/minestom/server/entity/fakeplayer/FakePlayer.java +++ b/src/main/java/net/minestom/server/entity/fakeplayer/FakePlayer.java @@ -25,6 +25,13 @@ public class FakePlayer extends Player { private final FakePlayerOption option; private final FakePlayerController fakePlayerController; + /** + * Initializes a new {@link FakePlayer} with the given {@code uuid}, {@code username} and {@code option}'s. + * + * @param uuid The unique identifier for the fake player. + * @param username The username for the fake player. + * @param option Any option for the fake player. + */ private FakePlayer(@NotNull UUID uuid, @NotNull String username, @NotNull FakePlayerOption option) { super(uuid, username, new FakePlayerConnection()); @@ -38,7 +45,7 @@ public class FakePlayer extends Player { } /** - * Inits a new {@link FakePlayer}. + * Initializes a new {@link FakePlayer}. * * @param uuid the FakePlayer uuid * @param username the FakePlayer username @@ -59,7 +66,7 @@ public class FakePlayer extends Player { } /** - * Inits a new {@link FakePlayer} without adding it in cache. + * Initializes a new {@link FakePlayer} without adding it in cache. *

* If you want the fake player to be obtainable with the {@link net.minestom.server.network.ConnectionManager} * you need to specify it in a {@link FakePlayerOption} and use {@link #initPlayer(UUID, String, FakePlayerOption, Consumer)}. @@ -82,11 +89,19 @@ public class FakePlayer extends Player { return option; } + /** + * Retrieves the controller for the fake player. + * + * @return The fake player's controller. + */ @NotNull public FakePlayerController getController() { return fakePlayerController; } + /** + * {@inheritDoc} + */ @Override protected void showPlayer(@NotNull PlayerConnection connection) { super.showPlayer(connection); diff --git a/src/main/java/net/minestom/server/entity/fakeplayer/FakePlayerController.java b/src/main/java/net/minestom/server/entity/fakeplayer/FakePlayerController.java index cec2627ef..56d7c75e2 100644 --- a/src/main/java/net/minestom/server/entity/fakeplayer/FakePlayerController.java +++ b/src/main/java/net/minestom/server/entity/fakeplayer/FakePlayerController.java @@ -12,8 +12,11 @@ import net.minestom.server.network.packet.client.play.*; import net.minestom.server.network.packet.server.ServerPacket; import net.minestom.server.network.packet.server.play.KeepAlivePacket; import net.minestom.server.network.packet.server.play.PlayerPositionAndLookPacket; +import net.minestom.server.network.player.PlayerConnection; import net.minestom.server.utils.BlockPosition; +import net.minestom.server.utils.MathUtils; import net.minestom.server.utils.inventory.PlayerInventoryUtils; +import net.minestom.server.utils.validate.Check; import org.jetbrains.annotations.NotNull; /** @@ -25,10 +28,24 @@ public class FakePlayerController { private final FakePlayer fakePlayer; + /** + * Initializes a new {@link FakePlayerController} with the given {@link FakePlayer}. + * + * @param fakePlayer The fake player that should used the controller. + */ public FakePlayerController(@NotNull FakePlayer fakePlayer) { this.fakePlayer = fakePlayer; } + /** + * Simulates a click in a window. + * + * @param playerInventory {@code true} if the window a {@link PlayerInventory}, otherwise {@code false}. + * @param slot The slot where the fake player should click on. + * @param button The mouse button that the fake player should used. + * @param action The action that the fake player should perform. + * @param mode The inventory operation mode that the fake player should used. + */ public void clickWindow(boolean playerInventory, short slot, byte button, short action, int mode) { Inventory inventory = playerInventory ? null : fakePlayer.getOpenInventory(); InventoryModifier inventoryModifier = inventory == null ? fakePlayer.getInventory() : inventory; @@ -48,6 +65,9 @@ public class FakePlayerController { addToQueue(clickWindowPacket); } + /** + * Closes the current opened inventory if there is any. + */ public void closeWindow() { Inventory openInventory = fakePlayer.getOpenInventory(); @@ -56,6 +76,12 @@ public class FakePlayerController { addToQueue(closeWindow); } + /** + * Sends a plugin message to the player. + * + * @param channel The channel of the message. + * @param message The message data. + */ public void sendPluginMessage(String channel, byte[] message) { ClientPluginMessagePacket pluginMessagePacket = new ClientPluginMessagePacket(); pluginMessagePacket.channel = channel; @@ -63,10 +89,21 @@ public class FakePlayerController { addToQueue(pluginMessagePacket); } + /** + * Sends a plugin message to the player. + * + * @param channel The channel of the message. + * @param message The message data. + */ public void sendPluginMessage(String channel, String message) { sendPluginMessage(channel, message.getBytes()); } + /** + * Attacks the given {@code entity}. + * + * @param entity The entity that is to be attacked. + */ public void attackEntity(Entity entity) { ClientInteractEntityPacket interactEntityPacket = new ClientInteractEntityPacket(); interactEntityPacket.targetId = entity.getEntityId(); @@ -74,6 +111,11 @@ public class FakePlayerController { addToQueue(interactEntityPacket); } + /** + * Respawns the player. + * + * @see Player#respawn() + */ public void respawn() { // Sending the respawn packet for some reason // Is related to FakePlayer#showPlayer and the tablist option (probably because of the scheduler) @@ -83,24 +125,48 @@ public class FakePlayerController { fakePlayer.respawn(); } + /** + * Changes the current held slot for the player. + * + * @param slot The slot that the player has to held. + * @throws IllegalArgumentException If {@code slot} is not between {@code 0} and {@code 8}. + */ public void setHeldItem(short slot) { + Check.argCondition(!MathUtils.isBetween(slot, 0, 8), "Slot has to be between 0 and 8!"); + ClientHeldItemChangePacket heldItemChangePacket = new ClientHeldItemChangePacket(); heldItemChangePacket.slot = slot; addToQueue(heldItemChangePacket); } + /** + * Sends an animation packet that animates the specified arm. + * + * @param hand The hand of the arm to be animated. + */ public void sendArmAnimation(Player.Hand hand) { ClientAnimationPacket animationPacket = new ClientAnimationPacket(); animationPacket.hand = hand; addToQueue(animationPacket); } + /** + * Uses the item in the given {@code hand}. + * + * @param hand The hand in which an ite mshould be. + */ public void useItem(Player.Hand hand) { ClientUseItemPacket useItemPacket = new ClientUseItemPacket(); useItemPacket.hand = hand; addToQueue(useItemPacket); } + /** + * Rotates the fake player. + * + * @param yaw The new yaw for the fake player. + * @param pitch The new pitch for the fake player. + */ public void rotate(float yaw, float pitch) { ClientPlayerRotationPacket playerRotationPacket = new ClientPlayerRotationPacket(); playerRotationPacket.yaw = yaw; @@ -109,34 +175,52 @@ public class FakePlayerController { addToQueue(playerRotationPacket); } - public void startDigging(BlockPosition blockPosition) { + /** + * Starts the digging process of the fake player. + * + * @param blockPosition The position of the block to be excavated. + * @param blockFace From where the block is struck. + */ + public void startDigging(BlockPosition blockPosition, BlockFace blockFace) { ClientPlayerDiggingPacket playerDiggingPacket = new ClientPlayerDiggingPacket(); playerDiggingPacket.status = ClientPlayerDiggingPacket.Status.STARTED_DIGGING; playerDiggingPacket.blockPosition = blockPosition; - playerDiggingPacket.blockFace = BlockFace.BOTTOM; // TODO not hardcode + playerDiggingPacket.blockFace = blockFace; addToQueue(playerDiggingPacket); } - public void stopDigging(BlockPosition blockPosition) { + /** + * Stops the digging process of the fake player. + * + * @param blockPosition The position of the block to be excavated. + * @param blockFace From where the block is struck. + */ + public void stopDigging(BlockPosition blockPosition, BlockFace blockFace) { ClientPlayerDiggingPacket playerDiggingPacket = new ClientPlayerDiggingPacket(); playerDiggingPacket.status = ClientPlayerDiggingPacket.Status.CANCELLED_DIGGING; playerDiggingPacket.blockPosition = blockPosition; - playerDiggingPacket.blockFace = BlockFace.BOTTOM; // TODO not hardcode + playerDiggingPacket.blockFace = blockFace; addToQueue(playerDiggingPacket); } - public void finishDigging(BlockPosition blockPosition) { + /** + * Finishes the digging process of the fake player. + * + * @param blockPosition The position of the block to be excavated. + * @param blockFace From where the block is struck. + */ + public void finishDigging(BlockPosition blockPosition, BlockFace blockFace) { ClientPlayerDiggingPacket playerDiggingPacket = new ClientPlayerDiggingPacket(); playerDiggingPacket.status = ClientPlayerDiggingPacket.Status.FINISHED_DIGGING; playerDiggingPacket.blockPosition = blockPosition; - playerDiggingPacket.blockFace = BlockFace.BOTTOM; // TODO not hardcode + playerDiggingPacket.blockFace = blockFace; addToQueue(playerDiggingPacket); } /** * Makes the player receives a packet * WARNING: pretty much unsafe, used internally to redirect packets here, - * you should instead use {@link net.minestom.server.network.player.PlayerConnection#sendPacket(ServerPacket)} + * you should instead use {@link PlayerConnection#sendPacket(ServerPacket)} * * @param serverPacket the packet to consume */ @@ -152,6 +236,12 @@ public class FakePlayerController { } } + /** + * All packets in the queue are executed in the {@link Player#update(long)} method. It is used internally to add all + * received packet from the client. Could be used to "simulate" a received packet, but to use at your own risk! + * + * @param clientPlayPacket The packet to add in the queue. + */ private void addToQueue(ClientPlayPacket clientPlayPacket) { this.fakePlayer.addPacketToQueue(clientPlayPacket); } diff --git a/src/main/java/net/minestom/server/entity/fakeplayer/FakePlayerOption.java b/src/main/java/net/minestom/server/entity/fakeplayer/FakePlayerOption.java index 67a8c41ad..6bcc31613 100644 --- a/src/main/java/net/minestom/server/entity/fakeplayer/FakePlayerOption.java +++ b/src/main/java/net/minestom/server/entity/fakeplayer/FakePlayerOption.java @@ -2,6 +2,9 @@ package net.minestom.server.entity.fakeplayer; import net.minestom.server.network.ConnectionManager; +/** + * Represents any options for a {@link FakePlayer}. + */ public class FakePlayerOption { private boolean registered = false;