playSound()

Overview

Sounds (and their beacons if applicable) are added to a queue so that if multiple sounds are requested they will be played one after the other.

Sounds and beacons will only be shown to the human player who's on the same client machine as your script – so this function isn't much use in multiplayer games. See "Examples" below for a way to handle this better.

Availability

Warzone 3.1 Beta 1 and above.

Syntax

var returnValue = playSound(sound[, x, y, z]);

If the x,y,z parameters are used (all three must be used, or none must be used) then a beacon will be shown on the map and minimap while the sound is played.

Parameters

 The last 3 parameters are optional, however you must specify all three of them or none at all.

Parameter	Type	Mandatory	Description	Game version
sound	String		The file name of the .ogg format audio file to play. The sound file must be stored in the /data/base/audio folder (thanks for info cybersphinx) either within Warzone itself or within your add-on. Warzone will search all .ogg files in that folder, and its sub-folders, for the file specified. A list of audio included with Warzone can be found in the Audio Directory.	3.1 Beta 1
x	Number	See note above	The x co-ordinate of a beacon to show when the sound plays	3.1 Beta 1
y	Number	See note above	The y co-ordinate of a beacon to show when the sound plays	3.1 Beta 1
z	Number	See note above	The z co-ordinate of a beacon to show when the sound plays	3.1 Beta 1

Return value

Example

The game rules (rules.js) will play a sound when buildings are attacked:

function eventAttacked(victim, attacker) {
  if (gameTime > lastHitTime + 10) { // de-spam the event
    lastHitTime = gameTime;
    if (victim.type == STRUCTURE) {
      playSound("pcv337.ogg", victim.x, victim.y, victim.z);
    } else {
      playSound("pcv399.ogg", victim.x, victim.y, victim.z);
    }
  }
}

The human player (selectedPlayer) that's on the same client machine as your script (me) may or may not be an ally (check with allianceExistsBetween()), in which case you might want to filter out sounds...

// only play sound (and show beacon if applicable) if human player is an ally
function playSoundIfAlly(sound,x,y,z) {
  if (allianceExistsBetween(me,selectedPlayer)) {
    playSound.apply(global,arguments);
  }
}
 
// only play sound (and show beacon if applicable) if human player is an enemy
function playSoundIfEnemy(sound,x,y,z) {
  if (!allianceExistsBetween(me,selectedPlayer)) {
    playSound.apply(global,arguments);
  }
}
 
// then use these functions instead of playSound(), for example:
playSoundIfAlly("pcv337.ogg", victim.x, victim.y, victim.z);
// ...the human on your machine will only hear this if they are allied with you

See also

• Audio (Sound) – guides to modding game audio (OGG files) and a directory of all Warzone audio files
• audioAlert(filename,pos,despam) – play a sound but not too often, an ideal alternative to playSound()
• Enhanced Situation Reporting mod (main Warzone forums) – a mod by Shadow Wolf TJC that adds additional audio feedback during gameplay.
• User Interface – quick reference of all JS API functions associated with the user interface