Package org.geysermc.geyser.api.event.lifecycle

Interface GeyserDefineEntityPropertiesEvent

All Superinterfaces:
org.geysermc.event.Event
public interface GeyserDefineEntityPropertiesEvent extends org.geysermc.event.Event
Lifecycle event fired during Geyser's startup to allow custom entity properties to be registered for a specific entity type.

Listeners can add new properties for any entity by passing the target entity's identifier (e.g., Identifier.of("player")) to the registration methods. The returned GeyserEntityProperty is used to identify the properties and to update the value of a specific entity instance.

Example usage


 public void onDefine(GeyserDefineEntityPropertiesEvent event) {
     Identifier player = Identifier.of("player");
     GeyserFloatEntityProperty ANIMATION_SPEED =
         event.registerFloatProperty(player, Identifier.of("my_group:animation_speed"), 0.0f, 1.0f, 0.1f);
     GeyserBooleanEntityProperty SHOW_SHORTS =
         event.registerBooleanProperty(player, Identifier.of("my_group:show_shorts"), false);
 }
Retrieving entity instances is possible with the EntityData.entityByJavaId(int) method, or EntityData.playerEntity() for the connection player entity. To update the value of a property on a specific entity, use GeyserEntity.updateProperty(GeyserEntityProperty, Object), or GeyserEntity.updatePropertiesBatched(Consumer) to update multiple properties efficiently at once.

Notes:

  • Default values must fall within the provided bounds.
  • There cannot be more than 32 properties registered per entity type in total
  • properties(Identifier) returns properties registered for the given entity (including those added earlier in the same callback), including vanilla properties.
Since:
2.9.0

  • Method Details

    • properties

      Collection<GeyserEntityProperty<?>> properties(Identifier entityType)
      Returns an unmodifiable view of all properties that have been registered so far for the given entity type. This includes entity properties used for vanilla gameplay, such as those used for creaking animations.
      Parameters:
      entityType - the Java edition entity type identifier
      Returns:
      an unmodifiable collection of registered properties
      Since:
      2.9.0

    • registerFloatProperty

      GeyserFloatEntityProperty registerFloatProperty(Identifier entityType, Identifier propertyIdentifier, float min, float max, @Nullable Float defaultValue)
      Registers a float-backed entity property.
      Parameters:
      entityType - the Java edition entity type identifier
      propertyIdentifier - the unique property identifier
      min - the minimum allowed value (inclusive)
      max - the maximum allowed value (inclusive)
      defaultValue - the default value assigned initially on entity spawn - if null, it will be the minimum value
      Returns:
      the created float property
      Since:
      2.9.0

    • registerFloatProperty

      default GeyserFloatEntityProperty registerFloatProperty(Identifier entityType, Identifier propertyIdentifier, float min, float max)
      Registers a float-backed entity property with a default value set to the minimum value.
      Parameters:
      entityType - the Java edition entity type identifier
      propertyIdentifier - the unique property identifier
      min - the minimum allowed value (inclusive)
      max - the maximum allowed value (inclusive)
      Returns:
      the created float property
      Since:
      2.9.0
      See Also:

    • registerIntegerProperty

      GeyserIntEntityProperty registerIntegerProperty(Identifier entityType, Identifier propertyIdentifier, int min, int max, @Nullable Integer defaultValue)
      Registers an int-backed entity property.
      Parameters:
      entityType - the Java edition entity type identifier
      propertyIdentifier - the unique property identifier
      min - the minimum allowed value (inclusive)
      max - the maximum allowed value (inclusive)
      defaultValue - the default value assigned initially on entity spawn - if null, it will be the minimum value
      Returns:
      the created int property
      Since:
      2.9.0

    • registerIntegerProperty

      default GeyserIntEntityProperty registerIntegerProperty(Identifier entityType, Identifier propertyIdentifier, int min, int max)
      Registers an int-backed entity property with a default value set to the minimum value.
      Parameters:
      entityType - the Java edition entity type identifier
      propertyIdentifier - the unique property identifier
      min - the minimum allowed value (inclusive)
      max - the maximum allowed value (inclusive)
      Returns:
      the created int property
      Since:
      2.9.0

    • registerBooleanProperty

      GeyserBooleanEntityProperty registerBooleanProperty(Identifier entityType, Identifier propertyIdentifier, boolean defaultValue)
      Registers a boolean-backed entity property.
      Parameters:
      entityType - the Java edition entity type identifier
      propertyIdentifier - the unique property identifier
      defaultValue - the default boolean value
      Returns:
      the created boolean property handle
      Since:
      2.9.0

    • registerBooleanProperty

      default GeyserBooleanEntityProperty registerBooleanProperty(Identifier entityType, Identifier propertyIdentifier)
      Registers a boolean-backed entity property with a default of false.
      Parameters:
      entityType - the Java edition entity type identifier
      propertyIdentifier - the unique property identifier
      Returns:
      the created boolean property
      Since:
      2.9.0
      See Also:

    • registerEnumProperty

      <E extends Enum<E>> GeyserEnumEntityProperty<E> registerEnumProperty(Identifier entityType, Identifier propertyIdentifier, Class<E> enumClass, @Nullable E defaultValue)
      Registers a typed enum-backed entity property.

      The enum constants define the allowed values. If defaultValue is null, the first enum value is set as the default.

      Type Parameters:
      E - the enum type
      Parameters:
      entityType - the Java edition entity type identifier
      propertyIdentifier - the unique property identifier
      enumClass - the enum class that defines allowed values
      defaultValue - the default enum value, or null for the first enum value to be the default
      Returns:
      the created enum property
      Since:
      2.9.0
      See Also:

    • registerEnumProperty

      default <E extends Enum<E>> GeyserEnumEntityProperty<E> registerEnumProperty(Identifier entityType, Identifier propertyIdentifier, Class<E> enumClass)
      Registers a typed enum-backed entity property with the first value set as the default.
      Type Parameters:
      E - the enum type
      Parameters:
      entityType - the Java edition entity type identifier
      propertyIdentifier - the unique property identifier
      enumClass - the enum class that defines allowed values
      Returns:
      the created enum property
      Since:
      2.9.0
      See Also:

    • registerEnumProperty

      GeyserStringEnumProperty registerEnumProperty(Identifier entityType, Identifier propertyIdentifier, List<String> values, @Nullable String defaultValue)
      Registers a string-backed "enum-like" entity property where the set of allowed values is defined by the provided list. If defaultValue is null, the first value is used as the default on entity spawn. The default must be one of the values in values.
      Parameters:
      entityType - the Java edition entity type identifier
      propertyIdentifier - the unique property identifier
      values - the allowed string values
      defaultValue - the default string value, or null for the first value to be used
      Returns:
      the created string-enum property
      Since:
      2.9.0
      See Also:

    • registerEnumProperty

      default GeyserStringEnumProperty registerEnumProperty(Identifier entityType, Identifier propertyIdentifier, List<String> values)
      Registers a string-backed "enum-like" entity property with the first value as the default.
      Parameters:
      entityType - the Java edition entity type identifier
      propertyIdentifier - the unique property identifier
      values - the allowed string values
      Returns:
      the created string-enum property handle
      Since:
      2.9.0
      See Also: