From b193c5f12a9edcfdad4418c8aab957419c18fbec Mon Sep 17 00:00:00 2001 From: Felix Cravic Date: Sun, 24 May 2020 19:59:50 +0200 Subject: [PATCH] Lot of comments --- .../net/minestom/server/entity/Entity.java | 53 ++++++++++++++++--- .../server/entity/EntityCreature.java | 22 +++++--- .../minestom/server/entity/ItemEntity.java | 34 +++++++++++- .../minestom/server/entity/LivingEntity.java | 24 +++++++++ .../minestom/server/entity/ObjectEntity.java | 5 ++ .../net/minestom/server/entity/Player.java | 38 +++++++++++++ .../server/listener/PlayerHeldListener.java | 4 +- .../net/minestom/server/utils/ChunkUtils.java | 24 +++++++++ 8 files changed, 190 insertions(+), 14 deletions(-) diff --git a/src/main/java/net/minestom/server/entity/Entity.java b/src/main/java/net/minestom/server/entity/Entity.java index 2dad5248d..9656d7b06 100644 --- a/src/main/java/net/minestom/server/entity/Entity.java +++ b/src/main/java/net/minestom/server/entity/Entity.java @@ -490,6 +490,7 @@ public abstract class Entity implements Viewable, EventHandler, DataContainer { } 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"); if (entity.getVehicle() != null) { @@ -503,11 +504,11 @@ public abstract class Entity implements Viewable, EventHandler, DataContainer { } 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"); - if (!passengers.contains(entity)) + if (!passengers.remove(entity)) return; - this.passengers.remove(entity); entity.vehicle = null; sendPacketToViewersAndSelf(getPassengersPacket()); } @@ -516,6 +517,9 @@ public abstract class Entity implements Viewable, EventHandler, DataContainer { return !passengers.isEmpty(); } + /** + * @return an unmodifiable list containing all the entity passengers + */ public Set getPassengers() { return Collections.unmodifiableSet(passengers); } @@ -534,6 +538,11 @@ public abstract class Entity implements Viewable, EventHandler, DataContainer { return passengersPacket; } + /** + * Entity statuses can be find here + * + * @param status the status to trigger + */ public void triggerStatus(byte status) { EntityStatusPacket statusPacket = new EntityStatusPacket(); statusPacket.entityId = getEntityId(); @@ -541,33 +550,65 @@ public abstract class Entity implements Viewable, EventHandler, DataContainer { sendPacketToViewersAndSelf(statusPacket); } + /** + * @return true if the entity is in fire, false otherwise + */ + public boolean isOnFire() { + return onFire; + } + + /** + * Set the entity in fire visually + *

+ * WARNING: if you want to apply damage or specify a duration, + * see {@link LivingEntity#setFireForDuration(int, TimeUnit)} + * + * @param fire should the entity be set in fire + */ public void setOnFire(boolean fire) { this.onFire = fire; sendMetadataIndex(0); } - public boolean isOnFire() { - return onFire; - } - public void setGlowing(boolean glowing) { this.glowing = glowing; sendMetadataIndex(0); } + /** + * @return true if the entity is glowing, false otherwise + */ public boolean isGlowing() { return glowing; } + /** + * @param noGravity should the entity ignore gravity + */ public void setNoGravity(boolean noGravity) { this.noGravity = noGravity; sendMetadataIndex(5); } + /** + * @return true if the entity ignore gravity, false otherwise + */ public boolean hasNoGravity() { return noGravity; } + /** + * Used to refresh the entity and its passengers position + * - put the entity in the right instance chunk + * - update the viewable chunks (load and unload) + * - add/remove players from the viewers list if {@link #isAutoViewable()} is enabled + *

+ * WARNING: unsafe, should only be used internally in Minestom + * + * @param x new position X + * @param y new position Y + * @param z new position Z + */ public void refreshPosition(float x, float y, float z) { this.lastX = position.getX(); this.lastY = position.getY(); diff --git a/src/main/java/net/minestom/server/entity/EntityCreature.java b/src/main/java/net/minestom/server/entity/EntityCreature.java index 3a2256607..0d6fdc910 100644 --- a/src/main/java/net/minestom/server/entity/EntityCreature.java +++ b/src/main/java/net/minestom/server/entity/EntityCreature.java @@ -66,18 +66,21 @@ public abstract class EntityCreature extends LivingEntity { } + /** + * @param x X movement offset + * @param y Y movement offset + * @param z Z movement offset + * @param updateView should the entity move its head toward the position? + */ public void move(float x, float y, float z, boolean updateView) { Position position = getPosition(); - float newX = position.getX() + x; - float newY = position.getY() + y; - float newZ = position.getZ() + z; Position newPosition = new Position(); // Calculate collisions boxes onGround = CollisionUtils.handlePhysics(this, new Vector(x, y, z), newPosition, new Vector()); // Refresh target position - newX = newPosition.getX(); - newY = newPosition.getY(); - newZ = newPosition.getZ(); + float newX = newPosition.getX(); + float newY = newPosition.getY(); + float newZ = newPosition.getZ(); // Creatures cannot move in unload chunk if (ChunkUtils.isChunkUnloaded(getInstance(), newX, newZ)) @@ -257,6 +260,13 @@ public abstract class EntityCreature extends LivingEntity { setPathTo(position, 1000, null); } + /** + * Used to move the entity toward {@code direction} in the axis X and Z + * Gravity is still applied but the entity will not attempt to jump + * + * @param direction the targeted position + * @param speed define how far the entity will move + */ public void moveTowards(Position direction, float speed) { float radians = (float) Math.atan2(direction.getZ() - position.getZ(), direction.getX() - position.getX()); float speedX = (float) (Math.cos(radians) * speed); diff --git a/src/main/java/net/minestom/server/entity/ItemEntity.java b/src/main/java/net/minestom/server/entity/ItemEntity.java index a502a5c4d..89e8e001e 100644 --- a/src/main/java/net/minestom/server/entity/ItemEntity.java +++ b/src/main/java/net/minestom/server/entity/ItemEntity.java @@ -17,6 +17,7 @@ public class ItemEntity extends ObjectEntity { private boolean pickable = true; private boolean mergeable = true; + private float mergeRange = 1; private long spawnTime; private long pickupDelay; @@ -45,7 +46,7 @@ public class ItemEntity extends ObjectEntity { continue; // Too far, do not merge - if (getDistance(itemEntity) > 1) + if (getDistance(itemEntity) > mergeRange) continue; synchronized (this) { @@ -125,22 +126,53 @@ public class ItemEntity extends ObjectEntity { this.pickable = pickable; } + /** + * @return true if the entity is mergeable, false otherwise + */ public boolean isMergeable() { return mergeable; } + /** + * When set to true, close {@link ItemEntity} will try to merge together as a single entity + * when their {@link #getItemStack()} is similar and allowed to stack together + * + * @param mergeable should the entity merge with other {@link ItemEntity} + */ public void setMergeable(boolean mergeable) { this.mergeable = mergeable; } + public float getMergeRange() { + return mergeRange; + } + + public void setMergeRange(float mergeRange) { + this.mergeRange = mergeRange; + } + + /** + * @return the pickup delay in milliseconds, defined by {@link #setPickupDelay(long, TimeUnit)} + */ public long getPickupDelay() { return pickupDelay; } + /** + * Set the pickup delay of the ItemEntity + * + * @param delay + * @param timeUnit + */ public void setPickupDelay(long delay, TimeUnit timeUnit) { this.pickupDelay = timeUnit.toMilliseconds(delay); } + /** + * Used to know if the ItemEntity can be pickup + * + * @return the time in milliseconds since this entity has spawn + */ public long getSpawnTime() { return spawnTime; } diff --git a/src/main/java/net/minestom/server/entity/LivingEntity.java b/src/main/java/net/minestom/server/entity/LivingEntity.java index dbe90354c..9bdb5cfab 100644 --- a/src/main/java/net/minestom/server/entity/LivingEntity.java +++ b/src/main/java/net/minestom/server/entity/LivingEntity.java @@ -255,14 +255,30 @@ public abstract class LivingEntity extends Entity implements EquipmentHandler { return getAttributeValue(Attribute.MAX_HEALTH); } + /** + * Set the heal of the entity as its max health + * retrieved from {@link #getAttributeValue(Attribute)} with the attribute {@link Attribute#MAX_HEALTH} + */ public void heal() { setHealth(getAttributeValue(Attribute.MAX_HEALTH)); } + /** + * Change the specified attribute value to {@code value} + * + * @param attribute The attribute to change + * @param value the new value of the attribute + */ public void setAttribute(Attribute attribute, float value) { this.attributeValues[attribute.ordinal()] = value; } + /** + * Retrieve the attribute value set by {@link #setAttribute(Attribute, float)} + * + * @param attribute the attribute value to get + * @return the attribute value + */ public float getAttributeValue(Attribute attribute) { return this.attributeValues[attribute.ordinal()]; } @@ -299,10 +315,18 @@ public abstract class LivingEntity extends Entity implements EquipmentHandler { return isDead; } + /** + * @return true if the entity is able to pickup items + */ public boolean canPickupItem() { return canPickupItem; } + /** + * When set to false, the entity will not be able to pick {@link ItemEntity} on the ground + * + * @param canPickupItem can the entity pickup item + */ public void setCanPickupItem(boolean canPickupItem) { this.canPickupItem = canPickupItem; } diff --git a/src/main/java/net/minestom/server/entity/ObjectEntity.java b/src/main/java/net/minestom/server/entity/ObjectEntity.java index 142353b17..d984b3bc3 100644 --- a/src/main/java/net/minestom/server/entity/ObjectEntity.java +++ b/src/main/java/net/minestom/server/entity/ObjectEntity.java @@ -11,6 +11,11 @@ public abstract class ObjectEntity extends Entity { setGravity(0.02f); } + /** + * Objects data can be found here + * + * @return an object data + */ public abstract int getObjectData(); @Override diff --git a/src/main/java/net/minestom/server/entity/Player.java b/src/main/java/net/minestom/server/entity/Player.java index 98710f235..e95c22bc1 100644 --- a/src/main/java/net/minestom/server/entity/Player.java +++ b/src/main/java/net/minestom/server/entity/Player.java @@ -797,10 +797,16 @@ public class Player extends LivingEntity { return playerConnection; } + /** + * @return true if the player is online, false otherwise + */ public boolean isOnline() { return playerConnection.isOnline(); } + /** + * @return the player settings + */ public PlayerSettings getSettings() { return settings; } @@ -809,14 +815,26 @@ public class Player extends LivingEntity { return inventory; } + /** + * Used to get the player latency, + * computed by seeing how long it takes the client to answer the {@link KeepAlivePacket} packet + * + * @return the player latency + */ public int getLatency() { return latency; } + /** + * @return the player current dimension + */ public Dimension getDimension() { return dimension; } + /** + * @return the player current gamemode + */ public GameMode getGameMode() { return gameMode; } @@ -1091,19 +1109,31 @@ public class Player extends LivingEntity { refreshAbilities(); } + /** + * @return true if the player if flying, false otherwise + */ public boolean isFlying() { return flying; } + /** + * @param flying should the player fly + */ public void setFlying(boolean flying) { this.flying = flying; refreshAbilities(); } + /** + * @return true if the player if allowed to fly, false otherwise + */ public boolean isAllowFlying() { return allowFlying; } + /** + * @param allowFlying should the player be allowed to fly + */ public void setAllowFlying(boolean allowFlying) { this.allowFlying = allowFlying; refreshAbilities(); @@ -1113,6 +1143,14 @@ public class Player extends LivingEntity { return instantBreak; } + /** + * Change the player ability "Creative Mode" + * see + *

+ * WARNING: this has nothing to do with {@link CustomBlock#getBreakDelay(Player, BlockPosition)} + * + * @param instantBreak + */ public void setInstantBreak(boolean instantBreak) { this.instantBreak = instantBreak; refreshAbilities(); diff --git a/src/main/java/net/minestom/server/listener/PlayerHeldListener.java b/src/main/java/net/minestom/server/listener/PlayerHeldListener.java index 2715e437f..14948f841 100644 --- a/src/main/java/net/minestom/server/listener/PlayerHeldListener.java +++ b/src/main/java/net/minestom/server/listener/PlayerHeldListener.java @@ -8,8 +8,10 @@ public class PlayerHeldListener { public static void heldListener(ClientHeldItemChangePacket packet, Player player) { short slot = packet.slot; - if (!MathUtils.isBetween(slot, 0, 8)) + if (!MathUtils.isBetween(slot, 0, 8)) { + // Incorrect packet, ignore return; + } player.refreshHeldSlot(slot); } diff --git a/src/main/java/net/minestom/server/utils/ChunkUtils.java b/src/main/java/net/minestom/server/utils/ChunkUtils.java index 5c7fa0f5f..37c152349 100644 --- a/src/main/java/net/minestom/server/utils/ChunkUtils.java +++ b/src/main/java/net/minestom/server/utils/ChunkUtils.java @@ -5,6 +5,12 @@ import net.minestom.server.instance.Instance; public class ChunkUtils { + /** + * @param instance the instance to check + * @param x instance X coordinate + * @param z instance Z coordinate + * @return true if the chunk is unloaded, false otherwise + */ public static boolean isChunkUnloaded(Instance instance, float x, float z) { int chunkX = getChunkCoordinate((int) x); int chunkZ = getChunkCoordinate((int) z); @@ -13,15 +19,28 @@ public class ChunkUtils { return chunk == null || !chunk.isLoaded(); } + /** + * @param xz the instance coordinate to convert + * @return the chunk X or Z based on the argument + */ public static int getChunkCoordinate(int xz) { // Assume Chunk.CHUNK_SIZE_X == Chunk.CHUNK_SIZE_Z return Math.floorDiv(xz, Chunk.CHUNK_SIZE_X); } + /** + * @param chunkX the chunk X + * @param chunkZ the chunk Z + * @return a number storing the chunk X and Z + */ public static long getChunkIndex(int chunkX, int chunkZ) { return (((long) chunkX) << 32) | (chunkZ & 0xffffffffL); } + /** + * @param index the chunk index computed by {@link #getChunkIndex(int, int)} + * @return an array containing both the chunk X and Z (index 0 = X; index 1 = Z) + */ public static int[] getChunkCoord(long index) { int chunkX = (int) (index >> 32); int chunkZ = (int) index; @@ -32,6 +51,11 @@ public class ChunkUtils { return y / Chunk.CHUNK_SECTION_SIZE; } + /** + * @param position the initial position + * @param range how far should it retrieves chunk + * @return an array containing chunks index which can be converted using {@link #getChunkCoord(long)} + */ public static long[] getChunksInRange(final Position position, int range) { long[] visibleChunks = new long[MathUtils.square(range + 1)]; final int startLoop = -(range / 2);