Overview

Plays a sound, optionally displaying a beacon on the map and mini map.

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

Value	Type	Description	Game version
`undefined`	Undefined	Currently this function always returns `undefined` regardless of whether the sound file was found/played.	3.1 Beta 1

Example

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

Announce warning when structure 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...

Filter sounds based on ally status

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

Browser not supported