implement feedback by Champ once again

docs/items/index.md

@@ -41,7 +41,7 @@ The `Item` class provides default functionality for food items, meaning you don'
 - `meat` - Whether this item should be considered meat or not. Used e.g. for determining if healing dogs with this food is possible.
 - `alwaysEat` - Whether this item can always be eaten, even if the hunger bar is full. `false` by default, `true` for golden apples and other items that provide bonuses beyond just filling the hunger bar.
 - `fast` - Whether fast eating should be enabled for this food. `false` by default, `true` for dried kelp in vanilla.
-- `effect` - Adds a `MobEffectInstance` to apply when eating this item. The second parameter denotes the probability of the effect being applied; for example, Rotten Flesh has an 80% chance of applying the Hunger effect when eaten. This method comes in two variants, one that takes in a supplier (for your own effects) and one that directly takes a `MobEffectInstance` (for vanilla effects).
+- `effect` - Adds a `MobEffectInstance` to apply when eating this item. The second parameter denotes the probability of the effect being applied; for example, Rotten Flesh has an 80% chance of applying the Hunger effect when eaten. This method comes in two variants; you should use the one that takes in a supplier (the other one directly takes a mob effect instance and is deprecated by NeoForge due to classloading issues).
 - `build` - Once you've set everything you want to set, call `build` to get a `FoodProperties` object for further use.
 
 For examples, or to look at the various values used by Minecraft, have a look at the `Foods` class.
@@ -50,7 +50,9 @@ To get the `FoodProperties` for an item, call `Item#getFoodProperties(ItemStack,
 
 ### More Functionality
 
-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. See also [below][using] for the most common use cases.
+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].
 
 ### Resources
 
@@ -71,7 +73,7 @@ An `ItemStack` consists of three major parts:
 
 To create a new `ItemStack`, call `new ItemStack(Item)`, passing in the backing item. By default, this uses a count of 1 and no NBT data; there are constructor overloads that accept a count and NBT data as well if needed.
 
-To clone an existing `ItemStack`, call `itemstack.copy()`.
+`ItemStack`s are mutable objects (see below), however it is sometimes required to treat them as immutables. If you need to modify an `ItemStack` that is to be treated immutable, you can clone the stack using `itemstack.copy()`.
 
 If you want to represent that a stack has no item, use `ItemStack.EMPTY`. If you want to check whether an `ItemStack` is empty, call `itemstack.isEmpty()`.
 
@@ -135,16 +137,6 @@ public static final Supplier<CreativeModeTab> EXAMPLE_TAB = CREATIVE_MODE_TABS.r
 );
 ```
 
-## Using Items
-
-### Left-Click
-
-See [Breaking a Block][breaking] and Attacking an Entity (WIP).
-
-### Right-Click
-
-See [The Interaction Pipeline][interactionpipeline].
-
 [block]: ../blocks/index.md
 [blockstates]: ../blocks/states.md
 [breaking]: ../blocks/index.md#breaking-a-block
@@ -157,4 +149,3 @@ See [The Interaction Pipeline][interactionpipeline].
 [registering]: ../concepts/registries.md#methods-for-registering
 [resources]: ../resources/client/index.md
 [sides]: ../concepts/sides.md
-[using]: #using-items

docs/items/mobeffects.md

@@ -5,17 +5,18 @@ Status effects, sometimes known as potion effects and referred to in-code as `Mo
 ## Terminology
 
 - A `MobEffect` affects an entity every tick. Like [blocks][block] or [items][item], `MobEffect`s are registry objects, meaning they must be [registered][registration] and are singletons.
+  - An **instant mob effect** is a special kind of mob effect that is designed to be applied for one tick. Vanilla has two instant effects, Instant Health and Instant Harming.
 - A `MobEffectInstance` is an instance of a `MobEffect`, with a duration, amplifier and some other properties set (see below). `MobEffectInstance`s are to `MobEffect`s what [`ItemStack`s][itemstack] are to `Item`s.
 - A `Potion` is a collection of `MobEffectInstance`s. Vanilla mainly uses potions for the four potion items (read on), however, they can be applied to any item at will. It is up to the item if and how the item then uses the potion set on it.
-- A **potion item** is an item that is meant to have a potion set on it. This is an informal term, the vanilla `PotionItem` class has nothing to do with this (it refers to the "normal" potion item). Minecraft currently has four potion items: potions, splash potions, lingering potions, and tipped arrows.
+- A **potion item** is an item that is meant to have a potion set on it. This is an informal term, the vanilla `PotionItem` class has nothing to do with this (it refers to the "normal" potion item). Minecraft currently has four potion items: potions, splash potions, lingering potions, and tipped arrows; however more may be added by mods.
 
 ## `MobEffect`s
 
 To create your own `MobEffect`, extend the `MobEffect` class:
 
 ```java
 public class MyMobEffect extends MobEffect {
-    public MobEffect(MobEffectCategory category, int color) {
+    public MyMobEffect(MobEffectCategory category, int color) {
         super(category, color);
     }
 
@@ -24,37 +25,17 @@ public class MyMobEffect extends MobEffect {
         // Apply your effect logic here.
     }
 
-    @Override
-    public void applyInstantaneousEffect(
-            @Nullable Entity directSource, // The entity causing the effect, for example a splash potion.
-            @Nullable Entity source, // The "source" entity, for example the player that threw the splash potion.
-            LivingEntity target, // The target entity.
-            int amplifier, // The amplifier of the effect.
-            double strength // The "strength" of the effect. If the potion is applied through drinking,
-                            // this is 1.0. If it is a lingering potion, this is 0.5. If it is a
-                            // splash potion, this depends on where the splash potion lands.
-    ) {
-        // Apply your instant effect logic here.
-        // Note: This calls applyEffectTick by default.
-    }
-
     // Whether the effect should apply this tick. Used e.g. by the Regeneration effect that only applies
     // once every x ticks, depending on the tick count and amplifier.
     @Override
     public boolean shouldApplyEffectTickThisTick(int tickCount, int amplifier) {
         return tickCount % 2 == 0; // replace this with whatever check you want
     }
 
-    // Called when the effect is first added to the entity.
+    // Utility method that is called when the effect is first added to the entity.
     @Override
     public void onEffectStarted(LivingEntity entity, int amplifier) {
     }
-
-    // Returns whether the effect is instantaneous or not.
-    @Override
-    public boolean isInstantenous() {
-        return false;
-    }
 }
 ```
 
@@ -81,6 +62,29 @@ public static final Supplier<MyMobEffect> MY_MOB_EFFECT = MOB_EFFECTS.register("
 );
 ```
 
+:::note
+The UUID used must be a valid and unique UUIDv4, as for some reason, Mojang decided to use UUIDs here instead of some text-based identifier. A UUID is best obtained through an online generator, for example [uuidgenerator.net][uuidgen].
+:::
+
+### `InstantenousMobEffect`
+
+If you want to create an instant effect, you can use the helper class `InstantenousMobEffect` instead of the regular `MobEffect` class, like so:
+
+```java
+public class MyMobEffect extends InstantenousMobEffect {
+    public MyMobEffect(MobEffectCategory category, int color) {
+        super(category, color);
+    }
+
+    @Override
+    public void applyEffectTick(LivingEntity entity, int amplifier) {
+        // Apply your effect logic here.
+    }
+}
+```
+
+Then, register your effect like normal.
+
 ### Events
 
 Many effects have their logic applied in other places. For example, the levitation effect is applied in the living entity movement handler. For modded `MobEffect`s, it often makes sense to apply them in an [event handler][events]. NeoForge also provides a few events related to effects:
@@ -115,6 +119,10 @@ MobEffectInstance instance = new MobEffectInstance(
 
 Several constructor overloads are available, omitting the last 1-5 parameters, respectively.
 
+:::info
+`MobEffectInstance`s are mutable. If you need a copy, call `new MobEffectInstance(oldInstance)`.
+:::
+
 ### Using `MobEffectInstance`s
 
 A `MobEffectInstance` can be added to an entity like so:
@@ -190,3 +198,4 @@ This should be called some time during setup, for example during [`FMLCommonSetu
 [item]: index.md
 [itemstack]: index.md#itemstacks
 [registration]: ../concepts/registries.md
+[uuidgen]: https://www.uuidgenerator.net/version4