=begin
                            Audio Engine XT

Version: 1.2
Release date: 30/04/2009
Author: Marco Di Antonio -> aka BulletXt (bulletxt@gmail.com)
License: GNU General Public License 3


Features:
This audio engine will:
- pause BGM when a battle starts and resumes from where it stopped when battle ends!
- BGM is normally set from VX editor as you normally do!
  The audio engine is fully integrated with VX editor!
- by turning a switch to ON, BGM will continue playing in battle!
- by turning a switch to ON, you will have support for Random Battle BGM!
- BGM always automatically loops!
- by pressing a key, it will Pause the game with BGM/BGS volume lowered/muted!
- at battle end, Victory ME will fade out (so ME can be as long as you want)!
- you can make a BGM loop making it restart at any seconds of the song you want!


Instructions:
To start the game, don't start it anymore from Game.exe as you normally do,
instead start StartGame.exe . You can rename this exe if you want, and if you
do so, be sure to change the name in this script under in CONFIGURATION.
To use this engine in your already-made game, read INSTALL below.
IMPORTANT: all BMG files must be of the same type. For example, they must be all
           mp3s. MIDI files are not supported.

          
If you want to manually pause a BGM at a specific time, put a script call
inside an event and type:
$audioxt = "pause"

Note: BGM will stay in pause until a new BGM play request comes in.
      For example while in pause status,
      if you do a map transfer with a map's BGM set, the audio
      engine will get out of pause status and play the new song (or continue the
      previous one if BGM is the same).
      If you save the game with BGM set to pause, when you load the game BGM
      will remember its pause status. If in pause status and a battle starts,
      when it ends BGM won't resume.


Loop BGM with a seek at n seconds feature:
Given that BGM always automatically loops, you can however decide if BGM must
loop with a seek at n seconds of the song. For example, you can make the BGM loop
restarting at 20 seconds instead of 0.
To do this easy task, simply put a script call inside an event and type:
$audioxt = seconds
Replace the word "seconds" with a number in seconds, for example 20.
Example:
$audioxt = 20
This means that the current BGM will loop and restart at 20 seconds instead of 0.

NOTE: You must do a script call of this type each time you play a new BGM song if
      you want the new BGM to loop at n seconds. There is no need to call the
      script on contiguous maps that have the same BGM playing. When saving the
      game, the engine will automatically remember if the current playing BGM
      has looping set to restart at n seconds. Keep in mind that it makes
      sense to do this script call only if there is a playing BGM, this means
      the script call isn't memorized for "future" playing BGM, instead it must
      be called only once BGM is playing.


For your conveniance, this engine can make you restore normal loop without
seek at any time. Just put a script call inside an event and type:
$audioxt = "stop_seek"
      
      
IMPORTANT: avoid putting the script calls
           inside Parallel events that loop the code infinite times. This might
           hang the engine. Be sure to trigger the event to a new page set to
           something different than Parallel or Autorun. Don't forget this!
      
      
Supported CODEC formats are: wav | mp3 | wma
If you want to have other format supports, like OGG Vorbis,
be sure to install the codec for your Windows DirectShow Filters. If doing this,
when releasing the game you must be sure the players also have the codec
installed.
IMPORTANT: I can't guarantee the engine is stable when using other codecs, so
           I suggest to use only native supported codecs: wav | mp3 | wma



INSTALL Audio Engine XT to your project:
- copy Audio_Engine_XT script in your game (if you have other scripts, be sure to place this one under all of them)
- copy Audio_Engine_XT_Pause_Game script in your game (place it below Audio_Engine_XT script)
- copy Audio_Engine_XT_Save/Load script in your game (place it below Audio_Engine_XT_Pause_Game script)
- copy StartGame.exe and Rescue_Audio_XT.exe to the root folder of
  your game (same folder where Game.exe is located)
- copy the following dlls to root folder of game:
  /phonon4.dll
  /QtCore4.dll
  /QtGui4.dll
  /QtNetwork4.dll
  /msvcp90.dll and msvcr90.dll
- copy "phonon_backend" folder to the root folder of your game
- copy /Graphics/System/Pause.png file to /Graphics/System folder of your project.


This is the order of Audio Engine XT scripts positions in VX editor:

1: Audio_Engine_XT
2: Audio_Engine_XT_Pause_Game
3: Audio_Engine_XT_Save/Load

=end


############################## CONFIGURATION ###################################


#this is the name of the exe to start the game. Do not add file extension.
$audio_engine_xt_exe = "StartGame"

#this is the name of the Recover Audio engine exe. Do not add file extension.
$rescue_gui_engine_xt = "Rescue_Audio_XT"

=begin
this is a switch ID. If this switch is ON, the engine will continue
playing BGM in battle instead of going in pause. Of course battle song
won't play. By default the switch is OFF so BGM will go in pause when a battle
starts.
=end
CONTINUE_MAP_SONG_IN_BATTLE =  1

=begin
since all bgm's must be of the same type, here you can set the type. This is
actually the extension of the file. Remember that MIDI files aren't supported.
General possible settings are:
FORMAT_OF_SONGS = "mp3"
or
FORMAT_OF_SONGS = "wav"
or
FORMAT_OF_SONGS = "wma"
=end
FORMAT_OF_SONGS = "ogg"

#this is a switch ID. When ON, it enables Random Battle BGM!
ENABLE_RANDOM_BATTLE_BGM = 2
=begin
these are the Battle BGMs that you want to play randomly.
example:
BATTLE_BGMS_THAT_PLAY_RANDOMLY = ["Battle1", "Battle2","Battle3"]
Please note that a battle bgm will never play 2 times consecutively! In this way
you have a better random effect avoiding that a battle bgm plays in a battle and
then plays again in the immediate next battle.
You can change this array at any time in game through a script call inside
event. To do this type for example:
$audioxt_random_battle = ["r_Battle1", "r_Battle2","r_Battle3"]
=end
BATTLE_BGMS_THAT_PLAY_RANDOMLY = ["r_Battle1", "r_Battle2","r_Battle3"]


=begin
The following settings are only used if you want to have Game Pause support.
Be sure to have Audio_Engine_XT_Pause_Game script placed under this one and
remember to have a picture named "Pause" inside /Graphics/System folder of your
project game.
It is possible to pause game when you're in Map or inside a battle.
=end
=begin
this is a switch ID. If ON, it will disable Game Pause feature.
By default this switch is OFF so the game will go in Pause when
pressing a key(you can set the key below).
=end
GAME_PAUSE_DISABLE = 3

=begin
These are the volume in % you want the BGM/BGS volume to go down when you Pause
the game. If for example you set it to 60, it means the BGM will go down of 60%.
Of course, to mute volume simply set the value to 100.
Default % is: 60 . Value must be between 0 and 100.
=end
$audioxt_game_pause_bgm_bgs_volume = 60


=begin
Set the keyboard key you want to press to make the game go in Pause. Please
remember that this setting key isn't the corresponding keyboard key. Instead,
it is the VX key. Here is a general table about VX keys corresponding to the real
keyboard key:
________________________________
|  VX Key  =   Real Keyboard key |
|--------------------------------|
|  X       =   A keyboard key    |
|  Y       =   S keyboard key    |
|  Z       =   D keyboard key    |
|________________________________|

Of course you shouldn't set the Pause key to dash, enter, or call menu key :)
=end

GAME_PAUSE_VX_KEY = "Y" # This is VX key and not keyboard key!

                      #                                #
                      #                                #
####################### 3d Party Compatibility Scripts #########################
                      #                                #
                      #                                #
                      
=begin
This section is provided for conveniance. It adds compatibility with some well
known and used scripts.
Supported List:
- Worotana Neo Save 1.0 released on 04/05/2008 at http://www.rpgrevolution.com/forums/?showtopic=13382
=end


=begin
                            Worotana Neo Save

To enable compatibility, open Worotana Neo Save script and search for the
following lines and delete all of them:
  def do_load    
    file = File.open(make_filename(@last_slot_index), "rb")
    read_save_data(file)
    file.close
    $scene = Scene_Map.new
    RPG::BGM.fade(1500)
    Graphics.fadeout(60)
    Graphics.wait(40)
    @last_bgm.play
    @last_bgs.play
  end
  
After you deleted the function, please set below WOROTANA_NEO_SAVE to true.
Finally, decide the ID switch to use for $worotana_neo_save_system. The switch
automatically turns ON if WOROTANA_NEO_SAVE is set to true.
=end
#default is false. Do not put Worotana Neo Save script in VX editor if this
#setting is set to false!
WOROTANA_NEO_SAVE = true
#this is an ID switch.
#If WOROTANA_NEO_SAVE is set to true, it automatically turns the switch ON.
$worotana_neo_save_system = 100

################################################################################
#############################                   ################################
############################# END CONFIGURATION ################################
#############################                   ################################
################################################################################




########################### Initialize Global Variables ########################
#start $audioxt as nil. this changes once a song is play|stop|pause
$audioxt = "nil"
#adds .exe to the CONFIGURATION string of the file name of the recover engine
$rescue_gui_engine_xt += ".exe"
=begin
this boolean becomes true only if the engine crashes and the recover GUI
mode starts. this is needed when closing the game to know if there is the need
to kill the gui or not.
IMPORTANT: this boolean becomes true also when starting game in TEST mode
=end
$audioxt_has_crashed_GUI_started = false

#when false, the map bgm resumes from pause status when a battle ends.
#this is only set to true when there is a pause request
$audioxt_song_in_pause_no_resume = false

=begin
this is a crucial global variable. this always tells the current map who is the
current playing song. if checkbox isn't enabled, this variable is always set
to the current playing bgm. It's set to "nil,nil" at first launch, or in special
cases like if in a manual pause request, a game over, a fadeout, or if going back
to title
=end
$audioxt_special_bgm_id = "nil,nil"
#this variable is like $audioxt_special_bgm_id. instead of id, it has the volume.
#this value is set everytime $audioxt_special_bgm_id is set..
$audioxt_special_volume = 100

#this variable is used when Random Battle BGM switch is ON. It's set to nil
#to avoid that at first run, it adds "nil" to the Battle BGM array
$audioxt_battle_bgm_random_tmp_id = "nil"

#set game pause switch globally
$audioxt_disable_game_pause = GAME_PAUSE_DISABLE
#set Game Pause key globally
$audioxt_game_pause_keyboard_key_activate = GAME_PAUSE_VX_KEY

#this holds the random battle array globally
$audioxt_random_battle = BATTLE_BGMS_THAT_PLAY_RANDOMLY

#set to false. used to call def stop_seek if it crashed
$audioxt_stop_seek_crashed = false

#this is the global variable that holds the seek value. needed for save/load
$audioxt_seek_status = "nil"
################################################################################


######################### GAME STARTS IN TEST MODE #############################
#if in test mode, start the recover audio engine
begin
if $TEST
#send a string to server. if it exists it means it must not open a new recover gui.  
open("\\\\.\\pipe\\audio_engine_xt",'w') { |pipe| pipe.write("nil,nil,nil"); } rescue $recover_safe_audioxt = 1    
    #this returns true if there is no recover gui engine running.
    if $recover_safe_audioxt == 1
    #if in battle test mode, it must not open engine
    Thread.new{system ($rescue_gui_engine_xt)} if !$BTEST
    $recover_safe_audioxt = 0
    end
#since we are in test mode, the recover gui must be closed when closing game later
$audioxt_has_crashed_GUI_started = true    
end
end

############################ Handle F12 Reset key ##############################
unless $f12_cleaner_F3XXEFA1.nil?
    #if in test mode, warn the user he is leaving testing mode
    if $TEST
    p sprintf("You are now leaving testing mode.")
    end
  
#kill recover GUI audio engine  
system ("start taskkill /IM #{$rescue_gui_engine_xt} /F")

# Opens the game executable in a new thread
Thread.new{system ($audio_engine_xt_exe)}
# Exits this thread
exit
end
$f12_cleaner_F3XXEFA1 = true
################################################################################


################### VX MAP BGM INTEGRATION WITH AUDIO ENGINE ###################
class Game_Map

  # initialize the Random Battle BGM array
  # the original Random Battle BGM code was made from ERZENGEL
  attr_accessor :rbmfiles
  alias audioxt_rbm_initialize initialize
  def initialize
    #set switch to ON if engine must support Worotana Neo Save System
    $game_switches[$worotana_neo_save_system] = true if WOROTANA_NEO_SAVE
    
    #set @rbmfiles to the Battle BGM array set by user in CONFIGURATION
    @rbmfiles = $audioxt_random_battle
    audioxt_rbm_initialize
  end
  
  #this is a real time update. gets executed each frame.
  #this makes the random battle array always be aware of any change
  #set from Player.
  alias bulletxt_random_battle_update update
  def update
  bulletxt_random_battle_update
  @rbmfiles = $audioxt_random_battle
  end  
  
  alias audioxt_engine_map_setup setup
    def setup(map_id)
    audioxt_engine_map_setup(map_id)
=begin
@map.autoplay_bgm returns a boolean. it's the checkbox inside the VX editor
when clicking on Map->Properties->Auto-Change BGM. If this check box is enabled,
this bool returns true so nothing should be changed. If instead, the checkbox
isn't enabled, this returns false. However for some strange reason, even if the
checkbox isn't enabled, VX will still set the @map.bgm.name to the last song
selecected in the window before unchecking the box. This causes the engine to
play the song even if checkbox is disabled. To avoid this, I see if the checkbox
is disabled. If it is, I set the @map.bgm.name to $audioxt_special_bgm_id.
At first start, in case very first map starts with no bgm, $audioxt_special_bgm_id
is set to "nil,nil" so the engine will receive nothing
to play (nil,nil.mp3,play,volume).
After, $audioxt_special_bgm_id is equal to the current id playing (without
extension suffix). This always remembers the current map who is the current
playing song. This gets reset to "nil,nil" when doing a manual pause request, a
fadeout, or when exiting from game (game over, go back to title)
=end
    if !@map.autoplay_bgm
    @map.bgm.name = $audioxt_special_bgm_id
    @map.bgm.volume = $audioxt_special_volume
    end
  end

  
def autoplay
#play map's bgs if bgs is requested  
@map.bgs.play if @map.autoplay_bgs
#get the volume of map's bgm and convert it to string
$audioxt_bgm_volume = @map.bgm.volume.to_s()
#this global variable holds the complete id of song. for ex: Jam.mp3
$audioxt_bgm_id = @map.bgm.name + "." + FORMAT_OF_SONGS
#set this variable map's bgm without extension suffix.its needed above in
#def setup .
$audioxt_special_bgm_id = @map.bgm.name
$audioxt_special_volume = @map.bgm.volume
#this is the string that gets sent to server. it is for ex: Jam.mp3,play,80
audioxt_send_song_play = $audioxt_bgm_id + ",play," + $audioxt_bgm_volume

#debug: what is the value of the current playing song when I enter a map?
#p sprintf(audioxt_send_song_play)

#send string to server
open("\\\\.\\pipe\\audio_engine_xt",'w') { |pipe| pipe.write(audioxt_send_song_play); } rescue $recover_safe_audioxt = 1
#if true, the engine has crashed so it must call recover engine gui.
if $recover_safe_audioxt == 1
recover
end
#set this to false. this means when a battle ends, the song should resume.
#this happens unless a manual pause request happens and this bool becomes true.
$audioxt_song_in_pause_no_resume = false

end    
    
######################## RECOVER ENGINE FOR MAP'S BGM ##########################
def recover
# start recover audio engine
Thread.new{system ($rescue_gui_engine_xt)}
#warn the user that the engine has crashed
$game_message.texts.push("The Audio Engine XT server has crashed.")
$game_message.texts.push("A Rescue GUI mode of the engine should have started.")
$game_message.texts.push("Remember to close it after closing game.")
#do a sleep of n seconds to give the time for the engine to start
sleep(6) #FIX: its not said 6 seconds are enough
$recover_safe_audioxt = 0 #turn recover to off
#sets the boolean to true so the when closing/F12 the game, it knows it has to
#close even the recover gui engine
$audioxt_has_crashed_GUI_started = true

=begin
when here, the engine should have started, so calls the autoplay again.
if everything went fine, the engine starts and the song previously crashed will
start playing
=end
autoplay
end
    
end
################################################################################
################################################################################


################# HANDLE BGM PLAY/FADEOUT REQUEST FROM EVENT COMMAND ###########
class Game_Interpreter

  #play song
  def command_241
  #get the id of song
  $audioxt_bgm_id = @params[0].name + "." + FORMAT_OF_SONGS
  #set this global variable to the current id playing. this is needed when
  #doing a map transfer and the checkbox (bgm autoplay) is disabled. This
  #remembers the map who is the current playing song
  $audioxt_special_bgm_id = @params[0].name
  $audioxt_special_volume = @params[0].volume
  #get volume and convert it to string
  $audioxt_bgm_volume = @params[0].volume.to_s()
  audioxt_send_song_play = $audioxt_bgm_id + ",play," + $audioxt_bgm_volume
open("\\\\.\\pipe\\audio_engine_xt",'w') { |pipe| pipe.write(audioxt_send_song_play); } rescue $recover_safe_audioxt = 1

    #if true, the engine has crashed so it must call recover engine gui.
    if $recover_safe_audioxt == 1
    recover
    end
#set this to false. this means when a battle ends, the song should resume.
#this happens unless a manual pause request happens and this bool becomes true.
$audioxt_song_in_pause_no_resume = false  
  return true
  end
  
####################### RECOVER ENGINE FOR EVENT COMMAND BGM ###################
def recover
# start recover audio engine
Thread.new{system ($rescue_gui_engine_xt)}
#warn the user that the engine has crashed
$game_message.texts.push("The Audio Engine XT server has crashed.")
$game_message.texts.push("A Rescue GUI mode of the engine should have started.")
$game_message.texts.push("Remember to close it after closing game.")
#do a sleep of n seconds to give the time for the engine to start
sleep(6) #FIX: its not said 6 seconds are enough
$recover_safe_audioxt = 0 #turn recover to off
#sets the boolean to true so the when closing/F12 the game, it knows it has to
#close even the recover gui engine
$audioxt_has_crashed_GUI_started = true

=begin
when here, the engine should have started, so calls the command_241 again.
if everything went fine, the engine starts and the song previously crashed will
start playing
=end
command_241
end  
################################################################################  
  
#fadeout
  def command_242
  #get the fadeout in seconds and convert it to string
  fade_seconds = @params[0].to_s()
  #prepeare string to send to server. it is for ex. Jam.mp3,stop,4
  fadeout = $audioxt_bgm_id + ",stop," + fade_seconds
  #reset bgm to nil. this avoids that next map (if it has checkbox disabled)
  #remembers last playing bgm and restarts it all over again
  $audioxt_special_bgm_id = "nil,nil"
  #since it did a fadeout, song must not restart when battle ends
  $audioxt_song_in_pause_no_resume = true
open("\\\\.\\pipe\\audio_engine_xt",'w') { |pipe| pipe.write(fadeout); } rescue nil
    return true
  end

end
################################################################################
################################################################################



############################### MODULE #########################################
=begin
The following module, called from class Scene_Map, handles a manual pause
request and sends data to the engine.
=end
module Bulletxt_audio_engine_xt

############################## PAUSE BGM #######################################
def pause
#sends id,pause string to engine. the id, is of the current playing map's bgm
pause_song =  $audioxt_bgm_id + "," + $audioxt
open("\\\\.\\pipe\\audio_engine_xt",'w') { |pipe| pipe.write(pause_song); } rescue nil
#setting this to true means map's bgm won't resume when a battle ends
$audioxt_song_in_pause_no_resume = true
#if going in a new map with checkbox disabled, this avoids that the paused
#song starts playing
$audioxt_special_bgm_id = "nil,nil"
$audioxt = "nil"
end


############################### LOOP SEEK BGM ##################################
#This function handles sending data to engine for the loop seek
def loop_seek
#globally remember the seek value  
$audioxt_seek_status = $audioxt
=begin
This needs to avoid wrong behaviour in case Player calls a loop seek inside a
map where BGM is set to None.
If True, it means Player is on a map with BGM checkbox enabledbut set to None.
If this is the case, the bgm id will return  FORMAT_OF_SONGS. This means it
must not send anythind to engine because if it would, it would make next map
with BGM set automatically loop with seek.
This check is not needed in case Player is on map with BGM checkbox disabled,
because it would either return the playing BGM id or "nil,nil" so the engine would
read "nil" instead of "loop" at second position of array.
=end
if $audioxt_bgm_id == "." + FORMAT_OF_SONGS
#reset $audioxt to nil  
$audioxt = "nil"
#exit pheww(avoided big bug)!
return
end

#if here, it means Player is on a map with BGM either set or with checkbox
#disabled. If disabled, it will send a null string to server(the engine won't
#be aware of the "seek" word.
loop_song_seek =  $audioxt_bgm_id + "," + "seek" + "," + $audioxt.to_s()  
open("\\\\.\\pipe\\audio_engine_xt",'w') { |pipe| pipe.write(loop_song_seek); } rescue $recover_safe_audioxt = 1
#if true, the engine has crashed so it must call recover engine gui.
if $recover_safe_audioxt == 1
recover
end
$audioxt = "nil"

end

############################### STOP SEEK ######################################

def stop_seek
loop_song_seek =  "nil" + "," + "stop_seek" + "," + $audioxt.to_s()  
open("\\\\.\\pipe\\audio_engine_xt",'w') { |pipe| pipe.write(loop_song_seek); } rescue $recover_safe_audioxt = 1  
  if $recover_safe_audioxt == 1
  $audioxt_stop_seek_crashed = true
  recover
  end
$audioxt = "nil"

end

####################### RECOVER ENGINE FOR LOOP SEEK CALL ######################
  def recover
# start recover audio engine
Thread.new{system ($rescue_gui_engine_xt)}
#warn the user that the engine has crashed
$game_message.texts.push("The Audio Engine XT server has crashed.")
$game_message.texts.push("A Rescue GUI mode of the engine should have started.")
$game_message.texts.push("Remember to close it after closing game.")
#do a sleep of n seconds to give the time for the engine to start
sleep(6) #FIX: its not said 6 seconds are enough
$recover_safe_audioxt = 0 #turn recover to off
#sets the boolean to true so the when closing/F12 the game, it knows it has to
#close even the recover gui engine
$audioxt_has_crashed_GUI_started = true
#call the play because loop_seek doesn't
loop_song_seek =  $audioxt_bgm_id + "," + "play" + "," + $audioxt_bgm_volume
open("\\\\.\\pipe\\audio_engine_xt",'w') { |pipe| pipe.write(loop_song_seek); } rescue nil

=begin
when here, the engine should have started, so calls the loop_seek again.
if everything went fine, the engine starts and the song previously crashed will
start playing
=end    
if $audioxt_stop_seek_crashed
$audioxt_stop_seek_crashed = false
stop_seek
else
loop_seek
end

end

# CLOSE module Bulletxt_audio_engine_xt
end
################################################################################
=begin
The following class Scene_Map
includes module Bulletxt_audio_engine_xt
=end
                                     #
                                    ###
                                  #######
                                ###########
################################           #####################################
################################           #####################################
                                ###########
                                  #######
                                    ###
                                     #
class Scene_Map
include Bulletxt_audio_engine_xt

####################### HANDLE MANUAL PAUSE REQUEST ############################
# this request only happens if a user makes a script call inside an event of
# this type:  $audioxt = "pause" or $audioxt = int

  #this def update, updates every frame time on map. its a real time code
  alias bullet_audio_update update
  def update
  bullet_audio_update
  if $audioxt != "nil" #if true, there is a possible pause request
  s = $audioxt # if pause request, this returns pause
    if s == "pause" #if pause, call pause
    pause
    else
    #if int number, call loop_seek
    loop_seek if s != "pause" && s != "stop_seek"
    stop_seek if s == "stop_seek"
    end
  end
  end

  
#################### PUT SONG IN PAUSE WHEN ENTERING A BATTLE ##################
# def function executed when a battle is about to start
  def call_battle
    # This handles Random Battle BGM
    rbmoff = $data_system.battle_bgm.name.clone
  # if true, it means Random Battle BGM should happen
  if $game_switches[ENABLE_RANDOM_BATTLE_BGM]
     #debug battle bgm array  
     #p $game_map.rbmfiles  
    # this gets a random element from the array
    audio = rand($game_map.rbmfiles.size)
    #if < 1, it must not add anything to array
    if $game_map.rbmfiles.size > 1
     #this puts back the previously removed element into array. at first run
     #this doesn't add anything because the variable is set to nil
    $game_map.rbmfiles.push($audioxt_battle_bgm_random_tmp_id) if $audioxt_battle_bgm_random_tmp_id != "nil"
    end
    #this global variable holds the last random Battle BGM. it's needed so at
    #next run we know the element to put back in array (since it gets deleted below)
    $audioxt_battle_bgm_random_tmp_id = $game_map.rbmfiles[audio]
    #debug the battle bgm that is about to play
    #p $audioxt_battle_bgm_random_tmp_id
    #this tells VX who is the random Battle BGM to play
    $data_system.battle_bgm.name = $game_map.rbmfiles[audio]
    #if < 1, it must not remove anything from array
    if $game_map.rbmfiles.size > 1
=begin  
remove current Battle BGM from array, so at next battle the random won't
play this again. This avoids that a battle BGM plays 2 times consecutively.
The element gets back in to array at next run after getting the new random
battle bgm to play.
=end    
    $game_map.rbmfiles.delete_at(audio)
    end
  #here the Random Battle BGM code finishes.
  end

    
    @spriteset.update
    Graphics.update
    $game_player.make_encounter_count
    $game_player.straighten
    $game_temp.map_bgm = RPG::BGM.last
    $game_temp.map_bgs = RPG::BGS.last

#if this switch is OFF, make engine go in pause
if $game_switches[CONTINUE_MAP_SONG_IN_BATTLE] == false
#send id,pause to engine
get_in_pause = $audioxt_bgm_id + ",pause"
open("\\\\.\\pipe\\audio_engine_xt",'w') { |pipe| pipe.write(get_in_pause); } rescue nil
end
=begin
TMP_OUTPUT_AUDIO_TXT = "tmp_audioxt.txt"
  f = File.open(TMP_OUTPUT_AUDIO_TXT,'w')
  f.puts $tmp_audio_engine_xt
  f.close  
=end
    
    RPG::BGS.stop
    Sound.play_battle_start
    #if this switch is OFF, the battle will play its music. if ON, it means
    #engine isn't in pause status so it must continue playing map's song
    if $game_switches[CONTINUE_MAP_SONG_IN_BATTLE] == false
    $game_system.battle_bgm.play
    end
    $game_temp.next_scene = nil
    $scene = Scene_Battle.new
    #this is needed for Random Battle BGM. not sure yet what's it meant for.
    $data_system.battle_bgm.name = rbmoff.clone
  end
end
################################################################################
################################################################################



########################## RESUME AUDIO AT BATTLE END ##########################
=begin
the following class, handles resuming song when a battle ends
=end
class Scene_Battle < Scene_Base

  def battle_end(result)
    if result == 2 and not $game_troop.can_lose
      call_gameover
    else
      $game_party.clear_actions
      $game_party.remove_states_battle
      $game_troop.clear
      if $game_temp.battle_proc != nil
        $game_temp.battle_proc.call(result)
        $game_temp.battle_proc = nil
      end
      #fadeout ME (useful in case Victory sound is long)
      RPG::ME.fade(1000)
      unless $BTEST
      #this stops the current BGM that is playing. in this case, the bgm is
      #the battle theme
      RPG::BGM.stop
=begin
if this is equal to false, it means that map's bgm wasn't manually
set to pause status before entering battle.
if true, it means map's bgm was in pause status so it must not resume song
=end
if $audioxt_song_in_pause_no_resume == false
#get the id of song previously playing
restore_song = $audioxt_bgm_id + ",play," + $audioxt_bgm_volume
#send string to server. when here it is:  id,play,volume
open("\\\\.\\pipe\\audio_engine_xt",'w') { |pipe| pipe.write(restore_song); } rescue $recover_safe_audioxt = 1    

#if true, the engine has crashed so it must call recover engine gui.
if $recover_safe_audioxt == 1
recover
end

end
#play maps bgs
$game_temp.map_bgs.play
        
      end
      $scene = Scene_Map.new
      @message_window.clear
      Graphics.fadeout(30)
    end
    $game_temp.in_battle = false
  end


  
  #--------------------------------------------------------------------------
  # * Victory Processing
  #--------------------------------------------------------------------------

####################### RECOVER ENGINE FOR RESUMING MAP'S BGM ##################
  def recover
# start recover audio engine
Thread.new{system ($rescue_gui_engine_xt)}
#warn the user that the engine has crashed
$game_message.texts.push("The Audio Engine XT server has crashed.")
$game_message.texts.push("A Rescue GUI mode of the engine should have started.")
$game_message.texts.push("Remember to close it after closing game.")
#do a sleep of n seconds to give the time for the engine to start
sleep(6) #FIX: its not said 6 seconds are enough
$recover_safe_audioxt = 0 #turn recover to off
#sets the boolean to true so the when closing/F12 the game, it knows it has to
#close even the recover gui engine
$audioxt_has_crashed_GUI_started = true

=begin
when here, the engine should have started, so calls the battle_end again.
if everything went fine, the engine starts and the song previously crashed will
start playing
=end
battle_end(0)
  end
    
  
end
################################################################################
################################################################################



=begin
###############################################################################
Handle audio playing in engine out of map and close rescue engine mode.
###############################################################################
=end

#close eventual rescue engine when in Title
class Scene_Title < Scene_Base
  alias audio_engine_xt_command_shutdown command_shutdown
  def command_shutdown
  #if true, the engine has previously crashed and the recover gui mode
  #has started. this returns also true if in test mode
  if $audioxt_has_crashed_GUI_started
  system ("start taskkill /IM #{$rescue_gui_engine_xt} /F")
  end
  audio_engine_xt_command_shutdown
  end
end


#close eventual rescue engine when in Menu -> Shutdown  
class Scene_End < Scene_Base
  alias audio_engine_xt_command_shutdown command_shutdown
  def command_shutdown
  #if true, the engine has previously crashed and the recover gui mode
  #has started. this returns also true if in test mode  
  if $audioxt_has_crashed_GUI_started
  system ("start taskkill /IM #{$rescue_gui_engine_xt} /F")
  end
  audio_engine_xt_command_shutdown
  end
  
    #stop song when going from Menu -> Title
    alias audio_engine_xt_command_to_title command_to_title
    def command_to_title
    #get the id of the current playing song and add stop status and fadeout
    stop_current_song = $audioxt_bgm_id
    stop_current_song += ',stop,1'
    open("\\\\.\\pipe\\audio_engine_xt",'w') { |pipe| pipe.write(stop_current_song); } rescue nil
    #this avoids that, if going back to title and then restarting game in a map
    #with checkbox disabled, it won't play previous playing song
    $audioxt_special_bgm_id = "nil,nil"
    audio_engine_xt_command_to_title
    end
end

#stop song when going in gameover
class Scene_Gameover < Scene_Base
  alias bullet_audio_engine_xt_start start
  def start
  #get the id of the current playing song and add stop status and fadeout
  stop_current_song = $audioxt_bgm_id
  stop_current_song += ',stop,0'
  open("\\\\.\\pipe\\audio_engine_xt",'w') { |pipe| pipe.write(stop_current_song); } rescue nil    
  #this avoids that, if going back to title and then restarting game in a map
  #with checkbox disabled, it won't play previous playing song
  $audioxt_special_bgm_id = "nil,nil"  
  bullet_audio_engine_xt_start
  end
end

# stop song if player from event requests to go back to Title Screen
class Scene_Map < Scene_Base
  alias audio_engine_xt_call_title call_title
   def call_title
    stop_current_song = $audioxt_bgm_id
    stop_current_song += ',stop,1'
    open("\\\\.\\pipe\\audio_engine_xt",'w') { |pipe| pipe.write(stop_current_song); } rescue nil    
    #this avoids that, if going back to title and then restarting game in a map
    #with checkbox disabled, it won't play previous playing song
    $audioxt_special_bgm_id = "nil,nil"
    audio_engine_xt_call_title
  end
end