Unify the useable behaviour

[ErrorCraft]

• Provide the use duration instead of using a static amount.
• Allow for an indefinite use duration in the minecraft:useable behaviour component.
• Migrate the minecraft:use_animation behaviour component to a field in minecraft:useable; It's not behaviour.
  Note: this introduces a discrepancy with the minecraft:start_using_item action, so look at ways to fix that!
• Migrate the other behaviour components and items to use minecraft:useable.
  Examples are minecraft:shooter and minecraft:playable for behaviour components and minecraft:shield for items.
• Introduce useable on block and entity behaviour to minecraft:useable. An example use case is the Brush item being used on blocks instead of being used as-is.
  Note: minecraft:useable_on_fluid should be migrated elsewhere or at least renamed later for consistency, as it involves the item being used on a block once instead of using the item over a duration.

Changes

Behaviour Components

• Removed minecraft:use_animation, which is now part of minecraft:useable instead.
• Modified minecraft:useable.

  • The ticks field now takes a provider instead of a hard amount and is optional too, in which case it will be used indefinitely. The field still allows a direct constant amount, just like before. Its value for a specific item stack may be overwritten with the new minecraft:use_duration data component as well now.
    Examples:
    Constant duration, same as the previous method.

     {
       "minecraft:useable": {
         "ticks": 10
       }
     }

    Indefinite duration.

     {
       "minecraft:useable": {}
     }

    Constant duration as a provider. See the Integer Providers section below for more information.

     {
       "minecraft:useable": {
         "ticks": {
           "type": "minecraft:constant",
           "amount": 10
         }
       }
     }

  • Moved the value from minecraft:use_animation to this component in the optional animation field. If not specified, will use none. Its value for a specific item stack may be overwritten with the new minecraft:use_animation data component as well now.
    So if you had this:

     {
       "minecraft:use_animation": "eat",
       "minecraft:useable": {
         "ticks": 32
       }
     }

    You now have to use this instead:

     {
       "minecraft:useable": {
         "animation": "eat",
         "ticks": {
           "type": "minecraft:constant",
           "amount": 32
         }
       }
     }

  • Added an optional passes field, which is a list of strings that allows its user to start using the item given a certain context.

    • normal: Allows the user to start using the item as-is.
    • block: Allows the user to start using the item when used on a block.
    • entity: Allows the user to start using the item when used on an entity.

    Its default value is ["normal"].
    Example:

     {
       "minecraft:useable": {
         "passes": [
           "block"
         ],
         "ticks": {
           "type": "minecraft:constant",
           "amount": 200
         }
       }
     }

• Modified minecraft:shooter.
  • This behaviour component no longer makes its user start using the item on its own and now requires minecraft:useable. An integer provider named minecraft:shooter was added that can be used in its place. See the Integer Providers section below for more information. Additionally, the ammunition and held_ammunition fields are now registry entry lists and thus require an additional # prefix to use a tag. They are also now modifiable on specific item stacks via the minecraft:shooter_ammunition and minecraft:shooter_held_ammunition data components respectively.
    So if you had this:

     {
       "minecraft:shooter": {
         "ammunition": "minecraft:bow_ammunition",
         "held_ammunition": "minecraft:bow_ammunition",
         "range": 15
       }
     }

    You now have to use this instead:

     {
       "minecraft:shooter": {
         "ammunition": "#minecraft:bow_ammunition",
         "held_ammunition": "#minecraft:bow_ammunition",
         "range": 15
       }
     }

    Examples:

     {
       "minecraft:shooter": {
         "ammunition": "#minecraft:bow_ammunition",
         "held_ammunition": "#minecraft:bow_ammunition",
         "range": 15
       },
       "minecraft:useable": {
         "ticks": {
           "type": "minecraft:shooter"
         }
       }
     }

     {
       "minecraft:shooter": {
         "ammunition": "#minecraft:bow_ammunition",
         "chargeable": {
           "quick_charge_sounds": {
             "default": "minecraft:item.crossbow.loading_start",
             "levels": [
               "minecraft:item.crossbow.quick_charge_1",
               "minecraft:item.crossbow.quick_charge_2",
               "minecraft:item.crossbow.quick_charge_3"
             ]
           }
         },
         "held_ammunition": "#minecraft:crossbow_ammunition",
         "range": 8
       },
       "minecraft:useable": {
         "ticks": {
           "type": "minecraft:shooter"
         }
       }
     }

• Modified minecraft:throwable.
  • Removed the use_riptide_check field as this is now part of an integer provider named minecraft:trident instead, which can be used in its place in minecraft:useable.
  • This also means that the component no longer makes its user start using the item on its own when the draw_duration field is specified and now requires minecraft:useable. The draw_duration field is now only used to check whether its user has been using the item for the specified duration when they stop using the item.

Data Components

• Added minecraft:use_duration.
  • This data component is specified and used by the minecraft:useable behaviour component. If this data component is removed, the minecraft:useable behaviour will no longer work. The format is the same as the map specified in the minecraft:useable behaviour component, with one addition, that being that it allows for a single integer as another shorthand.
    Examples:
    Constant duration, simplest form.

     {
       "minecraft:use_duration": 10
     }

    Constant duration, expanded form.

     {
       "minecraft:use_duration": {
         "ticks": 10
       }
     }

    Indefinite duration.

     {
       "minecraft:use_duration": {}
     }

    Constant duration as a provider. See the Integer Providers section below for more information.

     {
       "minecraft:use_duration": {
         "ticks": {
           "type": "minecraft:constant",
           "amount": 10
         }
       }
     }

• Added minecraft:use_animation.
  • This data component is specified and used by the minecraft:useable behaviour component. If this data component is removed, the none animation will be used instead. Its value is the same one as the one specified previously in the minecraft:use_animation item component.
    Examples:

     {
       "minecraft:use_animation": "eat"
     }

     {
       "minecraft:use_animation": "drink"
     }

• Added minecraft:shooter_ammunition and minecraft:shooter_held_ammunition.
  • This data component is specified and used by the minecraft:shooter behaviour component. If this data component is removed, the minecraft:shooter behaviour will no longer work. Its value is an item, list of items or hash-prefixed item tag.
    Examples:

     "#minecraft:bow_ammunition"

     "#minecraft:crossbow_ammunition"

Integer Providers

These providers are added so the use duration is not hardcoded for specific behaviour components by using different sources. The integer provider type is determined by the type field, and all types are visible further down. An integer provider may return an empty value, in which case the user will not start using the item.

minecraft:constant

Uses the item for a constant duration.

Fields

• amount: A positive integer. How long to use the item for.

Example

{
  "type": "minecraft:constant",
  "amount": 32
}

minecraft:playable

Uses the minecraft:playable item behaviour component to get the use duration from the minecraft:instrument data component or from a default set of instruments as defined by minecraft:playable otherwise.

Example

{
  "type": "minecraft:playable"
}

minecraft:shooter

Uses the minecraft:shooter item behaviour component to use the item indefinitely if the user is either holding ammunition as defined by the minecraft:shooter_held_ammunition data component or has ammunition in their inventory as defined by the minecraft:shooter_ammunition data component.

Example

{
  "type": "minecraft:shooter"
}

minecraft:trident

Uses the item indefinitely if the item stack has the Riptide enchantment and is either not damageable or not in a broken state and if its user is touching water or rain.

Example

{
  "type": "minecraft:trident"
}