XML:SNDD: Difference between revisions

XML:SNDD (view source)

Revision as of 17:49, 23 February 2023

1,577 bytes added , 23 February 2023

replaced old music scripting section with new one, correcting various information in the process

Iritscen

Bureaucrats, Interface administrators, Administrators

18,700

edits

@@ Line 223: / Line 223: @@
 |valign="top"| flag
 |
-: InterruptTracksOnStop — this flag must be set if you want to use the BSL command ''sound_music_stop''
+: InterruptTracksOnStop — don't wait for current .grp element to finish before stopping sound; used for dialogue, a few sound effects, some music pieces; music with this flag will immediately cut to its outro when <tt>sound_music_stop</tt> is called on it
-: PlayOnce
+: PlayOnce – prevents looping; used for dialogue, a few sound effects
 : CanPan
 |-
@@ Line 515: / Line 515: @@
          </SNDG>
-==Sound-related BSL commands==
+==Scripting music==
-* [[BSL:Functions#sound|Commands listed on wiki]]
+Here are the BSL commands you can use for music:<br>
-* [http://ssg.oni2.net/commands.htm#sound Original list on ssg's website]
+'''sound_music_start name:string [volume:float]''', e.g. <tt><code>sound_music_start mus_asian 0.75</code></tt>
-sound_music_stop ''soundtrack'' — can only be used if .amb file has the InterruptTracksOnStop flag<br>
+'''sound_music_stop name:string''', e.g. <tt><code>sound_music_stop mus_asian</code></tt><br>
-sound_music_stop ''soundtrack'' 1 — music drops to zero volume over 1 second
+If .amb file has InterruptTracksOnStop flag, music will proceed immediately to <OutSound>, otherwise current segment will finish playing and then <OutSound> will play.
-You need a custom function if you want to fade out a soundtrack over more than one second. It could look like this:
+'''sound_music_volume name:string volume:float [time:float]''', e.g. <tt><code>sound_music_volume mus_asian 0.35 1.0</code></tt><br>
+Volume change takes effect instantly unless you specify a time as the third parameter.
+----
+When Oni's BSL scripting wants to stop some music, it will either:
+# Call <tt>sound_music_stop</tt>.
+# Fade out the music with <tt>sound_music_volume</tt> and then call <tt>sound_music_stop</tt> when the music has reached zero volume.
- var float x = 1;
+When setting up your .amb file, you have to think about the timing of how the music will be used. If a music track has an <OutSound> in its .amb, then the sequence of events will be:<br>
- var int y = 0;
+:<tt>sound_music_stop</tt> called → current segment (SNDD) finishes playing → outro SNDD plays
- # Don't test this function with the console or the function might stop working after 4 cycles
+Thus it can be quite a while before the music really stops. If timing is a concern, such as in a cutscene, you could leave out the <OutSound> (but that would make your music end abruptly when the current segment finished playing), fade the music out over any amount of time that you desire, or use the InterruptTracksOnStop flag to skip to <OutSound> immediately so that the music ends sooner.
- func fade_music
- {
+Oni contains many variants of music OSBDs with and without the InterruptTracksOnStop flag, such as OSBDmus_amasian.amb and OSBDmus_amasian_hd.amb; they play the same actual SNDDs, but the "_hd" variant has the InterruptTracksOnStop flag; when <tt>sound_music_stop</tt> is called on a "_hd" OSBD, you will hear it immediately jump to the outro, which is slightly jarring but can be useful in some cases. An easily-observed example is OSBDmus_fiteb_hd, which plays in {{C2}} when combat starts after the opening cutscene. When the last blow is delivered to the attacking Strikers, the music will immediately jump to its outro, punctuating the end of the action.
-  	# An 'if' statement with float values doesn't seem to work, therefore the int y
- 	y = y + 1
- 	x = x - .01
- 	sound_music_volume (soundtrack, x)
- 	sleep 10
-  	if (y eq 99)
- 	{
- 		# dmsg "stop music"
- 		sound_music_stop soundtrack
- 	}
- 	if (y < 99)
- 	{
- 		fork fade_music
- 	}
- }
 ==OCF thread about making new music==