| Line 6,138: |
Line 6,138: |
| | | | |
| | ===Custom audio=== | | ===Custom audio=== |
| − | You can now add or edit [[Modding:Audio|music tracks or sound effects]] (called ''cues'') by editing the <samp>Data/AudioChanges</samp> asset. New cues are added to the game's soundbank, so they can be used anywhere normal audio can be used (e.g. the <samp>Music</samp> [[Modding:Maps|map property]]).
| + | : ''Main article: [[Modding:Audio]].'' |
| | | | |
| − | ====Format====
| + | You can now add or edit music tracks or sound effects by editing the new <samp>Data/AudioChanges</samp> asset. New cues are added to the game's soundbank, so they can be used anywhere normal audio can be used (e.g. the <samp>Music</samp> [[Modding:Maps|map property]]). This supports <samp>.ogg</samp> and <samp>.wav</samp> files, and the vanilla audio features (e.g. randomizing audio from one ID). |
| − | The <samp>Data/AudioChanges</samp> asset consists of a string → model lookup, where the key matches the <samp>ID</samp>, and the value is a model with the fields below.
| |
| | | | |
| − | Entries in this asset describe an '''override''' applied to the soundbank. The override is applied permanently for the current game session, even if the asset is edited to remove it. Overriding a cue will reset all values to the ones specified.
| + | Audio is also more fault-tolerant in 1.6: the game no longer crashes when playing audio which doesn't exist, it now logs an error and returns a default quiet click sound instead. (If you use <code>try..catch</code> to check if an audio cue exists, you should check <code>Game1.soundbank.Exists(name)</code> instead.) |
| − | | |
| − | {| class="wikitable"
| |
| − | |-
| |
| − | ! field
| |
| − | ! effect
| |
| − | |-
| |
| − | | <samp>ID</samp>
| |
| − | | The [[Modding:Common data field types#Unique string ID|unique string ID]] for the audio cue, used when playing the sound in-game.
| |
| − | |-
| |
| − | | <samp>FilePaths</samp>
| |
| − | | A list of absolute file paths (not asset names) from which to load the audio. Each file can be <samp>.ogg</samp> or <samp>.wav</samp>. If you list multiple paths, a random one will be chosen each time it's played.
| |
| − | |-
| |
| − | | <samp>Category</samp>
| |
| − | | The [[Modding:Audio#Category list|audio category]], which determines which volume slider in the game options applies. This should be one of <samp>Default</samp>, <samp>Music</samp>, <samp>Sound</samp>, <samp>Ambient</samp>, or <samp>Footsteps</samp> (see [[Modding:Audio#Category list|a description of each category]]). Defaults to <samp>Default</samp>.
| |
| − | |-
| |
| − | | <samp>StreamedVorbis</samp>
| |
| − | | Whether the audio should be streamed from disk when it's played, instead of being loaded into memory ahead of time. This is only possible for [[wikipedia:Vorbis|Ogg Vorbis]] (<samp>.ogg</samp>) files, which otherwise will be decompressed in-memory on load. Default false.
| |
| − | | |
| − | This is a tradeoff between memory usage and performance, so you should consider which value is best for each audio cue:
| |
| − | {| class="wikitable"
| |
| − | |-
| |
| − | ! value
| |
| − | ! effect
| |
| − | |-
| |
| − | | <samp>true</samp>
| |
| − | | Reduces memory usage when the audio cue isn't active, but increases performance impact when it's played. Playing the audio multiple times will multiply the memory and performance impact while they're active, since each play will stream a new instance. Recommended for longer audio cues (like music or ambient noise), or cues that are rarely used in a specific scenario (e.g. a sound that only plays once in an event).
| |
| − | |-
| |
| − | | <samp>false</samp>
| |
| − | | Increases memory usage (since it's fully loaded into memory), but reduces performance impact when it's played. It can be played any number of times without affecting memory or performance (it'll just play the cached audio). Recommended for sound effects, or short audio cues that are played occasionally.
| |
| − | |}
| |
| − | |-
| |
| − | | <samp>Looped</samp>
| |
| − | | Whether the audio cue loops continuously until stopped. Default false.
| |
| − | |-
| |
| − | | <samp>UseReverb</samp>
| |
| − | | Whether to apply a [[wikipedia:Reverberation|reverb]] effect to the audio. Default false.
| |
| − | |-
| |
| − | | <samp>CustomFields</samp>
| |
| − | | The [[#Custom data fields|custom fields]] for this entry.
| |
| − | |}
| |
| − | | |
| − | ====Example====
| |
| − | This content pack adds a new music cue to the game, and plays it when the player enters the bus stop:
| |
| − | | |
| − | {{#tag:syntaxhighlight|<nowiki>
| |
| − | {
| |
| − | "Format": "</nowiki>{{Content Patcher version}}<nowiki>",
| |
| − | "Changes": [
| |
| − | // add music cue
| |
| − | {
| |
| − | "Action": "EditData",
| |
| − | "Target": "Data/AudioChanges",
| |
| − | "Entries": {
| |
| − | "{{ModId}}_Music": {
| |
| − | "ID": "{{ModId}}_Music",
| |
| − | "Category": "Music",
| |
| − | "FilePaths": [ "{{AbsoluteFilePath: assets/music.ogg}}" ],
| |
| − | "StreamedVorbis": true,
| |
| − | "Looped": true
| |
| − | }
| |
| − | }
| |
| − | },
| |
| − | | |
| − | // add to bus stop
| |
| − | {
| |
| − | "Action": "EditMap",
| |
| − | "Target": "Maps/BusStop",
| |
| − | "MapProperties": {
| |
| − | "Music": "{{ModId}}_Music"
| |
| − | }
| |
| − | }
| |
| − | ]
| |
| − | }</nowiki>|lang=javascript}}
| |
| − | | |
| − | ====Other changes====
| |
| − | * The game no longer crashes when playing audio which doesn't exist. It now logs an error and returns a default quiet click sound instead. (If you use <code>try..catch</code> to check if an audio cue exists, you should check <code>Game1.soundbank.Exists(name)</code> instead.)
| |
| | | | |
| | ===Custom buffs=== | | ===Custom buffs=== |