Sound operators: Difference between revisions

Revision as of 03:52, 17 February 2021

These are the root sound operators referenced in Portal 2. See scripts/sound_operator_stacks.txt and Soundscripts#Operator stacks for more details.

To chain operators together, values can be set to @prev_op_name.property_name to read a value. For vectors the names can be appended with an index in square brackets to set/get a specific value.

Todo: Make this more beginner-friendy?

Usage

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

			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?
			}
		}
	}
}

Common properties

execute_once: Whether the operator should run every time the stack is evaluated, or only the first time. Output values are presumable stored between executions in the latter case.
input_execute: The operator will only run if this value is true (i.e. non-zero).
output: The result of the operator (if there is one). Accessed with @OperatorName.output.

There is also one special command that is not an operator:

import_stack: Inserts another named stack into this one.

Operator list

System

Affect sound playback.

sys_stop_entries

Ends existing sounds.

input_execute <float>

Will execute this operation if its value is greater than 0.0. Default value is 1.0

input_max_entries <float>

Amount of instances allowed to play before one of the instances is stopped and replaced by a new instance of the sound entry.

input_stop_delay <float>

Adds a delay before an instance of the sound entry is stopped.

match_entry <string>

The sound entry name to look for.

output_entries_matching

Confirm:Outputs the number of entries matching the defined entry.

Usage: "input1"(of a separate operation) "@your_stop_entry_operation.output_entries_matching"

output_this_matches_index: Uncertain. It's an output so it'd be used in the same manner as output_entries_matching.
match_sound <string>: Match the name of the audio file.; Confirm: Is the path needed or just the audio file name and format?
match_substring <bool>: Whether match_entry can be part of a larger string (e.g. "MyGun" matches MyGun.fire, MyGun.reload).
match_channel <bool>: Sound must have the same channel (e.g. CHAN_STATIC) as this one to match.
match_entity <bool>: Sound must be coming from the same entity as this one.
stop_oldest <bool>: Stops the oldest instance of the sound entry.
invert_match <bool>

sys_start_entry

Plays another sound.

input_execute <float>: If its value is greater than 0.0, this operation will execute. Default value is 1.0
input_start <float>: If its value is greater than 0.0 the sound entry will start. Default value is 1.0
entry_name <string>: The entry to play.
input_start_delay <float>: Adds a delay before an instance is played.
input_maintain_seed <float>: Greater than 0.0 will ensure that the rndwave selection is maintained.

sys_block_entries

Prevents new sounds from playing.

input_duration: How long to suppress sounds for.
input_active: Confirm:In addition to normal duration, suppress only when this value is true?
match_entry: Sound entry to suppress.
match_sound: A raw WAV/MP3 filename to match. Possibly deprecated?
match_substring: Whether match_entry can be part of a larger string (e.g. "MyGun" matches MyGun.fire, MyGun.reload).
match_channel: Sound must have the same channel (e.g. CHAN_STATIC) as this one to match.
match_entity: Sound must be coming from the same entity as this one.

sys_output

Sends a value back to the sound system relating to the current entry.

input_float

Takes a float value to send to the system.

input_vec3

Vector.

input_speakers

Takes an array of floats to send to the system, each to do with a certain speaker. Use only with the speakers output.

output

Says what value should be altered, for example:

speakers: Use in update_stacks only. Adjusts the volume of each speaker according to values given by input_speakers.
pitch: Use in update_stacks only. Adjusts the playback pitch of the sound to the value given with input_float.
dsp: Use in update_stacks only. Adjusts the DSP of the sound to the value given with input_float.
delay: Use in start_stacks only. Waits for the number of seconds specified in input_float before starting the sound. A negative value results in it starting the sound that many seconds into the WAV file instead of at the beginning.
block_start: Use in start_stacks only. Prevents the sound from starting if the value given with input_float is non-zero.
mixlayer_trigger: "Tell the mixlayer we're active" if the value given with input_float is non-zero.; Note:A mixlayer allows you to modify properties (volume, level, dsp) of individual mixgroups within the active soundmixer. mixlayers can be found and created in soundmixers.txt.
save_restore: Confirm:Use in update_stacks only. Tells the system to save and restore the state of the sound if the value given with input_float is non-zero.
stop_hold: Use in update_stacks only.
Confirm:Prevents the sound from stopping if the value given with input_float is non-zero.
facing: Confirm:Make the sound play in a certain direction?

sys_platform

Tests what platform the engine is running on.

pc
x360
ps3: Should the operator return true if running on this platform?

sys_mixlayer

Configures a Mixlayer. See scripts\soundmixers.txt

mixlayer <string>

The layer to alter.

Note:A mixlayer allows you to modify properties (volume, level, dsp) of individual mixgroups within the active soundmixer. mixlayers can be found and created in soundmixers.txt.

mixgroup <string>: The sound group within the layer to alter.
field <string>: Property of the group to alter.
input <float>

Maths

Generate or process numbers.

The result of these is stored in @name.output.

math_random

Produces a random number.

input_min
input_max: Range of values to output.
round_to_int: Set to "true" or "false"(default). This makes the output a whole number.

math_float

Performs elementary maths operations with two values.

input1

input2

The two operands to use.

apply

Specifies the operation to perform:

add: A + B
sub: A - B
mult: A * B
div: A / B. If B is negative or zero, returns zero.
pow: Raises the base input1 to the power of input2 (Exponent).
mod: Returns the remainder of A / B, or the modulus. If B is negative or zero, returns zero.

invert: Returns 1 - A, ignoring B.

invert_scale: Returns 1 + AB - B.
min: Outputs the smallest of the two numbers.
max: Outputs the largest of the two numbers.

less_than: Checks if A < B, and outputs 1.0 or 0.0.
greater_than: Checks if A > B, and outputs 1.0 or 0.0.
less_than_or_equal: Checks if A ≤ B, and outputs 1.0 or 0.0.
greater_than_or_equal: Checks if A ≥ B, and outputs 1.0 or 0.0.
equals: If both are equal outputs 1.0, otherwise 0.0.
not_equal: If both are different outputs 1.0, otherwise 0.0.

math_float_accumulate12

Does the same as math_float, but uses 12 inputs instead. All examples use mult.

math_func1

Executes various maths functions.

input1

The argument to pass.

function

Specifies the function to call:

none: Do nothing to the input.
round: Round to the nearest whole number.
floor: Round down to a whole number.
ceil: Round up to a whole number.
fabs: Compute the absolute value of the input.
sqrt: Computes the square root of the input.
exp: Computes e raised to the power of the input.
log: Computes the natural logarithm of the input.
log10: Computes the logarithm base 10 of the input.
sin
cos
tan: Computes the normal sin/cos/tan values. Angles are given in radians.
asin
acos
atan: Computes the inverse of sin/cos/tan. Angles are given in radians.
sinh
cosh
tanh: Computes the hyperbolic version of sin/cos/tan. Angles are given in radians.

normalise_trig: If set to "true", rescales the output from (-1, +1) to (0, 1).

math_logic_switch

Selects one of two possible outputs.

input_switch: Chooses which of the other values is outputted.
input1: The value to output if input_switch is 0.
input2: The value to output if input_switch is 1.

math_curve_2d_4knot

Multinode Remapper. Found in Insurgency(2014) and Day of Infamy sound_operator_stacks.txt.

curve_type: step, linear
input: Value that is compared to X: if input = X1 then ouput = Y1, if input = X2 then ouput = Y2, etc.
input_X1
input_Y1
input_X2
input_Y2
input_X3
input_Y3
input_X4
input_Y4

math_remap_float

Remaps a value from one range to another (identically to math_remap).

input <float>: The value to remap.
input_min <float>
input_max <float>: The smallest/largest value the input will be set to.
input_map_min <float>: When the input equals input_min, the output will be this value.
input_map_max <float>: When the input equals input_max, the output will be this value.

math_delta

input <float>

Getters

Provide values from the engine.

get_convar

Retrieve the value of a console variable.

convar: The name of the console variable to read.

get_dashboard

get_map_name: Checks if the given map_name matches the name of the map.

get_sys_time

Collects the host/client time.

output_client_time
output_host_time

get_entry_time

Collects information about the playing sound.

output_entry_elapsed: The time this sound has been playing.
output_sound_elapsed
output_stop_elapsed: -1 if playing, otherwise the time spent after being stopped.
output_sound_duration: The duration of the current sound. Zero during the start stack.

get_source_info

Collects a variety of information about the sound source.

source: Specify "entity" or "emitter" to choose which entity is checked. The emitter is the entity where the sound emmenates from, the entity is the entity which made it play.
game_multi_origin <bool>

Below are the data points output by this operator: @my_get_source_info_operator.output_position, etc..

output_entity_index: The index for this entity.
output_position: The position of the entity.
output_angles: The rotation of the entity.
output_radius: Only valid for the emitter.
output_volume
output_level
output_pitch: The relevant values of the soundscript.
output_source_count: The number of sounds (including this one) produced by the entity.

game_view_info

Collects a variety of game-specific information about the player for specialised uses.

output_velocity_xy
output_velocity_vector_z
output_position_x
output_position_y
output_position_z: Returns the vector or X/Y/Z position for the provided input_source_index.
output_stop_elapsed

get_track_syncpoint

Used to sync one sound entry to another.

syncpoint_list <string>
this_entry_syncpoints <bool>
input_min_time_to_next_sync <float>
input_max_time_to_next_sync <float>
match_entry <string>: Sound entry to match.

Example get_track_syncpoint

"start_delay_to_track_sync_point"
	{
		// the start sync point for the file we are syncing to
		"this_entry_syncpoints"
		{
			"operator" "get_track_syncpoint"
			"syncpoint_list" "syncpoints_1"
			"this_entry_syncpoints" "true"
		}
		"sync_track_syncpoints"
		{
			"operator" "get_track_syncpoint"
			"syncpoint_list" "syncpoints_1"
			"input_min_time_to_next_sync" 	"@this_entry_syncpoints.output_first_syncpoint"
			"input_max_time_to_next_sync" 	"1000"
			"match_entry" "DOTAMusic.BattleMusic"
		}
		// output our resulting delay value
		"delay_output"
		{
			"operator" "sys_output"
			"input_float" "@sync_track_syncpoints.output_time_to_next_syncpoint"
			"output" "delay"
		}
	}

get_soundmixer

Outputs the active soundmixer
mixgroup <string>
set_mixgroup_to_channel <bool>

get_opvar_float

Creates a variable to use in your stack.

opvar <string>

"MyStack"
{

 "Get_Opvar"
 {
     "operator"    "get_opvar_float"
     "opvar"       "myVar"
 }

 "Increment_myVar"
 {
     "operator"     "increment_opvar_float"
     "input"        "1.0"
     "opvar"        "myVar"
 }

 "Randomizer"
 {
    "operator"	    "math_random"
    "input_min"	    "500"
    "input_max"	    "1500"
    "round_to_int"  "true"
 }

 "gtoe"
 {
    "operator"	    "math_float"
    "apply"         "greater_than_or_equal"
    "input1"	    "@Increment_myVar.output"
    "input2"	    "@Randomizer.output"
 }

 "set_opvar"
 {
    "operator"      "set_opvar_float"
    "input_execute" "@gtoe.output"
    "opvar"         "myVar"
    "input"         "0.0"
 }

 "Play_Sound_Entry"
 {
    "operator"            "sys_start_entry"
    "input_execute"       "@gtoe.output"
    "execute_once"        "true"
    "input_start"         "1"
    "input_start_delay"   "0.0"
    "input_maintain_seed" "1"
    "entry_name"          "Name_Of_Sound_Entry.To_Play"
 }

}

In the above example (as a start_stack), every time the sound plays, the value of myVar increments by 1.
Once myVar equals or is greater-than the output of the math_random ("Ranomizer") operation by testing the output of the increment_opvar_float operation ("Increment_myVar") with the "Randomizer" output using a greater_than_or_equal operation ("gtoe"), myVar is reset to 0.
By inputing the output of the greater_than_or_equal operation into an input_execute parameter of a separate operation, you can use it to perform randomized events-like playing another sound entry using a sys_start_entry ("Play_Sound_Entry"), as seen in the code above.

Setters

Change values in the engine.

set_convar

Set a engine varaiable
convar <string>
input <float>

set_opvar_float

Set an opvar (operator varaible), created with the get_opvar_float operator, to the value defined in input
opvar <string>
input <float>: Note:See Sound operators#get_opvar_float for an example use of this operator.

increment_opvar_float

Increments an opvar variable created with the get_opvar_float operator, by the value set in the input parameter.
opvar <string>
input <float>: Note:See Sound operators#get_opvar_float for an example use of this operator.

Calculations

Calculate pre-set algorithms.

calc_source_distance

Calculates the distance from this sound source (emitter/entity) to the listener.

input_position: The sound source's position. Generally the output (@get_info_op.output_position) of a get_source_info operation.
in2D <bool>: X/Y vectors only.
force_not_player_sound <bool>

calc_falloff

Calculates the falloff of a sound based on the distance from the sound source (emitter/entity) to the listener and the multiplied output of the sound entries soundlevel and the level property value of its assigned mixgroup within the active soundmixer.

input_distance: Sound source position. Generally the output of a calc_source_distance operation.
input_level: Sound source's level/attenuation. Generally the output of a multiplication operation of the sound entries soundlevel and the mixgroup level within the active soundmixer.

calc_distant_dsp

Same setup as calc_fallof. Scales the dsp level defined in the sound's assigned mixgroup within the active soundmixer based on distance.

input_distance: Sound source position. Generally the output of a calc_source_distance operation.
input_level: Sound source's level/attenuation. Generally the output of a multiplication operation of the sound entries soundlevel and the mixgroup level within the active soundmixer.; Note:The output of this operation is then multipled by the dsp property value (@get_soundmixer_op.output_dsp) of the assigned mixgroup within the active soundmixer, with the output then being input to a sys_output dsp operation.

calc_spatialize_speakers

input_radius
input_distance
input_position
input_rear_stereo_scale

calc_occlusion

Performs audio occlusion calculations.

input_trace_interval
input_scalar
input_position: Generally the output (@get_info_op.output_position) of a get_source_info operation.

calc_angles_facing

input_angles: Generally the output (@get_info_op.output_angles) of a get_source_info operation.

Other

util_print_float

Displays a float in the console, along with the name of this operator.

input: The floating point value to show.

util_pos_vec8
op_accumulate_ss_float
iterate_merge_speakers
track_queue
track_stop
track_update

@@ Line 195: / Line 195: @@
 ::; <code>div</code>
 ::: A / B. If B is negative or zero, returns zero.
+::; <code>pow</code>
+::: Raises the base <code>input1</code> to the power of <code>input2</code> (Exponent).
 ::; <code>mod</code>
 ::: Returns the remainder of A / B, or the modulus. If B is negative or zero, returns zero.