Merge branch 'main' into pr/234

FabricMC · Dec 28, 2024 · a96073a · a96073a
2 parents 5427cf9 + 787ead4
commit a96073a
Show file tree

Hide file tree

Showing 4 changed files with 49 additions and 6 deletions.
diff --git a/develop/entities/effects.md b/develop/entities/effects.md
@@ -7,6 +7,7 @@ authors:
   - FireBlast
   - Friendly-Banana
   - SattesKrokodil
+  - Manchick0
 authors-nogithub:
   - siglong
   - tao0lu
@@ -57,10 +58,32 @@ language file.
 }
 ```
 
-### Testing {#testing}
+### Applying The Effect {#applying-the-effect}
 
-Use the command `/effect give @p fabric-docs-reference:tater` to give the player our Tater effect.
-Use `/effect clear @p fabric-docs-reference:tater` to remove the effect.
+It's worth taking a look at how you'd typically apply an effect to an entity.
+
+::: tip
+For a quick test, it might be a better idea to use the previously mentioned `/effect` command:
+
+```mcfunction
+effect give @p fabric-docs-reference:tater
+```
+
+:::
+
+To apply an effect internally, you'd want to use the `LivingEntity#addStatusEffect` method, which takes in
+a `StatusEffectInstance`, and returns a boolean, specifying whether the effect was successfully applied.
+
+@[code lang=java transcludeWith=:::1](@/reference/latest/src/main/java/com/example/docs/ReferenceMethods.java)
+
+| Argument    | Type                          | Description                                                                                                                                                                                                                   |
+|-------------|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `effect`    | `RegistryEntry<StatusEffect>` | A registry entry that represents the effect.                                                                                                                                                                                  |
+| `duration`  | `int`                         | The duration of the effect **in ticks**; **not** seconds                                                                                                                                                                      |
+| `amplifier` | `int`                         | The amplifier to the level of the effect. It doesn't correspond to the **level** of the effect, but is rather added on top. Hence, `amplifier` of `4` => level of `5`                                                         |
+| `ambient`   | `boolean`                     | This is a tricky one. It basically specifies that the effect was added by the environment (e.g. a **Beacon**) and doesn't have a direct cause. If `true`, the icon of the effect in the HUD will appear with an aqua overlay. |
+| `particles` | `boolean`                     | Whether to show particles.                                                                                                                                                                                                    |
+| `icon`      | `boolean`                     | Whether to display an icon of the effect in the HUD. The effect will be displayed in the inventory regardless of this flag.                                                                                                   |
 
 ::: info
 To create a potion that uses this effect, please see the [Potions](../items/potions) guide.

diff --git a/reference/latest/src/main/java/com/example/docs/ReferenceMethods.java b/reference/latest/src/main/java/com/example/docs/ReferenceMethods.java
@@ -0,0 +1,19 @@
+package com.example.docs;
+
+import net.minecraft.entity.LivingEntity;
+import net.minecraft.entity.effect.StatusEffectInstance;
+
+import com.example.docs.effect.FabricDocsReferenceEffects;
+
+/**
+ * A static-first class, used solely to provide version-aware
+ * references to internal methods.
+ */
+public class ReferenceMethods {
+	public static void addTaterEffect(LivingEntity entity) {
+		// :::1
+		var instance = new StatusEffectInstance(FabricDocsReferenceEffects.TATER, 5 * 20, 0, false, true, true);
+		entity.addStatusEffect(instance);
+		// :::1
+	}
+}
diff --git a/reference/latest/src/main/java/com/example/docs/effect/FabricDocsReferenceEffects.java b/reference/latest/src/main/java/com/example/docs/effect/FabricDocsReferenceEffects.java
@@ -3,16 +3,17 @@
 import net.minecraft.entity.effect.StatusEffect;
 import net.minecraft.registry.Registries;
 import net.minecraft.registry.Registry;
+import net.minecraft.registry.entry.RegistryEntry;
 import net.minecraft.util.Identifier;
 
 import net.fabricmc.api.ModInitializer;
 
 // :::1
 public class FabricDocsReferenceEffects implements ModInitializer {
-	public static final StatusEffect TATER_EFFECT;
+	public static final RegistryEntry<StatusEffect> TATER;
 
 	static {
-		TATER_EFFECT = Registry.register(Registries.STATUS_EFFECT, Identifier.of("fabric-docs-reference", "tater"), new TaterEffect());
+		TATER = Registry.registerReference(Registries.STATUS_EFFECT, Identifier.of("fabric-docs-reference", "tater"), new TaterEffect());
 	}
 
 	@Override

diff --git a/reference/latest/src/main/java/com/example/docs/potion/FabricDocsReferencePotions.java b/reference/latest/src/main/java/com/example/docs/potion/FabricDocsReferencePotions.java
@@ -21,7 +21,7 @@ public class FabricDocsReferencePotions implements ModInitializer {
 					Identifier.of("fabric-docs-reference", "tater"),
 					new Potion(
 							new StatusEffectInstance(
-									Registries.STATUS_EFFECT.getEntry(FabricDocsReferenceEffects.TATER_EFFECT),
+									FabricDocsReferenceEffects.TATER,
 									3600,
 									0)));