Forums » Community Projects
KombatTunes Plugin
KombatTunes v1.2
by Pizzasgood
kombattunes-1.2.zip
md5sum
kombattunes-1.2-lite.zip (same as above, but without sample audio)
md5sum
This is a plugin to play a random song on command. It can be used on its own but it is intended to be used in conjunction with a hail plugin such as LegionHail to start combat music when you engage in PVP. Since due to the limitations of VO it is somewhat annoying to add audio files to this plugin, I included a handful of them to serve as examples and so that this can be used and evaluated immediately. Most are recordings of midi versions of tunes from various Sonic games, with a couple other oddball tracks thrown in. (No, this does not support actual midi files.)
=== Commands ===
/kombattunes
* Play a song at random
/kombattunes "search_pattern"
* Play the first song found that matches the "search_pattern". For example, if you use "green" it might play "greenforest.ogg", or if you use "stardust" it might play "scd-stardust-f.ogg". You can use fancier patterns, such as "rock.*dragon" to match the first song that has the strings "rock" and "dragon" in its filename, e.g. "rock-the-dragon.ogg".
/kombattunes gui
* Opens the gui, which has a list of the songs available and buttons to play, mute, etc.
/kombattunes stop
* Stops all music, including the ambient game tracks
/kombattunes start
* Starts the game's ambient tracks. This is done automatically by the plugin at the end of the song, so you only need it if you used "stop" or if you want to switch back to ambient. Note that it currently always uses the game's "music/ambient_1.ogg" track, regardless of where you are. Yes this is lame, maybe I'll enhance it at some point.
=== Plugin Integration ===
To integrate this with another plugin, the KombatTunes.new() and KombatTunes.fight() functions are available. The former acts like running just "/kombattunes", and can be optionally given a string parameter with a filename pattern. The KombatTunes.fight() function is nearly the same, the only difference is that if a song is already playing it will do nothing. This way if you hail somebody and kill them before the music finishes, you can hail a second person without worrying about it cutting off the current song and switching to a new one.
=== Adding music ===
There are two ways to add music, manually and by using the provided Bash scripts. The Bash scripts will only work if you have Bash, sox, normalize, oggenc, and ogginfo installed. Windows users and probably Mac users as well will need to either use the manual procedure or else put together their own automated method.
--- The Manual Procedure ---
To manually add a song, first you must make sure the song is saved in the .ogg format, with a sample rate of 44100 kHz. I'm not sure if the sample rate requirement applies to all people, that might just be an oddity with my setup or the Linux version of VO. If you ignore it and the music seems like it's playing faster or slower than it should, try modifying the file to use that sample rate and it should work.
Store the .ogg file in the audio folder of the plugin.
Edit the list.lua file and add a line for your song. Make sure you place it within the brackets of the KombatTunes.tunes array, just like the example entries are. The number is the length of the song in milliseconds (thousandths of a second) and is necessary so that the plugin can know when the song is finished playing. Don't stress if you don't know *exactly* how long the song is, it will not hurt anything if it is slightly off. If the number you use is too small, the song may get cut short, and if too long there may be unnecessary silence after the song has completed, but it won't cause any harm either way.
Yes, the need to include that is lame, as is the need to have a list of the files rather than being able to just scan the folder and automatically use them all, but that is a result of the limited API that VO provides. Complain to the devs, not to me.
--- The Automatic Procedure ---
If you are on a *nix based system with Bash, sox, normalize, oggenc, and ogginfo installed, you can use the add.sh script provided inside the plugin to automate the addition of audio files to the plugin. Simply drop the files into the "kombattunes/new/" directory, open a terminal inside the kombattunes directory, and run "./add.sh". It will automatically go through each file and normalize it, convert it to a properly formatted .ogg file, move it to the audio directory, and update the list.lua file to match the current contents of the audio directory.
As I said in the above subsection, I realize the need to do this is lame, but it's the best I was able to do with the limited API that VO makes available. If you want it simpler, bug the devs to allow querying what audio is playing and what are the contents of directories within the plugin directory.
=== Removing Audio ===
This is fairly simple, just go into the kombattunes/audio/ directory and delete the files you don't want, and then edit the list.lua file to remove the lines corresponding to those files. Technically, editing the list.lua file is all you actually *have* to do, leaving the unused files around won't hurt anything (though if you ever use the automated method of adding audio, they will get re-added to the list unless you remove them).
=== Misc. Notes ===
As I stated a few times above, I found VO's API lacking. I could not scan a directory to see which files are already there, so I had to force the user to generate and maintain a listing himself. I could not detect how long the tracks are or whether they are still playing, so I had to force the user to include the songs' lengths in said listing. If anybody knows ways around this, please do let me know and I'll simplify things.
Another interesting application for KombatTunes would be to create a plugin that monitors your armor and runs KombatTunes.fight() when it decreases as a result of another player or ship (as opposed to an asteroid).
If you examine the code you will notice disabled support for announcing to the sector each time you play music. I used it for about 15 minutes back when I first started writing this plugin, decided it was retarded and spammy, and disabled it in favor of just printing to my own client what is playing. I haven't tested it since so it may or may not still work, and may or may not still be annoying. Feel free to try enabling it if you want to be the cool kid on the block though ;)
by Pizzasgood
kombattunes-1.2.zip
md5sum
kombattunes-1.2-lite.zip (same as above, but without sample audio)
md5sum
This is a plugin to play a random song on command. It can be used on its own but it is intended to be used in conjunction with a hail plugin such as LegionHail to start combat music when you engage in PVP. Since due to the limitations of VO it is somewhat annoying to add audio files to this plugin, I included a handful of them to serve as examples and so that this can be used and evaluated immediately. Most are recordings of midi versions of tunes from various Sonic games, with a couple other oddball tracks thrown in. (No, this does not support actual midi files.)
=== Commands ===
/kombattunes
* Play a song at random
/kombattunes "search_pattern"
* Play the first song found that matches the "search_pattern". For example, if you use "green" it might play "greenforest.ogg", or if you use "stardust" it might play "scd-stardust-f.ogg". You can use fancier patterns, such as "rock.*dragon" to match the first song that has the strings "rock" and "dragon" in its filename, e.g. "rock-the-dragon.ogg".
/kombattunes gui
* Opens the gui, which has a list of the songs available and buttons to play, mute, etc.
/kombattunes stop
* Stops all music, including the ambient game tracks
/kombattunes start
* Starts the game's ambient tracks. This is done automatically by the plugin at the end of the song, so you only need it if you used "stop" or if you want to switch back to ambient. Note that it currently always uses the game's "music/ambient_1.ogg" track, regardless of where you are. Yes this is lame, maybe I'll enhance it at some point.
=== Plugin Integration ===
To integrate this with another plugin, the KombatTunes.new() and KombatTunes.fight() functions are available. The former acts like running just "/kombattunes", and can be optionally given a string parameter with a filename pattern. The KombatTunes.fight() function is nearly the same, the only difference is that if a song is already playing it will do nothing. This way if you hail somebody and kill them before the music finishes, you can hail a second person without worrying about it cutting off the current song and switching to a new one.
=== Adding music ===
There are two ways to add music, manually and by using the provided Bash scripts. The Bash scripts will only work if you have Bash, sox, normalize, oggenc, and ogginfo installed. Windows users and probably Mac users as well will need to either use the manual procedure or else put together their own automated method.
--- The Manual Procedure ---
To manually add a song, first you must make sure the song is saved in the .ogg format, with a sample rate of 44100 kHz. I'm not sure if the sample rate requirement applies to all people, that might just be an oddity with my setup or the Linux version of VO. If you ignore it and the music seems like it's playing faster or slower than it should, try modifying the file to use that sample rate and it should work.
Store the .ogg file in the audio folder of the plugin.
Edit the list.lua file and add a line for your song. Make sure you place it within the brackets of the KombatTunes.tunes array, just like the example entries are. The number is the length of the song in milliseconds (thousandths of a second) and is necessary so that the plugin can know when the song is finished playing. Don't stress if you don't know *exactly* how long the song is, it will not hurt anything if it is slightly off. If the number you use is too small, the song may get cut short, and if too long there may be unnecessary silence after the song has completed, but it won't cause any harm either way.
Yes, the need to include that is lame, as is the need to have a list of the files rather than being able to just scan the folder and automatically use them all, but that is a result of the limited API that VO provides. Complain to the devs, not to me.
--- The Automatic Procedure ---
If you are on a *nix based system with Bash, sox, normalize, oggenc, and ogginfo installed, you can use the add.sh script provided inside the plugin to automate the addition of audio files to the plugin. Simply drop the files into the "kombattunes/new/" directory, open a terminal inside the kombattunes directory, and run "./add.sh". It will automatically go through each file and normalize it, convert it to a properly formatted .ogg file, move it to the audio directory, and update the list.lua file to match the current contents of the audio directory.
As I said in the above subsection, I realize the need to do this is lame, but it's the best I was able to do with the limited API that VO makes available. If you want it simpler, bug the devs to allow querying what audio is playing and what are the contents of directories within the plugin directory.
=== Removing Audio ===
This is fairly simple, just go into the kombattunes/audio/ directory and delete the files you don't want, and then edit the list.lua file to remove the lines corresponding to those files. Technically, editing the list.lua file is all you actually *have* to do, leaving the unused files around won't hurt anything (though if you ever use the automated method of adding audio, they will get re-added to the list unless you remove them).
=== Misc. Notes ===
As I stated a few times above, I found VO's API lacking. I could not scan a directory to see which files are already there, so I had to force the user to generate and maintain a listing himself. I could not detect how long the tracks are or whether they are still playing, so I had to force the user to include the songs' lengths in said listing. If anybody knows ways around this, please do let me know and I'll simplify things.
Another interesting application for KombatTunes would be to create a plugin that monitors your armor and runs KombatTunes.fight() when it decreases as a result of another player or ship (as opposed to an asteroid).
If you examine the code you will notice disabled support for announcing to the sector each time you play music. I used it for about 15 minutes back when I first started writing this plugin, decided it was retarded and spammy, and disabled it in favor of just printing to my own client what is playing. I haven't tested it since so it may or may not still work, and may or may not still be annoying. Feel free to try enabling it if you want to be the cool kid on the block though ;)
Updated to 1.1 - the "stop" action wasn't flagging the audio as having stopped despite stopping playback. There is probably also a bug when you explicitly stop and then start a new one right away though - the timer that restarts the ambient music is still left running and will kick in halfway through the next song. Will check if it happens tonight and deal with it later.
EDIT: no, that bug doesn't exist, as the same timer gets reused when you start a new song. So it should be bug free now. Well, unless you count it restarting the ambient after a period of silence if you use "stop" while a song is playing. I guess I'll see about fixing that tomorrow, and maybe rename "start" and "stop" to more appropriate commands, like "ambient" and "mute".
EDIT: no, that bug doesn't exist, as the same timer gets reused when you start a new song. So it should be bug free now. Well, unless you count it restarting the ambient after a period of silence if you use "stop" while a song is playing. I guess I'll see about fixing that tomorrow, and maybe rename "start" and "stop" to more appropriate commands, like "ambient" and "mute".
Updated to 1.2. Changed to using the "KombatTunes" namespace rather than the "kombattunes" one, in keeping with VO's naming conventions. (This does not affect the commands, only the lua functions. The CLI commands still use /kombattunes.) I did not implement the tweaks mentioned in the previous post yet - combination of forgetting and laziness.
I just uploaded LegionHail v1.0, which has also been updated to look for KombatTunes as "KombatTunes" rather than "kombattunes", so if you want to use this in conjunction with it, you will need to use at least this 1.2 version. The 1.0 and 1.1 versions I uploaded a week ago will not be detected.
I just uploaded LegionHail v1.0, which has also been updated to look for KombatTunes as "KombatTunes" rather than "kombattunes", so if you want to use this in conjunction with it, you will need to use at least this 1.2 version. The 1.0 and 1.1 versions I uploaded a week ago will not be detected.