Feature: Custom Entity API

api/src/main/java/org/geysermc/geyser/api/connection/GeyserConnection.java

@@ -25,23 +25,19 @@
 
 package org.geysermc.geyser.api.connection;
 
-import org.checkerframework.checker.index.qual.NonNegative;
 import org.checkerframework.checker.index.qual.Positive;
 import org.checkerframework.checker.nullness.qual.NonNull;
-import org.checkerframework.checker.nullness.qual.Nullable;
 import org.geysermc.api.connection.Connection;
 import org.geysermc.geyser.api.bedrock.camera.CameraData;
 import org.geysermc.geyser.api.bedrock.camera.CameraShake;
 import org.geysermc.geyser.api.command.CommandSource;
 import org.geysermc.geyser.api.entity.EntityData;
-import org.geysermc.geyser.api.entity.type.GeyserEntity;
 import org.geysermc.geyser.api.entity.type.player.GeyserPlayerEntity;
 import org.geysermc.geyser.api.skin.SkinData;
 
 import java.util.NoSuchElementException;
 import java.util.Set;
 import java.util.UUID;
-import java.util.concurrent.CompletableFuture;
 
 /**
  * Represents a player connection used in Geyser.
@@ -58,7 +54,7 @@ public interface GeyserConnection extends Connection, CommandSource {
 
     /**
      * Exposes the {@link EntityData} for this connection.
-     * It allows you to get entities by their Java entity ID, show emotes, and get the player entity.
+     * It allows you to look up other entities through various methods.
      *
      * @return the EntityData for this connection.
      */
@@ -166,15 +162,6 @@ public interface GeyserConnection extends Connection, CommandSource {
      */
     void sendSkin(@NonNull UUID player, @NonNull SkinData skinData);
 
-    /**
-     * @param javaId the Java entity ID to look up.
-     * @return a {@link GeyserEntity} if present in this connection's entity tracker.
-     * @deprecated Use {@link EntityData#entityByJavaId(int)} instead
-     */
-    @Deprecated
-    @NonNull
-    CompletableFuture<@Nullable GeyserEntity> entityByJavaId(@NonNegative int javaId);
-
     /**
      * Displays a player entity as emoting to this client.
      *

api/src/main/java/org/geysermc/geyser/api/entity/EntityData.java

@@ -41,13 +41,29 @@
  */
 public interface EntityData {
 
+    /**
+     * @deprecated use {@link #byJavaId(int)}
+     */
+    @Deprecated
+    @NonNull CompletableFuture<@Nullable GeyserEntity> entityByJavaId(@NonNegative int javaId);
+
     /**
      * Returns a {@link GeyserEntity} to e.g. make them play an emote.
      *
      * @param javaId the Java entity ID to look up
      * @return a {@link GeyserEntity} if present in this connection's entity tracker
      */
-    @NonNull CompletableFuture<@Nullable GeyserEntity> entityByJavaId(@NonNegative int javaId);
+    @Nullable GeyserEntity byJavaId(@NonNegative int javaId);
+
+    /**
+     * Returns a {@link GeyserEntity} to e.g. update entity properties.
+     */
+    @Nullable GeyserEntity byUuid(@NonNull UUID javaUuid);
+
+    /**
+     * Returns a {@link GeyserEntity} based on a Geyser entity id
+     */
+    @Nullable GeyserEntity byGeyserId(@NonNegative long geyserId);
 
     /**
      * (Un)locks the client's movement inputs, so that they cannot move.

api/src/main/java/org/geysermc/geyser/api/entity/custom/CustomEntityDefinition.java

@@ -0,0 +1,65 @@
+/*
+ * Copyright (c) 2025 GeyserMC. http://geysermc.org
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @author GeyserMC
+ * @link https://github.com/GeyserMC/Geyser
+ */
+
+package org.geysermc.geyser.api.entity.custom;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.geysermc.geyser.api.GeyserApi;
+import org.geysermc.geyser.api.entity.definition.GeyserEntityDefinition;
+import org.geysermc.geyser.api.util.Identifier;
+
+/**
+ * Represents a custom entity definition for a non-vanilla, custom Bedrock entity.
+ */
+public interface CustomEntityDefinition extends GeyserEntityDefinition {
+
+    @Override
+    default boolean vanilla() {
+        return false;
+    }
+
+    /**
+     * Creates or retrieves a GeyserEntityDefinition by the Bedrock entity type identifier.
+     *
+     * @param identifier the Bedrock entity identifier
+     * @return the CustomEntityDefinition
+     */
+    static @NonNull CustomEntityDefinition of(@NonNull Identifier identifier) {
+        if (identifier.vanilla()) {
+            throw new IllegalArgumentException("Use GeyserEntityDefinition#of for vanilla entity lookups!");
+        }
+        return GeyserApi.api().provider(CustomEntityDefinition.class, identifier);
+    }
+
+    /**
+     * Creates or retrieves a GeyserEntityDefinition by the Bedrock entity type identifier.
+     *
+     * @param identifier the Bedrock entity identifier, in string format
+     * @return the CustomEntityDefinition
+     */
+    static @NonNull CustomEntityDefinition of(@NonNull String identifier) {
+        return of(Identifier.of(identifier));
+    }
+}

api/src/main/java/org/geysermc/geyser/api/entity/custom/CustomJavaEntityType.java

@@ -0,0 +1,89 @@
+/*
+ * Copyright (c) 2025 GeyserMC. http://geysermc.org
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @author GeyserMC
+ * @link https://github.com/GeyserMC/Geyser
+ */
+
+package org.geysermc.geyser.api.entity.custom;
+
+import org.checkerframework.checker.index.qual.NonNegative;
+import org.checkerframework.checker.nullness.qual.Nullable;
+import org.geysermc.geyser.api.entity.definition.GeyserEntityDefinition;
+import org.geysermc.geyser.api.entity.definition.JavaEntityType;
+import org.geysermc.geyser.api.event.lifecycle.GeyserDefineEntitiesEvent;
+import org.geysermc.geyser.api.util.Identifier;
+
+/**
+ * Represents a custom Minecraft: Java Edition entity type.
+ * This can only be used with modded servers!
+ */
+public interface CustomJavaEntityType extends JavaEntityType {
+
+    @Override
+    default boolean vanilla() {
+        return false;
+    }
+
+    interface Builder {
+
+        /**
+         * The entity type's identifier. It cannot be in the Minecraft namespace
+         * for custom entities!
+         *
+         * @param entityType the identifier
+         * @return this builder
+         */
+        Builder type(Identifier entityType);
+
+        /**
+         * The entity type's numeric network id.
+         * @param javaId the java id
+         * @return this builder
+         */
+        Builder javaId(int javaId);
+
+        /**
+         * The width of this entity.
+         * @param width the width of this entity
+         * @return this builder
+         */
+        Builder width(@NonNegative float width);
+
+        /**
+         * The height of this entity
+         * @param height the height
+         * @return this builder
+         */
+        Builder height(@NonNegative float height);
+
+        /**
+         * The default Bedrock edition entity definition.
+         * You can define custom Bedrock entities, or use vanilla definitions
+         * obtainable via the {@link GeyserDefineEntitiesEvent#entities()} collection.
+         * This entity has to be registered before calling this method!
+         *
+         * @param defaultBedrockDefinition the default Bedrock definition
+         * @return this builder
+         */
+        Builder definition(@Nullable GeyserEntityDefinition defaultBedrockDefinition);
+    }
+}

api/src/main/java/org/geysermc/geyser/api/entity/data/GeyserEntityDataType.java

@@ -0,0 +1,68 @@
+/*
+ * Copyright (c) 2025 GeyserMC. http://geysermc.org
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @author GeyserMC
+ * @link https://github.com/GeyserMC/Geyser
+ */
+
+package org.geysermc.geyser.api.entity.data;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.geysermc.geyser.api.GeyserApi;
+import org.geysermc.geyser.api.entity.type.GeyserEntity;
+
+/**
+ * Represents a type of entity data that can be sent for an entity.
+ * <p>
+ * Entity data types define the kind of value stored for a particular piece of metadata,
+ * such as a {@code Byte}, {@code Integer}, {@code Float}; and the name associated with them.
+ * <p>
+ * Unlike custom items or blocks, it is possible to update entity metadata at runtime,
+ * which can be done using {@link GeyserEntity#update(GeyserEntityDataType, Object)}.
+ *
+ * @param <T> the value type associated with this entity data type
+ */
+public interface GeyserEntityDataType<T> {
+
+    /**
+     * Gets the Java class representing the value type associated with this data type.
+     *
+     * @return the class of the value used by this entity data type
+     */
+    @NonNull Class<T> typeClass();
+
+    /**
+     * Gets the unique name of this data type.
+     * <p>
+     * The name is used internally to identify and register the data type so it can be
+     * referenced when reading or writing entity metadata.
+     *
+     * @return the name of this entity data type
+     */
+    @NonNull String name();
+
+    /**
+     * For API usage only; use the types defined in {@link GeyserEntityDataTypes}
+     */
+    static <T> GeyserEntityDataType<T> of(@NonNull Class<T> typeClass, @NonNull String name) {
+        return GeyserApi.api().provider(GeyserEntityDataType.class, typeClass, name);
+    }
+}

api/src/main/java/org/geysermc/geyser/api/entity/data/GeyserEntityDataTypes.java

@@ -0,0 +1,87 @@
+/*
+ * Copyright (c) 2025 GeyserMC. http://geysermc.org
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @author GeyserMC
+ * @link https://github.com/GeyserMC/Geyser
+ */
+
+package org.geysermc.geyser.api.entity.data;
+
+import org.geysermc.geyser.api.entity.data.types.Hitbox;
+
+/**
+ * Contains commonly used {@link GeyserEntityDataType} constants for built-in entity
+ * metadata fields.
+ * <p>
+ * These data types define the structure of certain primitive or numeric metadata
+ * values that can be used for Bedrock entities. Each constant is backed by a
+ * pre-registered entity data type that can be used when reading or writing metadata
+ * through the Geyser API.
+ */
+public final class GeyserEntityDataTypes {
+
+    /**
+     * Represents a single-byte value used for color types
+     * (e.g., sheep wool color).
+     */
+    public static final GeyserEntityDataType<Byte> COLOR =
+        GeyserEntityDataType.of(Byte.class, "color");
+
+    /**
+     * Represents a numeric variant index that can be queried in resource packs.
+     */
+    public static final GeyserEntityDataType<Integer> VARIANT =
+        GeyserEntityDataType.of(Integer.class, "variant");
+
+    /**
+     * Represents the entity's width.
+     */
+    public static final GeyserEntityDataType<Float> WIDTH =
+        GeyserEntityDataType.of(Float.class, "width");
+
+    /**
+     * Represents the entity's height.
+     */
+    public static final GeyserEntityDataType<Float> HEIGHT =
+        GeyserEntityDataType.of(Float.class, "height");
+
+    /**
+     * Represents the entity's vertical offset.
+     */
+    public static final GeyserEntityDataType<Float> VERTICAL_OFFSET =
+        GeyserEntityDataType.of(Float.class, "vertical_offset");
+
+    /**
+     * Represents the scale multiplier.
+     */
+    public static final GeyserEntityDataType<Float> SCALE =
+        GeyserEntityDataType.of(Float.class, "scale");
+
+    /**
+     * Represents custom hitboxes for entities
+     */
+    public static final GeyserListEntityDataType<Hitbox> HITBOXES =
+        GeyserListEntityDataType.of(Hitbox.class, "hitboxes");
+
+    private GeyserEntityDataTypes() {
+        // no-op
+    }
+}