💥 refactor!: unify function callback names and internal variables

docs/_static/bookshelf.css

@@ -126,6 +126,11 @@ hr {
   border-top: 1px solid #888;
 }
 
+abbr[title] {
+  text-decoration: none;
+  border-bottom: none;
+}
+
 .bd-content .sd-tab-set>label {
   border-top: none;
 }

docs/_templates/changelog/v3.0.0.md

@@ -23,12 +23,12 @@
 ### `🧱 bs.block`
 
 - <abbr title="New Features">✨</abbr> **[#279](https://github.com/mcbookshelf/Bookshelf/issues/279)** - Added a `#bs.block:play_block_sound` tag for playing block sounds.
-- <abbr title="Bug fix">🐛</abbr> **[#320](https://github.com/mcbookshelf/Bookshelf/issues/320)** - Fixed functions that were unusable outside the Overworld.
+- <abbr title="Bug Fix">🐛</abbr> **[#320](https://github.com/mcbookshelf/Bookshelf/issues/320)** - Fixed functions that were unusable outside the Overworld.
 
 
 ### `🧱 bs.environment`
 
-- <abbr title="Bug fix">🐛</abbr> **[#320](https://github.com/mcbookshelf/Bookshelf/issues/320)** - Fixed functions that were unusable outside the Overworld.
+- <abbr title="Bug Fix">🐛</abbr> **[#320](https://github.com/mcbookshelf/Bookshelf/issues/320)** - Fixed functions that were unusable outside the Overworld.
 
 
 ### `🌱 bs.generate`
@@ -38,27 +38,34 @@
 
 ### `🌱 bs.generation`
 
-- <abbr title="Breaking Changes">⚠️</abbr> **[#296](https://github.com/mcbookshelf/Bookshelf/issues/296)** - Renamed the `bs.generate` module to `bs.generation`.
-  - <abbr title="Breaking Changes">⚠️</abbr> **[#296](https://github.com/mcbookshelf/Bookshelf/issues/296)** - Renamed the `bs.generate:fractal_shape_2d` function to `bs.generation:gen_fractal_shape_2d`.
-  - <abbr title="Breaking Changes">⚠️</abbr> **[#296](https://github.com/mcbookshelf/Bookshelf/issues/296)** - Renamed the `bs.generate:shape_2d` function to `bs.generation:gen_shape_2d`.
-  - <abbr title="Breaking Changes">⚠️</abbr> **[#296](https://github.com/mcbookshelf/Bookshelf/issues/296)** - Renamed the `bs.generate:simplex_shape_2d` function to `bs.generation:gen_simplex_shape_2d`.
+- <abbr title="Breaking Changes">⚠️</abbr> **[#282](https://github.com/mcbookshelf/Bookshelf/issues/282)** - Renamed scores used in callbacks to use the new `bs.lambda` objective.
+- <abbr title="Breaking Changes">⚠️</abbr> **[#296](https://github.com/mcbookshelf/Bookshelf/issues/296)** - Renamed the `bs.generate:fractal_shape_2d` function to `bs.generation:gen_fractal_shape_2d`.
+- <abbr title="Breaking Changes">⚠️</abbr> **[#296](https://github.com/mcbookshelf/Bookshelf/issues/296)** - Renamed the `bs.generate:shape_2d` function to `bs.generation:gen_shape_2d`.
+- <abbr title="Breaking Changes">⚠️</abbr> **[#296](https://github.com/mcbookshelf/Bookshelf/issues/296)** - Renamed the `bs.generate:simplex_shape_2d` function to `bs.generation:gen_simplex_shape_2d`.
 
 
 ### `🎯 bs.hitbox`
 
 - <abbr title="Breaking Changes">⚠️</abbr> **[#297](https://github.com/mcbookshelf/Bookshelf/issues/297)** - Renamed block tag `is_composite` to `not_full_cube` for better clarity.
 - <abbr title="New Features">✨</abbr> **[#285](https://github.com/mcbookshelf/Bookshelf/pull/285)** - Introduced a `#bs.hitbox:is_sized` tag for improved hitbox management.
 - <abbr title="New Features">✨</abbr> **[#299](https://github.com/mcbookshelf/Bookshelf/pull/299)** - Block tag `#bs.hitbox:can_pass_through` was moved from the move module and is now properly documented.
-- <abbr title="Bug fix">🐛</abbr> **[#320](https://github.com/mcbookshelf/Bookshelf/issues/320)** - Fixed functions that were unusable outside the Overworld.
+- <abbr title="Bug Fix">🐛</abbr> **[#320](https://github.com/mcbookshelf/Bookshelf/issues/320)** - Fixed functions that were unusable outside the Overworld.
 
 
 ### `🏃 bs.move`
 
-- <abbr title="Bug fix">🐛</abbr> **[#316](https://github.com/mcbookshelf/Bookshelf/issues/316)** - Fixed entities clipping into blocks during collision resolution.
+- <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/*`.
+- <abbr title="Bug Fix">🐛</abbr> **[#316](https://github.com/mcbookshelf/Bookshelf/issues/316)** - Fixed entities clipping into blocks during collision resolution.
+
+
+### `⏲️ Schedule`
+
+- <abbr title="Breaking Changes">⚠️</abbr> **[#282](https://github.com/mcbookshelf/Bookshelf/issues/282)** - Changed the `#bs.schedule:schedule` function signature for better consistency with others that use callbacks.
+
 
 ### `📰 bs.sidebar`
 
-- <abbr title="Bug fix">🐛</abbr> **[#301](https://github.com/mcbookshelf/Bookshelf/pull/301)** - Fixed the issue where `bs.sidebar:create` was not functioning correctly.
+- <abbr title="Bug Fix">🐛</abbr> **[#301](https://github.com/mcbookshelf/Bookshelf/pull/301)** - Fixed the issue where `bs.sidebar:create` was not functioning correctly.
 
 
 ### `👀 bs.view`

docs/contribute/shared-resources.md

@@ -10,25 +10,27 @@ To minimize redundancy and enhance efficiency, the library provides shared objec
 
 ## Objectives
 
-| Objectives | Description |
-|------------|-------------|
-| `bs.ctx`   | Contextual scoreboard for fast temporary values. Format: `#<single_letter>` |
-| `bs.const` | Stores constant values. Format: `<value>` |
-| `bs.data`  | Global score storage. Format:  `#<module>.<my_key>` |
-| `bs.in`    | Default scores for input values. Format:  `$<module>.<feature>.<input_key>` |
-| `bs.out`   | Default scores for output values. Format:  `$<module>.<feature>` or `$<module>.<feature>.<output_key>` |
+| Objectives  | Description |
+|-------------|-------------|
+| `bs.in`     | Stores input values. Format: `$<module>.<feature>.<input_key>` |
+| `bs.out`    | Stores output values. Format:  `$<module>.<feature>` or `$<module>.<feature>.<output_key>` |
+| `bs.ctx`    | Temporary contextual objective for fast computations. Format: `#<single_letter>` |
+| `bs.data`   | Global score storage. Format:  `#<module>.<my_key>` |
+| `bs.const`  | Stores constant values. Format: `<value>` |
+| `bs.lambda` | Stores values used in callbacks. Format: `$<module>.<my_key>` |
 
 ---
 
 ## Storages
 
-| Namespaces | Description |
-|------------|-------------|
-| `bs:ctx`   | Fast contextual storage. Keys: `x`, `y`, `z` for numeric values (store) and `_` for other data. |
-| `bs:const` | Stores constant data. Path format: `<module>.<my_key>` |
-| `bs:data`  | General-purpose global storage. Path format: `<module>.<my_key>` |
-| `bs:in`    | Input data storage. Path format: `<module>.<feature>.<input_key>` |
-| `bs:out`   | Output data storage. Path format: `<module>.<feature>` or `<module>.<feature>.<output_key>` |
+| Namespaces  | Description |
+|-------------|-------------|
+| `bs:in`     | Stores input data. Path: `<module>.<feature>.<input_key>` |
+| `bs:out`    | Stores output data. Path: `<module>.<feature>` or `<module>.<feature>.<output_key>` |
+| `bs:ctx`    | Fast contextual storage. Uses `x`, `y`, `z` for numeric values (ie: execute store) and `_` for other data. |
+| `bs:data`   | General-purpose global storage. Path: `<module>.<my_key>` |
+| `bs:const`  | Stores constant data. Path: `<module>.<my_key>` |
+| `bs:lambda` | Stores data used in callbacks. Path: `<module>.<my_key>` |
 
 ---
 
@@ -59,5 +61,5 @@ execute unless entity B5-0-0-0-1 run summon minecraft:marker -30000000 0 1600 {U
 execute unless entity B5-0-0-0-2 run summon minecraft:text_display -30000000 0 1600 {UUID:[I;181,0,0,2],Tags:["bs.entity","bs.persistent","smithed.entity","smithed.strict"],view_range:0f,alignment:"center"}
 
 # Item display entity for manipulating loots or computing transformations
-execute unless entity B5-0-0-0-3 run summon minecraft:item_display -30000000 0 1600 {UUID:[I;181,0,0,3],Tags:["bs.entity","bs.persistent","smithed.entity","smithed.strict"],view_range:0f,alignment:"center"}
+execute unless entity B5-0-0-0-3 run summon minecraft:item_display -30000000 0 1600 {UUID:[I;181,0,0,3],Tags:["bs.entity","bs.persistent","smithed.entity","smithed.strict"],view_range:0f}
 ```

docs/contribute/special-functions.md

@@ -4,13 +4,46 @@ Some functions follow specific conventions to streamline functionality and ensur
 
 ---
 
-##  👉 The "ata" Functions
+## 👉 The `ata` Functions
 
-This is a reduction of "as to at". Several functions require 2 positions to work (example: retrieve the distance between 2 points) or an entity and a position. To simplify the use, no need to pass 3 scores for each position. You will be able to place an entity on point 1 (if it is useful), then execute the function at point 2 while executing it as the entity on point 1.
+This is a reduction of "as to at". Several functions require two positions to work (example: retrieve the distance between 2 points) or an entity and a position. To simplify the use, no need to pass 3 scores for each position. You will be able to place an entity on point 1 (if it is useful), then execute the function at point 2 while executing it as the entity on point 1.
 
 ---
 
-## 🔒 The "reserved" Functions
+## 🔗 The `runner` Functions
+
+These functions use the `run` callback to specify an action that will often be executed immediately. It works like a subcommand, defining what action should take place after the function call.
+
+For example:
+```mcfunction
+function #bs.view:at_aimed_block {run: "<command>", with: {}}
+```
+
+---
+
+## 📡 The `listener` Functions
+
+These functions are designed to react to specific events. The naming convention `on_<event>` is used for the inputs to indicate commands that will be triggered when a particular event occurs.
+
+For example:
+```mcfunction
+function #bs.health:time_to_live {with: {on_death: "<command>", time: 10}}
+```
+
+---
+
+## ⚒️ The `callback` Functions
+
+These functions are intended to be executed exclusively as part of a callback, and their function tag must be placed inside a `callback` directory.
+
+For example:
+- `#bs.move:callback/bounce`
+- `#bs.move:callback/slide`
+- `#bs.interaction:callback/glow`
+
+---
+
+## 🔒 The `reserved` Functions
 
 Reserved functions are special functions within each module that serve predefined purposes. They are located at the root of each module.
 

docs/modules/generation.md

@@ -52,8 +52,8 @@ Generate a shape in 2D space at the specified origin, with the callback executed
   :::{treeview}
   - {nbt}`compound` Arguments
     - {nbt}`string` **run**: Callback to run at each step. For each step, the following scores can be used:
-      - **`$generation.x bs.data`**: The X coordinate of the current step.
-      - **`$generation.y bs.data`**: The Y coordinate of the current step.
+      - **`$generation.x bs.lambda`**: The X coordinate of the current step.
+      - **`$generation.y bs.lambda`**: The Y coordinate of the current step.
     - {nbt}`int` **width**: Width of the shape to generate.
     - {nbt}`int` **height**: Height of the shape to generate.
     - {nbt}`compound` **with**: Shape settings.
@@ -80,9 +80,9 @@ Generate a shape in 2D space using a Simplex noise algorithm. The shape is gener
   :::{treeview}
   - {nbt}`compound` Arguments
     - {nbt}`string` **run**: Callback to run at each step. For each step, the following scores can be used:
-      - **`$random.simplex_noise_2d bs.out`**: The noise value in the range [-1000, 1000].
-      - **`$generation.x bs.data`**: The X coordinate of the current step.
-      - **`$generation.y bs.data`**: The Y coordinate of the current step.
+      - **`$generation.noise bs.lambda`**: The noise value in the range [-1000, 1000].
+      - **`$generation.x bs.lambda`**: The X coordinate of the current step.
+      - **`$generation.y bs.lambda`**: The Y coordinate of the current step.
     - {nbt}`int` **width**: Width of the shape to generate.
     - {nbt}`int` **height**: Height of the shape to generate.
     - {nbt}`compound` **with**: Shape settings.
@@ -111,9 +111,9 @@ Generate a shape in 2D space using a Fractal noise algorithm. The shape is gener
   :::{treeview}
   - {nbt}`compound` Arguments
     - {nbt}`string` **run**: Callback to run at each step. For each step, the following scores can be used:
-      - **`$random.fractal_noise_2d bs.out`**: The noise value in the range [-1000, 1000].
-      - **`$generation.x bs.data`**: The X coordinate of the current step.
-      - **`$generation.y bs.data`**: The Y coordinate of the current step.
+      - **`$generation.noise bs.lambda`**: The noise value in the range [-1000, 1000].
+      - **`$generation.x bs.lambda`**: The X coordinate of the current step.
+      - **`$generation.y bs.lambda`**: The Y coordinate of the current step.
     - {nbt}`int` **width**: Width of the shape to generate.
     - {nbt}`int` **height**: Height of the shape to generate.
     - {nbt}`compound` **with**: Shape settings.

docs/modules/move.md

@@ -52,7 +52,7 @@ Teleport an entity by its velocity scores while handling collisions.
     - {nbt}`compound` **with**: Collision settings.
       - {nbt}`bool` **blocks**: Whether the entity should collide with blocks (default: true).
       - {nbt}`bool` {nbt}`string` **entities**: Whether the entity should collide with entities (default: false). Can also be a tag that entities must have.
-      - {nbt}`string` **on_collision**: Function to run on collision (default: `#bs.move:on_collision/bounce`).
+      - {nbt}`string` **on_collision**: Command to run when a collision occurs, used to resolve the collision (default: `function #bs.move:callback/bounce`).
       - {nbt}`string` **ignored_blocks**: Blocks to ignore (default: `#bs.hitbox:intangible`).
       - {nbt}`string` **ignored_entities**: Entities to ignore (default: `#bs.hitbox:intangible`).
   :::
@@ -88,7 +88,7 @@ Teleport an entity by its velocity scores, using the local reference frame, whil
     - {nbt}`compound` **with**: Collision settings.
       - {nbt}`bool` **blocks**: Whether the entity should collide with blocks (default: true).
       - {nbt}`bool` {nbt}`string` **entities**: Whether the entity should collide with entities (default: false). Can also be a tag that entities must have.
-      - {nbt}`string` **on_collision**: Function to run on collision (default: `#bs.move:on_collision/bounce`).
+      - {nbt}`string` **on_collision**: Command to run when a collision occurs, used to resolve the collision (default: `function #bs.move:callback/bounce`).
       - {nbt}`string` **ignored_blocks**: Blocks to ignore (default: `#bs.hitbox:intangible`).
       - {nbt}`string` **ignored_entities**: Entities to ignore (default: `#bs.hitbox:intangible`).
   :::
@@ -114,10 +114,10 @@ scoreboard players set @e[type=minecraft:block_display] bs.vel.z 50
 execute as @e[type=minecraft:block_display] run function #bs.move:apply_vel {scale:0.001,with:{}}
 
 # Choose between multiple collision behaviors
-execute as @e[type=minecraft:block_display] run function #bs.move:apply_vel {scale:0.001,with:{on_collision:"#bs.move:on_collision/bounce"}}
-execute as @e[type=minecraft:block_display] run function #bs.move:apply_vel {scale:0.001,with:{on_collision:"#bs.move:on_collision/damped_bounce"}}
-execute as @e[type=minecraft:block_display] run function #bs.move:apply_vel {scale:0.001,with:{on_collision:"#bs.move:on_collision/slide"}}
-execute as @e[type=minecraft:block_display] run function #bs.move:apply_vel {scale:0.001,with:{on_collision:"#bs.move:on_collision/stick"}}
+execute as @e[type=minecraft:block_display] run function #bs.move:apply_vel {scale:0.001,with:{on_collision:"function #bs.move:callback/bounce"}}
+execute as @e[type=minecraft:block_display] run function #bs.move:apply_vel {scale:0.001,with:{on_collision:"function #bs.move:callback/damped_bounce"}}
+execute as @e[type=minecraft:block_display] run function #bs.move:apply_vel {scale:0.001,with:{on_collision:"function #bs.move:callback/slide"}}
+execute as @e[type=minecraft:block_display] run function #bs.move:apply_vel {scale:0.001,with:{on_collision:"function #bs.move:callback/stick"}}
 ```
 
 ```{admonition} Performance Tip
@@ -227,19 +227,19 @@ This module allows you to customize collision behaviors according to your specif
 By modifying the `on_collision` input key, you have the freedom to specify the function that triggers upon collision. However, managing the resolution yourself can be quite challenging. This is why Bookshelf provides several predefined functions:
 
 :::{list-table}
-  *   - `#bs.move:on_collision/bounce`
+  *   - `#bs.move:callback/bounce`
       - The entity will bounce on the collision surface.
-  *   - `#bs.move:on_collision/damped_bounce`
+  *   - `#bs.move:callback/damped_bounce`
       - The entity speed is reduced by 2 on each bounce.
-  *   - `#bs.move:on_collision/slide`
+  *   - `#bs.move:callback/slide`
       - The entity will stick and slide along the collision surface.
-  *   - `#bs.move:on_collision/stick`
+  *   - `#bs.move:callback/stick`
       - The entity will stop and stick to the collision surface.
 :::
 
 ### How It Works?
 
-Upon collision, you have the freedom to update both the velocity score that will be used in the next tick `@s bs.vel.[x,y,z]` and the remaining velocity `$move.vel_remaining.[x,y,z] bs.data`. Since the module will attempt to continue moving based on the remaining velocity, it's crucial to avoid introducing a race condition.
+Upon collision, you have the freedom to update both the velocity score that will be used in the next tick `@s bs.vel.[x,y,z]` and the remaining velocity `$move.vel.[x,y,z] bs.lambda`. Since the module will attempt to continue moving based on the remaining velocity, it's crucial to avoid introducing a race condition.
 
 ```{admonition} Velocity Scaling
 :class: warning
@@ -250,22 +250,22 @@ To ensure stability, always manipulate these values independently of the scaling
 
 The simplest collision resolution is to stop the movement.
 
-*`#bs.move:on_collision/stick`*
+*`#bs.move:callback/stick`*
 ```mcfunction
 # set all components to 0 to cancel the movement
-execute store result score $move.vel_remaining.x bs.data run scoreboard players set @s bs.vel.x 0
-execute store result score $move.vel_remaining.y bs.data run scoreboard players set @s bs.vel.y 0
-execute store result score $move.vel_remaining.z bs.data run scoreboard players set @s bs.vel.z 0
+execute store result score $move.vel.x bs.lambda run scoreboard players set @s bs.vel.x 0
+execute store result score $move.vel.y bs.lambda run scoreboard players set @s bs.vel.y 0
+execute store result score $move.vel.z bs.lambda run scoreboard players set @s bs.vel.z 0
 ```
 
 For sliding, we need to cancel the velocity on the axis that was hit and continue traveling the remaining distance.
 
-*`#bs.move:on_collision/slide`*
+*`#bs.move:callback/slide`*
 ```mcfunction
 # set a component to 0 depending on the surface that was hit
-execute if score $move.hit_face bs.data matches 4..5 store result score $move.vel_remaining.x bs.data run scoreboard players set @s bs.vel.x 0
-execute if score $move.hit_face bs.data matches 0..1 store result score $move.vel_remaining.y bs.data run scoreboard players set @s bs.vel.y 0
-execute if score $move.hit_face bs.data matches 2..3 store result score $move.vel_remaining.z bs.data run scoreboard players set @s bs.vel.z 0
+execute if score $move.hit_face bs.lambda matches 4..5 store result score $move.vel.x bs.lambda run scoreboard players set @s bs.vel.x 0
+execute if score $move.hit_face bs.lambda matches 0..1 store result score $move.vel.y bs.lambda run scoreboard players set @s bs.vel.y 0
+execute if score $move.hit_face bs.lambda matches 2..3 store result score $move.vel.z bs.lambda run scoreboard players set @s bs.vel.z 0
 ```
 
 To simplify the creation of these behaviors, there's no need to handle a local velocity directly. The vector is automatically converted before and after the collision resolution. If you need help with custom collisions, you can ask us on our [discord server](https://discord.gg/MkXytNjmBt)!