add docs for the left click and middle click pipelines

docs/blocks/index.md

@@ -198,7 +198,7 @@ In several situations, multiple methods of `Block` are used at different times.
 
 ### Placing a Block
 
-Block placement logic is called from `BlockItem#useOn` (or some subclass's implementation thereof, such as in `PlaceOnWaterBlockItem`, which is used for lily pads). For more information on how the game gets there, see the [Interaction Pipeline][interactionpipeline]. In practice, this means that as soon as a `BlockItem` is right-clicked (for example a cobblestone item), this behavior is called.
+Block placement logic is called from `BlockItem#useOn` (or some subclass's implementation thereof, such as in `PlaceOnWaterBlockItem`, which is used for lily pads). For more information on how the game gets there, see [Right-Clicking Items][rightclick]. In practice, this means that as soon as a `BlockItem` is right-clicked (for example a cobblestone item), this behavior is called.
 
 - Several prerequisites are checked, for example that you are not in spectator mode, that all required feature flags for the block are enabled or that the target position is not outside the world border. If at least one of these checks fails, the pipeline ends.
 - `BlockBehaviour#canBeReplaced` is called for the block currently at the position where the block is attempted to be placed. If it returns `false`, the pipeline ends. Prominent cases that return `true` here are tall grass or snow layers.
@@ -230,11 +230,10 @@ while (leftClickIsBeingHeld()) {
 }
 ```
 
-The following subsections further break down these stages into actual method calls.
+The following subsections further break down these stages into actual method calls. For information about how the game gets from left-clicking to this pipeline, see [Left-Clicking an Item][leftclick].
 
 #### The "Initiating" Stage
 
-- Client-only: `InputEvent.InteractionKeyMappingTriggered` is fired with the left mouse button and the main hand. If the event is canceled, the pipeline ends.
 - Several prerequisites are checked, for example that you are not in spectator mode, that all required feature flags for the `ItemStack` in your main hand are enabled or that the block in question is not outside the world border. If at least one of these checks fails, the pipeline ends.
 - `PlayerInteractEvent.LeftClickBlock` is fired. If the event is canceled, the pipeline ends.
     - Note that when the event is canceled on the client, no packets are sent to the server and thus no logic runs on the server.
@@ -300,13 +299,13 @@ Random ticking is used by a wide range of mechanics in Minecraft, such as plant
 [blockstates]: states.md
 [bsfile]: ../resources/client/models/index.md#blockstate-files
 [codec]: ../datastorage/codecs.md#records
-[events]: ../concepts/events.md
-[interactionpipeline]: ../items/interactionpipeline.md
 [item]: ../items/index.md
+[leftclick]: ../items/interactions.md#left-clicking-an-item
 [model]: ../resources/client/models/index.md
 [randomtick]: #random-ticking
 [registration]: ../concepts/registries.md#methods-for-registering
 [resources]: ../resources/index.md#assets
+[rightclick]: ../items/interactions.md#right-clicking-an-item
 [sounds]: ../resources/client/sounds.md
 [textures]: ../resources/client/textures.md
 [usingblocks]: #using-blocks

docs/entities/index.md

@@ -148,6 +148,8 @@ For more complex spawn behavior, please refer to the [Spawning article][spawning
 
 ### Damaging Entities
 
+_See also [Left-Clicking an Item][leftclick]._
+
 While not all entities have the concept of hit points, they can still all receive damage. This is not only used by things like mobs and players: If you cast your mind to item entities (dropped items), they too can take damage from sources like fire or cacti, in which case they are usually deleted immediately.
 
 Damaging an entity is possible by calling `Entity#hurt`. `Entity#hurt` takes two arguments: the [`DamageSource`][damagesource] and the damage amount, as a float in half hearts. For example, calling `entity.hurt(entity.damageSources().wither(), 4.25)` will cause a little over two hearts of wither damage.
@@ -195,9 +197,9 @@ public void tick() {
 
 ### Picking Entities
 
-Entity picking is an ambiguous term because Mojang uses it for two things: the action of middle-clicking an entity to get a spawn egg or similar item, and for selecting the entity (or [block]) to begin with.
+_See also [Middle-Clicking][middleclick]._
 
-The result of middle-clicking, known as the "pick result", can be modified by your entity (be aware that the `Mob` class will select the correct spawn egg for you):
+Picking is the process of selecting the thing that the player is currently looking at, as well as subsequently picking the associated item. The result of middle-clicking, known as the "pick result", can be modified by your entity (be aware that the `Mob` class will select the correct spawn egg for you):
 
 ```java
 @Override
@@ -208,9 +210,7 @@ public ItemStack getPickResult() {
 }
 ```
 
-Selecting the entity or block to begin with is done through what is known as a ray cast in basically any other engine. This is mainly used by things like the F3 debug overlay, game-relevant things such as players attacking or breaking things have their own checks in place here.
-
-Our own entity can be disabled from picking like so:
+Your entity can also be disabled from picking entirely like so:
 
 ```java
 @Override
@@ -220,7 +220,7 @@ public boolean isPickable() {
 }
 ```
 
-If you want to do the picking (i.e. ray casting) yourself, you can call `Entity#pick` on the entity that you want to start the ray cast from. This will return a `HitResult` that you can further check for what exactly has been hit by the ray cast.
+If you want to do the picking (i.e. ray casting) yourself, you can call `Entity#pick` on the entity that you want to start the ray cast from. This will return a [`HitResult`][hitresult] that you can further check for what exactly has been hit by the ray cast.
 
 ### Entity Attachments
 
@@ -246,9 +246,12 @@ Several entities are also direct subclasses of `Entity`, simply because there wa
 [data]: data.md
 [entity]: #the-entity-class
 [hierarchy]: #entity-class-hierarchy
+[hitresult]: ../items/interactions.md#hitresults
 [item]: ../items/index.md
 [itemstack]: ../items/index.md#itemstacks
+[leftclick]: ../items/interactions.md#left-clicking-an-item
 [livingentity]: livingentity.md
+[middleclick]: ../items/interactions.md#middle-clicking
 [mobeffect]: ../items/mobeffects.md
 [particle]: ../resources/client/particles.md
 [projectile]: projectile.md

docs/gui/menus.md

@@ -345,4 +345,4 @@ Once again, this is the simplest way to implement the logic, not the only way.
 [screen]: ./screens.md
 [icf]: #icontainerfactory
 [side]: ../concepts/sides.md#the-logical-side
-[interaction]: ../items/interactionpipeline.md
+[interaction]: ../items/interactions.md#right-clicking-an-item

docs/items/index.md

@@ -52,7 +52,7 @@ To get the `FoodProperties` for an item, call `Item#getFoodProperties(ItemStack,
 
 Directly using `Item` only allows for very basic items. If you want to add functionality, for example right-click interactions, a custom class that extends `Item` is required. The `Item` class has many methods that can be overridden to do different things; see the classes `Item` and `IItemExtension` for more information.
 
-The two most common use cases for items are left-clicking and right-clicking. For left-clicking, see [Breaking a Block][breaking] and Attacking an Entity (WIP). For right-clicking, see [The Interaction Pipeline][interactionpipeline].
+The two most common use cases for items are left-clicking and right-clicking. Due to their complexity and their reaching into other systems, they are explained in a separate [Interaction article][interactions].
 
 ### `DeferredRegister.Items`
 
@@ -219,7 +219,7 @@ It is also possible to implement `ItemLike` on your custom objects. Simply overr
 [entity]: ../entities/index.md
 [food]: #food
 [hunger]: https://minecraft.wiki/w/Hunger#Mechanics
-[interactionpipeline]: interactionpipeline.md
+[interactions]: interactions.md
 [loottables]: ../resources/server/loottables/index.md
 [mobeffectinstance]: mobeffects.md#mobeffectinstances
 [modbus]: ../concepts/events.md#event-buses