Active Item API

[sovdeeth]

Description

This PR adds syntaxes that supports getting and interacting with a living entity's active item.
Active items are those that have non-instant actions when used, like drawing a bow, eating food, blocking with a shield, or loading a crossbow.

Syntax added:

• CondIsHandRaised: Adds a condition to check if the main hand, off hand, or both hands of the entity are raised, ie: doing something.
• ExprActiveItem: An expression that returns the item that an entity is currently using. It returns 0 air if nothing is being used. Currently, this returns an itemstack and therefore cannot be set. However, I have considered instead returning the slot that's being used, which would allow setting. I'd like opinions on this, as I don't know if setting an active item really makes sense, but at the same time it would be useful as the user would not have to check which hand is being used before using ExprTool to set it.
• ExprEntityItemUseTime: An expression that returns either the amount of time that an entity has been using something, or the amount of time that they have left before the item use is complete (eg: finishing drinking the potion). Items that don't have an end state (drawing a bow, blocking) have a use time of 1 hour, for some reason. The crossbow has a set use time, but once the loading finishes, continuing to hold the mouse button results in the elapsed use time increasing, but the remaining time to be 0 seconds. I think this behavior is fine.
• ExprMaxItemUseTime: An expression that returns the max use time of an item, if it exists. For crossbows this is 1.4s by default, 1.6s for potions, and 1hr for bows and shields.
• EffCancelItemUse: An effect that interrupts any usage the entity is currently doing. ex: cancelling a bow draw, eating food, etc.
• ExprReadiedArrow: an expression to get the arrow or bow used in a PlayerReadyArrow event.
• Added PlayerReadyArrow event and PlayerStopUsingItem event.

---

Target Minecraft Versions: 1.12+
Requirements: Paper 1.12.2+, EffCancelItemUse requires Paper 1.16.5+
Related Issues: #4185

[AyhamAl-Ali]

Tud stole my suggestions while I was lazy reviewing 😂 jk.
Nice PR ⚡

[AyhamAl-Ali]

Hi again ⚡

I accidentally left this as comment instead of change request, but it's a change request

[AyhamAl-Ali]

Building is failing due to my recent reviews not including braces due to the change of using a list inside Annotations.
Just wrap the values with braces

@Description({
    "",
    ""
})

[sovdeeth]

Building is failing due to my recent reviews not including braces due to the change of using a list inside Annotations. Just wrap the values with braces

Yeah I just wanted to batch commit, it'll be fixed when i push the commit w/ updated import and version requirement :)

[TheLimeGlass]

May also be worth adding these events as it's related to the expressions
https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/player/PlayerItemConsumeEvent.html
https://jd.papermc.io/paper/1.19/com/destroystokyo/paper/event/player/PlayerReadyArrowEvent.html
https://jd.papermc.io/paper/1.19/io/papermc/paper/event/player/PlayerStopUsingItemEvent.html

[sovdeeth]

May also be worth adding these events as it's related to the expressions https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/player/PlayerItemConsumeEvent.html https://jd.papermc.io/paper/1.19/com/destroystokyo/paper/event/player/PlayerReadyArrowEvent.html https://jd.papermc.io/paper/1.19/io/papermc/paper/event/player/PlayerStopUsingItemEvent.html

Ooh good idea, I'll work on those too.

[sovdeeth]

Waiting on Spigot to fix the PlayerItemConsumeEvent#setItem method (ticket), so I'm going to not include that in this PR and instead leave it for something in the future.

I'm planning on leaving it as ExprConsumedItem instead of a simple event-value for this reason. (returns the consumed item)

[UnderscoreTud]

Looks good!

[APickledWalrus]

looking pretty good!