From 146d8eb962ad3bceda4b62cf5fc9ef1948e26dab Mon Sep 17 00:00:00 2001
From: RednedEpic <redned235@gmail.com>
Date: Sat, 7 May 2022 15:20:59 -0500
Subject: [PATCH] Improve documentation for creating custom entities

---
 .../geyser/api/entity/EntityDefinition.java   | 44 +++++++++++++++++++
 .../lifecycle/GeyserDefineEntitiesEvent.java  |  4 ++
 2 files changed, 48 insertions(+)

diff --git a/api/geyser/src/main/java/org/geysermc/geyser/api/entity/EntityDefinition.java b/api/geyser/src/main/java/org/geysermc/geyser/api/entity/EntityDefinition.java
index 1a74c46f1..8036c1038 100644
--- a/api/geyser/src/main/java/org/geysermc/geyser/api/entity/EntityDefinition.java
+++ b/api/geyser/src/main/java/org/geysermc/geyser/api/entity/EntityDefinition.java
@@ -27,11 +27,55 @@ package org.geysermc.geyser.api.entity;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.geysermc.geyser.api.GeyserApi;
+import org.geysermc.geyser.api.event.downstream.entity.ServerSpawnEntityEvent;
+import org.geysermc.geyser.api.event.lifecycle.GeyserDefineEntitiesEvent;
 
 /**
  * Holds information about an entity that remains constant no matter
  * its properties. This is typically data such as its identifier,
  * its height/width, offset, etc.
+ * <p>
+ * This class can be used to register custom entities through the
+ * {@link GeyserDefineEntitiesEvent}. Custom entities can be created
+ * using the builder like so:
+ * <pre>
+ * {@code
+ *     public static final EntityDefinition CUSTOM_MOB = EntityDefinition.builder()
+ *                 .identifier(EntityIdentifier.builder()
+ *                         .identifier("geysermc:custom_mob")
+ *                         .summonable(false)
+ *                         .spawnEgg(false)
+ *                         .build())
+ *                 .width(1.0f)
+ *                 .height(1.0f)
+ *                 .offset(1.0f)
+ *                 .build();
+ * }
+ * </pre>
+ *
+ * <p>
+ * Within the {@link GeyserDefineEntitiesEvent}, you can then add the
+ * custom entity definition to the {@link GeyserDefineEntitiesEvent#definitions()}
+ * list. A resource pack utilizing this entity identifier will need to be
+ * provided for this to fully work.
+ * <p>
+ * Summoning custom entities on their own is not supported through the
+ * API exclusively. Third party extensions or plugins on supported platforms
+ * may provide an interface for this, but the current suggestion using
+ * the Geyser API exclusively is to listen for the {@link ServerSpawnEntityEvent}
+ * and modify the entity definition based on the data provided there.
+ * <p>
+ * An example of doing so is as follows:
+ * <pre>
+ * {@code
+ *     @Subscribe
+ *     public void onSpawn(ServerSpawnEntityEvent event) {
+ *         if (event.entityDefinition().identifier().equals("mob_to_replace")) {
+ *             event.setEntityDefinition(CUSTOM_MOB);
+ *         }
+ *     }
+ * }
+ * </pre>
  */
 public interface EntityDefinition {
 
diff --git a/api/geyser/src/main/java/org/geysermc/geyser/api/event/lifecycle/GeyserDefineEntitiesEvent.java b/api/geyser/src/main/java/org/geysermc/geyser/api/event/lifecycle/GeyserDefineEntitiesEvent.java
index 4638caa4d..5ce2cf6ab 100644
--- a/api/geyser/src/main/java/org/geysermc/geyser/api/event/lifecycle/GeyserDefineEntitiesEvent.java
+++ b/api/geyser/src/main/java/org/geysermc/geyser/api/event/lifecycle/GeyserDefineEntitiesEvent.java
@@ -33,6 +33,10 @@ import java.util.List;
 
 /**
  * Called when entities are defined within Geyser.
+ * <p>
+ * This event can be used to add custom entities to Geyser.
+ * Entity definitions can be created using the builder provided
+ * inside of {@link EntityDefinition}.
  *
  * @param definitions a mutable list of the currently
  *                    registered entity definitions