Feature: Custom Entity API #6010

onebeastchris · 2025-11-25T21:38:25Z

Introducing: Custom Entities!

tl;dr: with this PR, you can summon custom bedrock entities that replace the vanilla mapping

Additions

CustomEntityDefinition / GeyserEntityDefinition: Representations of custom, and vanilla Bedrock entities. Unlike custom blocks/items, bedrock entities have fewer properties that are defined in advance; it's just the identifier, and the Bedrock Entity Properties. Setting entity properties was introduced in a previous PR; and works the same way.
JavaEntityType: Represents a vanilla Java entity type, with the width / height / type identifier, as well as the default Bedrock entity associated with it. Similarly, CustomJavaEntityType represents a non-vanilla Java entity - however, that part of the API still needs some more work and should be regarded as unstable.
GeyserEntityDataType / GeyserEntityDataTypes: These are representations of various Bedrock entity metadata types, such as scale, width, height, variant, or color. Further, vertical_offset has been added as a "custom" data type to allow setting a vertical entity offset.
The GeyserEntity class has seen major additions! You can now query the entities' associated Bedrock entity definition, Java position, the Geyser id, UUID, or update / query the aforementioned data types.
You can now look up GeyserEntity instances using the entity UUID or Geyser entity ID, additionally to the Java entity id.

New Events

GeyserDefineEntitiesEvent: Allows registering custom Bedrock entities and querying existing entities.
SessionSpawnEntityEvent: Base entity spawn event extended by the server events. With it, you can set a pre-spawn consumer, and switch the Bedrock entity definition, or cancel the entity spawn outright.
ServerAttachParrotsEvent: Called every time a parrot is spawned on the player entity
ServerSpawnEntityEvent: Called for every non-player entity that is spawned by the Java server. Within this event, you can query the Java entity type, uuid, and entity id (and also have access to the methods provided by the SessionSpawnEntityEvent!

Here's some example code of the API in action:
https://gist.github.com/onebeastchris/1521ab585669792a79a9558d9d069834

Internal changes:

Bedrock entity definitions are now split from the Java entity definitions.
There is now a EntitySpawnContext that is passed in entity constructors - instead of many arguments. This should make it easier to add new entities, call events, or add more arguments in the future
Entity offsets are now properly handled in the base Entity class - no more hacks in TntEntity and the like!

TO-DO's:

Finish VanillaEntityBases split; potentially allow non-vanilla entities to extend those?
Debug logging for modifications
Sensible limits for scale / height / width
Docs

EXPERIMENTAL downloads:

…nition, create GeyserEntityType, target custom entities MCPL

…can now be modified in the ServerSpawnEntityEvent

Copilot

Pull request overview

This PR implements a Custom Entity API for Geyser, refactoring entity creation to use a context-based approach instead of individual constructor parameters. The changes enable support for custom entities while modernizing the entity type system.

Key Changes:

Introduced EntitySpawnContext as a unified way to pass entity creation parameters
Renamed EntityDefinition to EntityTypeDefinition for clarity
Changed EntityType to BuiltinEntityType to distinguish vanilla entities from custom ones
Added new registries for custom entities and Bedrock entity definitions
Refactored 100+ entity class constructors to use the new context pattern

Reviewed changes

Copilot reviewed 192 out of 193 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
gradle/libs.versions.toml	Updated mcprotocollib version to feature branch for custom entities
Test files	Updated mock entity creation to use EntitySpawnContext
StatisticsUtils.java	Changed entity name translation to use GeyserEntityType
EntityUtils.java	Refactored entity type comparisons from switch to if-else with .is() method
Translator classes	Updated to use BuiltinEntityType and new entity creation patterns
Session/cache classes	Updated entity instantiation with EntitySpawnContext
Registry classes	Added new registries for custom entity support
Entity hierarchy	All entity constructors refactored to accept EntitySpawnContext

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review for a chance to win a $100 gift card. Take the survey.

...a/org/geysermc/geyser/translator/protocol/bedrock/entity/player/input/BedrockMovePlayer.java

core/src/main/java/org/geysermc/geyser/util/EntityUtils.java

...in/java/org/geysermc/geyser/translator/protocol/java/entity/JavaSetPassengersTranslator.java

core/src/main/java/org/geysermc/geyser/level/physics/CollisionManager.java

core/src/main/java/org/geysermc/geyser/entity/EntityTypeDefinition.java

core/src/main/java/org/geysermc/geyser/entity/BedrockEntityDefinition.java

core/src/main/java/org/geysermc/geyser/entity/EntityTypeDefinition.java

core/src/main/java/org/geysermc/geyser/entity/NonVanillaEntityTypeDefinition.java

core/src/main/java/org/geysermc/geyser/entity/VanillaEntityType.java

… API Javadocs

Copilot

Pull request overview

Copilot reviewed 222 out of 223 changed files in this pull request and generated 11 comments.

Comments suppressed due to low confidence (1)

core/src/main/java/org/geysermc/geyser/session/GeyserSession.java:610

getAttachedFireworkRockets exposes the internal representation stored in field attachedFireworkRockets. The value may be modified after this call to getAttachedFireworkRockets.
getAttachedFireworkRockets exposes the internal representation stored in field attachedFireworkRockets. The value may be modified after this call to getAttachedFireworkRockets.
getAttachedFireworkRockets exposes the internal representation stored in field attachedFireworkRockets. The value may be modified after this call to getAttachedFireworkRockets.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review for a chance to win a $100 gift card. Take the survey.

core/src/main/java/org/geysermc/geyser/util/EntityUtils.java

core/src/main/java/org/geysermc/geyser/session/cache/waypoint/GeyserWaypoint.java

core/src/main/java/org/geysermc/geyser/entity/EntityTypeDefinition.java

core/src/main/java/org/geysermc/geyser/entity/GeyserEntityType.java

core/src/main/java/org/geysermc/geyser/entity/VanillaEntityType.java

core/src/main/java/org/geysermc/geyser/entity/type/Entity.java

Copilot

Copilot reviewed 243 out of 244 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 244 out of 245 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

…tities-api # Conflicts: # core/src/main/java/org/geysermc/geyser/entity/type/Entity.java # core/src/main/java/org/geysermc/geyser/entity/type/LivingEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/player/AvatarEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/player/MannequinEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/player/SkullPlayerEntity.java # core/src/main/java/org/geysermc/geyser/skin/SkinManager.java # core/src/main/java/org/geysermc/geyser/translator/protocol/bedrock/BedrockNetworkStackLatencyTranslator.java # core/src/main/java/org/geysermc/geyser/translator/protocol/java/entity/JavaRemoveMobEffectTranslator.java # core/src/main/java/org/geysermc/geyser/util/DimensionUtils.java

Copilot

Copilot reviewed 248 out of 249 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (1)

core/src/main/java/org/geysermc/geyser/session/GeyserSession.java:625

getAttachedFireworkRockets exposes the internal representation stored in field attachedFireworkRockets. The value may be modified after this call to getAttachedFireworkRockets.
getAttachedFireworkRockets exposes the internal representation stored in field attachedFireworkRockets. The value may be modified after this call to getAttachedFireworkRockets.
getAttachedFireworkRockets exposes the internal representation stored in field attachedFireworkRockets. The value may be modified after this call to getAttachedFireworkRockets.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-10T20:40:23Z

core/src/main/java/org/geysermc/geyser/impl/entity/HitboxImpl.java

+        }
+
+        List<Hitbox> boxes = new ArrayList<>();
+        List<NbtMap> hitboxes = metaDataMap.getList("Hitxboxes", NbtType.COMPOUND);


Typo in NBT key name: "Hitxboxes" should be "Hitboxes" (note the extra 'x')

core/src/main/java/org/geysermc/geyser/util/EntityUtils.java

core/src/main/java/org/geysermc/geyser/impl/entity/HitboxImpl.java

core/src/main/java/org/geysermc/geyser/entity/type/Entity.java

…tities-api # Conflicts: # core/src/main/java/org/geysermc/geyser/entity/VanillaEntities.java # core/src/main/java/org/geysermc/geyser/entity/spawn/EntitySpawnContext.java # core/src/main/java/org/geysermc/geyser/entity/type/AbstractArrowEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/BoatEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/Entity.java # core/src/main/java/org/geysermc/geyser/entity/type/FireballEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/FishingHookEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/InteractionEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/LeashKnotEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/LivingEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/MinecartEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/TNTEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/TextDisplayEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/ThrowableEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/ThrowableItemEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/WitherSkullEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/living/AbstractFishEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/living/AgeableEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/living/ArmorStandEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/living/MagmaCubeEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/living/SquidEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/living/animal/SnifferEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/living/animal/horse/CamelEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/living/merchant/AbstractMerchantEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/living/monster/EnderDragonEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/living/monster/EnderDragonPartEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/living/monster/ShulkerEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/living/monster/raid/SpellcasterIllagerEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/player/AvatarEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/player/PlayerEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/player/SessionPlayerEntity.java # core/src/main/java/org/geysermc/geyser/level/physics/CollisionManager.java # core/src/main/java/org/geysermc/geyser/session/cache/EntityCache.java # core/src/main/java/org/geysermc/geyser/session/cache/FormCache.java # core/src/main/java/org/geysermc/geyser/session/cache/SkullCache.java # core/src/main/java/org/geysermc/geyser/session/cache/WorldBorder.java # core/src/main/java/org/geysermc/geyser/translator/inventory/MerchantInventoryTranslator.java # core/src/main/java/org/geysermc/geyser/translator/level/block/entity/VaultBlockEntityTranslator.java # core/src/main/java/org/geysermc/geyser/translator/protocol/bedrock/entity/player/input/BedrockMovePlayer.java # core/src/main/java/org/geysermc/geyser/translator/protocol/java/entity/JavaAddEntityTranslator.java # core/src/main/java/org/geysermc/geyser/translator/protocol/java/entity/JavaEntityEventTranslator.java # core/src/main/java/org/geysermc/geyser/translator/protocol/java/entity/player/JavaPlayerInfoUpdateTranslator.java # core/src/main/java/org/geysermc/geyser/translator/protocol/java/entity/player/JavaPlayerPositionTranslator.java # core/src/main/java/org/geysermc/geyser/translator/protocol/java/level/JavaGameEventTranslator.java # core/src/test/java/org/geysermc/geyser/scoreboard/network/util/GeyserMockContextScoreboard.java

Copilot

Pull request overview

Copilot reviewed 133 out of 135 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

core/src/main/java/org/geysermc/geyser/entity/type/Entity.java:105

This method overrides GeyserEntity.uuid; it is advisable to add an Override annotation.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-12T01:02:20Z

core/src/main/java/org/geysermc/geyser/impl/entity/HitboxImpl.java

+        return NbtMap.builder().putList("Hitboxes", NbtType.COMPOUND, list).build();
+    }
+
+    public static class Builder implements Hitbox.Builder {


Builder has the same name as its supertype org.geysermc.geyser.api.entity.data.types.Hitbox$Builder.

…tities-api # Conflicts: # core/src/main/java/org/geysermc/geyser/entity/VanillaEntities.java # core/src/main/java/org/geysermc/geyser/entity/type/DisplayBaseEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/LivingEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/MinecartEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/TextDisplayEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/living/monster/ShulkerEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/player/AvatarEntity.java # core/src/main/java/org/geysermc/geyser/util/DimensionUtils.java

…tities-api

Copilot

Pull request overview

Copilot reviewed 133 out of 134 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-26T21:17:37Z

core/src/main/java/org/geysermc/geyser/entity/type/LivingEntity.java

    @Override
-    public void moveAbsolute(Vector3f position, float yaw, float pitch, float headYaw, boolean isOnGround, boolean teleported) {
+    public void moveAbsolute(Vector3f javaPosition, float yaw, float pitch, float headYaw, boolean isOnGround, boolean teleported) {
        // It's vanilla behaviour to lerp if the position is within 64 blocks, however we also check if the position is close enough to the player
        // position to see if it can actually affect anything to save network.
-        if (shouldLerp() && position.distanceSquared(this.position) < 4096 && position.distanceSquared(session.getPlayerEntity().position()) < 4096) {
+        if (shouldLerp() && javaPosition.distanceSquared(javaPosition) < 4096 && javaPosition.distanceSquared(session.getPlayerEntity().position()) < 4096) {
            this.dirtyPitch = this.dirtyYaw = this.dirtyHeadYaw = true;

            setYaw(yaw);
            setPitch(pitch);
            setHeadYaw(headYaw);
            setOnGround(isOnGround);

-            this.lerpPosition = position;
+            this.lerpPosition = javaPosition;
            this.lerpSteps = 3;
        } else {
-            super.moveAbsolute(position, yaw, pitch, headYaw, isOnGround, teleported);
+            super.moveAbsolute(javaPosition, yaw, pitch, headYaw, isOnGround, teleported);
        }


In moveAbsolute, the distance check for deciding whether to lerp is incorrect: javaPosition.distanceSquared(javaPosition) always returns 0, so the first half of the condition is effectively always true. This both defeats the intended 64-block range guard and can lead to unnecessary interpolation behavior; the comparison should be against the entity’s current position (e.g., javaPosition.distanceSquared(position())).

…ce of truth

eclipseisoffline and others added 13 commits November 22, 2025 17:41

Start working on custom entity API (for real this time)

5a7bf1b

Split EntityDefinition up into EntityDefinition and VanillaEntityDefi…

f4156c6

…nition, create GeyserEntityType, target custom entities MCPL

Allow creating custom entity types from API

0b8678e

Further refactor EntityDefinition, create a Base class

d843745

Work on exposing custom entity definitions in the API

7fe8992

Add EntityDefinition#is

e398c54

Implement CustomEntityDefinition, part one

a3869cf

Move CustomEntityDefinition into custom package

11e6b50

CustomEntityDefinition should extend GeyserEntityDefinition

6fab587

Separate BedrockEntityDefinition from Entity classes

3392510

EntityDefinition -> EntityTypeDefinition

c57f250

Continue splitting bedrock entities from java types

142cbae

Width, height and offset should be tied to the Java entity type; and …

8ff763b

…can now be modified in the ServerSpawnEntityEvent

Copilot AI review requested due to automatic review settings November 25, 2025 21:38

onebeastchris added Work in Progress The issue is currently being worked on. PR: Feature When a PR implements a new feature API The issue/feature request relates to the Geyser API labels Nov 25, 2025

onebeastchris mentioned this pull request Nov 25, 2025

Add support for custom entities in the API #3754

Closed

4 tasks

Copilot started reviewing on behalf of onebeastchris November 25, 2025 21:38 View session

Copilot finished reviewing on behalf of onebeastchris November 25, 2025 21:39

Copilot AI reviewed Nov 25, 2025

View reviewed changes

onebeastchris added 4 commits November 26, 2025 17:08

More work on events, closer to working

b2739e1

Fix startup

52b76f5

Expose geyserId in API, add SessionAttachParrotsEvent

8f8e3be

Rename SessionAttachParrotsEvent -> ServerAttachParrotsEvent, fill in…

9e6b133

… API Javadocs

Copilot AI review requested due to automatic review settings November 27, 2025 21:13

Copilot started reviewing on behalf of onebeastchris November 27, 2025 21:14 View session

Copilot finished reviewing on behalf of onebeastchris November 27, 2025 21:14

Apply some suggestions

75d5f07

Copilot AI reviewed Nov 27, 2025

View reviewed changes

onebeastchris added 2 commits December 17, 2025 14:58

Minor cleanup

2916f3f

Log unknown implementations of GeyserEntityDefinition

adf4063

Copilot AI review requested due to automatic review settings December 19, 2025 20:31

Copilot started reviewing on behalf of onebeastchris December 19, 2025 20:31 View session

Copilot AI reviewed Dec 19, 2025

View reviewed changes

onebeastchris added 2 commits December 21, 2025 14:49

Use position setter instead of directly setting entity position

927b72f

Fix client crashing related to sending & unlocking smithing recipes

9aefb36

Copilot AI review requested due to automatic review settings December 22, 2025 23:16

Copilot started reviewing on behalf of onebeastchris December 22, 2025 23:16 View session

Copilot AI reviewed Dec 22, 2025

View reviewed changes

Merge in upstream, we are on 1.21.11 now

ac29b54

onebeastchris mentioned this pull request Jan 10, 2026

Chore: Entity system refactor #6100

Merged

onebeastchris added 2 commits January 10, 2026 21:19

Merge upstream

7ef5998

Copilot AI review requested due to automatic review settings January 10, 2026 20:31

Copilot started reviewing on behalf of onebeastchris January 10, 2026 20:31 View session

Copilot AI reviewed Jan 10, 2026

View reviewed changes

onebeastchris added 3 commits January 11, 2026 23:58

Fix hitbox querying, fix offset handling for boats

ea8d896

Fix entity lerping

a52405c

Copilot AI review requested due to automatic review settings January 12, 2026 00:52

Copilot started reviewing on behalf of onebeastchris January 12, 2026 00:52 View session

Copilot AI reviewed Jan 12, 2026

View reviewed changes

onebeastchris added 3 commits January 25, 2026 03:53

Merge remote-tracking branch 'upstream/master' into feature/custom-en…

9bb0d31

…tities-api

Merge remote-tracking branch 'upstream/master' into feature/custom-en…

af9a456

…tities-api

Copilot AI review requested due to automatic review settings January 26, 2026 21:07

Copilot started reviewing on behalf of onebeastchris January 26, 2026 21:07 View session

Copilot AI reviewed Jan 26, 2026

View reviewed changes

Remove bedrockPosition variable again, simpler to only store one sour…

c0cac81

…ce of truth

Uh oh!

Feature: Custom Entity API #6010

Are you sure you want to change the base?

Feature: Custom Entity API #6010

Conversation

onebeastchris commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Additions

New Events

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Key Changes:

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

onebeastchris commented Nov 25, 2025 •

edited

Loading