Feature: 26.2

README.md

@@ -16,10 +16,10 @@ Special thanks to the DragonProxy project for being a trailblazer in protocol tr
 
 ## Supported Versions
 
-| Edition | Supported Versions                                                                                         |
-|---------|------------------------------------------------------------------------------------------------------------|
-| Bedrock | 26.0, 26.1, 26.2, 26.3, 26.10, 26.20, 26.21, 26.22, 26.23, 26.30, 26.31, 26.32                             |
-| Java    | 26.1 - 26.1.2 (For older versions, [see this guide](https://geysermc.org/wiki/geyser/supported-versions/)) |
+| Edition | Supported Versions                                                                                |
+|---------|---------------------------------------------------------------------------------------------------|
+| Bedrock | 26.0, 26.1, 26.2, 26.3, 26.10, 26.20, 26.21, 26.22, 26.23, 26.30, 26.31, 26.32                    |
+| Java    | 26.2 (For older versions, [see this guide](https://geysermc.org/wiki/geyser/supported-versions/)) |
 
 ## Setting Up
 Take a look [here](https://geysermc.org/wiki/geyser/setup/) for how to set up Geyser.

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

@@ -25,22 +25,19 @@
 
 package org.geysermc.geyser.api.connection;
 
-import org.checkerframework.checker.index.qual.NonNegative;
 import org.checkerframework.checker.index.qual.Positive;
 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 org.jspecify.annotations.Nullable;
 
 import java.util.NoSuchElementException;
 import java.util.Set;
 import java.util.UUID;
-import java.util.concurrent.CompletableFuture;
 
 /**
  * Represents a player connection used in Geyser.
@@ -57,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.
      */
@@ -164,14 +161,6 @@ public interface GeyserConnection extends Connection, CommandSource {
      */
     void sendSkin(UUID player, 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
-    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

@@ -29,24 +29,57 @@
 import org.geysermc.geyser.api.connection.GeyserConnection;
 import org.geysermc.geyser.api.entity.type.GeyserEntity;
 import org.geysermc.geyser.api.entity.type.player.GeyserPlayerEntity;
+import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.Nullable;
 
 import java.util.UUID;
 import java.util.concurrent.CompletableFuture;
 
 /**
- * This class holds all the methods that relate to entities.
- * Can be accessed through {@link GeyserConnection#entities()}.
+ * Provides entity lookup and input-lock utilities for a specific connection.
+ * Accessed via {@link GeyserConnection#entities()}.
  */
 public interface EntityData {
 
     /**
-     * Returns a {@link GeyserEntity} to e.g. make them play an emote.
+     * @deprecated use {@link #byJavaId(int)}
+     * @since 2.3.0
+     */
+    @Deprecated(since = "2.11.0")
+    CompletableFuture<@Nullable GeyserEntity> entityByJavaId(@NonNegative int javaId);
+
+    /**
+     * Returns the {@link GeyserEntity} for the given Java entity ID if it is tracked
+     * in this connection's entity cache, or {@code null} if not found.
      *
      * @param javaId the Java entity ID to look up
-     * @return a {@link GeyserEntity} if present in this connection's entity tracker
+     * @return the entity, or {@code null} if not found
+     * @since 2.11.0
      */
-    CompletableFuture<@Nullable GeyserEntity> entityByJavaId(@NonNegative int javaId);
+    @ApiStatus.Experimental
+    @Nullable GeyserEntity byJavaId(@NonNegative int javaId);
+
+    /**
+     * Returns the {@link GeyserEntity} for the given Java entity UUID if it is tracked
+     * in this connection's entity cache, or {@code null} if not found.
+     *
+     * @param javaUuid the Java entity UUID to look up
+     * @return the entity, or {@code null} if not found
+     * @since 2.11.0
+     */
+    @ApiStatus.Experimental
+    @Nullable GeyserEntity byUuid(UUID javaUuid);
+
+    /**
+     * Returns the {@link GeyserEntity} for the given Geyser runtime entity ID if it is tracked
+     * in this connection's entity cache, or {@code null} if not found.
+     *
+     * @param geyserId the Geyser entity ID (as returned by {@link GeyserEntity#geyserId()})
+     * @return the entity, or {@code null} if not found
+     * @since 2.11.0
+     */
+    @ApiStatus.Experimental
+    @Nullable GeyserEntity byGeyserId(@NonNegative long geyserId);
 
     /**
      * (Un)locks the client's movement inputs, so that they cannot move.
@@ -79,7 +112,7 @@ public interface EntityData {
     void showEmote(GeyserPlayerEntity emoter, String emoteId);
 
     /**
-     * @deprecated Use {@link GeyserConnection#playerEntity} instead.
+     * @deprecated Use {@link GeyserConnection#playerEntity()} instead.
      */
     @Deprecated(since = "2.9.3")
     GeyserPlayerEntity playerEntity();

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

@@ -0,0 +1,83 @@
+/*
+ * 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.geysermc.geyser.api.GeyserApi;
+import org.geysermc.geyser.api.entity.definition.GeyserEntityDefinition;
+import org.geysermc.geyser.api.event.java.ServerAttachParrotsEvent;
+import org.geysermc.geyser.api.event.java.ServerSpawnEntityEvent;
+import org.geysermc.geyser.api.util.Identifier;
+import org.jetbrains.annotations.ApiStatus;
+
+/**
+ * Represents a Bedrock entity definition for a custom entity.
+ * These cannot be in the {@code minecraft} namespace, and have to be manually
+ * spawned using either the {@link ServerSpawnEntityEvent} or {@link ServerAttachParrotsEvent}.
+ *
+ * @since 2.11.0
+ */
+@ApiStatus.Experimental
+public interface CustomEntityDefinition extends GeyserEntityDefinition {
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    @ApiStatus.Experimental
+    default boolean vanilla() {
+        return false;
+    }
+
+    /**
+     * Creates or retrieves a custom entity definition by the Bedrock entity type identifier.
+     *
+     * @param identifier the Bedrock entity identifier
+     * @return customEntityDefinition
+     * @since 2.11.0
+     */
+    @ApiStatus.Experimental
+    static CustomEntityDefinition of(Identifier identifier) {
+        if (identifier.vanilla()) {
+            throw new IllegalArgumentException(
+                "Custom entity identifiers cannot use the 'minecraft' namespace. "
+                    + "Use a non-vanilla namespace, e.g. 'mymod:my_entity'.");
+        }
+        return GeyserApi.api().provider(CustomEntityDefinition.class, identifier);
+    }
+
+    /**
+     * Creates or retrieves a {@link CustomEntityDefinition} by the Bedrock entity type identifier.
+     * The identifier must not use the {@code minecraft} namespace.
+     *
+     * @param identifier the Bedrock entity identifier, in {@code namespace:path} format
+     * @return the custom entity definition
+     * @since 2.11.0
+     */
+    @ApiStatus.Experimental
+    static CustomEntityDefinition of(String identifier) {
+        return of(Identifier.of(identifier));
+    }
+}

api/src/main/java/org/geysermc/geyser/api/entity/custom/package-info.java

@@ -0,0 +1,29 @@
+/*
+ * Copyright (c) 2026 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
+ */
+
+@NullMarked
+package org.geysermc.geyser.api.entity.custom;
+
+import org.jspecify.annotations.NullMarked;

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

@@ -0,0 +1,115 @@
+/*
+ * 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.type.GeyserEntity;
+import org.geysermc.geyser.api.util.Identifier;
+import org.jetbrains.annotations.ApiStatus;
+
+import java.util.Objects;
+
+/**
+ * Represents a type of entity data that can be sent for an entity.
+ * <p>
+ * Entity data types define the values stored for a particular piece of metadata,
+ * such as a {@code Byte}, {@code Integer}, {@code Float}; and the identifier associated with the types.
+ * <p>
+ * Unlike properties of custom items or blocks, it is possible to update entity metadata at runtime,
+ * which can be done using {@link GeyserEntity#override(GeyserEntityDataType, Object)}.
+ * <p>
+ * Only the built-in types in {@link GeyserEntityDataTypes} are supported. Attempting to use a type
+ * not provided by Geyser will throw an {@link IllegalArgumentException} at runtime.
+ *
+ * @param <T> the value type associated with this entity data type
+ * @since 2.11.0
+ */
+@ApiStatus.Experimental
+public abstract sealed class GeyserEntityDataType<T> permits GeyserEntityDataType.SimpleType, GeyserListEntityDataType {
+
+    private final Identifier identifier;
+    private final Class<T> typeClass;
+
+    @ApiStatus.Internal
+    GeyserEntityDataType(Identifier identifier, Class<T> typeClass) {
+        this.identifier = Objects.requireNonNull(identifier);
+        this.typeClass = Objects.requireNonNull(typeClass);
+    }
+
+    /**
+     * Gets the identifier associated with this entity data type.
+     *
+     * @return the identifier for this type
+     * @since 2.11.0
+     */
+    @ApiStatus.Experimental
+    public final Identifier identifier() {
+        return identifier;
+    }
+
+    /**
+     * 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
+     * @since 2.11.0
+     */
+    @ApiStatus.Experimental
+    public final Class<T> typeClass() {
+        return typeClass;
+    }
+
+    @Override
+    @ApiStatus.Experimental
+    public final boolean equals(Object o) {
+        if (this == o) return true;
+        if (!(o instanceof GeyserEntityDataType<?> that)) return false;
+        return identifier.equals(that.identifier);
+    }
+
+    @Override
+    @ApiStatus.Experimental
+    public final int hashCode() {
+        return identifier.hashCode();
+    }
+
+    @Override
+    @ApiStatus.Experimental
+    public String toString() {
+        return "GeyserEntityDataType{" + identifier + ", " + typeClass.getSimpleName() + "}";
+    }
+
+    @ApiStatus.Internal
+    static <T> GeyserEntityDataType<T> create(Identifier identifier, Class<T> typeClass) {
+        return new SimpleType<>(identifier, typeClass);
+    }
+
+    @ApiStatus.Internal
+    static final class SimpleType<T> extends GeyserEntityDataType<T> {
+        @ApiStatus.Internal
+        SimpleType(Identifier identifier, Class<T> typeClass) {
+            super(identifier, typeClass);
+        }
+    }
+}