From 7c659ca7f8caa470a4bf78c75536aadce2b9e41c Mon Sep 17 00:00:00 2001 From: daoge_cmd <3523206925@qq.com> Date: Sun, 15 Sep 2024 15:27:41 +0800 Subject: [PATCH] docs: add javadocs for EntityPhysicsService, EntityService, HasAABB, HasLongId --- .../world/service/EntityPhysicsService.java | 56 ++++++++++++++++++- .../api/world/service/EntityService.java | 22 ++++++-- .../allaymc/api/world/service/HasAABB.java | 7 ++- .../allaymc/api/world/service/HasLongId.java | 7 ++- .../service/AllayEntityPhysicsService.java | 5 -- 5 files changed, 84 insertions(+), 13 deletions(-) diff --git a/Allay-API/src/main/java/org/allaymc/api/world/service/EntityPhysicsService.java b/Allay-API/src/main/java/org/allaymc/api/world/service/EntityPhysicsService.java index e727be239..dc110653d 100644 --- a/Allay-API/src/main/java/org/allaymc/api/world/service/EntityPhysicsService.java +++ b/Allay-API/src/main/java/org/allaymc/api/world/service/EntityPhysicsService.java @@ -7,40 +7,92 @@ import java.util.List; /** - * Allay Project 2023/8/3 + * EntityPhysicsService is responsible for handling entity physics. * * @author daoge_cmd */ public interface EntityPhysicsService { - boolean containEntity(Entity entity); + /** + * Compute the entities that are colliding with the specified entity. + * + * @param entity The entity to compute the colliding entities. + * @return The entities that are colliding with the specified entity. + */ default List computeCollidingEntities(Entity entity) { return computeCollidingEntities(entity.getOffsetAABB(), other -> other.getRuntimeId() != entity.getRuntimeId()); } + /** + * Compute the entities that are colliding with the specified aabb. + * + * @param aabb The aabb to compute the colliding entities. + * @return The entities that are colliding with the specified aabb. + */ default List computeCollidingEntities(AABBfc aabb) { return computeCollidingEntities(aabb, entity -> true); } + /** + * Compute the entities that are colliding with the specified entity. + * + * @param entity The entity to compute the colliding entities. + * @param ignoreEntityHasCollision Whether to ignore the entity's "hasCollision" property. + * @return The entities that are colliding with the specified entity. + */ default List computeCollidingEntities(Entity entity, boolean ignoreEntityHasCollision) { return computeCollidingEntities(entity.getOffsetAABB(), other -> other.getRuntimeId() != entity.getRuntimeId() && (ignoreEntityHasCollision || entity.hasEntityCollision())); } + /** + * Compute the entities that are colliding with the specified aabb. + * + * @param aabb The entity to compute the colliding entities. + * @param ignoreEntityHasCollision Whether to ignore the entity's "hasCollision" property. + * @return The entities that are colliding with the specified aabb. + */ default List computeCollidingEntities(AABBfc aabb, boolean ignoreEntityHasCollision) { return computeCollidingEntities(aabb, entity -> ignoreEntityHasCollision || entity.hasEntityCollision()); } + /** + * Compute the entities that are colliding with the specified aabb. + * + * @param aabb The entity to compute the colliding entities. + * @param predicate The predicate to filter the entities. + * @return The entities that are colliding with the specified aabb and pass the predicate. + */ List computeCollidingEntities(AABBfc aabb, AABBOverlapFilter predicate); default List computeCollidingEntities(VoxelShape voxelShape) { return computeCollidingEntities(voxelShape, false); } + /** + * Compute the entities that are colliding with the specified voxel shape. + * + * @param voxelShape The voxel shape to compute the colliding entities. + * @param ignoreEntityHasCollision Whether to ignore the entity's has collision. + * @return The entities that are colliding with the specified voxel shape. + */ List computeCollidingEntities(VoxelShape voxelShape, boolean ignoreEntityHasCollision); + /** + * Get the cached entity colliding result of the specified entity. + * + * @param entity The entity to get the cached entity colliding result. + * @return The cached entity colliding result of the specified entity. + */ default List getCachedEntityCollidingResult(Entity entity) { return getCachedEntityCollidingResult(entity, false); } + /** + * Get the cached entity colliding result of the specified entity. + * + * @param entity The entity to get the cached entity colliding result. + * @param ignoreEntityHasCollision Whether to ignore the entity's "hasCollision" property. + * @return The cached entity colliding result of the specified entity. + */ List getCachedEntityCollidingResult(Entity entity, boolean ignoreEntityHasCollision); } diff --git a/Allay-API/src/main/java/org/allaymc/api/world/service/EntityService.java b/Allay-API/src/main/java/org/allaymc/api/world/service/EntityService.java index dcfbf815b..f86659711 100644 --- a/Allay-API/src/main/java/org/allaymc/api/world/service/EntityService.java +++ b/Allay-API/src/main/java/org/allaymc/api/world/service/EntityService.java @@ -3,7 +3,7 @@ import org.allaymc.api.entity.Entity; /** - * Allay Project 11/12/2023 + * EntityService is responsible for adding, removing and ticking entities. * * @author Cool_Loong */ @@ -13,10 +13,14 @@ default void addEntity(Entity entity) { } /** - * NOTICE: Before call this method, you should make sure the chunk which this entity will be spawned in has been loaded! + * Add an entity to the world. + *

+ * The entity won't be added to the world immediately. + * It will be added to the world in the next tick, and + * the callback will be called. * - * @param entity The entity pending to be spawned - * @param callback Called after the entity been pawned + * @param entity The entity pending to be spawned + * @param callback The callback to be called after the entity is added to the world */ void addEntity(Entity entity, Runnable callback); @@ -24,5 +28,15 @@ default void removeEntity(Entity entity) { removeEntity(entity, () -> {}); } + /** + * Remove an entity from the world. + *

+ * The entity won't be removed from the world immediately. + * It will be removed from the world in the next tick, and + * the callback will be called. + * + * @param entity The entity pending to be despawned + * @param callback The callback to be called after the entity is removed from the world + */ void removeEntity(Entity entity, Runnable callback); } diff --git a/Allay-API/src/main/java/org/allaymc/api/world/service/HasAABB.java b/Allay-API/src/main/java/org/allaymc/api/world/service/HasAABB.java index 60b5d1c72..b24c86458 100644 --- a/Allay-API/src/main/java/org/allaymc/api/world/service/HasAABB.java +++ b/Allay-API/src/main/java/org/allaymc/api/world/service/HasAABB.java @@ -3,10 +3,15 @@ import org.joml.primitives.AABBf; /** - * Allay Project 2023/7/30 + * HasAABB represents an object that has an AABB. * * @author daoge_cmd */ public interface HasAABB { + /** + * Copy the offset AABB to the specified dest AABB. + * + * @return the copied AABB + */ AABBf copyOffsetAABBTo(AABBf dest); } diff --git a/Allay-API/src/main/java/org/allaymc/api/world/service/HasLongId.java b/Allay-API/src/main/java/org/allaymc/api/world/service/HasLongId.java index 01f9e334c..1c8068f45 100644 --- a/Allay-API/src/main/java/org/allaymc/api/world/service/HasLongId.java +++ b/Allay-API/src/main/java/org/allaymc/api/world/service/HasLongId.java @@ -1,10 +1,15 @@ package org.allaymc.api.world.service; /** - * Allay Project 2023/7/30 + * HasLongId represents an object that has a long id. * * @author daoge_cmd */ public interface HasLongId { + /** + * Get the long id of this object. + * + * @return the long id + */ long getLongId(); } diff --git a/Allay-Server/src/main/java/org/allaymc/server/world/service/AllayEntityPhysicsService.java b/Allay-Server/src/main/java/org/allaymc/server/world/service/AllayEntityPhysicsService.java index b1be232ea..1a4581759 100644 --- a/Allay-Server/src/main/java/org/allaymc/server/world/service/AllayEntityPhysicsService.java +++ b/Allay-Server/src/main/java/org/allaymc/server/world/service/AllayEntityPhysicsService.java @@ -523,11 +523,6 @@ public void removeEntity(Entity entity) { entityCollisionCache.remove(entity.getRuntimeId()); } - @Override - public boolean containEntity(Entity entity) { - return entities.containsKey(entity.getRuntimeId()); - } - /** * Please note that this method usually been called asynchronously

* See {@link org.allaymc.server.network.processor.PlayerAuthInputPacketProcessor#handleAsync(EntityPlayer, PlayerAuthInputPacket, long)}