Refactored Tater Effect registration and updated docs (#224)

* Refactored Tater Effect registration and updated docs Refactored Tater Effect to use RegistryEntry, since the StatusEffect itself isn't used much anymore. Updated related potion usage to reflect this change. Enhanced documentation with detailed instructions on applying effects programmatically. * Refactor effects documentation for clarity and structure Updated effects section to improve readability and consistency. Introduced a table format for argument descriptions and refined terminology for better understanding. * Satisfy the building process * Update develop/entities/effects.md Co-authored-by: Miroma <[email protected]> * Update develop/entities/effects.md * Add ReferenceMethods class for version-aware method access This commit introduces a static utility class to centralize version-aware internal method references, starting with `addTaterEffect`. Additionally, updated documentation now transcludes the new method for consistent and maintainable reference examples. * Satisfy the building process --------- Co-authored-by: Manchick0 <[email protected]> Co-authored-by: Calum H. <[email protected]> Co-authored-by: Miroma <[email protected]>
FabricMC · Dec 28, 2024 · 787ead4 · 787ead4
1 parent f2a45b6
commit 787ead4
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)));