Changes

===Custom audio===

===Custom audio===

You can now add custom [[Modding:Audio|music or sounds]] to the game by editing the <samp>Data/AudioCueModificationData</samp> asset. This can be used both to add new music tracks, and to replace existing tracks with new audio. These 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]]).

You can now add custom [[Modding:Audio|music tracks or sound effects]] (called ''cues'') to the game by editing the <samp>Data/AudioCueModificationData</samp> asset. This can be used both to add new music cues, and to replace existing cues with new audio. These 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]]).

====Format====

====Format====

The <samp>Data/AudioCueModificationData</samp> asset consists of a string → model lookup, where the key is the unique audio ID, and the value is a model with these fields:

The <samp>Data/AudioCueModificationData</samp> asset consists of a string → model lookup, where the key is the unique cue ID, and the value is a model with these fields:

{| class="wikitable"

{| class="wikitable"

|-

|-

| <samp>ID</samp>

| <samp>ID</samp>

| A unique audio ID, used when playing the sound in-game. This should match the entry key.

| A unique cue ID, used when playing the sound in-game. This should match the entry key.

|-

|-

| <samp>FilePaths</samp>

| <samp>FilePaths</samp>

| ''(Optional if editing a track, required if adding a new one)'' A list of file paths (not asset names) from which to load the audio track, relative to the game's <samp>Content</samp> folder. 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.

| ''(Optional if editing a cue, required if adding a new one)'' A list of file paths (not asset names) from which to load the audio, relative to the game's <samp>Content</samp> folder. 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>

| <samp>Category</samp>

| ''(Optional)'' 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.

| ''(Optional)'' 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 track:

This is a tradeoff between memory usage and performance, so you should consider which value is best for each audio cue:

{| class="wikitable"

{| class="wikitable"

|-

|-

|-

|-

| <samp>true</samp>

| <samp>true</samp>

| Reduces memory usage when the audio track 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 tracks (like music or ambient noise), or tracks that are rarely used in a specific scenario (e.g. a sound that only plays once in an event).

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

| <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 tracks that are played occasionally.

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

| <samp>Looped</samp>

| ''(Optional)'' Whether the audio track loops continuously until stopped. Default false.

| ''(Optional)'' Whether the audio cue loops continuously until stopped. Default false.

|-

|-

| <samp>UseReverb</samp>

| <samp>UseReverb</samp>

|}

|}

This describes a '''change''' applied to the soundbank. For example, you can specify only <samp>ID</samp> and <samp>Category</samp> to change the category for an existing music track without overwriting other values.

This describes a '''change''' applied to the soundbank. For example, you can specify only <samp>ID</samp> and <samp>Category</samp> to change the category for an existing music cue without overwriting other values.

====Example====

====Example====

This content pack adds a new music track to the game, and plays it when the player enters the bus stop:

This content pack adds a new music cue to the game, and plays it when the player enters the bus stop:

{{#tag:syntaxhighlight|<nowiki>

{{#tag:syntaxhighlight|<nowiki>

     "Format": "</nowiki>{{Content Patcher version}}<nowiki>",

     "Format": "</nowiki>{{Content Patcher version}}<nowiki>",

     "Changes": [

     "Changes": [

         // add music track

         // add music cue

         {

         {

             "Action": "EditData",

             "Action": "EditData",

====Limitations====

====Limitations====

* As hinted by the unusual asset name (<samp>Data/AudioCueModificationData</samp> instead of <samp>Data/AudioCues</samp>), this is a list of changes applied to the current audio tracks for the remainder of the game session. That means:

* As hinted by the unusual asset name (<samp>Data/AudioCueModificationData</samp> instead of <samp>Data/AudioCues</samp>), this is a list of changes applied to the current audio cues for the remainder of the game session. That means:

** You can't remove an audio track once it's added.

** You can't remove an audio cue once it's added.

** You can't undo a change by removing it from the data asset. For example, if you change an audio track's category, it won't revert to the original value when you remove it from the asset. To undo a change, you'd need to add a new entry which sets the original values.

** You can't undo a change by removing it from the data asset. For example, if you change an audio cue's category, it won't revert to the original value when you remove it from the asset. To undo a change, you'd need to add a new entry which sets the original values.

* The game will crash if it tries to play an audio track that doesn't exist.

* The game will crash if it tries to play an audio cue that doesn't exist.

===Custom location contexts===

===Custom location contexts===