View source for Soundscripts/Operator Stacks

'''Operator stacks''' are a system for soundscripts allowing to add complex behaviour to sounds.

They are unrelated to [[Soundscape]]s.

Operator stacks were introduced in the {{p2branch|4}}. Outside {{p2|2}}, they are supported in {{csgo|2}} and {{dota2|2}} (which now uses {{src2|2}}; the operator stacks have been greatly expanded upon and many of their names have been changed), {{doi|2}}, and {{insurgency|2}}.

== Syntax ==

Any [[Soundscripts|soundscript]] can use operator stacks by specifying the key-value pair <code>soundentry_version 2</code> as well as a keyvalue named <code>operator_stacks</code>.

{{note|We may refer to "''this'' sound entry" in the context of a sound operator; It means the sound entry inside which the operator is used.}}
<syntaxhighlight lang=php>
"Entry.Name"
{
	channel		CHAN_STATIC
	soundlevel	SNDLVL_NONE
	volume		1.0
	wave		"common/null.wav"

	soundentry_version 2

	operator_stacks
	{
		prestart_stack	// optional
		{
			// sound operators...
		}
		start_stack		// optional
		{
			// sound operators...
		}
		update_stack	// optional
		{
			// sound operators...
		}
		stop_stack		// optional
		{
			// sound operators...
		}
	}
}
</syntaxhighlight>
{{note|Soundscripts and thus operator stacks are written in the [[KeyValues]] format where quotation marks <code>"..."</code> around tokens are always optional if the token does not contain any whitespace. In your code, you are free to use or omit quotes in any way you want. Thanks to syntaxhighlighting, we can use quoted strings on this page in a sparing but meaningful way to emphasize:
*sound entry names (<code>"Sound.Entry"</code>),
*file paths (<code>"sound/file.wav"</code>),
*operator types (<code>"sys_stop_entries"</code>) and
*operator stack names when using <code>import_stack</code> (<code>"p2_update_default"</code>).
}}

=== Stack types ===

There are four types of stacks, each triggered at different times. Inside these stacks, one can put one or multiple ''sound operators''.

{| class=wikitable
| <code>prestart_stack</code><br><code>start_stack</code>
| Executed once when the sound entry is started, in this order. For {{ent|ambient_generic}}, this is when it receives the <code>PlaySound</code> input.
|-
| <code>update_stack</code>
| Executed regularly during playback.
{{note|Adding an empty <code>update_stack</code> plays no sound at all. That's normal. You likely want to start every <code>update_stack</code> by importing a stack that targets speakers, such as <code>import_stack</code> with a value of {{operator stack|p2_update_default|p2}} or {{operator stack|update_music_stereo|p2}}. Look through <code>scripts\[[sound_operator_stacks.txt]]</code> to find a fitting base for your purpose.}}
|-
| <code>stop_stack</code>
| Executed once when the sound entry ends or is stopped. For {{ent|ambient_generic}}, this is when it receives the <code>StopSound</code> input. Note that this does not necessarily stop the sound immediately if the operator <code>sys_output</code> with <code>output stop_hold</code> is used, allowing for concepts like fadeout.
|}

=== Sound operators ===

''Sound operators'' (or just ''operators'') are keyvalues inside any of the stack types and consist of the following.
{| style=margin:0
|- style=vertical-align:top
|
<syntaxhighlight lang=php>
// Pseudo code ("<...>" represents a string):

<operator_name>
{
	operator "<operator_type>"
	<attribute1> <value1>
	<attribute2> <value2>
	// ...
}
// may define an output value: @<operator_name>.<output1>
</syntaxhighlight>
|
<syntaxhighlight lang=php>
// Concrete example:

add_floats
{
	operator "math_float"
	apply add
	input1 3.0
	input2 5.0
}
// defines the output value: @add_floats.output (hopefully 8.0)
</syntaxhighlight>
|}
This entire structure is what we call a "sound operator" (or just "operator" for short), consisting of an "operator name", an "operator type" and its "operator attributes". A sequence of operators form an '''"operator stack"'''. The order of operators matters.
{{note|We use the term "operator type" to avoid confusion. It may be tempting to also call it the "operator name", but otherwise we have two different things with the same term.<br>Similar with the term "operator" which we use to describe the entire sound operator keyvalues (that one can refer to by its operator name). By "operator" one might also mean an operator type.}}

{| class=wikitable
! Operator name
|
The name of an operator can be an arbitrarily chosen string. This name is needed to reference an operator's output ("which operator?") and for debug printing purposes.

There is special behavior going on if there are two operators with an equal name: The latter will ''override'' any attributes of the former (by ''merging'' the latter keyvalues into the former).
When [[#Importing stacks]], overriding operators by choosing an equal operator name is intentional. Otherwise, equal operator names are most likely unnecessary or &ndash; if overlooked &ndash; cause problems and should thus be avoided.
|-
! Operator type
|
The operator type determines what the operator does and which attributes and outputs it has. A list of available operators can be obtained with the console command <code>snd_sos_print_operators</code>. Examples are <code>sys_output</code>, <code>math_float</code> or <code>get_entry_time</code>.
{{main|Sound operators}}
|-
! Operator&nbsp;attributes
|
Depending on the operator type, the operator has some set of internal attributes with some value (floats, strings, ...) which can be set to either a constant expression such as <code>1.0</code>, <code>"Default.Null"</code>, etc. or to the output of a previous operator using a preceding <code>@</code> symbol, such as <code>"@<operator_name>.<output>"</code>.
Every attribute has some default value, which is used whenever an attribute in an operator is omitted.
When trying to set an attribute that the operator doesn't know, the system writes a line to the console:
<code>Error: Operator <operator_name>, unknown sound operator attribute <attribute></code>

 {| style="float:right; margin-left:1em; padding:0"
 |
<syntaxhighlight lang=php>
rand_default
{
	operator		"math_random"
	execute_once	false
	input_execute	1
	input_min		0.0
	input_max		1.0
	input_seed		-1.0
}
</syntaxhighlight>
 |
<syntaxhighlight lang=php>
rand_default
{
	operator "math_random"
}



// equal to the left one
// due to default values
</syntaxhighlight>
 |}
 {| class=standard-table
 |+ Attributes that all sound operators have in common
 ! Attribute !! Default
 ! Description
 |-
 | <code>input_execute</code> || 1.0
 | If set to a value &le; 0.0, this operator is not executed, i. e. skipped.
 |-
 | <code>execute_once</code> || false
 | Whether the operator should run every time the stack is evaluated, or only the first time. Output values are presumably stored between executions in the latter case.
 |}
|-
! Operator outputs
|
Furthermore, an operator may have ''outputs'' depending on the operator type. As opposed to ''attributes'', outputs can be read and not set. Outputs receive their values after an operator has finished execution (i. e. their value is undefined in the text editor).
|}

Example for a <code>start_stack</code> referencing the operator types {{Sound operator|math_random}} and {{Sound operator|sys_output}}:
<syntaxhighlight lang=php>
"Entry.Name"
{
	// ...

	operator_stacks
	{
		start_stack
		{
			random_number	// operator name (arbitrary)
			{
				operator	"math_random"	// operator type. "math_random" stores a random number (-3 <= x <= 3) inside '@random_number.output'
				input_min	-3.0			// lower boundary for the random value
				input_max	 3.0			// upper boundary for the random value
			}
			apply_delay		// operator name (arbitrary)
			{
				operator	"sys_output"			// operator type. The effect of "sys_output" depends on its attribute named 'output'
													// (which is not an operator output in this case)
				output		delay					// applies a delay to the sound (negative delay = skip into the sound)
				input_float	@random_number.output	// accesses the output of the previous operator 'random_number' which (also) has the name 'output'
			}
		}
	}
}
</syntaxhighlight>

=== Importing stacks ===

Instead of always starting from scratch, one can use the <code>import_stack</code> command to extend a predefined template.
There are 28 operators used in {{portal2|3}}, but they are re-configured and combined in hundreds of different ways. Most of the resulting "stacks" are very specific, and this page will only deal with the more general ones.
{{todo|Work out a sane way of documenting all this!}}

Inside any operator stack, one can add the statement <code>import_stack <stack_name></code> where <code><stack_name></code> is one from <code>[[sound_operator_stacks.txt]]</code>. One can imagine that its effect is that the text is copied over. The clue is that any operator (including imported ones of course) can be ''overridden'' in their values (see the examples below). That's why predefined operator stacks typically define operators with constant changes, null sound entry names or things like a fade time of 0 seconds: After importing, one only needs to override the right value to get a fade time of 3 seconds, because the "hard work" of performing a volume fade is already solved by the imported stack!
{| style="border:2px solid rgba(255,255,255,0.2); padding:1em; margin:2em"
|+ '''What happens when importing a stack?'''
|colspan=5|
Inside <code>portal2\scripts\sound_operator_stacks.txt</code>, under <code>stop_stacks</code>, one can find {{operator stack|stop_and_play|p2}}:
<syntaxhighlight lang=php>

"stop_and_play"
{
	play_entry
	{
		operator "sys_start_entry"
		execute_once true
		input_execute	1
		input_start 1
		entry_name "Default.Null" //Replace with the sound you want to play.
	}	
}
</syntaxhighlight>
|-
|
<syntaxhighlight lang=php highlight=3>
// What you type:

import_stack "stop_and_play"

play_entry
{
	entry_name "Player.PickupWeapon"
}
</syntaxhighlight>
| <span style=font-size:200%>&rarr;</span>
|
<syntaxhighlight lang=php highlight=3-10>
// What it becomes after copying over:

play_entry
{
	operator "sys_start_entry"
	execute_once true
	input_execute	1
	input_start 1
	entry_name "Default.Null"
}	

play_entry
{
	entry_name "Player.PickupWeapon"
}
</syntaxhighlight>
| <span style=font-size:200%>&rarr;</span>
|
<syntaxhighlight lang=php>
// What it becomes after merging:

play_entry
{
	operator "sys_start_entry"
	execute_once true
	input_execute	1
	input_start 1
	entry_name "Player.PickupWeapon" // <-- overridden
}	
</syntaxhighlight>
|}

Full sound entry example using <code>import_stack</code> on {{operator stack|P2_exclusion_time_blocker_start|p2}}:
<syntaxhighlight lang=php <!--highlight=14-31-->
VFX.LightFlickerEnd 
{
	channel		CHAN_AUTO
	soundlevel	SNDLVL_105db
	volume		1.0
	rndwave
	{
		wave	"vfx/light_flicker/light_flicker_end_01.wav"
		wave	"vfx/light_flicker/light_flicker_end_02.wav"
		wave	"vfx/light_flicker/light_flicker_end_03.wav"
		wave	"vfx/light_flicker/light_flicker_end_04.wav"
	}

	soundentry_version 2

	operator_stacks
	{
		start_stack // applied when the sound begins
		{
			import_stack 	"P2_exclusion_time_blocker_start" // defined in scripts/sound_operator_stacks.txt

			// We are now extending/configuring "P2_exclusion_time_blocker_start"
			// which contains an operator with the exact name "block_entries" whose values we will now override:

			block_entries // prevents another sound from playing
			{
				input_duration	0.25					// seconds to block for
				match_entry		"World.LightFlickerEnd"	// the sound entry to block
				match_entity	false					// only on the same entity that this sound is playing from?
			}
		}
	}
}
</syntaxhighlight>

== Debugging tools ==

=== util_print_float ===
There is the operator type {{Sound operator|util_print_float}} to write a float value to the console along with its operator name.
If it is no longer needed, this operator can safely be commented out with no other impact.
<syntaxhighlight lang=php>
print_operator
{
	operator	"util_print_float"
	input		123					// more useful: "@<other_operator>.<output>"
}
// will print to the console:
// "SOS PRINT FLOAT: print_operator: 123.000000"
</syntaxhighlight>

=== Useful console commands ===
In-game, there are various useful console commands or convars to show debug information about sounds or sound operators being executed. Note the abbreviation <code>sos</code>, presumably for Sound Operator System. There are more commands starting with <code>snd_sos_*</code>.
{| class=wikitable
| <code>playgamesound <sound_entry></code> || Plays a sound entry.
|-
| <code>stopsound</code> || Stops all current sounds.
|-
| <code>snd_show 1</code> || Shows all current sound channels along with file path, sound entry, duration and volumes.
|-
| <code>sv_soundemitter_flush</code> || Reloads all soundscripts. Useful to apply changes to a soundscript without having to restart the game.
|-
|
<code>snd_sos_show_operator_prestart <0/1></code><br>
<code>snd_sos_show_operator_start <0/1></code><br>
<code>snd_sos_show_operator_update <0/1></code><br>
<code>snd_sos_show_operator_stop_entry&nbsp;<0/1></code>
| Shows the state of all operators for the different stack types, including existing properties and their current values. For example, when the above operator is executed in a <code>start_stack</code>, the following output will be written to the console:
<pre>
    Name: print_operator

    Execute Once: false
    input_execute: 1.000000
    input: 123.000000
</pre>
|}

== Examples ==

=== Start another sound ===

Plays another sound entry. The following two examples are equivalent.
{{seealso|{{sound operator|sys_start_entry}}, {{operator stack|stop_and_play|p2}}}}
<syntaxhighlight lang=php>
play_other_entry // arbitrary name
{
	operator	"sys_start_entry"
	entry_name	"VFX.FizzlerDestroy" // sound entry to start
	input_start	1
}
</syntaxhighlight>
<syntaxhighlight lang=php>
import_stack "stop_and_play"	// this is defined under the stop_stacks in Portal 2, hence
								// the misleading name. importing this does not stop anything.

play_entry // overriding, not arbitrary!
{
	entry_name "VFX.FizzlerDestroy" // sound entry to start
}
</syntaxhighlight>

=== Limit the number of sounds ===

Limits the maximum number of sounds that can be played at once, either by sound name or entity. A sound will not stop itself from playing.
{{seealso|{{operator stack|P2_poly_limiting_start|p2}}}}
<syntaxhighlight lang=php>
start_stack
{
	import_stack "P2_poly_limiting_start"
	
	limit_sound
	{
		match_entry			"VFX.OGSignFlicker"
		input_max_entries	3.000000
	}
}
</syntaxhighlight>

=== Crop a sound ===

The following skips the first <code>7.10</code> seconds of the sound file and plays only for <code>0.50</code> seconds. An alternative solution takes the time stamp, not the duration. If only one end of the sound should be cropped, you can remove the appropriate stack.
{{note|The stack <code>update_stop_at_time</code> takes a sound duration to define the stop time, <code>p2_update_stop_at_elapsed</code> takes a time stamp. The difference comes from the former using {{Sound operator|get_entry_time}}'s output <code>output_entry_elapsed</code> and the latter using <code>output_sound_elapsed</code> instead.}}
{{seealso|{{sound operator|sys_output}}, {{operator stack|p2_update_default|p2}}, {{operator stack|update_stop_at_time|p2}}}}
<syntaxhighlight lang=php>
start_stack
{
	// skips the first 7.10 seconds of the sound file
	crop_start
	{
		operator	"sys_output"
		input_float	-7.10		// note the negative delay
		output		delay
	}
}
update_stack
{
	// plays only 0.50 seconds of the entry
	import_stack "p2_update_default"
	import_stack "update_stop_at_time"	// alternative: "p2_update_stop_at_elapsed"
	usat_stop_time						// alternative: time_elapsed_trigger
	{
		input2 0.50						// alternative: 7.60
	}
}
</syntaxhighlight>

=== Music ===

Observing the Portal 2 music soundscripts, it is generally recommended for music to use the stream [[Soundscripts#Sound characters|sound character]] before its path (<code>*music/file.wav</code>) and to include one of the predefined stacks {{operator stack|update_music_stereo|p2}} or {{operator stack|update_music_spatial|p2}}. These two already contain useful operators that one can override, which solve fade in, fade out, [[LFO]], [[DSP]] and spatializing:
{| class=wikitable
! Operator name
! Attribute
! Default
! Effect
|-
| <code>volume_fade_in</code>
| <code>input_max</code> || 0.0
| Fade in time in seconds when the sound starts
|-
| <code>volume_fade_out</code>
| <code>input_max</code> || 0.0
| Fade out time in seconds after the entry is stopped
|-
| <code>volume_apply_adjust</code>
| <code>input1</code> || 1.0
| Volume scale factor (will be clamped to sound system's maximum volume)
|-
| <code>volume_lfo_time_scale</code>
| <code>input2</code> || 0.0
|| LFO time scale factor. Setting it to <code>t</code> makes the volume oscillate with a cycle of <code>|t| * 2 * PI</code> seconds. To get a specific cycle in seconds, use that number times 6.283. (The underlying cos function accepts radians and receives seconds.)
|-
| <code>volume_lfo_scale</code>
| <code>input2</code> || 0.0
| LFO volume scale factor. Setting it to <code>x</code> (between 0.0 and 1.0) will make the volume oscillate between <code>1.0</code> and <code>1.0-x</code> times the normal volume. If set to a value too close to 1.0, the sound may stop; use a lower value such as 0.98.
|}

The following apply only to <code>update_music_spatial</code>:
{| class=wikitable
! Operator name
! Attribute
! Default
! Effect
|-
| <code>dsp_output</code>
| <code>input_float</code>
| 0.0
| Sets the DSP value via {{Sound operator|sys_output}}.
|-
| <code>speakers_spatialize</code>
| <code>input_radius</code>
| 300
| Sets the radius of the "sphere" around the music source inside which the sound becomes no longer directional (L/R volume levels equalize), see {{sound operator|calc_spatialize_speakers}}.
|}

<syntaxhighlight lang=php>
// Any music should import an update_music stack

update_stack
{
	import_stack "update_music_stereo" // or "update_music_spatial"

	// loop up operators that we want to override in the above table
	volume_fade_in
	{
		input_max 3.0
	}
}
</syntaxhighlight>

==== Synchronization ====
Suppose <code>music.b0</code> is already looping and we want to start <code>music.b1</code> (which has the same length) such that it plays in sync.
{{seealso|{{operator stack|start_sync_to_entry|p2}}}}
<syntaxhighlight lang=php>
// We're inside the entry "music.b1"

start_stack
{
	import_stack "start_sync_to_entry" // or "start_delay_sync_to_entry" to instead make "music.b1" wait until it can start in sync, without skipping into the music
	elapsed_time
	{
		entry "music.b0" // find the music that is already playing
	}
	duration_div
	{
		input2 1 // default is 4; if "music.b1" is 1/x the length of music.b0, then use x
	}
}
</syntaxhighlight>

=== Moving sound ===

Smoothly transitions a sound from one location to up to eight others as the player moves through a map. An unreleased tool can auto-generate these. Position 1 is where the sound was emitted from.
{{tip|The tool mentioned above ''may'' be in the files of {{ddd|4}}.}}
{{seealso|{{operator stack|p2_update_dialog_spatial_cave|p2}}}}
<syntaxhighlight lang=php>
import_stack "p2_update_dialog_spatial_cave"

position_array
{
	input_entry_count 3
	// position 2
	input_position_1[0]	2129
	input_position_1[1]	-850
	input_position_1[2]	-1267
	// position 3
	input_position_2[0]	1473
	input_position_2[1]	-1200
	input_position_2[2]	-1343
}
</syntaxhighlight>

== See also ==
*[[Sound operators]]
*[[sound_operator_stacks.txt]]
*[[Soundscripts]]
*[[Sound and Music]]


[[Category:Sound System]]