docs: add javadocs for EntityPhysicsService, EntityService, HasAABB, …

…HasLongId

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<Entity> 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<Entity> 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<Entity> 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<Entity> 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<Entity> computeCollidingEntities(AABBfc aabb, AABBOverlapFilter<Entity> predicate);
 
     default List<Entity> 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<Entity> 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<Entity> 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<Entity> getCachedEntityCollidingResult(Entity entity, boolean ignoreEntityHasCollision);
 }

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,16 +13,30 @@ 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.
+     * <p>
+     * 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);
 
     default void removeEntity(Entity entity) {
         removeEntity(entity, () -> {});
     }
 
+    /**
+     * Remove an entity from the world.
+     * <p>
+     * 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);
 }

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);
 }

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();
 }

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 <p/>
      * See {@link org.allaymc.server.network.processor.PlayerAuthInputPacketProcessor#handleAsync(EntityPlayer, PlayerAuthInputPacket, long)}