View source for User:Yakumo koishi/Soundscapes cn

{{LanguageBar}}

<!-- Add the categories to the main page, not here. Some template, such as {{This is a}}, and all Table templates should be placed to the main page. -->
{{subpage|[[Sound and Music]]}}

'''Soundscape（音景）'''是一种音效脚本，用于向地图添加环境音效，它在地图中的数量没有严格限制，只需一个实体即可完成所有步骤，并且不会产生任何网络开销。音景通常为循环音效和随机音效的组合，这些声音可以通过从8个可分配的目标位置之一发出；同时还可以强制使用[[DSP]]和[[Soundmixer]]

每次只能同时播放一个音景，并且其中的任何声音都无法用I/O系统控制，当另一个音景启用时，游戏会自动淡入淡出

{{tip|
* 过渡时间由[[cvar|控制台指令]]<code>soundscape_fadetime</code>定义，或者在更新的游戏中由<code>fadetime</code>键值定义。
* 使用[[cvar|控制台指令]]<code>soundscape_debug</code>来检查哪个音景处于活动状态以及原因}}
{{note|
* 在不正常编译VVIS的情况下（如：以快速模式（<code>-fast</code>）编译），音景将无法正常工作
* 除非音频文件有标记点，否则它们无法作为循环音效，详见[[Looping a Sound]]
* 在''大部分''起源游戏中，音景无法同时播放统一音效，即便音调，音量和Sound Level不同，有关解决方法详见下方
* [[:Category:player spawn entities|玩家出生点]]至少应位于一个音景的半径范围内（[[trigger_soundscape|或边界框]]），否则玩家将在没有音景播放的情况下生成}}

==音景==
===浏览音景===
音景通常位于游戏的<code>scripts\</code>文件夹下多个以<code>soundscapes_</code>为前缀的文本文件。每一个音景都由全局清单<code>scripts\soundscapes_manifest.txt</code>控制，其中列出了游戏应读取的所有音景脚本。通过这种方法加载的音景可以用于游戏中的任何地方，即便它们是为某个场景专门设计的

音景同时还可以以地图专用的方法进行使用
{{pre|
scripts\soundscapes_<地图名>.txt
}}
此处的<code><地图名></code>应为它们所对应的BSP文件名称。这种音景可以在不修改全局清单的情况由地图自动读取，但也只能用于该地图中。
{{note|在{{Mapbase|4}}中，此方法变为<code>maps/<地图名>_soundscapes.txt</code>}}
{{note|在官方起源游戏中，这些文件通常被打包到VPK中，但可以被同路径下的未打包版本自动覆盖}}
你可以在页面底部找到部分游戏的音景列表链接，以及社区对部分音景效果的描述

You can browse through all the available soundscapes in a current game first hand, using the in-game console command <code>PlaySoundscape</code>. After typing in the first letter as the commands parameter, the auto-complete feature will list them as suggestions. You can then scroll through this list using the arrow keys.

===Configuring Soundscapes===
Soundscapes can only be configured through these entities:
*[[env_soundscape]]
*[[env_soundscape_triggerable]]
There are other entities which can activate the soundscape, but these are the only entities which actually define soundscape properties. The other entities will point to these and use them as masters to remotely trigger the soundscape.
Whenever these entities activate a soundscape, any positional audio will originate from the targets defined under their properties.{{tip| Many soundscapes define positions for sounds to emanate from, so it is always a good idea to  peek into the soundscape entry and get a feel for what you can do. Most entries are found in the text files listed in the <code><game>/scripts/soundscapes_manifest.txt</code> file. To better understand soundscape entries, [[Soundscape#Custom_Soundscapes|see below]].}}

===Activating Soundscapes===
Any soundscape entity that is enabled and becomes triggered by the player, activates its - or its master's - specified soundscape. Soundscapes remain active until a map change occurs, or another soundscape is activated, even if the entity that originally activated it becomes disabled. {{tip|The <code>soundscape_flush</code> console command will cancel an active soundscape.}}


===Soundscape entities===
Soundscapes can be activated by any of the following entities:

*[[env_soundscape]]
*[[env_soundscape_triggerable]] (in turn typically activated by a [[trigger_soundscape]].)
*[[env_soundscape_proxy]] (in turn activates an env_soundscape or an env_soundscape_triggerable.)

Soundscape entities are themselves [[point_entities|point-based]], but trigger when the player enters their specified radius and the entity has a [[line of sight]] to them.

The two exceptions to this are env_soundscape_proxy (that is triggered through an env_soundscape or an env_soundscape_triggerable), and env_soundscape_triggerable (that is typically set to also be triggered by a trigger_soundscape).

As only one soundscape can be active at any one time, if one or more soundscape entities are triggered simultaneously, the closest one is given precedence. (The radius of soundscape entities always take precedence over trigger_soundscape brushes.)

Note that a soundscape will ''not'' stop playing just because a player exits its radius or it loses line of sight to them.


{{tip|Use the [[cvar]] [[soundscape_debug]] to examine which entity is active and why.}}


===Soundscape Placement===
At first, a good rule is to place only as many soundscapes as you absolutely need. Try to choose from a similar set of soundscapes to be played, and then pick one that will be your primary soundscape. After that, place your secondary soundscapes at every contrasting location (e.g. house, generator room).  Make sure that every location with localized sound effects has its own master soundscape that is tied to the proper targets.  

Once you've gotten a general idea of where your soundscapes will be located, you'll then be able to start adding/configuring the entities that will trigger your soundscapes and create a kind of ''blueprint'' for how soundscapes will flow from one to another. In many cases, you'll be placing entities that block off all exits from your contrasting locations with triggers to your primary soundscapes. Basically, the goal is to anticipate the player's movement throughout the map, and to block off each area in such a way that it will always have the proper soundscape activated.

After your flow is organized, you'll be able to specialize your soundscapes/triggers to behave in complex ways (e.g responding to game events).

===Multiple instances of one sound in one soundscape===
Currently, in most ''Source'' engine branches, it is impossible to play two or more identical sounds at same time in the same soundscape, even if the volume, the pitch or the sound level is different.

This issue has been remedied {{csgo|since}}, allowing soundscapes to play multiple instances of identical sounds concurrently.
{{clarify|Has this been fixed in any pre-CS:GO branches?}}

A possible solution is to create a copy of the first sound and name it differently. This can be a workaround for really short sounds like light hum, but not recommended for others due to the fact that it increase the overall size uselessly. This is the solution that Valve has chosen in ''cs_militia'', in [[Counter-Strike:_Source|Counter-Strike Source]]. In the kitchen, there are two fluorescent lights with hum sounds, but the first one is "<code>ambient/machines/fluorescent_hum_1.wav</code>" and the second one is "<code>ambient/machines/fluorescent_hum_2.wav</code>". Those two sounds are completely identical, but need to be two different name in order to be used in the same soundscape.

Another example is the situation below. We have 3 fluorescent lights and we want hum sounds at their locations. In order to work correctly, soundscape file and Hammer entities should be configured like below.

[[File:Soundscape identicalsounds.jpg|right|325px]]
[[File:Hammer_identicalsounds.jpg|right|325px]]
{{pre|style=display:block|
"soundscape.demovdc"
{
	"playlooping"
	{
		"volume"	".65"
		"pitch"		"92"
		"channel"	"CHAN_AUTO"
		"position"	"0"
		"attenuation"	"1.2"
		"wave"		"ambient\machines\fluorescent_hum_1.wav"
	}
	
	"playlooping"
	{
		"volume"	".65"
		"pitch"		"92"
		"channel"	"CHAN_AUTO"
		"position"	"1"
		"attenuation"	"1.2"
		"wave"		"ambient\machines\fluorescent_hum_2.wav"
	}
	
	"playlooping"
	{
		"volume"	".65"
		"pitch"		"92"
		"channel"	"CHAN_AUTO"
		"position"	"2"
		"attenuation"	"1.2"
		"wave"		"ambient\machines\fluorescent_hum_3.wav"
	}
}
}}
Despite the fact that most Source engine branches cannot play more than one identical sound at once, in some situations, it appears that it is possible to play the same sound multiple time at different locations using channels.
After many tests in various situations and source code exploration, it seems to be possible by using different channels. For example, instead of using different names, we use different channels like <code>CHAN_STATIC</code>, <code>CHAN_STREAM</code>, <code>CHAN_AUTO</code>, etc. For an unknown reason at the moment, this won't work every time or for each time the map is loaded.
See [[Soundscript]] for more information.

==Custom Soundscapes==
===Creation===
Soundscape scripts are very similar to [[soundscripts]], but still remain entirely different things.

Soundscapes require a few of their own rules, and are placed in plain text files that are separate from normal soundscript files. A typical soundscape file might be named <code>soundscape_mall.txt</code> and may contain anywhere from 5-30 different soundscapes that take on the following format.
{{bug|If a soundscape's name is too long, soundscape entities will not be able to trigger it, although it will still be triggerable through console. Character limit unknown.}}
{{pre|
<name>
{
	<rule>
	{
		<keyvalue>
		...
	}

	...
}
}}

===Common keyvalues===
; <code>wave <[[string]]></code>
: The path and filename of the sound to play, relative to <code>game\sound\</code>.{{tip|Despite the name, this KV is used to play any supported audio filetype, not just [[WAV]] files.}}<!--Not explicitly mentioning MP3: while only WAV and MP3 are supported in vanilla first-party titles, third-party games and mods can add other types (ex: Black Mesa adds Ogg Vorbis).}}-->
; <code>volume <[[normal]]></code>
: 1 is full power, 0 is silent.
; <code>pitch <[[integer]]></code>
: Percentage value. 70-130 is the useful range.
; <code>music <[[boolean]]></code> {{ship|only}}
: The sound is considered "music", and will be affected by the music volume setting. Akin to setting the {{code|<nowiki>#</nowiki>}} [[sound character]], only it is affected by [[DSP]] and is directional.
[[File:Sound_attenuation.jpg|right|200px]]
; <code>position <0-7></code>
: One of eight locations in the world (defined by the mapper) from which a sound can be emitted.
; <code>position random</code>
: As above, but the sound emits from a completely random location near the player.
; <code>origin <origin></code> {{l4d|since}}
: Plays a sound at this origin, for example <tt>"0,0,0"</tt>. The coordinates must be comma-delimited but may contain preceding and following spaces. {{note|Similar to <code>position</code> but the script itself decides where to play this sound. Only useful for soundscapes intended for one single map, because on other maps you won't have any way of changing the location of the sound.}}
; <code>attenuation <[[float]]></code>
: How quickly the sound's volume drops as the camera moves away from it. Only relevant with a <code>position</code> specified. Default value is: "1.00". The lower the value is, greater the radius of the sound will be. And the opposite, higher the value is, smaller the radius of the sound will be. See the image above for illustrated example.
; <code>soundlevel <string></code>
: Can be used instead of <code>attenuation</code>. Accepts [[Soundscripts#SoundLevel|one of the engine's pre-set values]].
{{warning|Remember to enclose any values with space characters in "quote marks".}}
; <code>suppress_on_restore <0 or 1></code>
: Prevents sound from restarting upon loading a saved game.{{tip|It's intended for music played inside soundscape.}}

===Randomized values===
Some rules accept 'upper' and 'lower' parameter values. For example:
{{pre|
"pitch"	"80,120"
}}
Whenever the rule is executed the value will be randomly selected within the given range. 

===Rules===
====playlooping====
{{pre|style=float:right;margin-left:1em|
"playlooping"
{
	"volume"	"0.98"
	"pitch"		"110"
	"soundlevel"	"SNDLVL_85dB"

	"position"	"0"

	"wave"	"ambient/swamps/water_Lap_loop_st.wav"
}
}}
Plays a sound constantly. Does not allow random values.

{{note|Sound files will not properly loop unless they have a cue point. See [[Looping a Sound]].}}
{{bug|If another soundscape containing the same "playlooping" sound is triggered, but the sound has a different "pitch" value, the sound will cease to play unless the soundscape is re-triggerred from the one not containing said sound.}}
{{clr}}
====playrandom====
{{pre|style=float:right;margin-left:1em|
"playrandom"
{
        // Play every 1 to 4 seconds
	"time"		"1,4"

	"volume"	"0.4,1"
	"pitch"		"90,105"
	"soundlevel"	"SNDLVL_85dB"
	
	"position"	"0"
	
	"rndwave"
	{
		"wave"	"ambient/wind/wind_med1.wav"
		"wave"	"ambient/wind/wind_hit1.wav"
	}
}
}}

Plays a sound after the given range of the minimum and maximum numbers of seconds specified in the <code>time</code> KV. Allows random values.

Playrandom requires all <code>wave</code> KVs to be inside <code>rndwave</code> (even if there is only one). A random selection will be made every time the rule is executed.

{{warning|Be careful not to specify any looping sounds in a playrandom group as they may not stop even if a different soundscape is activated.}}
:{{note|Even non-looping sounds such as mp3s will not stop if a different soundscape is activated. (Tested in {{css}})}}
{{clr}}

====playsoundscape====
{{pre|style=float:right;margin-left:1em|
"SubScape"
{
	"playsoundscape"
	{
		"name"	"GenericIndoor"
		
		// Overall sub-scape volume to 50%
		"volume"	"0.5"
		
		// Emit all positioned sounds from position 0
		"positionoverride"	"0"
		
		// Emit all ambient sounds from position 1
		"ambientpositionoverride"	"1"
	}
}
}}
Plays a complete soundscape. DSP presets in the 'sub-scape' are ignored.

; <code>name</code>
: Name of the soundscape to play.
; <code>position <int></code>
: Offsets each position index of the sub-scape.
: For example, if set to 2, then sounds at positions 0, 1, 2, and 3 from the sub-scape would be played at positions 2, 3, 4, and 5 respectively.
; <code>positionoverride <int></code>
: Forces all positioned sounds in the sub-scape to emit from one location.
; <code>ambientpositionoverride <int></code>
: Forces all unpositioned (i.e. ambient) sounds in the sub-scape to emit from one location.
{{clr}}
====dsp <[[integer]]>====
{{pre|style=float:right;margin-left:1em|
// Disable DSP and play no ambient sounds
"Empty"
{
	"dsp"	"0"
	"dsp_volume"	"1.0"
}

//DSP room type with a DSP spatial type
"Empty2"
{ 
	"dsp"	"40"
        "dsp_spatial"	"119"
	"dsp_volume"	"1.0"
}
}}
;dsp_spatial <[[integer]]>
;;dsp_volume <[[float]]>

Set the current [[DSP]] preset. {{code|"dsp" "1"}} derives from the [[$surfaceprop]] of nearby [[material]]s.

For a list of values, open <code>scripts\[[dsp_presets|dsp_presets.txt]]</code>. You may need to extract this from the relevant engine VPK with [[GCFScape]]. To preview a DSP preset, submit <code>room_type <[[int]]></code> to the console.

{{note|Be careful when setting presets in soundscapes that could be used in many different locations.}}
{{note|You can also use <code>dsp_volume</code> to define how loud the dsp effect is.}}
{{note|In newer branches of Source (2009+) the cvar for ''room_type'' is ''dsp_room'' with the addition of a spatial dsp preset ''dsp_spatial''.}}
{{note|A dsp spatial type can also be assigned to a soundscape in conjunction with dsp room type ("dsp") with <code>"dsp_spatial" "''n''"</code>}}
{{clr}}

====fadetime <[[float]]>====
{{pre|style=float:right;margin-left:1em|
"SoundScapeName"
{
	"fadetime"  "1.0"
	"playlooping"
	{
		// ...
	}
}
}}
{{l4d2|since}}

The amount of time, in seconds, at which a soundscape fades in.
{{note|In games without fadetime such as {{css}} you can partially control it by setting a volume higher than 1 which will increase fadeout time from that soundscape.}}
{{clr}}

====soundmixer <[[string]]>====
{{pre|style=float:right;margin-left:1em|
"quiet"
{
	"soundmixer"	"Citadel_Dialog_Only"
	
	// ...
}
}}
Selects a custom [[soundmixer]]. Soundmixers manage the priority and volume of groups of sounds; create new ones in <code>scripts\soundmixers.txt</code>  (ALWAYS use Default_Mix as a template).
{{clr}}
===Example===
{{pre|style=display:block|
"swamp.water.slow"
{
	"dsp" "1"
	"dsp_spatial" "20"
	"dsp_volume"  "1.0"
	"fadetime"  "1.0"
	"soundmixer" "outside_swap_mixer"
	"playlooping"
	{
		"volume"	"0.98"
		"pitch"		"110"
		"soundlevel"	"SNDLVL_85dB"
		
		"position"	"0"
		
		"wave"	"ambient/swamps/water_Lap_loop_st.wav"
	}
	
	"playrandom"
	{
		"time"		"1,4"
		"volume"	"0.4,1"
		"pitch"		"90,105"
		"soundlevel"	"SNDLVL_85dB"
		"origin"	"3424.676025, 381.604095, 152.927948"
		
		"rndwave"
		{
			"wave"	"ambient/wind/wind_med1.wav"
			"wave"	"ambient/wind/wind_hit1.wav"
		}
	}
}
}}
====Looping MP3 Files====
MP3 files cannot be looped in Source, and are only recommended for non-looping sounds. Nonetheless, it is possible to somewhat simulate looping using {{code|rndwave}} with identical files and set the time to the length of those files:
{{pre|style=display:block|
//////////// Outside bird sounds (loop mp3 sound file trick by gtamike_TSGK) ////////////
//////////// The 2 .mp3 files are the same as each other just not the same file name ////////////
//////////// MP3 Sound file runtime 3.29mins {{=}} 3 X 60 + 29 {{=}} 209secs ////////////

// mp3_loop

"mp3_loop"
{
	"dsp" "1"
	"playlooping"
	{
		"volume"	"1.0"
		"pitch"		"100"
		"soundlevel"	"SNDLVL_150dB"

		"wave"	"loop_mp3_soundscape/outside_1MB_20KB_part_1.mp3"
	}

	"playrandom"
	{
		"time"		"209"
		"volume"	"1.0"
		"pitch"		"100"	
		"soundlevel"	"SNDLVL_150dB"

		"rndwave"
		{
			"wave"	"loop_mp3_soundscape/outside_1MB_20KB_part_1.mp3"
			"wave"	"loop_mp3_soundscape/outside_1MB_20KB_part_2.mp3"
		}
	}
} 
}}

{{warning|Mp3 soundscapes might save filesize for custom maps but are not recommended for looping sounds. It can happen that the FIRST file at "rndwave" plays after the half of the time value has passed. In this case you have to double the value (418 in this case, but live with the consequence that there will be a pause after the soundfile has played twice. Consider using an ADPCM-compressed [[WAV]] instead; see [[Compression_(Source_1)#Audio_Compression]].}}

===Storing and using custom soundscapes===

The engine uses <code>scripts/soundscapes_manifest.txt</code> to find soundscapes files, but you could also use <code>scripts/soundscapes_%mapname%.txt</code> to load soundscapes on a map-by-map basis. All soundscapes are loaded on map start.
{{Note|In {{Mapbase|4}}, this method has been changed to <code>maps/%mapname%_soundscapes.txt</code>}}
The <code>soundscapes_%mapname%</code> method should be used when modifying the manifest is unnecessary or impossible (e.g. on custom maps without their own mod directories). This file can be [[BSPZIP|zipped into the BSP itself]] as well.

New soundscapes can be added to the manifest by adding a new "file" line at the bottom, like this:

{{pre|
	"file"		"<file location>"
}}

{{important|All soundscape names must be globally unique within a game.}}
{{modernConfusion|Although map-specific soundscripts are mounted in a similar way through <code>maps/%mapname%_level_sounds.txt</code>, soundscapes are mounted through the <code>scripts</code> folder and start with <code>soundscapes_</code> instead of starting in the <code>maps</code> folder with <code>%mapname%</code> at the beginning. You can still use both map-specific soundscripts and map-specific soundscapes at the same time.}}

==Creating Soundscapes using XBLAH's Modding Tool==
Soundscapes can now be easily created or modified using {{Xblahmt|4}}. The UI provides an intuitive way to create new soundscapes, using the integrated file explorer. This allows the user to browse all the files mounted (VPKs and loose files), let the user preview the files individually and let the user preview how the whole soundscape is gonna play in-game.

<br/><span style="color: #FFFFFF; font-weight: bold">Where to find it</span><br/>
This can be accessed within the tool through '''Sounds > Soundscape Editor'''.

[[File:XBLAH's Modding Tool - Soundscape Editor.png|1000px]]

==See also==
* [[env_soundscape]]
* [[env_soundscape_proxy]]
* [[env_soundscape_triggerable]]
* [[trigger_soundscape]]
* [[Notepad++ VDF languages]]

{{soundscape lists}}

[[Category:Sound System]]
[[Category:Level Design]]
[[Category:Plain text formats]]
[[Category:Plain text files]]
[[Category:Tutorials]] <!-- due to XBLAH's Modding Tool -->