✨ feat: add tag to check if interaction is hovered

docs/_templates/changelog/v3.0.0.md

@@ -55,6 +55,11 @@
 - <abbr title="Bug Fix">🐛</abbr> **[#320](https://github.com/mcbookshelf/Bookshelf/issues/320)** - Fixed functions that were unusable outside the Overworld.
 
 
+### `🖱️ bs.interaction`
+
+- <abbr title="New Features">✨</abbr> **[#300](https://github.com/mcbookshelf/bookshelf/issues/300)** - Added `bs.interaction.hovered` tag to check if an interaction is currently hovered.
+
+
 ### `🏃 bs.move`
 
 - <abbr title="Breaking Changes">⚠️</abbr> **[#282](https://github.com/mcbookshelf/Bookshelf/issues/282)** - Updated `on_collison` callback: scores now use the `bs.lambda` objective, and the input requires a full command instead of a function path. Additionally, `on_collision/*` functions have been renamed to `callback/*`.

docs/modules/interaction.md

@@ -244,6 +244,42 @@ You can find below all tags available in this API.
 
 ---
 
+### Is Hovered?
+
+**`bs.interaction.hovered`**
+
+Determine if an interaction is currently hovered by a player.
+
+```{note}
+This is useful in `hover_enter` and `hover_leave` events, which are per player. Since `hover_leave` triggers when a player stops hovering but doesn't check if all players have stopped, this tag can be used to determine when every player has left the interaction.
+```
+
+> **Credits**: Aksiome
+
+---
+
+### Is Source?
+
+**`bs.interaction.source`**
+
+Usable only in the callback of an event.
+Determine if the current entity is the source of the event.
+
+> **Credits**: theogiraudet
+
+---
+
+### Is Target?
+
+**`bs.interaction.target`**
+
+Usable only in the callback of an event.
+Determine if the current entity is the target of the event.
+
+> **Credits**: theogiraudet
+
+---
+
 ### Listen to a Specific Event?
 
 :::::{tab-set}
@@ -284,28 +320,6 @@ Determine if the current interaction listen to leave hover interaction.
 
 ---
 
-### Is Source?
-
-**`bs.interaction.source`**
-
-Usable only in the callback of an event.
-Determine if the current entity is the source of the event.
-
-> **Credits**: theogiraudet
-
----
-
-### Is Target?
-
-**`bs.interaction.target`**
-
-Usable only in the callback of an event.
-Determine if the current entity is the target of the event.
-
-> **Credits**: theogiraudet
-
----
-
 <div id="gs-comments" align=center>
 
 **💬 Did it help you?**

modules/bs.interaction/data/bs.interaction/function/on_event/hover/hover.mcfunction

@@ -18,7 +18,7 @@
 
 tag @s add bs.interaction.source
 execute store result storage bs:ctx y int 1 run scoreboard players get @s bs.interaction.id
-execute as @n[type=minecraft:interaction,predicate=bs.interaction:check_id] run tag @s add bs.interaction.target
+execute as @n[type=minecraft:interaction,predicate=bs.interaction:match_id] run tag @s add bs.interaction.target
 $execute unless predicate {"condition":"minecraft:entity_properties","entity":"this","predicate":{"type_specific":{"type":"minecraft:player","looking_at":{"type":"minecraft:interaction","nbt":"{\"Tags\":[\"bs.interaction.target\"]}","distance":{"absolute":{"max":$(y)}}}}}} run return run function bs.interaction:on_event/hover_leave/hover_leave
 execute as @n[type=minecraft:interaction,tag=bs.interaction.target,distance=..24] run function bs.interaction:on_event/hover/as_target
 tag @s remove bs.interaction.source

modules/bs.interaction/data/bs.interaction/function/on_event/hover_enter/as_target.mcfunction

@@ -17,5 +17,6 @@ scoreboard players add @s bs.interaction.hover 1
 scoreboard players add #interaction.active_hover bs.data 1
 execute store result storage bs:ctx y int 1 run scoreboard players operation @p[distance=0,tag=bs.interaction.source] bs.interaction.id = @s bs.interaction.id
 execute if entity @s[tag=bs.interaction.listen_hover_enter] run function bs.interaction:on_event/hover_enter/dispatch with storage bs:ctx
+tag @s add bs.interaction.hovered
 execute if entity @s[tag=bs.interaction.listen_hover] run function bs.interaction:on_event/hover/dispatch with storage bs:ctx
 tag @s remove bs.interaction.target

modules/bs.interaction/data/bs.interaction/function/on_event/hover_leave/as_target.mcfunction

@@ -16,5 +16,6 @@
 tag @s add bs.interaction.target
 scoreboard players remove @s bs.interaction.hover 1
 scoreboard players remove #interaction.active_hover bs.data 1
+execute if score @s bs.interaction.hover matches ..0 run tag @s remove bs.interaction.hovered
 execute if entity @s[tag=bs.interaction.listen_hover_leave] run function bs.interaction:on_event/hover_leave/dispatch with storage bs:ctx
 tag @s remove bs.interaction.target

modules/bs.interaction/data/bs.interaction/function/on_event/hover_leave/try_leave.mcfunction

@@ -15,6 +15,6 @@
 
 execute store result score #i bs.ctx run scoreboard players get @s bs.interaction.hover
 execute store result storage bs:ctx y int 1 run scoreboard players get @s bs.interaction.id
-execute at @s store result score #p bs.ctx if entity @a[distance=..24,predicate=bs.interaction:check_id]
+execute at @s store result score #p bs.ctx if entity @a[distance=..24,predicate=bs.interaction:match_id]
 scoreboard players operation #i bs.ctx -= #p bs.ctx
 execute if score #i bs.ctx matches 1.. run function bs.interaction:on_event/hover_leave/as_target

modules/bs.interaction/data/bs.interaction/test/on_hover_once.mcfunction

@@ -0,0 +1,37 @@
+# ------------------------------------------------------------------------------------------------------------
+# Copyright (c) 2025 Gunivers
+#
+# This file is part of the Bookshelf project (https://github.com/mcbookshelf/Bookshelf).
+#
+# This source code is subject to the terms of the Mozilla Public License, v. 2.0.
+# If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+#
+# Conditions:
+# - You may use this file in compliance with the MPL v2.0
+# - Any modifications must be documented and disclosed under the same license
+#
+# For more details, refer to the MPL v2.0.
+# ------------------------------------------------------------------------------------------------------------
+
+## === SETUP ===
+
+fill ~-1 ~-1 ~-1 ~1 ~1 ~1 minecraft:air replace minecraft:barrier
+summon minecraft:interaction ~.5 ~ ~1.5 {Tags: ["bs.packtest","bs.packtest.1"], width: 1.0, height: 2.0}
+execute as @n[type=minecraft:interaction,tag=bs.packtest,distance=..3] run function #bs.interaction:on_hover_enter { run: "execute unless entity @s[tag=bs.interaction.hovered] run scoreboard players add #packtest.interaction_hover_once bs.data 1", executor: "target" }
+execute as @n[type=minecraft:interaction,tag=bs.packtest,distance=..3] run function #bs.interaction:on_hover_leave { run: "execute unless entity @s[tag=bs.interaction.hovered] run scoreboard players remove #packtest.interaction_hover_once bs.data 1", executor: "target" }
+scoreboard players set #packtest.interaction_hover_once bs.data 0
+
+## === EXPECTED BEHAVIORS ===
+
+execute positioned ~.5 ~ ~.5 run dummy on_hover_once_1 spawn
+await delay 2t
+assert score #packtest.interaction_hover_once bs.data matches 1
+execute positioned ~.5 ~ ~.5 run dummy on_hover_once_2 spawn
+await delay 2t
+assert score #packtest.interaction_hover_once bs.data matches 1
+dummy on_hover_once_2 leave
+await delay 2t
+assert score #packtest.interaction_hover_once bs.data matches 1
+dummy on_hover_once_1 leave
+await delay 2t
+assert score #packtest.interaction_hover_once bs.data matches 0