Package de.gurkenlabs.litiengine.sound

Class SoundEngine

java.lang.Object
de.gurkenlabs.litiengine.sound.SoundEngine
All Implemented Interfaces:
ILaunchable, IUpdateable
public final class SoundEngine extends Object implements IUpdateable, ILaunchable
This SoundEngine class provides all methods to play back sounds and music in your game. It allows to define the 2D coordinates of the sound or even pass in the source entity of the sound which will adjust the position according to the position of the entity.

The sound engine supports .wav, .mp3 and .ogg by default. If you need other file extensions, you have to write an own SPI implementation and inject it in your project.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    DEFAULT_MAX_DISTANCE
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    SoundEngine()
    You should never call this manually! Instead use the Game.audio() instance.

  • Method Summary

    Modifier and Type
    Method
    Description
    SFXPlayback
    createSound(Sound sound, Supplier<Point2D> supplier, boolean loop, int range, float volume)
    Creates an SFXPlayback object that can be configured prior to starting.
    void
    fadeMusic(int duration)
    Fades out all music volume to 0 over the specified time.
    void
    fadeMusic(int duration, float target, TweenFunction easeType)
    Fades all music volume to a given value over the specified time.
    Collection<MusicPlayback>
    getAllMusic()
    Gets a list of all music playbacks.
    int
    getMaxDistance()
    Gets the maximum distance from the listener at which a sound source can still be heard.
    MusicPlayback
    getMusic()
    Gets the "main" music that is playing.
    MusicPlayback
    playMusic(Sound music)
    Sets the currently playing track to a LoopedTrack with the specified music Sound.
    MusicPlayback
    playMusic(Track track)
    Sets the currently playing track to the specified track.
    MusicPlayback
    playMusic(Track track, boolean restart)
    Sets the currently playing track to the specified track.
    MusicPlayback
    playMusic(Track track, boolean restart, boolean stop)
    Plays the specified track.
    MusicPlayback
    playMusic(Track track, Consumer<? super MusicPlayback> config, boolean restart, boolean stop)
    Plays the specified track, optionally configuring it before starting.
    MusicPlayback
    playMusic(String musicName)
    Sets the currently playing track to a LoopedTrack with the sound defined by the specified music name.
    SFXPlayback
    playSound(Sound sound)
    Plays the specified sound with the volume configured in the SOUND config with a center pan.
    SFXPlayback
    playSound(Sound sound, boolean loop)
    Plays the specified sound with the volume configured in the SOUND config with a center pan.
    SFXPlayback
    playSound(Sound sound, boolean loop, int range)
    Plays the specified sound with the volume configured in the SOUND config with a center pan.
    SFXPlayback
    playSound(Sound sound, boolean loop, int range, float volume)
    Plays the specified sound with the volume configured in the SOUND config with a center pan.
    SFXPlayback
    playSound(Sound sound, double x, double y)
    Plays the specified sound at the specified location and updates the volume and pan in relation to the listener location.
    SFXPlayback
    playSound(Sound sound, double x, double y, boolean loop)
    Plays the specified sound at the specified location and updates the volume and pan in relation to the listener location.
    SFXPlayback
    playSound(Sound sound, IEntity entity)
    Plays the specified sound and updates its volume and pan by the current entity location in relation to the listener location.
    SFXPlayback
    playSound(Sound sound, IEntity entity, boolean loop)
    Plays the specified sound and updates its volume and pan by the current entity location in relation to the listener location.
    SFXPlayback
    playSound(Sound sound, IEntity entity, boolean loop, int range)
    Plays the specified sound and updates its volume and pan by the current entity location in relation to the listener location.
    SFXPlayback
    playSound(Sound sound, IEntity entity, boolean loop, int range, float volume)
    Plays the specified sound and updates its volume and pan by the current entity location in relation to the listener location.
    SFXPlayback
    playSound(Sound sound, Point2D location)
    Plays the specified sound at the specified location and updates the volume and pan in relation to the listener location.
    SFXPlayback
    playSound(Sound sound, Point2D location, boolean loop)
    Plays the specified sound at the specified location and updates the volume and pan in relation to the listener location.
    SFXPlayback
    playSound(Sound sound, Point2D location, boolean loop, int range)
    Plays the specified sound at the specified location and updates the volume and pan in relation to the listener location.
    SFXPlayback
    playSound(Sound sound, Point2D location, boolean loop, int range, float volume)
    Plays the specified sound at the specified location and updates the volume and pan in relation to the listener location.
    SFXPlayback
    playSound(String soundName)
    Plays a Sound with the specified name with the volume configured in the SOUND config with a center pan.
    SFXPlayback
    playSound(String soundName, boolean loop)
    Plays a Sound with the specified name with the volume configured in the SOUND config with a center pan.
    SFXPlayback
    playSound(String soundName, double x, double y)
    Plays a Sound with the specified name at the specified location and updates the volume and pan in relation to the listener location.
    SFXPlayback
    playSound(String soundName, double x, double y, boolean loop)
    Plays a Sound with the specified name at the specified location and updates the volume and pan in relation to the listener location.
    SFXPlayback
    playSound(String soundName, IEntity entity)
    Plays a Sound with the specified name and updates its volume and pan by the current entity location in relation to the listener location.
    SFXPlayback
    playSound(String soundName, IEntity entity, boolean loop)
    Plays a Sound with the specified name and updates its volume and pan by the current entity location in relation to the listener location.
    SFXPlayback
    playSound(String soundName, Point2D location)
    Plays a Sound with the specified name at the specified location and updates the volume and pan in relation to the listener location.
    SFXPlayback
    playSound(String soundName, Point2D location, boolean loop)
    Plays a Sound with the specified name at the specified location and updates the volume and pan in relation to the listener location.
    void
    setListenerLocationCallback(UnaryOperator<Point2D> callback)
    This method allows to set the callback that is used by the SoundEngine to determine where the listener location is.
    void
    setMaxDistance(int radius)
    Sets the default maximum distance from the listener at which a sound source can still be heard.
    void
    start()
    Starts the operation of this instance.
    void
    stopMusic()
    Stops the playback of the current background music.
    void
    terminate()
    Terminates the operation of this instance.
    void
    update()
    This method is called by the game loop on all objects that are attached to the loop.

    Methods inherited from class java.lang.Object

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

  • Field Details

  • Constructor Details

    • SoundEngine

      public SoundEngine()
      You should never call this manually! Instead use the Game.audio() instance.
      See Also:

  • Method Details

    • getMaxDistance

      public int getMaxDistance()
      Gets the maximum distance from the listener at which a sound source can still be heard.
      Returns:
      The maximum distance at which a sound can be heard.

    • playMusic

      public MusicPlayback playMusic(String musicName)
      Sets the currently playing track to a LoopedTrack with the sound defined by the specified music name. This has no effect if the specified track is already playing.
      Parameters:
      musicName - The name of the Sound to be played.
      Returns:
      The playback of the music

    • playMusic

      public MusicPlayback playMusic(Sound music)
      Sets the currently playing track to a LoopedTrack with the specified music Sound. This has no effect if the specified track is already playing.
      Parameters:
      music - The Sound to be played.
      Returns:
      The playback of the music

    • playMusic

      public MusicPlayback playMusic(Track track)
      Sets the currently playing track to the specified track. This has no effect if the specified track is already playing.
      Parameters:
      track - The track to play
      Returns:
      The playback of the music

    • playMusic

      public MusicPlayback playMusic(Track track, boolean restart)
      Sets the currently playing track to the specified track.
      Parameters:
      track - The track to play
      restart - Whether to restart if the specified track is already playing, determined by Object.equals(Object)
      Returns:
      The playback of the music

    • playMusic

      public MusicPlayback playMusic(Track track, boolean restart, boolean stop)
      Plays the specified track.
      Parameters:
      track - The track to play
      restart - Whether to restart if the specified track is already playing, determined by Object.equals(Object)
      stop - Whether to stop an existing track if present
      Returns:
      The playback of the music

    • playMusic

      public MusicPlayback playMusic(Track track, Consumer<? super MusicPlayback> config, boolean restart, boolean stop)
      Plays the specified track, optionally configuring it before starting.
      Parameters:
      track - The track to play
      config - A call to configure the playback prior to starting, which can be null
      restart - Whether to restart if the specified track is already playing, determined by Object.equals(Object)
      stop - Whether to stop an existing track if present
      Returns:
      The playback of the music

    • fadeMusic

      public void fadeMusic(int duration)
      Fades out all music volume to 0 over the specified time.
      Parameters:
      duration - The fade duration in milliseconds

    • fadeMusic

      public void fadeMusic(int duration, float target, TweenFunction easeType)
      Fades all music volume to a given value over the specified time.
      Parameters:
      duration - The fade duration in milliseconds
      target - The target volume.
      easeType - The easing Function used for Tweening the volume

    • getMusic

      public MusicPlayback getMusic()
      Gets the "main" music that is playing. This usually means the last call to playMusic, though if the music has been stopped it will be null.
      Returns:
      The main music, which could be null.

    • getAllMusic

      public Collection<MusicPlayback> getAllMusic()
      Gets a list of all music playbacks.
      Returns:
      A list of all music playbacks.

    • playSound

      public SFXPlayback playSound(Sound sound, IEntity entity)
      Plays the specified sound and updates its volume and pan by the current entity location in relation to the listener location.
      Parameters:
      sound - The sound to play.
      entity - The entity at which location the sound should be played.
      Returns:
      An SFXPlayback instance that allows to further process and control the played sound.

    • playSound

      public SFXPlayback playSound(String soundName, IEntity entity)
      Plays a Sound with the specified name and updates its volume and pan by the current entity location in relation to the listener location.
      Parameters:
      soundName - The name of the sound to play.
      entity - The entity at which location the sound should be played.
      Returns:
      An SFXPlayback instance that allows to further process and control the played sound.

    • playSound

      public SFXPlayback playSound(Sound sound, IEntity entity, boolean loop)
      Plays the specified sound and updates its volume and pan by the current entity location in relation to the listener location.
      Parameters:
      sound - The sound to play.
      entity - The entity at which location the sound should be played.
      loop - Determines whether this playback should be looped or not.
      Returns:
      An SFXPlayback instance that allows to further process and control the played sound.

    • playSound

      public SFXPlayback playSound(Sound sound, IEntity entity, boolean loop, int range)
      Plays the specified sound and updates its volume and pan by the current entity location in relation to the listener location.
      Parameters:
      sound - The sound to play.
      entity - The entity at which location the sound should be played.
      loop - Determines whether this playback should be looped or not.
      range - the range in pixels for which this sound can be heard
      Returns:
      An SFXPlayback instance that allows to further process and control the played sound.

    • playSound

      public SFXPlayback playSound(Sound sound, IEntity entity, boolean loop, int range, float volume)
      Plays the specified sound and updates its volume and pan by the current entity location in relation to the listener location.
      Parameters:
      sound - The sound to play.
      entity - The entity at which location the sound should be played.
      loop - Determines whether this playback should be looped or not.
      range - the range in pixels for which this sound can be heard
      volume - The volume modifier for the sound playback instance.
      Returns:
      An SFXPlayback instance that allows to further process and control the played sound.

    • playSound

      public SFXPlayback playSound(String soundName, IEntity entity, boolean loop)
      Plays a Sound with the specified name and updates its volume and pan by the current entity location in relation to the listener location.
      Parameters:
      soundName - The name of the sound to play.
      entity - The entity at which location the sound should be played.
      loop - Determines whether this playback should be looped or not.
      Returns:
      An SFXPlayback instance that allows to further process and control the played sound.

    • playSound

      public SFXPlayback playSound(Sound sound, Point2D location)
      Plays the specified sound at the specified location and updates the volume and pan in relation to the listener location.
      Parameters:
      sound - The sound to play.
      location - The location at which to play the sound.
      Returns:
      An SFXPlayback instance that allows to further process and control the played sound.

    • playSound

      public SFXPlayback playSound(String soundName, Point2D location)
      Plays a Sound with the specified name at the specified location and updates the volume and pan in relation to the listener location.
      Parameters:
      soundName - The name of the sound to play.
      location - The location at which to play the sound.
      Returns:
      An SFXPlayback instance that allows to further process and control the played sound.

    • playSound

      public SFXPlayback playSound(Sound sound, double x, double y)
      Plays the specified sound at the specified location and updates the volume and pan in relation to the listener location.
      Parameters:
      sound - The sound to play.
      x - The x-coordinate of the location at which to play the sound.
      y - The y-coordinate of the location at which to play the sound.
      Returns:
      An SFXPlayback instance that allows to further process and control the played sound.

    • playSound

      public SFXPlayback playSound(String soundName, double x, double y)
      Plays a Sound with the specified name at the specified location and updates the volume and pan in relation to the listener location.
      Parameters:
      soundName - The name of the sound to play.
      x - The x-coordinate of the location at which to play the sound.
      y - The y-coordinate of the location at which to play the sound.
      Returns:
      An SFXPlayback instance that allows to further process and control the played sound.

    • playSound

      public SFXPlayback playSound(Sound sound, Point2D location, boolean loop)
      Plays the specified sound at the specified location and updates the volume and pan in relation to the listener location.
      Parameters:
      sound - The sound to play.
      location - The location at which to play the sound.
      loop - Determines whether this playback should be looped or not.
      Returns:
      An SFXPlayback instance that allows to further process and control the played sound.

    • playSound

      public SFXPlayback playSound(Sound sound, Point2D location, boolean loop, int range)
      Plays the specified sound at the specified location and updates the volume and pan in relation to the listener location.
      Parameters:
      sound - The sound to play.
      location - The location at which to play the sound.
      loop - Determines whether this playback should be looped or not.
      range - the range in pixels for which this sound can be heard
      Returns:
      An SFXPlayback instance that allows to further process and control the played sound.

    • playSound

      public SFXPlayback playSound(Sound sound, Point2D location, boolean loop, int range, float volume)
      Plays the specified sound at the specified location and updates the volume and pan in relation to the listener location.
      Parameters:
      sound - The sound to play.
      location - The location at which to play the sound.
      loop - Determines whether this playback should be looped or not.
      range - the range in pixels for which this sound can be heard
      volume - The volume modifier for the sound playback instance.
      Returns:
      An SFXPlayback instance that allows to further process and control the played sound.

    • playSound

      public SFXPlayback playSound(String soundName, Point2D location, boolean loop)
      Plays a Sound with the specified name at the specified location and updates the volume and pan in relation to the listener location.
      Parameters:
      soundName - The name of the sound to play.
      location - The location at which to play the sound.
      loop - Determines whether this playback should be looped or not.
      Returns:
      An SFXPlayback instance that allows to further process and control the played sound.

    • playSound

      public SFXPlayback playSound(Sound sound, double x, double y, boolean loop)
      Plays the specified sound at the specified location and updates the volume and pan in relation to the listener location.
      Parameters:
      sound - The sound to play.
      x - The x-coordinate of the location at which to play the sound.
      y - The y-coordinate of the location at which to play the sound.
      loop - Determines whether this playback should be looped or not.
      Returns:
      An SFXPlayback instance that allows to further process and control the played sound.

    • playSound

      public SFXPlayback playSound(String soundName, double x, double y, boolean loop)
      Plays a Sound with the specified name at the specified location and updates the volume and pan in relation to the listener location.
      Parameters:
      soundName - The name of the sound to play.
      x - The x-coordinate of the location at which to play the sound.
      y - The y-coordinate of the location at which to play the sound.
      loop - Determines whether this playback should be looped or not.
      Returns:
      An SFXPlayback instance that allows to further process and control the played sound.

    • playSound

      public SFXPlayback playSound(Sound sound)
      Plays the specified sound with the volume configured in the SOUND config with a center pan.
      Parameters:
      sound - The sound to play.
      Returns:
      An SFXPlayback instance that allows to further process and control the played sound.

    • playSound

      public SFXPlayback playSound(String soundName)
      Plays a Sound with the specified name with the volume configured in the SOUND config with a center pan.
      Parameters:
      soundName - The name of the sound to play.
      Returns:
      An SFXPlayback instance that allows to further process and control the played sound.

    • playSound

      public SFXPlayback playSound(Sound sound, boolean loop)
      Plays the specified sound with the volume configured in the SOUND config with a center pan.
      Parameters:
      sound - The sound to play.
      loop - Determines whether this playback should be looped or not.
      Returns:
      An SFXPlayback instance that allows to further process and control the played sound.

    • playSound

      public SFXPlayback playSound(Sound sound, boolean loop, int range)
      Plays the specified sound with the volume configured in the SOUND config with a center pan.
      Parameters:
      sound - The sound to play.
      loop - Determines whether this playback should be looped or not.
      range - the range in pixels for which this sound can be heard
      Returns:
      An SFXPlayback instance that allows to further process and control the played sound.

    • playSound

      public SFXPlayback playSound(Sound sound, boolean loop, int range, float volume)
      Plays the specified sound with the volume configured in the SOUND config with a center pan.
      Parameters:
      sound - The sound to play.
      loop - Determines whether this playback should be looped or not.
      range - the range in pixels for which this sound can be heard
      volume - The volume modifier for the sound playback instance.
      Returns:
      An SFXPlayback instance that allows to further process and control the played sound.

    • playSound

      public SFXPlayback playSound(String soundName, boolean loop)
      Plays a Sound with the specified name with the volume configured in the SOUND config with a center pan.
      Parameters:
      soundName - The name of the sound to play.
      loop - Determines whether this playback should be looped or not.
      Returns:
      An SFXPlayback instance that allows to further process and control the played sound.

    • setMaxDistance

      public void setMaxDistance(int radius)
      Sets the default maximum distance from the listener at which a sound source can still be heard. If the distance between the sound source and the listener is greater than the specified value, the volume is set to 0.
      Parameters:
      radius - The maximum distance at which sounds can still be heard.

    • stopMusic

      public void stopMusic()
      Stops the playback of the current background music.

    • createSound

      public SFXPlayback createSound(Sound sound, Supplier<Point2D> supplier, boolean loop, int range, float volume)
      Creates an SFXPlayback object that can be configured prior to starting. Also allows for a custom source supplier.

      Unlike the playSound methods, the SFXPlayback objects returned by this method must be started using the SoundPlayback.start() method. However, necessary resources are acquired immediately upon calling this method, and will remain in use until the playback is either cancelled or finalized.

      Parameters:
      sound - The sound to play
      supplier - A function to get the sound's current source location (the sound is statically positioned if the location is null)
      loop - Whether to loop the sound
      range - the range in pixels for which this sound can be heard
      volume - The volume modifier for the sound playback instance.
      Returns:
      An SFXPlayback object that can be configured prior to starting, but will need to be manually started.

    • setListenerLocationCallback

      public void setListenerLocationCallback(UnaryOperator<Point2D> callback)
      This method allows to set the callback that is used by the SoundEngine to determine where the listener location is.

      If not explicitly set, the SoundEngine uses the camera focus (center of the screen) as listener location.

      Parameters:
      callback - The callback that determines the location of the sound listener.

    • start

      public void start()
      Description copied from interface: ILaunchable
      Starts the operation of this instance.
      Specified by:
      start in interface ILaunchable

    • terminate

      public void terminate()
      Description copied from interface: ILaunchable
      Terminates the operation of this instance.
      Specified by:
      terminate in interface ILaunchable

    • update

      public void update()
      Description copied from interface: IUpdateable
      This method is called by the game loop on all objects that are attached to the loop. It's called on every tick of the loop and the frequency can be configured using the ClientConfiguration.
      Specified by:
      update in interface IUpdateable
      See Also: