From 1c3099f61a3a81b566232d8da292481a19498680 Mon Sep 17 00:00:00 2001 From: Felix Cravic Date: Fri, 29 May 2020 23:17:14 +0200 Subject: [PATCH] Entity & Player comments --- .../net/minestom/server/entity/Entity.java | 205 ++++++++++++++++-- .../net/minestom/server/entity/Player.java | 189 ++++++++++++---- 2 files changed, 339 insertions(+), 55 deletions(-) diff --git a/src/main/java/net/minestom/server/entity/Entity.java b/src/main/java/net/minestom/server/entity/Entity.java index 5af05889a..ca364ff3d 100644 --- a/src/main/java/net/minestom/server/entity/Entity.java +++ b/src/main/java/net/minestom/server/entity/Entity.java @@ -14,9 +14,7 @@ import net.minestom.server.event.entity.EntitySpawnEvent; import net.minestom.server.event.entity.EntityTickEvent; import net.minestom.server.event.entity.EntityVelocityEvent; import net.minestom.server.event.handler.EventHandler; -import net.minestom.server.instance.Chunk; -import net.minestom.server.instance.Instance; -import net.minestom.server.instance.WorldBorder; +import net.minestom.server.instance.*; import net.minestom.server.instance.block.CustomBlock; import net.minestom.server.network.packet.PacketWriter; import net.minestom.server.network.packet.server.play.*; @@ -301,6 +299,11 @@ public abstract class Entity implements Viewable, EventHandler, DataContainer { this.data = data; } + /** + * Update the entity, called every tick + * + * @param time update time in milliseconds + */ public void tick(long time) { if (instance == null) return; @@ -464,9 +467,9 @@ public abstract class Entity implements Viewable, EventHandler, DataContainer { } /** - * Returns the number of ticks this entity has been active for + * Get the number of ticks this entity has been active for * - * @return + * @return the number of ticks this entity has been active for */ public long getAliveTicks() { return ticks; @@ -507,30 +510,73 @@ public abstract class Entity implements Viewable, EventHandler, DataContainer { return id; } + /** + * Return the entity type id, can convert using {@link EntityType#fromId(int)} + * + * @return the entity type id + */ public int getEntityType() { return entityType; } + /** + * Get the entity UUID + * + * @return the entity UUID + */ public UUID getUuid() { return uuid; } + /** + * Return false just after instantiation, set to true after calling {@link #setInstance(Instance)} + * + * @return true if the entity has been linked to an instance, false otherwise + */ public boolean isActive() { return isActive; } + /** + * Is used to check collision with coordinates or other blocks/entities + * + * @return the entity bounding box + */ public BoundingBox getBoundingBox() { return boundingBox; } + /** + * Change the internal entity bounding box + *

+ * WARNING: this does not change the entity hit-box which is client-side + * + * @param x the bounding box X size + * @param y the bounding box Y size + * @param z the bounding box Z size + */ public void setBoundingBox(float x, float y, float z) { this.boundingBox = new BoundingBox(this, x, y, z); } + /** + * Get the entity current instance + * + * @return the entity instance + */ public Instance getInstance() { return instance; } + /** + * Change the entity instance + * + * @param instance the new instance of the entity + * @throws NullPointerException if {@code instance} is null + * @throws IllegalStateException if {@code instance} has not been registered in + * {@link InstanceManager#createInstanceContainer()} or + * {@link InstanceManager#createSharedInstance(InstanceContainer)} + */ public void setInstance(Instance instance) { Check.notNull(instance, "instance cannot be null!"); Check.stateCondition(!MinecraftServer.getInstanceManager().getInstances().contains(instance), @@ -548,16 +594,22 @@ public abstract class Entity implements Viewable, EventHandler, DataContainer { callEvent(EntitySpawnEvent.class, entitySpawnEvent); } + /** + * Get the entity current velocity + * + * @return the entity current velocity + */ public Vector getVelocity() { return velocity; } - public boolean hasVelocity() { - return velocity.getX() != 0 || - velocity.getY() != 0 || - velocity.getZ() != 0; - } - + /** + * Change the entity velocity and calls {@link EntityVelocityEvent}. + *

+ * The final velocity can be cancelled or modified by the event + * + * @param velocity the new entity velocity + */ public void setVelocity(Vector velocity) { EntityVelocityEvent entityVelocityEvent = new EntityVelocityEvent(this, velocity); callCancellableEvent(EntityVelocityEvent.class, entityVelocityEvent, () -> { @@ -566,19 +618,51 @@ public abstract class Entity implements Viewable, EventHandler, DataContainer { }); } + /** + * @return true if velocity is not set to 0 + */ + public boolean hasVelocity() { + return velocity.getX() != 0 || + velocity.getY() != 0 || + velocity.getZ() != 0; + } + + /** + * Change the gravity of the entity + * + * @param gravityDragPerTick + */ public void setGravity(float gravityDragPerTick) { this.gravityDragPerTick = gravityDragPerTick; } + /** + * Get the distance between two entities + * + * @param entity the entity to get the distance from + * @return the distance between this and {@code entity} + */ public float getDistance(Entity entity) { Check.notNull(entity, "Entity cannot be null"); return getPosition().getDistance(entity.getPosition()); } + /** + * Get the entity vehicle or null + * + * @return the entity vehicle, or null if there is not any + */ public Entity getVehicle() { return vehicle; } + /** + * Add a new passenger to this entity + * + * @param entity the new passenger + * @throws NullPointerException if {@code entity} is null + * @throws IllegalStateException if {@link #getInstance()} returns null + */ public void addPassenger(Entity entity) { Check.notNull(entity, "Passenger cannot be null"); Check.stateCondition(instance == null, "You need to set an instance using Entity#setInstance"); @@ -593,6 +677,13 @@ public abstract class Entity implements Viewable, EventHandler, DataContainer { sendPacketToViewersAndSelf(getPassengersPacket()); } + /** + * Remove a passenger to this entity + * + * @param entity the passenger to remove + * @throws NullPointerException if {@code entity} is null + * @throws IllegalStateException if {@link #getInstance()} returns null + */ public void removePassenger(Entity entity) { Check.notNull(entity, "Passenger cannot be null"); Check.stateCondition(instance == null, "You need to set an instance using Entity#setInstance"); @@ -603,11 +694,18 @@ public abstract class Entity implements Viewable, EventHandler, DataContainer { sendPacketToViewersAndSelf(getPassengersPacket()); } + /** + * Get if the entity has any passenger + * + * @return true if the entity has any passenger, false otherwise + */ public boolean hasPassenger() { return !passengers.isEmpty(); } /** + * Get the entity passengers + * * @return an unmodifiable list containing all the entity passengers */ public Set getPassengers() { @@ -641,6 +739,8 @@ public abstract class Entity implements Viewable, EventHandler, DataContainer { } /** + * Get if the entity is on fire + * * @return true if the entity is in fire, false otherwise */ public boolean isOnFire() { @@ -660,40 +760,79 @@ public abstract class Entity implements Viewable, EventHandler, DataContainer { sendMetadataIndex(0); } + /** + * Get if the entity is invisible or not + * + * @return true if the entity is invisible, false otherwise + */ public boolean isInvisible() { return invisible; } + /** + * Change the internal invisible value and send a {@link EntityMetaDataPacket} + * to make visible or invisible the entity to its viewers + * + * @param invisible true to set the entity invisible, false otherwise + */ public void setInvisible(boolean invisible) { this.invisible = invisible; sendMetadataIndex(0); } - public void setGlowing(boolean glowing) { - this.glowing = glowing; - sendMetadataIndex(0); - } - /** + * Get if the entity is glowing or not + * * @return true if the entity is glowing, false otherwise */ public boolean isGlowing() { return glowing; } + /** + * Set or remove the entity glowing effect + * + * @param glowing true to make the entity glows, false otherwise + */ + public void setGlowing(boolean glowing) { + this.glowing = glowing; + sendMetadataIndex(0); + } + + /** + * Get the entity custom name + * + * @return the custom name of the entity, null if there is not + */ public String getCustomName() { return customName; } + /** + * Change the entity custom name + * + * @param customName the custom name of the entity, null to remove it + */ public void setCustomName(String customName) { this.customName = customName; sendMetadataIndex(2); } + /** + * Get the custom name visible metadata field + * + * @return true if the custom name is visible, false otherwise + */ public boolean isCustomNameVisible() { return customNameVisible; } + /** + * Change the internal custom name visible field and send a {@link EntityMetaDataPacket} + * to update the entity state to its viewers + * + * @param customNameVisible true to make the custom name visible, false otherwise + */ public void setCustomNameVisible(boolean customNameVisible) { this.customNameVisible = customNameVisible; sendMetadataIndex(3); @@ -709,6 +848,8 @@ public abstract class Entity implements Viewable, EventHandler, DataContainer { } /** + * Change the noGravity metadata field and change the gravity behaviour accordingly + * * @param noGravity should the entity ignore gravity */ public void setNoGravity(boolean noGravity) { @@ -717,6 +858,8 @@ public abstract class Entity implements Viewable, EventHandler, DataContainer { } /** + * Get the noGravity metadata field + * * @return true if the entity ignore gravity, false otherwise */ public boolean hasNoGravity() { @@ -766,6 +909,10 @@ public abstract class Entity implements Viewable, EventHandler, DataContainer { } } + /** + * @param position the new position + * @see #refreshPosition(float, float, float) + */ public void refreshPosition(Position position) { refreshPosition(position.getX(), position.getY(), position.getZ()); } @@ -851,21 +998,35 @@ public abstract class Entity implements Viewable, EventHandler, DataContainer { } /** + * Get the entity position + * * @return the current position of the entity */ public Position getPosition() { return position; } + /** + * Get the entity eye height + * + * @return the entity eye height + */ public float getEyeHeight() { return eyeHeight; } + /** + * Change the entity eye height + * + * @param eyeHeight the entity eye eight + */ public void setEyeHeight(float eyeHeight) { this.eyeHeight = eyeHeight; } /** + * Get if this entity is in the same chunk as the specified position + * * @param position the checked position chunk * @return true if the entity is in the same chunk as {@code position} */ @@ -881,6 +1042,12 @@ public abstract class Entity implements Viewable, EventHandler, DataContainer { return chunkX1 == chunkX2 && chunkZ1 == chunkZ2; } + /** + * Get if the entity is in the same chunk as another + * + * @param entity the entity to check + * @return true if both entities are in the same chunk, false otherwise + */ public boolean sameChunk(Entity entity) { return sameChunk(entity.getPosition()); } @@ -913,6 +1080,8 @@ public abstract class Entity implements Viewable, EventHandler, DataContainer { } /** + * Get if the entity removal is scheduled + * * @return true if {@link #scheduleRemove(long, TimeUnit)} has been called, false otherwise */ public boolean isRemoveScheduled() { @@ -1081,7 +1250,7 @@ public abstract class Entity implements Viewable, EventHandler, DataContainer { } /** - * Ask for a synchronization (position) to happen during next entity update + * Ask for a synchronization (position) to happen during next entity tick */ public void askSynchronization() { this.lastSynchronizationTime = 0; @@ -1091,7 +1260,7 @@ public abstract class Entity implements Viewable, EventHandler, DataContainer { return (float) (time - lastUpdate) >= MinecraftServer.TICK_MS * 0.9f; // Margin of error } - public enum Pose { + private enum Pose { STANDING, FALL_FLYING, SLEEPING, diff --git a/src/main/java/net/minestom/server/entity/Player.java b/src/main/java/net/minestom/server/entity/Player.java index 84488b1c7..74d8ed20b 100644 --- a/src/main/java/net/minestom/server/entity/Player.java +++ b/src/main/java/net/minestom/server/entity/Player.java @@ -640,8 +640,13 @@ public class Player extends LivingEntity { sendMessage(Chat.fromLegacyText(message, colorChar)); } - public void sendMessage(Component textObject) { - String json = Chat.toJsonString(textObject); + /** + * Send a message to the player + * + * @param component the text component + */ + public void sendMessage(Component component) { + String json = Chat.toJsonString(component); playerConnection.sendPacket(new ChatMessagePacket(json, ChatMessagePacket.Position.CHAT)); } @@ -676,6 +681,9 @@ public class Player extends LivingEntity { playerConnection.sendPacket(packet); } + /** + * Send a {@link StopSoundPacket} packet + */ public void stopSound() { StopSoundPacket stopSoundPacket = new StopSoundPacket(); stopSoundPacket.flags = 0x00; @@ -779,7 +787,9 @@ public class Player extends LivingEntity { } /** - * @return the additional hearts of the player + * Get the player additional hearts + * + * @return the player additional hearts */ public float getAdditionalHearts() { return additionalHearts; @@ -796,7 +806,9 @@ public class Player extends LivingEntity { } /** - * @return the food of the player + * Get the player food + * + * @return the player food */ public int getFood() { return food; @@ -829,14 +841,18 @@ public class Player extends LivingEntity { } /** - * @return true if the player is currently eating, false otherwise + * Get if the player is eating + * + * @return true if the player is eating, false otherwise */ public boolean isEating() { return isEating; } /** - * @return the default eating time for the player + * Get the player default eating time + * + * @return the player default eating time */ public long getDefaultEatingTime() { return defaultEatingTime; @@ -852,31 +868,21 @@ public class Player extends LivingEntity { } /** - * Used to change the player gamemode + * Get the player display name in the tab-list * - * @param gameMode the new player gamemode - */ - public void setGameMode(GameMode gameMode) { - Check.notNull(gameMode, "GameMode cannot be null"); - this.gameMode = gameMode; - sendChangeGameStatePacket(ChangeGameStatePacket.Reason.CHANGE_GAMEMODE, gameMode.getId()); - - PlayerInfoPacket infoPacket = new PlayerInfoPacket(PlayerInfoPacket.Action.UPDATE_GAMEMODE); - infoPacket.playerInfos.add(new PlayerInfoPacket.UpdateGamemode(getUuid(), gameMode)); - sendPacketToViewersAndSelf(infoPacket); - } - - /** - * @return the displayed name of the player in the tab-list, - * null means that {@link #getUsername()} is display + * @return the player display name, + * null means that {@link #getUsername()} is displayed */ public String getDisplayName() { return displayName; } /** - * @param displayName the new displayed name of the player in the tab-list, - * set to null to show the player username + * Change the player display name in the tab-list + *

+ * Set to null to show the player username + * + * @param displayName the display name */ public void setDisplayName(String displayName) { this.displayName = displayName; @@ -887,15 +893,34 @@ public class Player extends LivingEntity { sendPacketToViewersAndSelf(infoPacket); } + /** + * Get if the player has the respawn screen enabled or disabled + * + * @return true if the player has the respawn screen, false if he didn't + */ public boolean isEnableRespawnScreen() { return enableRespawnScreen; } + /** + * Enable or disable the respawn screen + * + * @param enableRespawnScreen true to enable the respawn screen, false to disable it + */ public void setEnableRespawnScreen(boolean enableRespawnScreen) { this.enableRespawnScreen = enableRespawnScreen; sendChangeGameStatePacket(ChangeGameStatePacket.Reason.ENABLE_RESPAWN_SCREEN, enableRespawnScreen ? 0 : 1); } + /** + * Get the player username + * + * @return the player username + */ + public String getUsername() { + return username; + } + private void sendChangeGameStatePacket(ChangeGameStatePacket.Reason reason, float value) { ChangeGameStatePacket changeGameStatePacket = new ChangeGameStatePacket(); changeGameStatePacket.reason = reason; @@ -1097,15 +1122,20 @@ public class Player extends LivingEntity { teleport(position, null); } - public String getUsername() { - return username; - } - + /** + * Get the player connection + *

+ * Used to send packets and get relatives stuff to the connection + * + * @return the player connection + */ public PlayerConnection getPlayerConnection() { return playerConnection; } /** + * Get if the player is online or not + * * @return true if the player is online, false otherwise */ public boolean isOnline() { @@ -1113,12 +1143,23 @@ public class Player extends LivingEntity { } /** + * Get the player settings + * * @return the player settings */ public PlayerSettings getSettings() { return settings; } + /** + * Get the player dimension + * + * @return the player current dimension + */ + public Dimension getDimension() { + return dimension; + } + public PlayerInventory getInventory() { return inventory; } @@ -1134,19 +1175,29 @@ public class Player extends LivingEntity { } /** - * @return the player current dimension - */ - public Dimension getDimension() { - return dimension; - } - - /** + * Get the player GameMode + * * @return the player current gamemode */ public GameMode getGameMode() { return gameMode; } + /** + * Change the player GameMode + * + * @param gameMode the new player GameMode + */ + public void setGameMode(GameMode gameMode) { + Check.notNull(gameMode, "GameMode cannot be null"); + this.gameMode = gameMode; + sendChangeGameStatePacket(ChangeGameStatePacket.Reason.CHANGE_GAMEMODE, gameMode.getId()); + + PlayerInfoPacket infoPacket = new PlayerInfoPacket(PlayerInfoPacket.Action.UPDATE_GAMEMODE); + infoPacket.playerInfos.add(new PlayerInfoPacket.UpdateGamemode(getUuid(), gameMode)); + sendPacketToViewersAndSelf(infoPacket); + } + /** * Returns true iff this player is in creative. Used for code readability * @@ -1174,13 +1225,23 @@ public class Player extends LivingEntity { playerConnection.sendPacket(respawnPacket); } - public void kick(TextComponent message) { + /** + * Kick the player with a reason + * + * @param textComponent the kick reason + */ + public void kick(TextComponent textComponent) { DisconnectPacket disconnectPacket = new DisconnectPacket(); - disconnectPacket.message = Chat.toJsonString(message); + disconnectPacket.message = Chat.toJsonString(textComponent); playerConnection.sendPacket(disconnectPacket); playerConnection.disconnect(); } + /** + * Kick the player with a reason + * + * @param message the kick reason + */ public void kick(String message) { kick(Chat.fromLegacyText(message)); } @@ -1205,6 +1266,8 @@ public class Player extends LivingEntity { } /** + * Get the player held slot (0-8) + * * @return the current held slot for the player */ public short getHeldSlot() { @@ -1243,6 +1306,8 @@ public class Player extends LivingEntity { } /** + * Get the player open inventory + * * @return the currently open inventory, null if there is not (player inventory is not detected) */ public Inventory getOpenInventory() { @@ -1332,6 +1397,8 @@ public class Player extends LivingEntity { } /** + * Get the player viewable chunks + * * @return an unmodifiable {@link Set} containing all the chunks that the player sees */ public Set getViewableChunks() { @@ -1369,6 +1436,8 @@ public class Player extends LivingEntity { } /** + * Get the player permission level + * * @return the player permission level */ public int getPermissionLevel() { @@ -1391,6 +1460,8 @@ public class Player extends LivingEntity { } /** + * Set or remove the reduced debug screen + * * @param reduced should the player has the reduced debug screen */ public void setReducedDebugScreenInformation(boolean reduced) { @@ -1402,6 +1473,8 @@ public class Player extends LivingEntity { } /** + * Get if the player has the reduced debug screen + * * @return true if the player has the reduced debug screen, false otherwise */ public boolean hasReducedDebugScreenInformation() { @@ -1429,6 +1502,8 @@ public class Player extends LivingEntity { } /** + * Get if the player is currently flying + * * @return true if the player if flying, false otherwise */ public boolean isFlying() { @@ -1436,6 +1511,8 @@ public class Player extends LivingEntity { } /** + * Set the player flying + * * @param flying should the player fly */ public void setFlying(boolean flying) { @@ -1456,6 +1533,8 @@ public class Player extends LivingEntity { } /** + * Get if the player is allowed to fly + * * @return true if the player if allowed to fly, false otherwise */ public boolean isAllowFlying() { @@ -1463,6 +1542,8 @@ public class Player extends LivingEntity { } /** + * Allow or forbid the player to fly + * * @param allowFlying should the player be allowed to fly */ public void setAllowFlying(boolean allowFlying) { @@ -1488,6 +1569,8 @@ public class Player extends LivingEntity { } /** + * Get the player flying speed + * * @return the flying speed of the player */ public float getFlyingSpeed() { @@ -1523,6 +1606,11 @@ public class Player extends LivingEntity { return statisticValueMap; } + /** + * Get the player vehicle information + * + * @return the player vehicle information + */ public PlayerVehicleInformation getVehicleInformation() { return vehicleInformation; } @@ -1719,6 +1807,8 @@ public class Player extends LivingEntity { } /** + * Get the last sent keep alive id + * * @return the last keep alive id sent to the player */ public long getLastKeepAlive() { @@ -1823,18 +1913,38 @@ public class Player extends LivingEntity { private byte displayedSkinParts; private MainHand mainHand; + /** + * The player game language + * + * @return the player locale + */ public String getLocale() { return locale; } + /** + * Get the player view distance + * + * @return the player view distance + */ public byte getViewDistance() { return viewDistance; } + /** + * Get the player chat mode + * + * @return the player chat mode + */ public ChatMode getChatMode() { return chatMode; } + /** + * Get if the player has chat colors enabled + * + * @return true if chat colors are enabled, false otherwise + */ public boolean hasChatColors() { return chatColors; } @@ -1843,6 +1953,11 @@ public class Player extends LivingEntity { return displayedSkinParts; } + /** + * Get the player main hand + * + * @return the player main hand + */ public MainHand getMainHand() { return mainHand; }