feat: add onEndermanTakeBlock event [#233] (#283)

Author: zimuya4153

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Added onEndermanTakeBlock event [#233] @zimuya4153
+
 ## [0.11.2] - 2025-06-01
 
 ### Fixed
@@ -906,6 +910,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#226]: https://github.com/LiteLDev/LegacyScriptEngine/issues/226
 [#227]: https://github.com/LiteLDev/LegacyScriptEngine/issues/227
 [#231]: https://github.com/LiteLDev/LegacyScriptEngine/issues/231
+[#233]: https://github.com/LiteLDev/LegacyScriptEngine/issues/233
 [#236]: https://github.com/LiteLDev/LegacyScriptEngine/issues/236
 [#240]: https://github.com/LiteLDev/LegacyScriptEngine/issues/240
 [#242]: https://github.com/LiteLDev/LegacyScriptEngine/issues/242

docs/apis/EventAPI/EntityEvents.md

@@ -246,3 +246,19 @@ hooks).
 Note: This event is triggered when the `TransformationComponent` of the entity in `Addons` is activated, and is mostly
 used for the interaction between the engine and the Addon. Only `UniqueId` is provided since the entity pointer before
 the transition is destroyed quickly.
+
+#### `"onEndermanTakeBlock"` - Enderman Take Block Event
+
+!!! warning
+    This event is only available in 0.11.3 and later versions.
+
+- Listener function prototype
+  `function(entity, block, pos)`
+- Parameters
+    - entity : `Entity`  
+      Enderman entity.
+    - block : `Block`  
+      Pick up the Block
+    - pos : `BlockPos`  
+      The coordinates of the block.
+- Intercept events: function returns `false`

docs/apis/EventAPI/EntityEvents.zh.md

@@ -255,3 +255,20 @@ ActorDamageCause 为伤害原因枚举，枚举值如下，有问号的待验证
 
 注：此事件为 `Addons` 中实体的 `TransformationComponent` 激活时触发，多用于引擎与Addon交互。由于转变前的实体指针很快被销毁，因此只提供
 `UniqueId`。
+
+
+#### `"onEndermanTakeBlock"` - 末影人搬运方块
+
+!!! warning
+    此事件仅在0.11.3及更高版本中可用。
+
+- 监听函数原型
+  `function(entity, block, pos)`
+- 参数：
+    - entity : `Entity`  
+      搬运方块的末影人
+    - block : `Block`  
+      被搬运的方块
+    - pos : `BlockPos`  
+      被搬运的方块坐标
+- 拦截事件：函数返回`false`

src/legacy/api/EventAPI.cpp

@@ -738,6 +738,9 @@ void EnableEventListener(int eventId) {
     case EVENT_TYPES::onNpcCmd:
         lse::events::entity::NpcCommandEvent();
         break;
+    case EVENT_TYPES::onEndermanTakeBlock:
+        lse::events::entity::EndermanTakeBlockEvent();
+        break;
     default:
         break;
     }

src/legacy/api/EventAPI.h

@@ -73,6 +73,7 @@ enum class EVENT_TYPES : int {
     onMobTrySpawn,
     onMobSpawned,
     onNpcCmd,
+    onEndermanTakeBlock,
     /* Block Events */
     onBlockInteracted,
     onBlockChanged,

src/lse/events/EntityEvents.cpp

@@ -370,6 +370,44 @@ LL_TYPE_INSTANCE_HOOK(
     origin(originalActor, transformed, transformation, ownerID, level);
 }
 
+LL_TYPE_INSTANCE_HOOK(
+    ActorDestroyBlockEventHook,
+    HookPriority::Normal,
+    ActorEventCoordinator,
+    &ActorEventCoordinator::sendEvent,
+    CoordinatorResult,
+    EventRef<ActorGameplayEvent<CoordinatorResult>> const& event
+)
+try {
+    return event.get().visit([&](auto&& arg) {
+        if constexpr (std::is_same_v<std::decay_t<decltype(arg)>, Details::ValueOrRef<ActorGriefingBlockEvent const>>) {
+            auto& griefingEvent = arg.value();
+
+            if (auto entity = griefingEvent.mActorContext->tryUnwrap(); entity && entity->isType(ActorType::EnderMan)) {
+                IF_LISTENED(EVENT_TYPES::onEndermanTakeBlock) {
+                    if (!CallEvent(
+                            EVENT_TYPES::onEndermanTakeBlock,
+                            EntityClass::newEntity(entity.as_ptr()),
+                            BlockClass::newBlock(
+                                *griefingEvent.mBlock,
+                                BlockPos(griefingEvent.mPos),
+                                entity->getDimensionId()
+                            ),
+                            IntPos::newPos(BlockPos(griefingEvent.mPos), entity->getDimensionId())
+                        )) {
+                        return CoordinatorResult::Cancel;
+                    }
+                }
+                IF_LISTENED_END(EVENT_TYPES::onEndermanTakeBlock);
+            }
+            return CoordinatorResult::Continue;
+        }
+        return origin(event);
+    });
+} catch (...) {
+    return origin(event);
+}
+
 void ProjectileSpawnEvent() {
     ProjectileSpawnHook1::hook();
     ProjectileSpawnHook2::hook();
@@ -385,6 +423,7 @@ void MobHurtEvent() {
     MobHurtEffectHook::hook();
 }
 void NpcCommandEvent() { NpcCommandHook::hook(); }
+void EndermanTakeBlockEvent() { ActorDestroyBlockEventHook::hook(); }
 void EffectUpdateEvent() { EffectUpdateHook::hook(); }
 void TransformationEvent() { TransformationHook::hook(); }
 } // namespace lse::events::entity

src/lse/events/EntityEvents.h

@@ -9,6 +9,7 @@ void ProjectileHitEntityEvent();
 void ProjectileHitBlockEvent();
 void MobHurtEvent();
 void NpcCommandEvent();
+void EndermanTakeBlockEvent();
 void EffectUpdateEvent();
 void TransformationEvent();
 } // namespace lse::events::entity