Class SoundEvent

java.lang.Object
com.github.darksoulq.abyssallib.server.resource.asset.SoundEvent
public class SoundEvent extends Object
Represents a logical sound event within Minecraft (e.g., "entity.zombie.ambient").

A SoundEvent acts as the central trigger point that the client listens for. It does not contain audio itself, but instead houses one or more SoundEntry variants which point to physical .ogg files on the disk.

  • Constructor Summary

    Constructors
    Constructor
    Description
    SoundEvent(@NotNull org.bukkit.plugin.Plugin plugin, @NotNull String namespace, @NotNull String eventName)
    Constructs a new SoundEvent representation.

  • Method Summary

    Modifier and Type
    Method
    Description
    @NotNull SoundEntry
    addVariant(@NotNull String fileName)
    Adds a physical .ogg file variant to this sound event by attempting to read it from the plugin's internal resources.
    @NotNull SoundEntry
    addVariant(@NotNull String fileName, byte[] data)
    Adds a physical .ogg file variant to this sound event using raw byte data.
    @NotNull SoundEvent
    category(@NotNull org.bukkit.SoundCategory category)
    Assigns the master sound category governing this event's volume controls.
    void
    emitFiles(@NotNull Map<String,byte[]> files)
    Iterates through all registered variants and delegates the physical file byte writing process.
    @NotNull String
    id()
    Retrieves the fully qualified namespaced ID of this sound event used by Minecraft clients.
    void
    play(@NotNull org.bukkit.Location location)
    Plays this sound event at a specific world location for all nearby players with default volume and pitch.
    void
    play(@NotNull org.bukkit.Location location, float volume, float pitch)
    Plays this sound event at a specific world location for all nearby players with customized volume and pitch.
    void
    play(@NotNull org.bukkit.entity.Player player)
    Plays this sound event for a specific player at their current location with default volume and pitch.
    void
    play(@NotNull org.bukkit.entity.Player player, float volume, float pitch)
    Plays this sound event for a specific player at their current location with customized volume and pitch.
    @NotNull SoundEvent
    replace(boolean replace)
    Determines whether this custom event should completely overwrite a vanilla event of the same name.
    @NotNull SoundEvent
    subtitle(@Nullable String subtitle)
    Assigns the translation key or raw text to display when the client has subtitles enabled.
    @NotNull com.google.gson.JsonObject
    toJson()
    Serializes this event and all its encapsulated entries into the standard sounds.json format.

    Methods inherited from class Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • SoundEvent

      public SoundEvent(@NotNull @NotNull org.bukkit.plugin.Plugin plugin, @NotNull @NotNull String namespace, @NotNull @NotNull String eventName)
      Constructs a new SoundEvent representation.
      Parameters:
      plugin - The plugin context for file resolution.
      namespace - The namespace this event is registered under.
      eventName - The key identifier for this event.

  • Method Details

    • addVariant

      @NotNull public @NotNull SoundEntry addVariant(@NotNull @NotNull String fileName)
      Adds a physical .ogg file variant to this sound event by attempting to read it from the plugin's internal resources.
      Parameters:
      fileName - The path of the .ogg file relative to "resourcepack/{namespace}/sounds/".
      Returns:
      The newly generated SoundEntry to allow for localized variant modifications.
      Throws:
      RuntimeException - If the specified resource path cannot be found or read.

    • addVariant

      @NotNull public @NotNull SoundEntry addVariant(@NotNull @NotNull String fileName, byte[] data)
      Adds a physical .ogg file variant to this sound event using raw byte data.
      Parameters:
      fileName - The path string where the file should be placed.
      data - The raw .ogg audio byte array data.
      Returns:
      The newly generated SoundEntry to allow for localized variant modifications.

    • category

      @NotNull public @NotNull SoundEvent category(@NotNull @NotNull org.bukkit.SoundCategory category)
      Assigns the master sound category governing this event's volume controls.
      Parameters:
      category - The Bukkit SoundCategory to apply.
      Returns:
      This SoundEvent instance for chaining.

    • subtitle

      @NotNull public @NotNull SoundEvent subtitle(@Nullable @Nullable String subtitle)
      Assigns the translation key or raw text to display when the client has subtitles enabled.
      Parameters:
      subtitle - The subtitle string.
      Returns:
      This SoundEvent instance for chaining.

    • replace

      @NotNull public @NotNull SoundEvent replace(boolean replace)
      Determines whether this custom event should completely overwrite a vanilla event of the same name.
      Parameters:
      replace - True to replace existing vanilla sounds, false to append variants to them.
      Returns:
      This SoundEvent instance for chaining.

    • play

      public void play(@NotNull @NotNull org.bukkit.entity.Player player)
      Plays this sound event for a specific player at their current location with default volume and pitch.
      Parameters:
      player - The target player.

    • play

      public void play(@NotNull @NotNull org.bukkit.entity.Player player, float volume, float pitch)
      Plays this sound event for a specific player at their current location with customized volume and pitch.
      Parameters:
      player - The target player.
      volume - The volume scalar.
      pitch - The pitch scalar.

    • play

      public void play(@NotNull @NotNull org.bukkit.Location location)
      Plays this sound event at a specific world location for all nearby players with default volume and pitch.
      Parameters:
      location - The target origin location.

    • play

      public void play(@NotNull @NotNull org.bukkit.Location location, float volume, float pitch)
      Plays this sound event at a specific world location for all nearby players with customized volume and pitch.
      Parameters:
      location - The target origin location.
      volume - The volume scalar.
      pitch - The pitch scalar.

    • id

      @NotNull public @NotNull String id()
      Retrieves the fully qualified namespaced ID of this sound event used by Minecraft clients.
      Returns:
      The formatted namespaced ID (e.g., "namespace:event_name").

    • emitFiles

      public void emitFiles(@NotNull @NotNull Map<String,byte[]> files)
      Iterates through all registered variants and delegates the physical file byte writing process.
      Parameters:
      files - The global map of resource pack files.

    • toJson

      @NotNull public @NotNull com.google.gson.JsonObject toJson()
      Serializes this event and all its encapsulated entries into the standard sounds.json format.
      Returns:
      A compiled JsonObject representing the sound event logic.