Difference between revisions of "Soundsequence"

From Eternity Wiki
Jump to: navigation, search
(Corrected argument number mistake)
(Added documentation for all commands, and documentation of features new to SVN r1420.)
Line 13: Line 13:
 
  soundsequence <mnemonic>
 
  soundsequence <mnemonic>
 
  {
 
  {
   id              = <number>
+
   id              <number>
   cmds            = { <string>, ... }
+
   cmds            { <string>, ... }
   type            = <sequence type>
+
  commands        <heredoc string>
   stopsound      = <sound mnemonic>
+
   type            <sequence type>
   attenuation    = <attenuation type>
+
   stopsound      <sound mnemonic>
   volume          = <number>
+
   attenuation    <attenuation type>
   minvolume      = <number>
+
  randomplayvol  <boolean>
   nostopcutoff    = <boolean>
+
   volume          <number>
   doorsequence    = <sound sequence mnemonic>
+
   minvolume      <number>
   platsequence    = <sound sequence mnemonic>
+
   nostopcutoff    <boolean>
   floorsequence  = <sound sequence mnemonic>
+
   doorsequence    <sound sequence mnemonic>
   ceilingsequence = <sound sequence mnemonic>
+
   platsequence    <sound sequence mnemonic>
 +
   floorsequence  <sound sequence mnemonic>
 +
   ceilingsequence <sound sequence mnemonic>
 
  }
 
  }
  
Line 35: Line 37:
  
 
*'''cmds'''
 
*'''cmds'''
:''Default:'' {"end"}
+
:''Default:'' { "end" }
:The list of Hexen-style commands to control the playing of sounds. Each command is written as a string, separated with a comma from the others.
+
:'''(Deprecated)''' The list of Hexen-style commands to control the playing of sounds. Each command is written as a string, separated with a comma from the others. While this syntax will continue to be supported, it is recommended that new modifications use the heredoc-enabled syntax via the '''commands''' field instead.
 +
 
 +
*'''commands'''
 +
:''Default'': @" end "@
 +
:The commands field allows specification of sound sequences in the natural Hexen-derived syntax, without quotations or commas, by embedding the commands one per line inside an EDF heredoc (a literally interpreted string delimited by @" and "@ sequences). This is the recommended method of specification. '''SVN r1420+'''
  
 
*'''type'''
 
*'''type'''
Line 49: Line 55:
 
:''Default:'' "normal"
 
:''Default:'' "normal"
 
:Can be: normal, idle, static, none.
 
:Can be: normal, idle, static, none.
 +
 +
*'''randomplayvol'''
 +
:''Default:'' false
 +
:If set to true, every normal "play" command which doesn't specify a volume will begin at a randomized volume level which may be modified by the user's s_enviro_volume setting. This property exists to support Heretic-compatible global environmental sequence behavior. '''SVN r1420+'''
  
 
*'''volume'''
 
*'''volume'''
Line 61: Line 71:
 
==Sequence commands==
 
==Sequence commands==
 
*play <sound>
 
*play <sound>
 +
: The indicated sound will be played but the sequence will not delay in moving to the next command. If this is the last sound in the sequence, the sound might be cutoff unless other properties prevent this.
 
*playuntildone <sound>
 
*playuntildone <sound>
 +
: The indicated sound will be played, and the sequence will not move on to the next command or terminate until the sound has finished playing.
 
*playtime <sound> <time>
 
*playtime <sound> <time>
 +
: The indicated sound will be played and the sequence will pause for the number of gametics (35 per second) before moving on to the next command.
 
*playrepeat <sound>  
 
*playrepeat <sound>  
 +
: The indicated sound will be played continuously without interruption. This command never ends, so the sequence will not terminate unless something such as a sector action stops it externally. This command should not be used in global environmental sequences.
 
*playloop <sound> <time>
 
*playloop <sound> <time>
 +
: The indicated sound will be played in a loop every "time" gametics. As above, this command will never end.
 
*playabsvol <sound> <vol>
 
*playabsvol <sound> <vol>
 +
: Like the play command, but allows specification of the sound's base volume from 0 to 127.
 
*playrelvol <sound> <vol>
 
*playrelvol <sound> <vol>
 +
: Like the play command, but specifies a volume which is relative to the sound sequence's previous volume setting.
 
*delay <tics>
 
*delay <tics>
 +
: Stop the sound sequence from progressing for the indicated number of gametics.
 
*delayrand <min> <max>
 
*delayrand <min> <max>
 +
: Delay the sound sequence from progressing for a random number of gametics between and including "min" and "max".
 
*volume <vol>
 
*volume <vol>
 +
: Set the sequence's current absolute volume level to the indicated value between 0 and 127.
 
*relvolume <vol>
 
*relvolume <vol>
 +
: Modify the sequence's current absolute volume level by the indicated amount. The number specified should be negative to make the sequence more quiet.
 
*attenuation <attn>
 
*attenuation <attn>
 +
: Set the sequence's attenuation value. This command is executed at game startup and therefore the last one specified is the only one that will take effect.
 
*stopsound <snd>
 
*stopsound <snd>
 +
: Set the sequence's stopsound attribute. This command is executed at game startup and therefore the last one specified is the only one that will take effect.
 
*nostopcutoff
 
*nostopcutoff
 +
: Set the sequence's nostopcutoff attribute. This command is executed at game startup and therefore the last one specified is the only one that will take effect.
 
*restart
 
*restart
 +
: Restart the current sound sequence. This command should not be used in global environmental sequences.
 
*end
 
*end
 +
: End the sequence. This command is not required by the Eternity Engine, and exists for Hexen compatibility.

Revision as of 19:25, 12 January 2011

Sound sequences are effects that play while a sector is moving, a polyobject is moving, or when a Heretic-style (environmental) ambient sound is under way. Similar to things, frames or individual sounds, sequences are defined in EDF by using the soundsequence block. The mnemonic must be at most 32 characters long. Sound sequence definitions can be cascaded, and the latter ones will overwrite other identically named sequences.

Sector movement sequences are used by placing thing types #1400 to #1411 on the map, inside the designated sectors. The ones numbered from #1400 to #1410 will play the sequence with the id between 0 and 10, while #1411 will use its first argument in the ExtraData definition.

Polyobject sequences are set up from the Polyobj_StartLine and Polyobj_ExplicitLine ExtraData linedef specials. Polyobj_StartLine uses the 3rd argument for this, while Polyobj_ExplicitLine uses the 4th.

Environmental sequences are set up similarly with sector sequences, by placing thing types #1200 to #1300 anywhere inside the map. #1200 to #1299 use the last two digits to designate the number, while #1300 uses the first ExtraData argument.

NOTE: You can include all soundsequence blocks inside a ESNDSEQ lump. It will be loaded automatically at game startup, independent of EDFROOT.

Syntax

soundsequence <mnemonic>
{
  id              <number>
  cmds            { <string>, ... }
  commands        <heredoc string>
  type            <sequence type>
  stopsound       <sound mnemonic>
  attenuation     <attenuation type>
  randomplayvol   <boolean>
  volume          <number>
  minvolume       <number>
  nostopcutoff    <boolean>
  doorsequence    <sound sequence mnemonic>
  platsequence    <sound sequence mnemonic>
  floorsequence   <sound sequence mnemonic>
  ceilingsequence <sound sequence mnemonic>
}

Parameters

The fields are as follows:

  • id
Default: -1
Sets up the sound sequence number to recognize it in maps. Environmental sequences use a different namespace from sector ones, and sector sequences can be separated in door, platform and general sequences (see below)
  • cmds
Default: { "end" }
(Deprecated) The list of Hexen-style commands to control the playing of sounds. Each command is written as a string, separated with a comma from the others. While this syntax will continue to be supported, it is recommended that new modifications use the heredoc-enabled syntax via the commands field instead.
  • commands
Default: @" end "@
The commands field allows specification of sound sequences in the natural Hexen-derived syntax, without quotations or commas, by embedding the commands one per line inside an EDF heredoc (a literally interpreted string delimited by @" and "@ sequences). This is the recommended method of specification. SVN r1420+
  • type
Default: "sector"
There are four separate namespaces: sector, door, plat and environment. The second is restricted to doors and polys; the third to general moving floors/ceilings and lifts.
  • stopsound
Default: "none"
The sound mnemonic to play when the sector stops. Will never happen if this is an environmental sequence.
  • attenuation
Default: "normal"
Can be: normal, idle, static, none.
  • randomplayvol
Default: false
If set to true, every normal "play" command which doesn't specify a volume will begin at a randomized volume level which may be modified by the user's s_enviro_volume setting. This property exists to support Heretic-compatible global environmental sequence behavior. SVN r1420+
  • volume
Default: 127
  • minvolume
Default: -1
  • nostopcutoff
Default: false

Sequence commands

  • play <sound>
The indicated sound will be played but the sequence will not delay in moving to the next command. If this is the last sound in the sequence, the sound might be cutoff unless other properties prevent this.
  • playuntildone <sound>
The indicated sound will be played, and the sequence will not move on to the next command or terminate until the sound has finished playing.
  • playtime <sound>
The indicated sound will be played and the sequence will pause for the number of gametics (35 per second) before moving on to the next command.
  • playrepeat <sound>
The indicated sound will be played continuously without interruption. This command never ends, so the sequence will not terminate unless something such as a sector action stops it externally. This command should not be used in global environmental sequences.
  • playloop <sound> <time>
The indicated sound will be played in a loop every "time" gametics. As above, this command will never end.
  • playabsvol <sound> <vol>
Like the play command, but allows specification of the sound's base volume from 0 to 127.
  • playrelvol <sound> <vol>
Like the play command, but specifies a volume which is relative to the sound sequence's previous volume setting.
  • delay <tics>
Stop the sound sequence from progressing for the indicated number of gametics.
  • delayrand <min> <max>
Delay the sound sequence from progressing for a random number of gametics between and including "min" and "max".
  • volume <vol>
Set the sequence's current absolute volume level to the indicated value between 0 and 127.
  • relvolume <vol>
Modify the sequence's current absolute volume level by the indicated amount. The number specified should be negative to make the sequence more quiet.
  • attenuation <attn>
Set the sequence's attenuation value. This command is executed at game startup and therefore the last one specified is the only one that will take effect.
  • stopsound <snd>
Set the sequence's stopsound attribute. This command is executed at game startup and therefore the last one specified is the only one that will take effect.
  • nostopcutoff
Set the sequence's nostopcutoff attribute. This command is executed at game startup and therefore the last one specified is the only one that will take effect.
  • restart
Restart the current sound sequence. This command should not be used in global environmental sequences.
  • end
End the sequence. This command is not required by the Eternity Engine, and exists for Hexen compatibility.