Sound operators

From Valve Developer Community
Jump to: navigation, search

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.

To do: 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
mod
Returns the remainder of A / B, or the modulus.
invert_scale
Unknown behaviour. Always performed on the output of cos(), and then used to multiply another value.
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

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:
round
Round to the nearest 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.
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.
normalise_trig
Set to "true" or "false". Unknown behaviour, but false computes normal trignometric values.

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
The value to remap.
input_min
input_max
The smallest/largest value the input will be set to.
input_map_min
When the input equals input_min, the output will be this value.
input_map_max
When the input equals input_max, the output will be this value.
  • math_delta

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.
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

get_opvar_float

Setters

Change values in the engine.

  • set_convar
  • set_opvar_float
  • increment_opvar_float


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.

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