From ae65f5a255b29851d746ecc9cbd03671c31cdfb8 Mon Sep 17 00:00:00 2001
From: Joseph B <josephbettendorff@yahoo.com>
Date: Sat, 25 Mar 2023 22:57:39 -0400
Subject: [PATCH] Rename RegisterParticleProviderEvent's register methods to
 describe what kind of particle providers they register (deprecating old
 methods to avoid breaking) and minor docs tweaks (#9388)

---
 .../event/RegisterParticleProvidersEvent.java | 102 +++++++++++++++---
 1 file changed, 87 insertions(+), 15 deletions(-)

diff --git a/src/main/java/net/minecraftforge/client/event/RegisterParticleProvidersEvent.java b/src/main/java/net/minecraftforge/client/event/RegisterParticleProvidersEvent.java
index eacb569436..4fc92d9bed 100644
--- a/src/main/java/net/minecraftforge/client/event/RegisterParticleProvidersEvent.java
+++ b/src/main/java/net/minecraftforge/client/event/RegisterParticleProvidersEvent.java
@@ -7,6 +7,7 @@ package net.minecraftforge.client.event;
 
 import net.minecraft.client.particle.ParticleEngine;
 import net.minecraft.client.particle.ParticleProvider;
+import net.minecraft.client.particle.TextureSheetParticle;
 import net.minecraft.core.particles.ParticleOptions;
 import net.minecraft.core.particles.ParticleType;
 import net.minecraftforge.eventbus.api.Cancelable;
@@ -39,38 +40,109 @@ public class RegisterParticleProvidersEvent extends Event implements IModBusEven
     }
 
     /**
-     * Registers a ParticleProvider for a non-json-based ParticleType.
-     * These particles do not receive a list of texture sprites to use for rendering themselves.
+     * <p>Registers a ParticleProvider for a non-json-based ParticleType.
+     * These particles do not receive a list of texture sprites to use for rendering themselves.</p>
+     *
+     * <p>There must be <strong>no</strong> particle json with an ID matching the ParticleType,
+     * or a redundant texture list error will occur when particle jsons load.</p>
+     *
      * @param <T> ParticleOptions used by the ParticleType and ParticleProvider.
      * @param type ParticleType to register a ParticleProvider for.
-     * There must be no particle json with an ID matching this ParticleType,
-     * or a redundant texture list error will occur when particle jsons load.
-     * @param provider ParticleProvider responsible for providing that ParticleType's particles.
+     * @param provider ParticleProvider function responsible for providing that ParticleType's particles.
      */
     @SuppressWarnings("deprecation")
-    public <T extends ParticleOptions> void register(ParticleType<T> type, ParticleProvider<T> provider)
-    {
+    public <T extends ParticleOptions> void registerSpecial(ParticleType<T> type, ParticleProvider<T> provider) {
         particleEngine.register(type, provider);
     }
 
+    /**
+     * <p>Registers a ParticleProvider for a non-json-based ParticleType.
+     * These particles do not receive a list of texture sprites to use for rendering themselves.</p>
+     *
+     * There must be <strong>no</strong> particle json with an ID matching the ParticleType,
+     * or a redundant texture list error will occur when particle jsons load.</p>
+     *
+     * @param <T> ParticleOptions used by the ParticleType and ParticleProvider.
+     * @param type ParticleType to register a ParticleProvider for.
+     * @param provider ParticleProvider function responsible for providing that ParticleType's particles.
+     * @see #registerSpecial
+     * @deprecated Renamed to {@link #registerSpecial}
+     */
+    @Deprecated(forRemoval = true, since = "1.19.4")
+    public <T extends ParticleOptions> void register(ParticleType<T> type, ParticleProvider<T> provider)
+    {
+        registerSpecial(type, provider);
+    }
+
+    /**
+     * <p>Registers a ParticleProvider for a json-based ParticleType with a single texture;
+     * the resulting {@link TextureSheetParticle}s will use that texture when created.</p>
+     *
+     * <p>A particle json with an ID matching the ParticleType <strong>must exist</strong> in the <code>particles</code> asset folder,
+     * or a missing texture list error will occur when particle jsons load.</p>
+     *
+     * @param <T> ParticleOptions used by the ParticleType and Sprite function.
+     * @param type ParticleType to register a ParticleProvider for.
+     * @param sprite Sprite function responsible for providing that ParticleType's particles.
+     */
     @SuppressWarnings("deprecation")
-    public <T extends ParticleOptions> void register(ParticleType<T> type, ParticleProvider.Sprite<T> sprite)
+    public <T extends ParticleOptions> void registerSprite(ParticleType<T> type, ParticleProvider.Sprite<T> sprite)
     {
         particleEngine.register(type, sprite);
     }
 
     /**
-     * Registers a ParticleProvider for a json-based ParticleType.
-     * Particle jsons define a list of texture sprites which the particle can use to render itself.
-     * @param <T> ParticleOptions used by the ParticleType and ParticleProvider.
+     * <p>Registers a ParticleProvider for a json-based ParticleType with a single texture;
+     * the resulting {@link TextureSheetParticle}s will use that texture when created.</p>
+     *
+     * <p>A particle json with an ID matching the ParticleType <strong>must exist</strong> in the <code>particles</code> asset folder,
+     * or a missing texture list error will occur when particle jsons load.</p>
+     *
+     * @param <T> ParticleOptions used by the ParticleType and Sprite function.
      * @param type ParticleType to register a ParticleProvider for.
-     * There must be a particle json with an ID matching this ParticleType in the <code>particles</code> asset folder,
-     * or a missing texture list error will occur when particle jsons load.
-     * @param registration SpriteParticleRegistration responsible for providing that ParticleType's particles.
+     * @param sprite Sprite function responsible for providing that ParticleType's particles.
+     * @see #registerSprite
+     * @deprecated Renamed to {@link #registerSprite}
+     */
+    @Deprecated(forRemoval = true, since = "1.19.4")
+    public <T extends ParticleOptions> void register(ParticleType<T> type, ParticleProvider.Sprite<T> sprite)
+    {
+        registerSprite(type, sprite);
+    }
+
+    /**
+     * <p>Registers a ParticleProvider for a json-based ParticleType.
+     * Particle jsons define a list of texture sprites which the particle can use to render itself.</p>
+     *
+     * <p>A particle json with an ID matching the ParticleType <strong>must exist</strong> in the <code>particles</code> asset folder,
+     * or a missing texture list error will occur when particle jsons load.</p>
+     *
+     * @param <T> ParticleOptions used by the ParticleType and SpriteParticleRegistration function.
+     * @param type ParticleType to register a particle provider for.
+     * @param registration SpriteParticleRegistration function responsible for providing that ParticleType's particles.
      */
     @SuppressWarnings("deprecation")
-    public <T extends ParticleOptions> void register(ParticleType<T> type, ParticleEngine.SpriteParticleRegistration<T> registration)
+    public <T extends ParticleOptions> void registerSpriteSet(ParticleType<T> type, ParticleEngine.SpriteParticleRegistration<T> registration)
     {
         particleEngine.register(type, registration);
     }
+
+    /**
+     * <p>Registers a ParticleProvider for a json-based ParticleType.
+     * Particle jsons define a list of texture sprites which the particle can use to render itself.</p>
+     *
+     * <p>A particle json with an ID matching the ParticleType <strong>must exist</strong> in the <code>particles</code> asset folder,
+     * or a missing texture list error will occur when particle jsons load.</p>
+     *
+     * @param <T> ParticleOptions used by the ParticleType and SpriteParticleRegistration function.
+     * @param type ParticleType to register a particle provider for.
+     * @param registration SpriteParticleRegistration function responsible for providing that ParticleType's particles.
+     * @see #registerSpriteSet
+     * @deprecated Renamed to {@link #registerSpriteSet}
+     */
+    @Deprecated(forRemoval = true, since = "1.19.4")
+    public <T extends ParticleOptions> void register(ParticleType<T> type, ParticleEngine.SpriteParticleRegistration<T> registration)
+    {
+        registerSpriteSet(type, registration);
+    }
 }