Merge branch 'master' into 1.16

docs/scarpet/Full.md

@@ -2781,6 +2781,53 @@ If `slot` is not specified, it defaults to the main hand.
 
 Number indicating the selected slot of entity's inventory. Currently only applicable to players.
 
+### `query(e, 'active_block')`
+
+Returns currently mined block by the player, as registered by the game server.
+
+### `query(e, 'breaking_progress')`
+
+Returns current breaking progress of a current player mining block, or `null`, if no block is mined.
+Breaking progress, it not null, is any number 0 or above, while 10 means that the block should already be 
+broken by the client. This value may tick above 10, if the client / connection is lagging
+
+Example:
+
+The following program provides custom breaking times, including nice block breaking animations, including instamine, for
+blocks that otherwise would take longer to mine.
+
+[Video demo](https://youtu.be/zvEEuGxgCio)
+```py
+global_blocks = {
+  'oak_planks' -> 0,
+  'obsidian' -> 1,
+  'end_portal_frame' -> 5,
+  'bedrock' -> 10
+};
+  
+__on_player_clicks_block(player, block, face) ->
+(
+   step = global_blocks:str(block);
+   if (step == 0,
+      destroy(block, -1); // instamine
+   , step != null,
+      schedule(0, '_break', player, pos(block), str(block), step, 0);
+   )
+);
+
+_break(player, pos, name, step, lvl) ->
+(
+   current = player~'active_block';
+   if (current != name || pos(current) != pos, 
+      modify(player, 'breaking_progress', null);
+   ,
+      modify(player, 'breaking_progress', lvl);
+      if (lvl >= 10, destroy(pos, -1));
+      schedule(step, '_break', player, pos, name, step, lvl+1)
+   );
+)
+```
+
 ### `query(e, 'facing', order?)`
 
 Returns where the entity is facing. optional order (number from 0 to 5, and negative), indicating primary directions 
@@ -3013,6 +3060,12 @@ Modifies directly player raw hunger components. Has no effect on non-players
 adds exhaustion value to the current player exhaustion level - that's the method you probably want to use
 to manipulate how much 'food' some action cost.
 
+### `modify(e, 'breaking_progress', value)` 
+
+Modifies a breaking progress of a player currently mined block. Value of `null`, `-1` make it reset. 
+Values `0` to `10` will show respective animation of a breaking block. Check `query(e, 'breaking_progress')` for 
+examples.
+
 ### `modify(e, 'nbt_merge', partial_tag)`
 
 Merges a partial tag into the entity data and reloads the entity from its updated tag. Cannot be applied to players
@@ -3267,6 +3320,7 @@ __on_player_places_block(player, item_tuple, hand, block) // player have just pl
 __on_player_interacts_with_entity(player, entity, hand)
 __on_player_chooses_recipe(player, recipe, full_stack)
 __on_player_switches_slot(player, from, to)
+__on_player_swaps_hands(player)
 __on_player_attacks_entity(player, entity)
 __on_player_takes_damage(player, amount, source, source_entity)
 __on_player_deals_damage(player, amount, entity)

docs/scarpet/api/Entities.md

@@ -347,6 +347,53 @@ If `slot` is not specified, it defaults to the main hand.
 
 Number indicating the selected slot of entity's inventory. Currently only applicable to players.
 
+### `query(e, 'active_block')`
+
+Returns currently mined block by the player, as registered by the game server.
+
+### `query(e, 'breaking_progress')`
+
+Returns current breaking progress of a current player mining block, or `null`, if no block is mined.
+Breaking progress, it not null, is any number 0 or above, while 10 means that the block should already be 
+broken by the client. This value may tick above 10, if the client / connection is lagging
+
+Example:
+
+The following program provides custom breaking times, including nice block breaking animations, including instamine, for
+blocks that otherwise would take longer to mine.
+
+[Video demo](https://youtu.be/zvEEuGxgCio)
+```py
+global_blocks = {
+  'oak_planks' -> 0,
+  'obsidian' -> 1,
+  'end_portal_frame' -> 5,
+  'bedrock' -> 10
+};
+  
+__on_player_clicks_block(player, block, face) ->
+(
+   step = global_blocks:str(block);
+   if (step == 0,
+      destroy(block, -1); // instamine
+   , step != null,
+      schedule(0, '_break', player, pos(block), str(block), step, 0);
+   )
+);
+
+_break(player, pos, name, step, lvl) ->
+(
+   current = player~'active_block';
+   if (current != name || pos(current) != pos, 
+      modify(player, 'breaking_progress', null);
+   ,
+      modify(player, 'breaking_progress', lvl);
+      if (lvl >= 10, destroy(pos, -1));
+      schedule(step, '_break', player, pos, name, step, lvl+1)
+   );
+)
+```
+
 ### `query(e, 'facing', order?)`
 
 Returns where the entity is facing. optional order (number from 0 to 5, and negative), indicating primary directions 
@@ -579,6 +626,12 @@ Modifies directly player raw hunger components. Has no effect on non-players
 adds exhaustion value to the current player exhaustion level - that's the method you probably want to use
 to manipulate how much 'food' some action cost.
 
+### `modify(e, 'breaking_progress', value)` 
+
+Modifies a breaking progress of a player currently mined block. Value of `null`, `-1` make it reset. 
+Values `0` to `10` will show respective animation of a breaking block. Check `query(e, 'breaking_progress')` for 
+examples.
+
 ### `modify(e, 'nbt_merge', partial_tag)`
 
 Merges a partial tag into the entity data and reloads the entity from its updated tag. Cannot be applied to players

docs/scarpet/api/Events.md

@@ -34,6 +34,7 @@ __on_player_places_block(player, item_tuple, hand, block) // player have just pl
 __on_player_interacts_with_entity(player, entity, hand)
 __on_player_chooses_recipe(player, recipe, full_stack)
 __on_player_switches_slot(player, from, to)
+__on_player_swaps_hands(player)
 __on_player_attacks_entity(player, entity)
 __on_player_takes_damage(player, amount, source, source_entity)
 __on_player_deals_damage(player, amount, entity)

docs/scarpet/resources/editors/idea/4.txt

@@ -23,6 +23,7 @@ __on_player_starts_sprinting
 __on_player_stops_sneaking
 __on_player_stops_sprinting
 __on_player_switches_slot
+__on_player_swaps_hands
 __on_player_uses_item
 __on_player_wakes_up
 __on_statistic

docs/scarpet/resources/editors/npp/scarpet.xml

@@ -106,6 +106,7 @@
                 __on_player_stops_sneaking
                 __on_player_stops_sprinting
                 __on_player_switches_slot
+                __on_player_swaps_hands
                 __on_player_uses_item
                 __on_player_wakes_up
                 __on_statistic