feat: added a item damage event

[maxencelobry]

Introduction

At the moment, when we want to modify the durability of an item, we have to override items

But overriding items can be inconvenient in several cases (sometimes)

The event here allows you to change the durability of items when they are damaged, but could be even more developed (for example, to modify durability via a position where the item is in use)

If you need more questions or additions to the event to be "more relevant", ask me

[xRookieFight]

pmmp/PocketMine-MP#2330 (comment)

[maxencelobry]

Reworked the implementation to provide proper context to ItemDamageEvent

The event now exposes the damage cause, holder/user, target, inventory and slot in addition to the damage and Unbreaking reduction. Core durability changes now pass context from the higher-level code where it is available, while applyDamage() remains available for direct plugin usage

onAttackEntity() and onDestroyBlock() signatures were kept unchanged for backwards compatibility; contextual wrappers are used instead

This addresses the main limitation of the previous implementation: listeners can now determine not only that an item was damaged, but also how, where and by whom it was damaged

(btw, dylan originally asked me to add this pmmp/PocketMine-MP#6240 (comment))

[maxencelobry]

The implementation was also tested in-game with a simple plugin listening to ItemDamageEvent, and the different durability paths, event cancellation and custom durability changes all worked as expected

[xRookieFight]

I think Dylan's comment on this before is really necessary. I'll leave it to another maintainers but my strongly opinion is this event shouldn't exist or should get a better usage. There always could be a item damage cause addition in future. This means maintaining the cause constants would be a pain in future too. Leaving to other maintainers for their reviews.

[maxencelobry]

I actually added item damage causes in the latest revision of the PR, precisely to address this concern.

I understand the maintenance concern around adding new cause constants over time, but I still think the event itself is useful. One of the main use cases is allowing plugins to implement items with custom durability behaviour while still going through PocketMine's normal durability logic instead of having to replace or duplicate it.

For example, this is something I've already had to implement manually in one of my projects by extending/reworking the durability logic:

https://github.com/nitrofaction/kitmap/blob/main/src/item/Durable.php

and then handling the custom behaviour separately here:

https://github.com/nitrofaction/kitmap/blob/80cde4fdc626de0287247d3ad1ab523242bc43a5/src/listener/EventListener.php#L570

Having ItemDamageEvent in the core makes this kind of use case much cleaner: plugins can modify/cancel durability damage and Unbreaking reduction while still respecting PocketMine's existing item durability flow.

The new implementation also provides the context that was missing from the original PR (cause, entity, target, inventory and slot), rather than firing a context-less event directly from a low-level method.

[xRookieFight]

Some nits.

Also please remove your unrelated documentation formatting changes. And it would be good if you can add a small protected helper on Block (damageHeldItem(Durable $item, ?Player $player)) and the functions you've replaced to block classes can collapse to one argument.
Also. Every armor hit now fires 4 events, more with thorns I guess. I don't think you can do anything for this. But would be good to do some optimization here.

[maxencelobry]

that's good