✨ init bs.interaction

docs/CHANGELOG.md

@@ -18,13 +18,12 @@ Bookshelf is now based on **Minecraft 1.21.2**.
   - Random distributions: uniform, binomial, geometric, and Poisson.
   - Noise generation functions: white, simplex, and fractal.
   - Random selection of an element from a list.
-
 - **[#6](https://github.com/Gunivers/Bookshelf/issues/6)** Added the `bs.generate` module for terrain generation. Currently supports 2D shape algorithms, enabling texture and heightmap-based terrain generation.
+- **[#222](https://github.com/Gunivers/Bookshelf/issues/193)** Added the `bs.interaction` module, which proposes interactions to listen to different players' events: left click, right click, hover (enter, leave and continuous).
 
 ### ✨ Added features
 
 - **[#222](https://github.com/Gunivers/Bookshelf/issues/222)** Added `#bs.block:fill_random` for filling regions with randomly selected blocks.
-- **[#251](https://github.com/Gunivers/Bookshelf/issues/251)** Enhanced `bs.block` fill functions to accept `from` and `to` inputs as either `[x, y, z]` lists or as stringified coordinates (e.g., `~ ~5 25`).
 - **[#258](https://github.com/Gunivers/Bookshelf/issues/258)** Added `#bs.block:emit_block_particle` to emit block particles in specific locations.
 - **[#245](https://github.com/Gunivers/Bookshelf/issues/245)** Added `piercing` and callback options to `#bs.raycast:run`.
 - **[#203](https://github.com/Gunivers/Bookshelf/issues/203)** Added `#bs.hitbox:is_entity_in_block` and `#bs.hitbox:is_entity_in_blocks` to verify if an entity is within a block.
@@ -35,6 +34,7 @@ Bookshelf is now based on **Minecraft 1.21.2**.
 
 ### 🔁 Tweaks
 
+- **[#251](https://github.com/Gunivers/Bookshelf/issues/251)** Enhanced `bs.block` fill functions to accept `from` and `to` inputs as either `[x, y, z]` lists or as stringified coordinates (e.g., `~ ~5 25`).
 - **[#247](https://github.com/Gunivers/Bookshelf/pull/247)** Improved the default `bs.log` format for clarity.
 - **[#252](https://github.com/Gunivers/Bookshelf/pull/252)** Optimized `bs.hitbox` module for improved performance.
 - **[#265](https://github.com/Gunivers/Bookshelf/pull/265)** Optimized `bs.schedule` module for improved performance.

docs/modules/interaction.md

@@ -12,7 +12,6 @@ Create and manage Graphical User Interfaces (GUIs) in Minecraft.
 
 The Interaction API is a low-level API to create GUIs based on the [Interaction](https://minecraft.wiki/w/Interaction) entity.
 This API is low level since the possible events are directly and manually bind to the interaction.
-In this API, the interaction that listen to events is named **listener**.
 
 ---
 
@@ -26,10 +25,10 @@ You can find below all functions available in this API.
 
 ```{function} #bs.interaction:clear_events
 
-Clear events registered for the specified listener entity.
+Clear events registered for the specified interaction entity.
 
 :Inputs:
-  **Execution `as <entity>`**: Listener entity for which the events will be cleared.
+  **Execution `as <entity>`**: Interaction entity for which the events will be cleared.
 
   **Function Macro**:
   :::{treeview}
@@ -42,18 +41,18 @@ Clear events registered for the specified listener entity.
 :Outputs:
   **Return**: The number of events removed.
 
-  **State**: The specified events for the listener entity will be removed.
+  **State**: The specified events for the interaction entity will be removed.
 ```
 
-*Clear hover events for the listener entity:*
+*Clear hover events for the interaction entity:*
 
 ```mcfunction
 summon minecraft:interaction ~ ~ ~ { Tags: ["bs.entity.interaction"], width: 1f, height: 1f }
 
-# Register hover events for the listener
+# Register hover events for the interaction
 execute as @n[tag=bs.entity.interaction] run function #bs.interaction:on_hover { run: "say Hovered", executor: "target" }
 
-# Clear hover events for the listener
+# Clear hover events for the interaction
 execute as @n[tag=bs.entity.interaction] run function #bs.interaction:clear_events { with: { type: "hover" } }
 ```
 
@@ -68,153 +67,177 @@ execute as @n[tag=bs.entity.interaction] run function #bs.interaction:clear_even
 
 ```{function} #bs.interaction:on_left_click
 
-Register a command to run when the left click is pressed on the current listener.
-Each listener can respond to multiple events.
+Register a command to run when the left click is pressed on the current interaction.
+Each interaction can respond to multiple events.
 
 :Inputs:
-  **Execution `as <entity>`**: Listener entity for which the event is registered.
+  **Execution `as <entity>`**: Interaction entity for which the event is registered.
 
   **Function macro**:
   :::{treeview}
   - {nbt}`compound` Arguments
     - {nbt}`string` **run**: Command to execute upon left-click.
-    - {nbt}`string` {nbt}`compound` **executor**: Defines the entity on which the command will be executed. Can be either **"source"** for the player who performed the action or **"target"** for the listener entity itself. A compound can also be used to target other entities:
+    - {nbt}`string` {nbt}`compound` **executor**: Defines the entity on which the command will be executed. Can be either **"source"** for the player who performed the action or **"target"** for the interaction entity itself. A compound can also be used to target other entities:
       - {nbt}`string` **selector**: Specifies entities for the command execution (`execute as <entity>`).
       - {nbt}`bool` **lazy**: Determines whether to resolve the selector immediately (`false`) or at runtime (`true`, default). If `false`, the selector must target only one entity, replacing the selector with that entity’s UUID. Useful for optimizing execution, especially when targeting graphical representations. If multiple entities are targeted, the first one is selected.
   :::
 
 :Outputs:
   **Return**: The ID of the created event.
 
-  **State**: The listener will trigger the event when left clicked.
+  **State**: The interaction will trigger the event when left clicked.
 ```
 ::::
 ::::{tab-item} Right click
 
 ```{function} #bs.interaction:on_right_click
 
-Register a command to run when the right click is pressed on the current listener.
-Each listener can respond to multiple events.
+Register a command to run when the right click is pressed on the current interaction.
+Each interaction can respond to multiple events.
 
 :Inputs:
-  **Execution `as <entity>`**: Listener entity for which the event is registered.
+  **Execution `as <entity>`**: Interaction entity for which the event is registered.
 
   **Function Macro**:
   :::{treeview}
   - {nbt}`compound` **Arguments**:
     - {nbt}`string` **run**: Command to execute upon right-click.
-    - {nbt}`string` {nbt}`compound` **executor**: Defines the entity on which the command will be executed. Can be either **"source"** for the player who performed the action or **"target"** for the listener entity itself. A compound can also be used to target other entities:
+    - {nbt}`string` {nbt}`compound` **executor**: Defines the entity on which the command will be executed. Can be either **"source"** for the player who performed the action or **"target"** for the interaction entity itself. A compound can also be used to target other entities:
       - {nbt}`string` **selector**: Specifies entities for the command execution (`execute as <entity>`).
       - {nbt}`bool` **lazy**: Determines whether to resolve the selector immediately (`false`) or at runtime (`true`, default). If `false`, the selector must target only one entity, replacing the selector with that entity’s UUID. Useful for optimizing execution, especially when targeting graphical representations. If multiple entities are targeted, the first one is selected.
   :::
 
 :Outputs:
   **Return**: The ID of the created event.
 
-  **State**: The listener will trigger the event when right clicked.
+  **State**: The interaction will trigger the event when right clicked.
 ```
 ::::
 ::::{tab-item} Hover
 
 ```{function} #bs.interaction:on_hover
 
-Register a command to run continuously while the player is hovering over the listener.
-Each listener can respond to multiple events.
+Register a command to run continuously while the player is hovering over the interaction.
+Each interaction can respond to multiple events.
 
 :Inputs:
-  **Execution `as <entity>`**: Listener entity for which the event is registered.
+  **Execution `as <entity>`**: Interaction entity for which the event is registered.
 
   **Function Macro**:
   :::{treeview}
   - {nbt}`compound` **Arguments**:
-    - {nbt}`string` **run**: Command to execute while hovering over the listener.
-    - {nbt}`string` {nbt}`compound` **executor**: Defines the entity on which the command will be executed. Can be either **"source"** for the player who performed the action or **"target"** for the listener entity itself. A compound can also be used to target other entities:
+    - {nbt}`string` **run**: Command to execute while hovering over the interaction.
+    - {nbt}`string` {nbt}`compound` **executor**: Defines the entity on which the command will be executed. Can be either **"source"** for the player who performed the action or **"target"** for the interaction entity itself. A compound can also be used to target other entities:
       - {nbt}`string` **selector**: Specifies entities for the command execution (`execute as <entity>`).
       - {nbt}`bool` **lazy**: Determines whether to resolve the selector immediately (`false`) or at runtime (`true`, default). If `false`, the selector must target only one entity, replacing the selector with that entity’s UUID. Useful for optimizing execution, especially when targeting graphical representations. If multiple entities are targeted, the first one is selected.
   :::
 
 :Outputs:
   **Return**: The ID of the created event.
 
-  **State**: The listener will trigger the event continuously while hovered over.
+  **State**: The interaction will trigger the event continuously while hovered over.
 ```
 ::::
 ::::{tab-item} Enter hover
 
 ```{function} #bs.interaction:on_hover_enter
 
-Register a command to run once when the player begins hovering over the listener.
-Each listener can respond to multiple events.
+Register a command to run once when the player begins hovering over the interaction.
+Each interaction can respond to multiple events.
 
 :Inputs:
-  **Execution `as <entity>`**: Listener entity for which the event is registered.
+  **Execution `as <entity>`**: Interaction entity for which the event is registered.
 
   **Function Macro**:
   :::{treeview}
   - {nbt}`compound` **Arguments**:
     - {nbt}`string` **run**: Command to execute when hovering begins.
-    - {nbt}`string` {nbt}`compound` **executor**: Defines the entity on which the command will be executed. Can be either **"source"** for the player who performed the action or **"target"** for the listener entity itself. A compound can also be used to target other entities:
+    - {nbt}`string` {nbt}`compound` **executor**: Defines the entity on which the command will be executed. Can be either **"source"** for the player who performed the action or **"target"** for the interaction entity itself. A compound can also be used to target other entities:
       - {nbt}`string` **selector**: Specifies entities for the command execution (`execute as <entity>`).
       - {nbt}`bool` **lazy**: Determines whether to resolve the selector immediately (`false`) or at runtime (`true`, default). If `false`, the selector must target only one entity, replacing the selector with that entity’s UUID. Useful for optimizing execution, especially when targeting graphical representations. If multiple entities are targeted, the first one is selected.
   :::
 
 :Outputs:
   **Return**: The ID of the created event.
 
-  **State**: The listener will trigger the event once upon hover entry.
+  **State**: The interaction will trigger the event once upon hover entry.
 ```
 ::::
 ::::{tab-item} Leave hover
 
 ```{function} #bs.interaction:on_hover_leave
 
-Register a command to run once when the player stops hovering over the listener.
-Each listener can respond to multiple events.
+Register a command to run once when the player stops hovering over the interaction.
+Each interaction can respond to multiple events.
 
 :Inputs:
-  **Execution `as <entity>`**: Listener entity for which the event is registered.
+  **Execution `as <entity>`**: Interaction entity for which the event is registered.
 
   **Function Macro**:
   :::{treeview}
   - {nbt}`compound` **Arguments**:
     - {nbt}`string` **run**: Command to execute when hovering ends.
-    - {nbt}`string` {nbt}`compound` **executor**: Defines the entity on which the command will be executed. Can be either **"source"** for the player who performed the action or **"target"** for the listener entity itself. A compound can also be used to target other entities:
+    - {nbt}`string` {nbt}`compound` **executor**: Defines the entity on which the command will be executed. Can be either **"source"** for the player who performed the action or **"target"** for the interaction entity itself. A compound can also be used to target other entities:
       - {nbt}`string` **selector**: Specifies entities for the command execution (`execute as <entity>`).
       - {nbt}`bool` **lazy**: Determines whether to resolve the selector immediately (`false`) or at runtime (`true`, default). If `false`, the selector must target only one entity, replacing the selector with that entity’s UUID. Useful for optimizing execution, especially when targeting graphical representations. If multiple entities are targeted, the first one is selected.
   :::
 
 :Outputs:
   **Return**: The ID of the created event.
 
-  **State**: The listener will trigger the event once upon hover exit.
+  **State**: The interaction will trigger the event once upon hover exit.
 ```
 
 
 ```{admonition} Edge case
 :class: warning
 
-If a player logs out while hovering over the listener, the hover leave event will trigger on the executor. If the executor is the player, the event won’t be triggered again when they log back in. Be sure to account for this edge case and handle it appropriately when the player returns.
+If a player logs out while hovering over the interaction, the hover leave event will trigger on the executor. If the executor is the player, the event won’t be triggered again when they log back in. Be sure to account for this edge case and handle it appropriately when the player returns.
 ```
 
 ::::
 :::::
 
-*Glow the listener's icon while the listener is hovered and unglow it when it is not hovered anymore:*
+*Glow the interaction's icon while the interaction is hovered and unglow it when it is not hovered anymore:*
 
 ```mcfunction
 summon minecraft:interaction ~ ~ ~ { Tags: ["bs.entity.interaction"], width: 1f, height: 1f }
 summon block_display ~-.5 ~ ~-.5 { Tags: ["bs.entity.block_display"], width: 1f, height: 1f, block_state: { Name: "minecraft:slime_block" }}
 
-# Callback to glow the icon when the listener is hovered
+# Callback to glow the icon when the interaction is hovered
 execute as @n[tag=bs.entity.interaction] run function #bs.interaction:on_hover_enter { run: "function #bs.interaction:callback/glow", executor: { selector: "@e[tag=bs.entity.block_display]", lazy: false } }
-# Callback to unglow the icon when the listener is not hovered anymore
+# Callback to unglow the icon when the interaction is not hovered anymore
 execute as @n[tag=bs.entity.interaction] run function #bs.interaction:on_hover_leave { run: "function #bs.interaction:callback/unglow", executor: { selector: "@e[tag=bs.entity.block_display]", lazy: false } }
 ```
 
 > **Credits**: Aksiome, theogiraudet
 
 ---
 
+### Default callbacks
+
+:::::{tab-set}
+::::{tab-item} Glow
+**`#bs.interaction:callback/glow`**
+
+Makes the target entity glow.
+::::
+
+::::{tab-item} Unglow
+**`#bs.interaction:callback/unglow`**
+
+Removes the glow effect from the target entity.
+::::
+
+::::{tab-item} None
+**`#bs.interaction:callback/none`**
+
+An empty callback that does nothing. May be used as a placeholder or to explicitly indicate that no action should occur.
+::::
+:::::
+
+---
+
 ## 🏷️ Entity Tags
 
 You can find below all tags available in this API.
@@ -229,31 +252,31 @@ You can find below all tags available in this API.
 **`bs.interaction.listen_right_click`**
 
 
-Determine if the current listener listen to right click interaction.
+Determine if the current interaction listen to right click interaction.
 ::::
 ::::{tab-item} Left click
 
 **`bs.interaction.listen_left_click`**
 
-Determine if the current listener listen to left click interaction.
+Determine if the current interaction listen to left click interaction.
 ::::
 ::::{tab-item} Hover
 
 **`bs.interaction.listen_hover`**
 
-Determine if the current listener listen to hover interaction.
+Determine if the current interaction listen to hover interaction.
 ::::
 ::::{tab-item} Enter hover
 
 **`bs.interaction.listen_hover_enter`**
 
-Determine if the current listener listen to enter hover interaction.
+Determine if the current interaction listen to enter hover interaction.
 ::::
 ::::{tab-item} Leave hover
 
 **`bs.interaction.listen_hover_leave`**
 
-Determine if the current listener listen to leave hover interaction.
+Determine if the current interaction listen to leave hover interaction.
 ::::
 :::::