[pecenipicek]

Good day everybody. I'm here to release something that fredders all around might find useful. Forget about using the old "play-sound-from-file" sexp.

Please read the post before screaming "wrong board!".

Also, i'm very much aware that this becomes irrelevant when somebody makes a proper sexp for the function.

So without further ado,

Code: (README) [Select]

------
Readme file for play-music-from-file script v0.04, by pecenipicek
------
First off, the script itself is simplicity incarnate. It takes its info from FRED events and plays the music.


------ Variables

The current implementation uses the following fred variables:

String variables:
    str_au_file         - filename, string, <name>.<extension>
    str_au_vol          - audio volume, string, 0 - 100
    str_au_fade         - fade, string, 0 = false, 1 = true, anything else = script fail. You have been warned.
    str_au_play         - string that feeds the script, built from the above three vars
    str_au_play_hlp1    - helper variable to assist in string building
    str_au_play_hlp2    - helper variable to assist in string building

------ Basic setup explained
   
The basic setup is as follows:

Event "music play"

Open the event, you will see a simple when. Fill in the situation where you want it to trigger.
Further on, you will see three "modify-variable" parts.
Open them, place values as follows:

First "modify-variable": The most obviously, name of the file to be played.
    Filename limited to 23 characters, due to the 32 character string limit of FSO.

Second "modify-variable": Fade status, aka, wether the music will fade out when it is stopped, or will it end abruptly. Accepts values "true" or "false". Enter it without quotation marks.

Third "modify-variable": Volume, enter a value from 0 to 100.

This is all you need to modify to be able to use this handy-dandy function with arbitrary values.

Filename string length is constrained to 20 character, including extension. If the game errors out with an error about trying to put something into a 32 byte buffer, you can bet that your filename length is too long.

Event "music stop"

Nothing fancy here, just modify the first field in the "when" with when you actually want to stop music.

------ The "This is all fine and dandy, but how the hell can i use this?" section

My advice would be to simply copy over the important things from the attached mission, and paste them in your mission.
In other words, what is relevant are the "#SEXP Variables" and the "#Events" stuff.
In the case that your mission already uses some variables, adjust the indices of the variables you paste into the mission file.

You cannot do this in fred, mind you. Use notepad++ or any other competent text editor to open the mission in question and proceed accordingly.

Obviously, you will most likely want to use it more than once in your missions.
Since the event set up is relatively complicated, just copy paste it as many times as you need.
Note: you do not need to copy paste the variables again, only the event, and proceed as written in the "Basic setup explained" part of this readme.


------ The "I want to integrate this into my mod" section
You can just easily put the play-music-from-file-sct.tbm into your tables section, and use the provided events and variables in your missions.

If your mod is currently using some script that uses the "$On Game Init:" conditional hook, just copypaste what is in the square brackets of the play-music-from-file-sct.tbm to your own script.
Same as above with the stuff in the $On Mission End: part.

If you have no clue what i'm talking about, ignore the above snippet.

------ Thanks section
HLP wiki, for basic scripting information.
The E, for invaluable assistance in making this bloody thing work.
mjn.mixael for testing and telling me what was wrong.

Cheers and lets hope this will be useful to you.

------ Changelog
v0.01 -- Initial release
v0.02 -- Fixed music not stopping on mission end, reduced mission variable count to 5, reduced event count to 1, update readme to reflect changes, added capability to stop currently playing music when the event is triggered again.
v0.03 -- Added the function to stop currently playing music.
v0.04 -- Fixed fadeing on mission end, fixed a potentially crushing bug with mission-rerun, since nobody remembered to test how it behaved when running two missions in the same run of FSO...

Script, Mission variables, Mission events:

Code: (play_music_from_file-sct.tbm) [Select]

#Conditional Hooks
; play-music-from-file script v0.04 - by pecenipicek
$Application: FS2_Open

$On Game Init:
[       
    ahret = -1
    fadeh  = false
        pm = function( MFile, fade, Vol)
            Vol = Vol / 100.0
            if fade == 0 then
                fadeh = false
            end
            if fade == 1 then
                fadeh = true
            end
            if ahret ~= nil then
                if ahret ~= -1 then
                    ad.stopMusic(ahret, fadeh)
                end
            end
            ahret = ad.playMusic(MFile, Vol)
        end
        sm = function()
            if ahret ~= nil then
                if ahret ~= -1 then
                    ad.stopMusic(ahret, fadeh)
                    ahret = -1
                    fade = false
                end
            end
        end
]

$On Mission End:
[
    if ahret ~= -1 then
        ad.stopMusic(ahret, fadeh)
        ahret = -1
        fadeh = false
    end
]
#End


Code: (VARIABLES) [Select]

#Sexp_variables

$Variables:
(
0 "str_au_fade" " " "string"
1 "str_au_file" " " "string"
2 "str_au_play" " " "string"
3 "str_au_play_hlp1" " " "string"
4 "str_au_play_hlp2" " " "string"
5 "str_au_vol" " " "string"
)


Code: (EVENTS) [Select]

$Formula: ( when
   ( has-time-elapsed 2 )
   ( modify-variable
      "@str_au_file[ ]"
      "ambdeath.ogg"
   )
   ( modify-variable
      "@str_au_fade[ ]"
      "1"
   )
   ( modify-variable
      "@str_au_vol[ ]"
      "100"
   )
   ( string-set-substring
      "pm('',,)"
      7
      0
      "@str_au_vol[ ]"
      "@str_au_play_hlp1[ ]"
   )
   ( string-set-substring
      "@str_au_play_hlp1[ ]"
      6
      0
      "@str_au_fade[ ]"
      "@str_au_play_hlp2[ ]"
   )
   ( string-set-substring
      "@str_au_play_hlp2[ ]"
      4
      0
      "@str_au_file[ ]"
      "@str_au_play[ ]"
   )
   ( script-eval "@str_au_play[ ]" )
)
+Name: music play 1
+Repeat Count: 1
+Interval: 1

$Formula: ( when
   ( has-time-elapsed 20 )
   ( script-eval "sm()" )
)
+Name: music stop
+Repeat Count: 1
+Interval: 1


Spoiler:

FOR POWER USERS! If you dont feel comfortable manually messing around the string, use the events and variables from above. You still need the script itself, which is the play_music_from_file-sct.tbm

You can just feed "script-eval" sexp with the following string.
pm('<filename.extension>',<fade status 0 or 1>,<volume 0-100>)
pm('Ambient01a.ogg',1,100)

You can stop music by just feeding script-eval with "sm()".

BE VERY CAREFUL WITH MANIPULATING THE STRING. YOU MESS SOMETHING UP, THE SCRIPT WILL NOT WORK. READ THE README IF YOU ARENT 100% SURE!

Thank you and take care all.

[mjn.mixael]

 

[Droid803]

looping?

is it possible?

if not I'll still have to stick to play-sound-from-file sexp

[mjn.mixael]

Loops automatically and indefinitely until you change the track or close the file.

[Droid803]

awesome.

EDIT: I don't understand the purpose of all the FRED variables when I can just feed script-eval the function. Seems like the whole variable thing is more likely to cause ****ups (during copy/pasting) than the feeding script-eval a single string (and god help you if you can't even properly format one string)

[pecenipicek]

EDIT: I don't understand the purpose of all the FRED variables when I can just feed script-eval the function. Seems like the whole variable thing is more likely to cause ****ups (during copy/pasting) than the feeding script-eval a single string (and god help you if you can't even properly format one string)

Relative ease of use. and if you cant copypaste a single when and modify three values, god help you.

it basically takes out the potential to **** it up, by making sure that the fredder cant **** it up if he followed the readme.


call it overkill, but i like to think i might have stopped a few occurences of idiocy and morons.

[Droid803]

Still feel that telling people to open the mission with a text to paste in events and variables manually has more of a chance to **** up something than just telling them to input a script-eval string if they don't know what they're doing, but ok.