add(api/enums): particle and sound effect enumerations (#1154)

* add(api/enums): particle and sound effect enumerations

- Adds new GregTech API enumerations:
  - `ParticleFX`: Enumerates known EntityFX particles.
  - `SoundResource`: Enumerates known sounds with, id and ResourceLocation.
- Refactors code to use the new enumerations instead of string literals.
- Uses `ParticleFX` and `onRandomDisplayTick` to improve or implement
  new particle effects for these machines:
  - BBF: Adds random flames in front of the firebox.
  - Steam machines: Changes pressure-exhaust particles to white vapour,
    rather than dark smoke.
  - Magic Energy Absorber: Adds random effect, of absorbed magical purple
    particles, by the EnderDragon Egg siphon.
  - Forge Hammer: Adds sparse random sparks, ejected from the main face.

4 files changed, 113 insertions, 22 deletions

diff --git a/src/main/java/gregtech/api/util/GT_FoodStat.java b/src/main/java/gregtech/api/util/GT_FoodStat.java
index 193977476a..87c38a8073 100644
--- a/src/main/java/gregtech/api/util/GT_FoodStat.java
+++ b/src/main/java/gregtech/api/util/GT_FoodStat.java
@@ -1,6 +1,7 @@
 package gregtech.api.util;
 
 import gregtech.api.damagesources.GT_DamageSources;
+import gregtech.api.enums.SoundResource;
 import gregtech.api.interfaces.IFoodStat;
 import gregtech.api.items.GT_MetaBase_Item;
 import net.minecraft.entity.player.EntityPlayer;
@@ -70,7 +71,7 @@ public class GT_FoodStat implements IFoodStat {
             aPlayer.dropPlayerItemWithRandomChoice(tStack, true);
 
         new WorldSpawnedEventBuilder.SoundAtEntityEventBuilder()
-                .setIdentifier("random.burp")
+                .setIdentifier(SoundResource.RANDOM_BURP)
                 .setVolume(0.5F)
                 .setPitch(aPlayer.worldObj.rand.nextFloat() * 0.1F + 0.9F)
                 .setEntity(aPlayer)
diff --git a/src/main/java/gregtech/api/util/GT_PlayedSound.java b/src/main/java/gregtech/api/util/GT_PlayedSound.java
index 82c728ff8b..fa27bbb9d4 100644
--- a/src/main/java/gregtech/api/util/GT_PlayedSound.java
+++ b/src/main/java/gregtech/api/util/GT_PlayedSound.java
@@ -1,18 +1,29 @@
 package gregtech.api.util;
 
+import net.minecraft.util.ResourceLocation;
+
 import static gregtech.api.enums.GT_Values.E;
 
 public class GT_PlayedSound {
     public final String mSoundName;
     public final int mX, mY, mZ;
 
-    public GT_PlayedSound(String aSoundName, double aX, double aY, double aZ) {
-        mSoundName = aSoundName == null ? E : aSoundName;
+    public GT_PlayedSound(ResourceLocation aSoundResourceLocation, double aX, double aY, double aZ) {
+        mSoundName = aSoundResourceLocation.toString();
         mX = (int) aX;
         mY = (int) aY;
         mZ = (int) aZ;
     }
 
+    /**
+     * @inheritDoc
+     * @deprecated Use {@link GT_PlayedSound(ResourceLocation, double, double, double)}
+     */
+    @Deprecated
+    public GT_PlayedSound(String aSoundName, double aX, double aY, double aZ) {
+        this(new ResourceLocation(aSoundName == null ? E : aSoundName), aX, aY, aZ);
+    }
+
     @Override
     public boolean equals(Object aObject) {
         if (aObject instanceof GT_PlayedSound) {
diff --git a/src/main/java/gregtech/api/util/GT_Utility.java b/src/main/java/gregtech/api/util/GT_Utility.java
index 70659c7003..e244bb4460 100644
--- a/src/main/java/gregtech/api/util/GT_Utility.java
+++ b/src/main/java/gregtech/api/util/GT_Utility.java
@@ -14,13 +14,7 @@ import gregtech.api.GregTech_API;
 import gregtech.api.damagesources.GT_DamageSources;
 import gregtech.api.damagesources.GT_DamageSources.DamageSourceHotItem;
 import gregtech.api.enchants.Enchantment_Radioactivity;
-import gregtech.api.enums.GT_Values;
-import gregtech.api.enums.ItemList;
-import gregtech.api.enums.Materials;
-import gregtech.api.enums.OrePrefixes;
-import gregtech.api.enums.SubTag;
-import gregtech.api.enums.Textures;
-import gregtech.api.enums.ToolDictNames;
+import gregtech.api.enums.*;
 import gregtech.api.events.BlockScanningEvent;
 import gregtech.api.interfaces.IBlockContainer;
 import gregtech.api.interfaces.IDebugableBlock;
@@ -76,11 +70,7 @@ import net.minecraft.potion.Potion;
 import net.minecraft.potion.PotionEffect;
 import net.minecraft.tileentity.TileEntity;
 import net.minecraft.tileentity.TileEntityChest;
-import net.minecraft.util.AxisAlignedBB;
-import net.minecraft.util.ChatComponentText;
-import net.minecraft.util.DamageSource;
-import net.minecraft.util.EnumChatFormatting;
-import net.minecraft.util.MathHelper;
+import net.minecraft.util.*;
 import net.minecraft.world.World;
 import net.minecraft.world.WorldServer;
 import net.minecraft.world.chunk.Chunk;
@@ -1387,7 +1377,7 @@ public class GT_Utility {
             }
         }
         ItemStack[] tStack = GT_OreDictUnificator.getStackArray(true, aOutput);
-        if(tStack==null||(tStack.length>0&& areStacksEqual(aInput, tStack[0])))return false;
+        if(tStack.length > 0 && areStacksEqual(aInput, tStack[0]))return false;
         if (tOreName != null) {
         	if(tOreName.toString().equals("dustAsh")&&tStack[0].getUnlocalizedName().equals("tile.volcanicAsh"))return false;
             aRecipeList.put(new RecipeInputOreDict(tOreName.toString(), aInput.stackSize), new RecipeOutput(aNBT, tStack));
@@ -1443,31 +1433,91 @@ public class GT_Utility {
         return doSoundAtClient(aSoundName, aTimeUntilNextSound, aSoundStrength, GT.getThePlayer());
     }
 
+    public static boolean doSoundAtClient(SoundResource sound, int aTimeUntilNextSound, float aSoundStrength) {
+        return doSoundAtClient(sound.resourceLocation, aTimeUntilNextSound, aSoundStrength, GT.getThePlayer());
+    }
+
+    public static boolean doSoundAtClient(ResourceLocation aSoundResourceLocation, int aTimeUntilNextSound, float aSoundStrength) {
+        return doSoundAtClient(aSoundResourceLocation, aTimeUntilNextSound, aSoundStrength, GT.getThePlayer());
+    }
+
     public static boolean doSoundAtClient(String aSoundName, int aTimeUntilNextSound, float aSoundStrength, Entity aEntity) {
         if (aEntity == null) return false;
         return doSoundAtClient(aSoundName, aTimeUntilNextSound, aSoundStrength, aEntity.posX, aEntity.posY, aEntity.posZ);
     }
 
+    public static boolean doSoundAtClient(ResourceLocation aSoundResourceLocation, int aTimeUntilNextSound, float aSoundStrength, Entity aEntity) {
+        if (aEntity == null) return false;
+        return doSoundAtClient(aSoundResourceLocation.toString(), aTimeUntilNextSound, aSoundStrength, aEntity.posX, aEntity.posY, aEntity.posZ);
+    }
+
+    public static boolean doSoundAtClient(ResourceLocation aSoundResourceLocation, int aTimeUntilNextSound, float aSoundStrength, double aX, double aY, double aZ) {
+        return doSoundAtClient(aSoundResourceLocation, aTimeUntilNextSound, aSoundStrength, 1.01818028F, aX, aY, aZ);
+    }
+
+    /**
+     * @inheritDoc
+     * @deprecated Use {@link #doSoundAtClient(ResourceLocation, int, float, double, double, double)}
+     */
+    @Deprecated
     public static boolean doSoundAtClient(String aSoundName, int aTimeUntilNextSound, float aSoundStrength, double aX, double aY, double aZ) {
-        return doSoundAtClient(aSoundName, aTimeUntilNextSound, aSoundStrength, 1.01818028F, aX, aY, aZ);
+        return doSoundAtClient(new ResourceLocation(aSoundName), aTimeUntilNextSound, aSoundStrength, 1.01818028F, aX, aY, aZ);
     }
 
-    public static boolean doSoundAtClient(String aSoundName, int aTimeUntilNextSound, float aSoundStrength, float aSoundModulation, double aX, double aY, double aZ) {
-        if (isStringInvalid(aSoundName) || !FMLCommonHandler.instance().getEffectiveSide().isClient() || GT.getThePlayer() == null || !GT.getThePlayer().worldObj.isRemote)
+    public static boolean doSoundAtClient(SoundResource aSound, int aTimeUntilNextSound, float aSoundStrength, double aX, double aY, double aZ) {
+        return doSoundAtClient(aSound.resourceLocation, aTimeUntilNextSound, aSoundStrength, aX, aY, aZ);
+    }
+
+    public static boolean doSoundAtClient(
+            SoundResource aSound, int aTimeUntilNextSound, float aSoundStrength, float aSoundModulation,
+            double aX, double aY, double aZ) {
+        return doSoundAtClient(aSound.resourceLocation, aTimeUntilNextSound, aSoundStrength, aSoundModulation, aX, aY, aZ);
+    }
+
+
+    public static boolean doSoundAtClient(
+        ResourceLocation aSoundResourceLocation, int aTimeUntilNextSound, float aSoundStrength, float aSoundModulation,
+        double aX, double aY, double aZ) {
+        if (!FMLCommonHandler.instance().getEffectiveSide().isClient()
+            || GT.getThePlayer() == null
+            || !GT.getThePlayer().worldObj.isRemote)
             return false;
         if (GregTech_API.sMultiThreadedSounds)
-            new Thread(new GT_Runnable_Sound(GT.getThePlayer().worldObj, MathHelper.floor_double(aX), MathHelper.floor_double(aY), MathHelper.floor_double(aZ), aTimeUntilNextSound, aSoundName, aSoundStrength, aSoundModulation), "Sound Effect").start();
+            new Thread(new GT_Runnable_Sound(
+                GT.getThePlayer().worldObj,
+                MathHelper.floor_double(aX), MathHelper.floor_double(aY), MathHelper.floor_double(aZ),
+                aTimeUntilNextSound, aSoundResourceLocation, aSoundStrength, aSoundModulation), "Sound Effect")
+                .start();
         else
-            new GT_Runnable_Sound(GT.getThePlayer().worldObj, MathHelper.floor_double(aX), MathHelper.floor_double(aY), MathHelper.floor_double(aZ), aTimeUntilNextSound, aSoundName, aSoundStrength, aSoundModulation).run();
+            new GT_Runnable_Sound(
+                GT.getThePlayer().worldObj,
+                MathHelper.floor_double(aX), MathHelper.floor_double(aY), MathHelper.floor_double(aZ),
+                aTimeUntilNextSound, aSoundResourceLocation, aSoundStrength, aSoundModulation).run();
         return true;
     }
 
+    /**
+     * @inheritDoc
+     * @Deprecated Use {@link #doSoundAtClient(ResourceLocation, int, float, float, double, double, double)}
+     */
+    @Deprecated
+    public static boolean doSoundAtClient(String aSoundName, int aTimeUntilNextSound, float aSoundStrength, float aSoundModulation, double aX, double aY, double aZ) {
+        if (isStringInvalid(aSoundName)) return false;
+        return doSoundAtClient(new ResourceLocation(aSoundName), aTimeUntilNextSound, aSoundStrength, aSoundModulation, aX, aY, aZ);
+    }
+
     public static boolean sendSoundToPlayers(World aWorld, String aSoundName, float aSoundStrength, float aSoundModulation, int aX, int aY, int aZ) {
         if (isStringInvalid(aSoundName) || aWorld == null || aWorld.isRemote) return false;
         NW.sendPacketToAllPlayersInRange(aWorld, new GT_Packet_Sound(aSoundName, aSoundStrength, aSoundModulation, aX, (short) aY, aZ), aX, aZ);
         return true;
     }
 
+    public static boolean sendSoundToPlayers(World aWorld, SoundResource sound, float aSoundStrength, float aSoundModulation, int aX, int aY, int aZ) {
+        if (aWorld == null || aWorld.isRemote) return false;
+        NW.sendPacketToAllPlayersInRange(aWorld, new GT_Packet_Sound(sound.resourceLocation.toString(), aSoundStrength, aSoundModulation, aX, (short) aY, aZ), aX, aZ);
+        return true;
+    }
+
     public static int stackToInt(ItemStack aStack) {
         if (isStackInvalid(aStack)) return 0;
         return itemToInt(aStack.getItem(), Items.feather.getDamage(aStack));
diff --git a/src/main/java/gregtech/api/util/WorldSpawnedEventBuilder.java b/src/main/java/gregtech/api/util/WorldSpawnedEventBuilder.java
index 354b3748be..f2bb79657a 100644
--- a/src/main/java/gregtech/api/util/WorldSpawnedEventBuilder.java
+++ b/src/main/java/gregtech/api/util/WorldSpawnedEventBuilder.java
@@ -27,7 +27,7 @@ public abstract class WorldSpawnedEventBuilder implements Runnable {
         return this;
     }
 
-    /* Methodes */
+    /* Methods */
 
     @SuppressWarnings("unchecked")
     public <U extends WorldSpawnedEventBuilder> void times(int times, Consumer<U> action) {
@@ -66,6 +66,7 @@ public abstract class WorldSpawnedEventBuilder implements Runnable {
     private interface IStringIdentifierWorldSpawnedEvent {
          String getIdentifier();
          IStringIdentifierWorldSpawnedEvent setIdentifier(String identifier);
+         IStringIdentifierWorldSpawnedEvent setIdentifier(Enum<?> identifier);
     }
 
     private interface ISoundWorldSpawnedEvent {
@@ -150,6 +151,12 @@ public abstract class WorldSpawnedEventBuilder implements Runnable {
             this.identifier = identifier;
             return this;
         }
+
+        @Override
+        public StringIdentifierPositionedWorldSpawnedEventBuilder setIdentifier(Enum<?> identifier){
+            this.identifier = identifier.toString();
+            return this;
+        }
     }
 
     private abstract static class SoundStringIdentifierPositionedWorldSpawnedEventBuilder extends StringIdentifierPositionedWorldSpawnedEventBuilder implements ISoundWorldSpawnedEvent {
@@ -221,6 +228,11 @@ public abstract class WorldSpawnedEventBuilder implements Runnable {
         }
 
         @Override
+        public ParticleEventBuilder setIdentifier(Enum<?> identifier) {
+            return (ParticleEventBuilder) super.setIdentifier(identifier);
+        }
+
+        @Override
         public void run() {
             if (getPosition() == null || getIdentifier() == null || getMotion() == null || getWorld() == null)
                 throw new IllegalStateException("Position, identifier, motion and world must be set");
@@ -256,6 +268,11 @@ public abstract class WorldSpawnedEventBuilder implements Runnable {
         }
 
         @Override
+        public SoundEffectEventBuilder setIdentifier(Enum<?> identifier) {
+            return (SoundEffectEventBuilder) super.setIdentifier(identifier);
+        }
+
+        @Override
         public SoundEffectEventBuilder setPitch(float pitch) {
             return (SoundEffectEventBuilder) super.setPitch(pitch);
         }
@@ -497,6 +514,12 @@ public abstract class WorldSpawnedEventBuilder implements Runnable {
         }
 
         @Override
+        public SoundAtEntityEventBuilder setIdentifier(Enum<?> identifier) {
+            this.identifier = identifier.toString();
+            return this;
+        }
+
+        @Override
         public float getPitch() {
             return pitch;
         }
@@ -556,6 +579,12 @@ public abstract class WorldSpawnedEventBuilder implements Runnable {
         }
 
         @Override
+        public SoundToNearExceptEventBuilder setIdentifier(Enum<?> identifier) {
+            this.identifier = identifier.toString();
+            return this;
+        }
+
+        @Override
         public float getPitch() {
             return pitch;
         }