Sound operators: Difference between revisions

Revision as of 12:02, 13 May 2019

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 entry defined in any of the match_* variables?

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_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 within the LayerTriggers block. Use this to activate a mixlayer.
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 LayerTrigger. 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.

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

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

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

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_opvar_float
get_soundmixer
get_track_syncpoint

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

Setters

Change values in the engine.

set_convar
set_opvar_float
increment_opvar_float

Calculations

Calculate pre-set algorithms.

calc_angles_facing
calc_distant_dsp
calc_occlusion
calc_falloff

calc_source_distance: Calculates the distance from this sound to the provided input_position.

calc_spatialize_speakers

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 64: / Line 64: @@
 ; <code>sys_stop_entries</code>
 : Ends existing sounds.
-:; <code>match_entry</code>
+:; <code>input_execute</code> <[[float]]>
+:: Will execute this operation if its value is greater than <code>0.0</code>. Default value is <code>1.0</code>
+:; <code>input_max_entries</code> <[[float]]>
+:: Amount of instances allowed to play before one of the instances is stopped and replaced by a new instance of the sound entry.
+:; <code>input_stop_delay</code> <[[float]]>
+:: Adds a delay before an instance of the sound entry is stopped.
+:; <code>match_entry</code> <[[string]]>
 :: The sound entry name to look for.
-:; <code>match_substring</code>
+:; <code>output_entries_matching</code>
+:: {{Confirm|Outputs the number of entries matching the entry defined in any of the <code>match_*</code> variables?}}
+::: ''Usage: <code>"input1"</code>(of a separate operation) <code>"@your_stop_entry_operation.output_entries_matching"</code>''
+:; <code>output_this_matches_index</code>
+:: Uncertain. It's an output so it'd be used in the same manner as <code>output_entries_matching</code>.
+:; <code>match_sound</code> <[[string]]>
+:: Match the name of the audio file.
+:: {{Confirm| Is the path needed or just the audio file name and format?}}
+:; <code>match_substring</code> <[[bool]]>
 :: Whether <code>match_entry</code> can be part of a larger string (e.g. "MyGun" matches MyGun.fire, MyGun.reload).
-:; <code>match_channel</code>
+:; <code>match_channel</code> <[[bool]]>
 :: Sound must have the same channel (e.g. CHAN_STATIC) as this one to match.
-:; <code>match_entity</code>
+:; <code>match_entity</code> <[[bool]]>
 :: Sound must be coming from the same entity as this one.
-:; <code>input_max_entries</code>
+:; <code>stop_oldest</code> <[[bool]]>
-:: {{confirm|Stop all but this many instances of the sound?}}
+:: Stops the oldest instance of the sound entry.
+:; <code>invert_match</code> <[[bool]]>
 ; <code>sys_start_entry</code>
 : Plays another sound.
-:; <code>input_start</code>
+:; <code>input_execute</code> <[[float]]>
-:: {{confirm|In addition to whether the operator is active, only start if/when this value is true?}}
+:: If its value is greater than <code>0.0</code>, this operation will execute. Default value is <code>1.0</code>
-:;<code>entry_name</code>
+:; <code>input_start</code> <[[float]]>
+:: If its value is greater than <code>0.0</code> the sound entry will start. Default value is <code>1.0</code>
+:;<code>entry_name</code> <[[string]]>
 :: The entry to play.
+:; <code>input_start_delay</code> <[[float]]>
+:: Adds a delay before an instance is played.
+:; <code>input_maintain_seed</code> <[[float]]>
+:: Greater than <code>0.0</code> will ensure that the <code>rndwave</code> selection is maintained.
 ; <code>sys_block_entries</code>
 : Prevents new sounds from playing.
@@ Line 116: / Line 139: @@
 ::; <code>mixlayer_trigger</code>
 ::: "Tell the mixlayer we're active" if the value given with <code>input_float</code> is non-zero.
-::: {{todo|What does this mean?}}
+::: {{Note|A <code>mixlayer</code> allows you to modify properties (<code>volume</code>, <code>level</code>, <code>dsp</code>) of individual <code>mixgroups</code> within the active <code>soundmixer</code>. <code>mixlayers</code> can be found and created in <code>soundmixers.txt</code> within the <code>LayerTriggers</code> block. Use this to activate a <code>mixlayer</code>.}}
 ::; <code>save_restore</code>
 ::: {{confirm|Use in <code>update_stack</code>s only. Tells the system to save and restore the state of the sound if the value given with <code>input_float</code> is non-zero.}}
@@ Line 130: / Line 153: @@
 :: Should the operator return true if running on this platform?
 ; <code>sys_mixlayer</code>
-: Configures a [[sound mixer]]. See <code>scripts\soundmixers.txt</code>
+: Configures a <code>LayerTrigger</code>. See <code>scripts\soundmixers.txt</code>
-:; <code>mixlayer</code>
+:; <code>mixlayer</code> <[[string]]>
 :: The layer to alter.
-:; <code>mixgroup</code>
+:::{{Note|A <code>mixlayer</code> allows you to modify properties (<code>volume</code>,<code>level</code>,<code>dsp</code>) of individual <code>mixgroups</code> within the active <code>soundmixer</code>.}}
+:; <code>mixgroup</code> <[[string]]>
 :: The sound group within the layer to alter.
-:; <code>field</code>
+:; <code>field</code> <[[string]]>
 :: Property of the group to alter.
-:; <code>input</code>
+:; <code>input</code> <[[float]]>
-:: [[Floating point]] value to set.
 ; <code>get_track_syncpoint</code>
 : Used to sync one sound entry to another.
-:; <code>syncpoint_list</code>
+:; <code>syncpoint_list</code> <[[string]]>
-:; <code>this_entry_syncpoints</code>
+:; <code>this_entry_syncpoints</code> <[[bool]]>
-:: [[Boolean]] <code>true/false</code>.
+:; <code>input_min_time_to_next_sync</code> <[[float]]>
-:; <code>input_min_time_to_next_sync</code>
+:; <code>input_max_time_to_next_sync</code> <[[float]]>
-:; <code>input_max_time_to_next_sync</code>
+:; <code>match_entry</code> <[[string]]>
-:; <code>match_entry</code>
 :: Sound entry to match.
 ===== Example <code>get_track_syncpoint</code> =====

Sound operators: Difference between revisions

Revision as of 12:02, 13 May 2019

Contents

Usage

Common properties

Operator list

System

Example `get_track_syncpoint`

Maths

Getters

Setters

Calculations

Other

Navigation menu

Sound operators: Difference between revisions

Revision as of 12:02, 13 May 2019

Usage

Common properties

Operator list

System

Example get_track_syncpoint

Maths

Getters

Setters

Calculations

Other

Navigation menu

Search

Example `get_track_syncpoint`