"Soundscript" container

From TrainzOnline
(Difference between revisions)
Jump to: navigation, search
m (sound)
m (Added value-range. This tag could use a better description as the current is a bit vague.)
Line 13: Line 13:
 
   trigger      ""
 
   trigger      ""
 
   volume        1
 
   volume        1
 +
  value-range  0,0
 
   sound
 
   sound
 
   {
 
   {
 
   }
 
   }
 
====repeat-delay====
 
:Type: Decimal Pair
 
:Desc: Time range (in seconds) to delay, after the sound finishes playing, before playing the sound again. To set a constant delay either set both these values the same or only provide one of them, otherwise a random value between them will be chosen. When used with a trigger event (see the 'trigger' tag), a positive value indicates that the sound should not repeat, but should wait until triggered again.
 
 
====distance====
 
:Type: Decimal Pair
 
:Desc: Distance range from the source, in meters, where the sound is audible. The minimum distance defines the radius within which the sound remains at 100% volume. Beyond that distance, the sound volume will begin to decay naturally. The maximum distance defines a radius beyond which the game will no longer play the sound. This does not mean that the sound will fade to zero by the maximum distance, but rather that the sound will cut off abruptly at that point. It is up to the content creator to choose an appropriate distance - smaller is better for performance.
 
  
 
====ambient====
 
====ambient====
 
:Type: Boolean
 
:Type: Boolean
 +
:Default: 0
 +
:Compulsory: No
 
:Desc: If true this is an 'ambient' sound, ambient sounds are played in 2D and do not make use of 3D positioning in the world other than to affect volume. Unlike positional sounds, ambient sounds may be stereo.
 
:Desc: If true this is an 'ambient' sound, ambient sounds are played in 2D and do not make use of 3D positioning in the world other than to affect volume. Unlike positional sounds, ambient sounds may be stereo.
  
 
====attachment====
 
====attachment====
:Type: String
+
:Type: Attachment point
 +
:Default: ""
 +
:Compulsory: No
 
:Desc: Point to attach the sound source to. Attachment points are specified in the mesh file during creation.
 
:Desc: Point to attach the sound source to. Attachment points are specified in the mesh file during creation.
 +
 +
====distance====
 +
:Type: Decimal Pair
 +
:Default: 50,150
 +
:Compulsory: No
 +
:Desc: Distance range from the source, in meters, where the sound is audible. The minimum distance defines the radius within which the sound remains at 100% volume. Beyond that distance, the sound volume will begin to decay naturally. The maximum distance defines a radius beyond which the game will no longer play the sound. This does not mean that the sound will fade to zero by the maximum distance, but rather that the sound will cut off abruptly at that point. It is up to the content creator to choose an appropriate distance - smaller is better for performance.
  
 
====nostartdelay====
 
====nostartdelay====
 
:Type: Boolean
 
:Type: Boolean
 +
:Default: 0
 +
:Compulsory: No
 
:Desc: If added and true this tag specifies that the sound will play immediately once triggered. By default sounds have a random start delay between 0 & 4 seconds. Start delay should be left active in most cases, as turning it off may cause significant audio artifacts when several identical sounds are in proximity.
 
:Desc: If added and true this tag specifies that the sound will play immediately once triggered. By default sounds have a random start delay between 0 & 4 seconds. Start delay should be left active in most cases, as turning it off may cause significant audio artifacts when several identical sounds are in proximity.
  
Line 40: Line 45:
 
:Type: Integer
 
:Type: Integer
 
:Desc: Sets the priority of the sound, if their are not enough sound channels available higher priority sounds will be played first. Defaults to 1, can be negative.
 
:Desc: Sets the priority of the sound, if their are not enough sound channels available higher priority sounds will be played first. Defaults to 1, can be negative.
 +
 +
====repeat-delay====
 +
:Type: Decimal Pair
 +
:Default: 0,0
 +
:Compulsory: Yes (3.4)
 +
:Desc: Time range (in seconds) to delay, after the sound finishes playing, before playing the sound again. To set a constant delay either set both these values the same or only provide one of them, otherwise a random value between them will be chosen. When used with a trigger event (see the 'trigger' tag), a positive value indicates that the sound should not repeat, but should wait until triggered again.
 +
 +
====sound====
 +
:Type: Container
 +
:Default: {}
 +
:Compulsory: Yes
 +
:Desc: Contains a key/string list of the sound files to play. If the list has more than one entry then one file will be picked at random from the list.  The value of each tag in this container is the filename of a WAV sound file.  Filenames are relative to the base directory of the asset, i.e. relative to the location of the config file.  The keys used within the list are not important: Trainz convention for lists like this is to numerically number each option from zero, and while it is strongly recommended to follow this convention, there is no technical requirement to do so.
 +
 +
:Valid WAV files are:
 +
:* Uncompressed.
 +
:* 8 or 16 bit
 +
:* Mono, Stereo or Surround (As of build 3.7 Surround is not fully tested)
 +
 +
:Sampling rate can be 22kHz (22,050Hz) or 44kHz (44,100Hz).  The higher sampling rate doubles the size of the file for no significant improvement in quality, and is not recommended.  For some purposes there are additional requirements - for instance directional sounds must be mono.
  
 
====trigger====
 
====trigger====
 
:Type: String
 
:Type: String
 +
:Default: ""
 +
:Compulsory: No
 
:Desc: The 'trigger' tag gives your sound a name that can allow it to be played from [[Scripting|TrainzScript]], animations and certain predefined events. (At least one of these "predefined events" is to use the word "toggle" when including a soundscript container in the config.txt of a "MOjunction".  This will make the sound fire each time the turnout is switched)
 
:Desc: The 'trigger' tag gives your sound a name that can allow it to be played from [[Scripting|TrainzScript]], animations and certain predefined events. (At least one of these "predefined events" is to use the word "toggle" when including a soundscript container in the config.txt of a "MOjunction".  This will make the sound fire each time the turnout is switched)
 +
 +
====value-range====
 +
:Type: Float pair
 +
:Default: 0,0 (off)
 +
:Compulsory: No
 +
:Desc: 2 numbers, where the numbers are not the same, which set the start and end times for the sound to play. Midnight is 0.5, midday = 0.0 or 1.0. (TBD.  This is a bit vague.)
  
 
====volume====
 
====volume====
 
:Type: Decimal
 
:Type: Decimal
 +
:Default: 1
 +
:Compulsory: No
 
:Desc: Specifies the volume gain of the sound. Defaults to 1 (100%).
 
:Desc: Specifies the volume gain of the sound. Defaults to 1 (100%).
  
====sound====
 
:Type: Container
 
:Desc: Contains a key/string list of the sound files to play. If the list has more than one entry then one file will be picked at random from the list.  The value of each tag in this container is the filename of a WAV sound file.  Filenames are relative to the base directory of the asset, i.e. relative to the location of the config file.  The keys used within the list are not important: Trainz convention for lists like this is to numerically number each option from zero, and while it is strongly recommended to follow this convention, there is no technical requirement to do so.
 
 
Valid WAV files are:
 
* Uncompressed.
 
* 8 or 16 bit
 
* Mono, Stereo or Surround (As of build 3.7 Surround is not fully tested)
 
 
Sampling rate can be 22kHz (22,050Hz) or 44kHz (44,100Hz).  The higher sampling rate doubles the size of the file for no significant improvement in quality, and is not recommended.  For some purposes there are additional requirements - for instance directional sounds must be mono.
 
  
 
==Example Config.txt==
 
==Example Config.txt==

Revision as of 14:44, 17 March 2014

A container type tag for defining asset sounds.

Contents

Supported Tags

Each soundscript subcontainer supports the following tags. Each tag is shown here with its default value.

 repeat-delay  0,0
 distance      50,150
 ambient       0
 attachment    ""
 nostartdelay  0
 priority      1
 trigger       ""
 volume        1
 value-range   0,0
 sound
 {
 }

ambient

Type: Boolean
Default: 0
Compulsory: No
Desc: If true this is an 'ambient' sound, ambient sounds are played in 2D and do not make use of 3D positioning in the world other than to affect volume. Unlike positional sounds, ambient sounds may be stereo.

attachment

Type: Attachment point
Default: ""
Compulsory: No
Desc: Point to attach the sound source to. Attachment points are specified in the mesh file during creation.

distance

Type: Decimal Pair
Default: 50,150
Compulsory: No
Desc: Distance range from the source, in meters, where the sound is audible. The minimum distance defines the radius within which the sound remains at 100% volume. Beyond that distance, the sound volume will begin to decay naturally. The maximum distance defines a radius beyond which the game will no longer play the sound. This does not mean that the sound will fade to zero by the maximum distance, but rather that the sound will cut off abruptly at that point. It is up to the content creator to choose an appropriate distance - smaller is better for performance.

nostartdelay

Type: Boolean
Default: 0
Compulsory: No
Desc: If added and true this tag specifies that the sound will play immediately once triggered. By default sounds have a random start delay between 0 & 4 seconds. Start delay should be left active in most cases, as turning it off may cause significant audio artifacts when several identical sounds are in proximity.

priority

Type: Integer
Desc: Sets the priority of the sound, if their are not enough sound channels available higher priority sounds will be played first. Defaults to 1, can be negative.

repeat-delay

Type: Decimal Pair
Default: 0,0
Compulsory: Yes (3.4)
Desc: Time range (in seconds) to delay, after the sound finishes playing, before playing the sound again. To set a constant delay either set both these values the same or only provide one of them, otherwise a random value between them will be chosen. When used with a trigger event (see the 'trigger' tag), a positive value indicates that the sound should not repeat, but should wait until triggered again.

sound

Type: Container
Default: {}
Compulsory: Yes
Desc: Contains a key/string list of the sound files to play. If the list has more than one entry then one file will be picked at random from the list. The value of each tag in this container is the filename of a WAV sound file. Filenames are relative to the base directory of the asset, i.e. relative to the location of the config file. The keys used within the list are not important: Trainz convention for lists like this is to numerically number each option from zero, and while it is strongly recommended to follow this convention, there is no technical requirement to do so.
Valid WAV files are:
  • Uncompressed.
  • 8 or 16 bit
  • Mono, Stereo or Surround (As of build 3.7 Surround is not fully tested)
Sampling rate can be 22kHz (22,050Hz) or 44kHz (44,100Hz). The higher sampling rate doubles the size of the file for no significant improvement in quality, and is not recommended. For some purposes there are additional requirements - for instance directional sounds must be mono.

trigger

Type: String
Default: ""
Compulsory: No
Desc: The 'trigger' tag gives your sound a name that can allow it to be played from TrainzScript, animations and certain predefined events. (At least one of these "predefined events" is to use the word "toggle" when including a soundscript container in the config.txt of a "MOjunction". This will make the sound fire each time the turnout is switched)

value-range

Type: Float pair
Default: 0,0 (off)
Compulsory: No
Desc: 2 numbers, where the numbers are not the same, which set the start and end times for the sound to play. Midnight is 0.5, midday = 0.0 or 1.0. (TBD. This is a bit vague.)

volume

Type: Decimal
Default: 1
Compulsory: No
Desc: Specifies the volume gain of the sound. Defaults to 1 (100%).


Example Config.txt

Sample config.txt file for a map asset that has a different day and night background sounds:

 kind map
 kuid <KUID:0:0>
 soundscript
 {
   morning
   {
     ambient 1
     value-range 1, 0.1
     volume 0.3
     sound
     {
       0 ctry_day_1.wav
       1 ctry_day_2.wav
     }
   }
   night
   {
     ambient 1
     value-range 0, 0.9
     volume 0.3
     sound
     {
       0 night_loop.wav
     }
   }
 }


Categories

Personal tools