Feature: Custom Entity API by onebeastchris · Pull Request #6010 · GeyserMC/Geyser

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.

… 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.

Copilot

Pull request overview

Copilot reviewed 130 out of 131 changed files in this pull request and generated 2 comments.

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

You can also share your feedback on Copilot code review. Take the survey.

+            GeyserImpl.getInstance().getLogger().debug("Client %s tried to request pack with an invalid id %s)",
                session.bedrockUsername(), id);


This will be later reworked to allow setting a height + width combo that accounts for the entity pose. For now, it's a general override

Copilot

Pull request overview

Copilot reviewed 130 out of 131 changed files in this pull request and generated 2 comments.

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

You can also share your feedback on Copilot code review. Take the survey.

+    @Override
+    public @Nullable GeyserEntity byJavaId(@NonNegative int javaId) {
+        //noinspection ConstantValue
+        if (javaId < 0) {
+            throw new IllegalArgumentException("entity id cannot be negative! (got: " + javaId + ")");
+        }
+        return session.getEntityCache().getEntityByJavaId(javaId);
+    }
+
+    @Override
+    public @Nullable GeyserEntity byUuid(@NonNull UUID javaUuid) {
+        Objects.requireNonNull(javaUuid, "javaUuid");
+        return session.getEntityCache().getEntityByUuid(javaUuid);
+    }
+
+    @Override
+    public @Nullable GeyserEntity byGeyserId(@NonNegative long geyserId) {
+        //noinspection ConstantValue
+        if (geyserId < 0) {
+            throw new IllegalArgumentException("geyser entity id cannot be negative! (got: " + geyserId + ")");
+        }
+        return session.getEntityCache().getEntityByGeyserId(geyserId);
+    }


…tities-api

Copilot

Pull request overview

Copilot reviewed 130 out of 131 changed files in this pull request and generated 1 comment.

💡 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/spawn/EntitySpawnContext.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/EvokerFangsEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/ItemEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/ItemFrameEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/LightningEntity.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/ThrowableEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/ThrowableItemEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/living/ArmorStandEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/living/animal/OcelotEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/living/animal/SnifferEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/living/merchant/VillagerEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/living/monster/CreakingEntity.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/EndermanEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/player/AvatarEntity.java # core/src/main/java/org/geysermc/geyser/entity/type/player/SessionPlayerEntity.java # core/src/main/java/org/geysermc/geyser/entity/vehicle/BoatVehicleComponent.java # core/src/main/java/org/geysermc/geyser/entity/vehicle/VehicleComponent.java # core/src/main/java/org/geysermc/geyser/inventory/holder/BlockInventoryHolder.java # core/src/main/java/org/geysermc/geyser/level/physics/CollisionManager.java # core/src/main/java/org/geysermc/geyser/session/cache/BlockBreakHandler.java # core/src/main/java/org/geysermc/geyser/session/cache/BossBar.java # core/src/main/java/org/geysermc/geyser/session/cache/WorldBorder.java # core/src/main/java/org/geysermc/geyser/translator/inventory/chest/DoubleChestInventoryTranslator.java # core/src/main/java/org/geysermc/geyser/translator/level/event/PlaySoundEventTranslator.java # core/src/main/java/org/geysermc/geyser/translator/protocol/bedrock/BedrockInventoryTransactionTranslator.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/bedrock/entity/player/input/BedrockPlayerAuthInputTranslator.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/JavaPlayerLookAtTranslator.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/main/java/org/geysermc/geyser/translator/protocol/java/level/JavaLevelParticlesTranslator.java # core/src/main/java/org/geysermc/geyser/util/InventoryUtils.java

…nto feature/custom-entities-api

Copilot

Pull request overview

Copilot reviewed 101 out of 102 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/ItemEntity.java:127

ItemEntity's offset field is updated inside the setOffset override, but moveAbsoluteImmediate uses this.offset as the base offset and then calls setOffset again (including with a negated value when in water). This means that once the offset is negated, the next tick in water will negate it again, causing the entity to flip offset every tick. Keep an immutable/base offset (e.g., from the entity type/initial context) and only apply the temporary sign change to the Bedrock offset without overwriting the base.

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

Copilot · 2026-03-28T20:53:56Z

+    public EntitySpawnContext(GeyserSession session, EntityTypeDefinition<?> definition, int javaId, UUID uuid, BedrockEntityDefinition bedrockEntityDefinition, Vector3f position,
+                              Vector3f motion, float yaw, float pitch, float headYaw, float offset, @Nullable Long geyserId) {
        this.session = session;
        this.entityTypeDefinition = definition;
        this.javaId = javaId;
        this.uuid = uuid;
        this.position = position;
        this.offset = definition.offset();
+        this.bedrockEntityDefinition = bedrockEntityDefinition;
        this.motion = motion;


EntitySpawnContext's constructor accepts an offset parameter but ignores it and always assigns this.offset = definition.offset();. This makes it impossible to override the per-spawn offset (e.g., for event-driven/custom entity adjustments) and contradicts the call sites that pass an explicit offset value. Use the provided offset parameter when assigning this.offset (and ensure the other constructors pass the intended value).

…tities-api # Conflicts: # core/src/main/java/org/geysermc/geyser/entity/VanillaEntities.java

…tities-api

Copilot

Pull request overview

Copilot reviewed 95 out of 96 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-04-24T00:00:00Z

    protected void moveAbsoluteImmediate(Vector3f position, float yaw, float pitch, float headYaw, boolean isOnGround, boolean teleported) {
-        float offset = definition.offset();
+        float offset = this.offset;
        if (waterLevel.join() == 0) { // Item is in a full block of water
            // Move the item entity down so it doesn't float above the water
-            offset = -definition.offset();
+            offset = -this.offset;
        }
        setOffset(offset);
        super.moveAbsoluteImmediate(position, 0, 0, 0, isOnGround, teleported);


moveAbsoluteImmediate uses this.offset as the base offset and then calls setOffset(offset), which mutates this.offset. Once the item enters water and the offset is negated, the stored offset stays negative and won't reset when the item leaves water. Consider keeping an immutable/base offset (e.g., from the entity type definition) and computing the water adjustment from that, instead of reusing the mutable offset field.

Copilot · 2026-04-24T00:00:00Z

    protected final GeyserDirtyMetadata dirtyMetadata = new GeyserDirtyMetadata();
+    /**
+     * A container storing all current metadata for an entity.
+     */
+    // TODO only store what is needed for API
+    protected final Map<EntityDataType<?>, Object> metadata = new Object2ObjectLinkedOpenHashMap<>();
+


metadata is introduced as the source of truth for GeyserEntity#value(...), but nothing in this class ever writes to it (all updates go to dirtyMetadata and then get cleared on apply(...)). As a result, value(...) will always return null/stale values for data types backed by EntityDataTypes (e.g., color/variant/hitboxes). Consider updating metadata whenever a metadata field is changed (e.g., a helper that writes to both dirtyMetadata and metadata, or extending GeyserDirtyMetadata to also persist applied entries).

Copilot

Pull request overview

Copilot reviewed 96 out of 97 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:456

The new metadata map is used by the Custom Entity API (GeyserEntityDataImpl.value() reads from entity.getMetadata()), but spawnEntity()/updateBedrockMetadata() only apply dirtyMetadata to outgoing packets and never persist those values into this.metadata. As a result, GeyserEntity#value(...) will always return null for data backed by EntityDataTypes (and list types like hitboxes).

Persist applied dirty metadata into this.metadata (and keep it in sync on subsequent updates), e.g., by merging the dirty entries into metadata before/while clearing them.

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

Copilot · 2026-04-27T01:19:43Z

        attachedBlocks.forEach((blockPos, state) -> {
            blockPos = blockPos.add(movement);
            // Don't place blocks that collide with the player
            if (!SOLID_BOUNDING_BOX.checkIntersection(blockPos.toDouble(), playerBoundingBox)) {
-                ChunkUtils.updateBlock(session, state, blockPos);
+                ChunkUtils.updateBlock(session, session.getGeyser().getWorldManager().blockAt(session, blockPos), blockPos);
            }


placeFinalBlocks() iterates attachedBlocks.forEach((blockPos, state) -> ...), but the final block placement ignores state and instead re-reads the current world state via worldManager().blockAt(...). This will typically re-place the moving block/air (or whatever is currently there), not the intended final pushed block state.

Use the state from attachedBlocks when calling ChunkUtils.updateBlock(...) so the piston finalization places the correct block.

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

Copilot started reviewing on behalf of onebeastchris March 14, 2026 19:43 View session

Copilot AI reviewed Mar 14, 2026

View reviewed changes

onebeastchris added 2 commits March 15, 2026 15:38

Improve height / width handling

d9e0c6b

This will be later reworked to allow setting a height + width combo that accounts for the entity pose. For now, it's a general override

Allow custom height / width to be 0

a21d9e8

Copilot AI review requested due to automatic review settings March 15, 2026 16:36

Copilot started reviewing on behalf of onebeastchris March 15, 2026 16:36 View session

Copilot AI reviewed Mar 15, 2026

View reviewed changes

onebeastchris added 3 commits March 20, 2026 21:49

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

61fbc7a

…tities-api

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

93ddfc7

…tities-api

Likely fix entity registration

34b1d98

Copilot AI review requested due to automatic review settings March 20, 2026 23:07

Copilot started reviewing on behalf of onebeastchris March 20, 2026 23:08 View session

Copilot AI reviewed Mar 20, 2026

View reviewed changes

Comment thread core/src/main/java/org/geysermc/geyser/entity/type/player/SessionPlayerEntity.java

onebeastchris added 3 commits March 26, 2026 14:35

Merge branch 'master' into feature/custom-entities-api

ee0a40a

Merge remote-tracking branch 'upstream/feature/custom-entities-api' i…

ee610d3

…nto feature/custom-entities-api

Copilot AI review requested due to automatic review settings March 28, 2026 20:50

Copilot started reviewing on behalf of onebeastchris March 28, 2026 20:50 View session

Copilot AI reviewed Mar 28, 2026

View reviewed changes

onebeastchris added 3 commits April 10, 2026 22:23

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

427a00b

…tities-api # Conflicts: # core/src/main/java/org/geysermc/geyser/entity/VanillaEntities.java

Reduce diff, fix issue related to odd entity movement

ed4e0c6

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

304a294

…tities-api

Copilot AI review requested due to automatic review settings April 23, 2026 23:52

Copilot started reviewing on behalf of onebeastchris April 23, 2026 23:52 View session

Copilot AI reviewed Apr 24, 2026

View reviewed changes

onebeastchris added 2 commits April 27, 2026 03:11

Work around pistons creating ghost blocks

f7b6ae8

Merge branch 'master' into feature/custom-entities-api

781e08c

Copilot AI review requested due to automatic review settings April 27, 2026 01:14

Copilot started reviewing on behalf of onebeastchris April 27, 2026 01:14 View session

Copilot AI reviewed Apr 27, 2026

View reviewed changes

		GeyserImpl.getInstance().getLogger().debug("Client %s tried to request pack with an invalid id %s)",
		session.bedrockUsername(), id);

Uh oh!

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

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 28, 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 Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 24, 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 Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

onebeastchris commented Nov 25, 2025 •

edited

Loading