Entity docs

docs/blockentities/container.md

@@ -264,7 +264,7 @@ Be aware that menus that directly interface with `Container`s must `#copy()` the
 
 ## `Container`s on `Entity`s
 
-`Container`s on `Entity`s are finicky: whether an entity has a container or not cannot be universally determined. It all depends on what entity you are handling, and as such can require a lot of special-casing.
+`Container`s on [`Entity`s][entity] are finicky: whether an entity has a container or not cannot be universally determined. It all depends on what entity you are handling, and as such can require a lot of special-casing.
 
 If you are creating an entity yourself, there is nothing stopping you from implementing `Container` on it directly, though be aware that you will not be able to use superclasses such as `SimpleContainer` (since `Entity` is the superclass).
 
@@ -307,6 +307,7 @@ When iterating over the inventory contents, it is recommended to iterate over `i
 [blockentity]: index.md
 [component]: ../resources/client/i18n.md#components
 [datacomponent]: ../items/datacomponents.md
+[entity]: ../entities/index.md
 [item]: ../items/index.md
 [itemstack]: ../items/index.md#itemstacks
 [menu]: ../gui/menus.md

docs/blockentities/index.md

@@ -1,6 +1,6 @@
 # Block Entities
 
-Block entities allow the storage of data on [blocks][block] in cases where [block states][blockstate] are not suitable. This is especially the case for data with a non-finite amount of options, such as inventories. Block entities are stationary and bound to a block, but otherwise share many similarities with entities, hence the name.
+Block entities allow the storage of data on [blocks][block] in cases where [block states][blockstate] are not suitable. This is especially the case for data with a non-finite amount of options, such as inventories. Block entities are stationary and bound to a block, but otherwise share many similarities with [entities], hence the name.
 
 :::note
 If you have a finite and reasonably small amount (= a few hundred at most) of possible states for your block, you might want to consider using [block states][blockstate] instead.
@@ -237,6 +237,7 @@ It is important that you do safety checks, as the `BlockEntity` might already be
 [blockreg]: ../blocks/index.md#basic-blocks
 [blockstate]: ../blocks/states.md
 [dataattachments]: ../datastorage/attachments.md
+[entities]: ../entities/index.md
 [modbus]: ../concepts/events.md#event-buses
 [nbt]: ../datastorage/nbt.md
 [networking]: ../networking/index.md

docs/blocks/index.md

@@ -25,8 +25,8 @@ After registering the block, all references to the new `my_block` should use thi
 
 ```java
 level.getBlockState(position) // returns the blockstate placed in the given level (world) at the given position
-        //highlight-next-line
-        .is(MyBlockRegistrationClass.MY_BLOCK);
+    //highlight-next-line
+    .is(MyBlockRegistrationClass.MY_BLOCK);
 ```
 
 This approach also has the convenient effect that `block1 == block2` works and can be used instead of Java's `equals` method (using `equals` still works, of course, but is pointless since it compares by reference anyway).
@@ -69,16 +69,16 @@ So for example, a simple implementation would look something like this:
 ```java
 //BLOCKS is a DeferredRegister.Blocks
 public static final DeferredBlock<Block> MY_BETTER_BLOCK = BLOCKS.register(
-        "my_better_block", 
-        registryName -> new Block(BlockBehaviour.Properties.of()
-                //highlight-start
-                .setId(ResourceKey.create(Registries.BLOCK, registryName))
-                .destroyTime(2.0f)
-                .explosionResistance(10.0f)
-                .sound(SoundType.GRAVEL)
-                .lightLevel(state -> 7)
-                //highlight-end
-        ));
+    "my_better_block", 
+    registryName -> new Block(BlockBehaviour.Properties.of()
+        //highlight-start
+        .setId(ResourceKey.create(Registries.BLOCK, registryName))
+        .destroyTime(2.0f)
+        .explosionResistance(10.0f)
+        .sound(SoundType.GRAVEL)
+        .lightLevel(state -> 7)
+        //highlight-end
+    ));
 ```
 
 For further documentation, see the source code of `BlockBehaviour.Properties`. For more examples, or to look at the values used by Minecraft, have a look at the `Blocks` class.
@@ -104,7 +104,6 @@ If the block subclass only takes in the `BlockBehaviour.Properties`, then `Block
 ```java
 // For some block subclass
 public class SimpleBlock extends Block {
-
     public SimpleBlock(BlockBehavior.Properties properties) {
         // ...
     }
@@ -129,7 +128,6 @@ If the block subclass contains more parameters, then [`RecordCodecBuilder#mapCod
 ```java
 // For some block subclass
 public class ComplexBlock extends Block {
-
     public ComplexBlock(int value, BlockBehavior.Properties properties) {
         // ...
     }
@@ -170,28 +168,28 @@ We already discussed how to create a `DeferredRegister.Blocks` [above], as well
 public static final DeferredRegister.Blocks BLOCKS = DeferredRegister.createBlocks("yourmodid");
 
 public static final DeferredBlock<Block> EXAMPLE_BLOCK = BLOCKS.register(
-        "example_block", registryName -> new Block(
-            BlockBehaviour.Properties.of()
-                // The ID must be set on the block
-                .setId(ResourceKey.create(Registries.BLOCK, registryName))
-        )
+    "example_block", registryName -> new Block(
+        BlockBehaviour.Properties.of()
+            // The ID must be set on the block
+            .setId(ResourceKey.create(Registries.BLOCK, registryName))
+    )
 );
 
 // Same as above, except that the block properties are constructed eagerly.
 // setId is also called internally on the properties object.
 public static final DeferredBlock<Block> EXAMPLE_BLOCK = BLOCKS.registerBlock(
-        "example_block",
-        Block::new, // The factory that the properties will be passed into.
-        BlockBehaviour.Properties.of() // The properties to use.
+    "example_block",
+    Block::new, // The factory that the properties will be passed into.
+    BlockBehaviour.Properties.of() // The properties to use.
 );
 ```
 
 If you want to use `Block::new`, you can leave out the factory entirely:
 
 ```java
 public static final DeferredBlock<Block> EXAMPLE_BLOCK = BLOCKS.registerSimpleBlock(
-        "example_block",
-        BlockBehaviour.Properties.of() // The properties to use.
+    "example_block",
+    BlockBehaviour.Properties.of() // The properties to use.
 );
 ```
 
@@ -209,7 +207,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.
@@ -241,11 +239,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.
@@ -281,6 +278,38 @@ The following subsections further break down these stages into actual method cal
         - Server-only: `BlockDropsEvent` is fired. If the event is canceled, then nothing is dropped when the block breaks. Otherwise, every `ItemEntity` in `BlockDropsEvent#getDrops` is added to the current level.
 - Server-only: `Block#popExperience` is called with the result of the previous `IBlockExtension#getExpDrop` call, if that call returned a value greater than 0.
 
+#### Mining Speed
+
+The mining speed is calculated from the block's hardness, the used [tool]'s speed, and several entity [attributes] according to the following rules:
+
+```java
+// This will return the tool's mining speed, or 1 if the held item is either empty, not a tool,
+// or not applicable for the block being broken.
+float destroySpeed = item.getDestroySpeed();
+// If we have an applicable tool, add the minecraft:mining_efficiency attribute as an additive modifier.
+if (destroySpeed > 1) {
+    destroySpeed += player.getAttributeValue(Attributes.MINING_EFFICIENCY);
+}
+// Apply effects from haste, conduit power, and slowness multiplicatively.
+if (player.hasEffect(MobEffects.DIG_SPEED))     { destroySpeed *= ...; }
+if (player.hasEffect(MobEffects.CONDUIT_POWER)) { destroySpeed *= ...; }
+if (player.hasEffect(MobEffects.DIG_SLOWDOWN))  { destroySpeed *= ...; }
+// Add the minecraft:block_break_speed attribute as a multiplicative modifier.
+destroySpeed *= player.getAttributeValue(Attributes.BLOCK_BREAK_SPEED);
+// If the player is underwater, apply the underwater mining speed penalty multiplicatively.
+if (player.isEyeInFluid(FluidTags.WATER)) {
+    destroySpeed *= player.getAttributeValue(Attributes.SUBMERGED_MINING_SPEED);
+}
+// If the player is trying to break a block in mid-air, make the player mine 5 times slower.
+if (!player.onGround()) {
+    destroySpeed /= 5;
+}
+destroySpeed = /* The PlayerEvent.BreakSpeed event is fired here, allowing modders to further modify this value. */;
+return destroySpeed;
+```
+
+The exact code for this can be found in `Player#getDigSpeed` for reference.
+
 ### Ticking
 
 Ticking is a mechanism that updates (ticks) parts of the game every 1 / 20 seconds, or 50 milliseconds ("one tick"). Blocks provide different ticking methods that are called in different ways.
@@ -306,19 +335,21 @@ Random ticks occur every tick for a set amount of blocks in a chunk. That set am
 Random ticking is used by a wide range of mechanics in Minecraft, such as plant growth, ice and snow melting, or copper oxidizing.
 
 [above]: #one-block-to-rule-them-all
+[attributes]: ../entities/attributes.md
 [below]: #deferredregisterblocks-helpers
 [blockentities]: ../blockentities/index.md
 [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
+[tool]: ../items/tools.md
 [usingblocks]: #using-blocks
 [usingblockstates]: states.md#using-blockstates

docs/concepts/events.md

@@ -120,6 +120,7 @@ graph TD;
     PlayerEvent-->CanPlayerSleepEvent;
 
     class Event,BlockEvent,EntityEvent,LivingEvent,PlayerEvent red;
+    class BlockDropsEvent,CanPlayerSleepEvent blue;
 ```
 
 ### Cancellable Events

docs/datastorage/attachments.md

@@ -99,7 +99,7 @@ To sync block entity, chunk, or entity attachments to a client, you need to [sen
 
 ## Copying data on player death
 
-By default, entity data attachments are not copied on player death. To automatically copy an attachment on player death, set `copyOnDeath` in the attachment builder.
+By default, [entity] data attachments are not copied on player death. To automatically copy an attachment on player death, set `copyOnDeath` in the attachment builder.
 
 More complex handling can be implemented via `PlayerEvent.Clone` by reading the data from the original entity and assigning it to the new entity. In this event, the `#isWasDeath` method can be used to distinguish between respawning after death and returning from the End. This is important because the data will already exist when returning from the End, so care has to be taken to not duplicate values in this case.
 
@@ -113,6 +113,7 @@ NeoForge.EVENT_BUS.register(PlayerEvent.Clone.class, event -> {
 });
 ```
 
-[saveddata]: saveddata.md
 [datacomponents]: ../items/datacomponents.md
+[entity]: ../entities/index.md
 [network]: ../networking/index.md
+[saveddata]: saveddata.md

docs/datastorage/nbt.md

@@ -89,7 +89,7 @@ tag.get("Tag");
 
 ## Usages of NBT
 
-NBT is used in a lot of places in Minecraft. Some of the most common examples include [`BlockEntity`][blockentity]s and `Entity`s.
+NBT is used in a lot of places in Minecraft. Some of the most common examples include [`BlockEntity`][blockentity]s and [`Entity`s][entity].
 
 :::note
 `ItemStack`s abstract away the usage of NBT into [data components][datacomponents].
@@ -102,4 +102,5 @@ NBT is used in a lot of places in Minecraft. Some of the most common examples in
 [blockentity]: ../blockentities/index.md
 [datapack]: ../resources/index.md#data
 [datacomponents]: ../items/datacomponents.md
+[entity]: ../entities/index.md
 [nbtwiki]: https://minecraft.wiki/w/NBT_format

docs/entities/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Entities",
+  "position": 5
+}