[[https://sourceforge.net/tracker/index.php?func=detail&aid=1082436&group_id=13833&atid=363833|On sourceforge tracker]]

====== Current implementation ======
(section copied from server/doc/Developers/sound)

This document describes the sound support for Crossfire, and how the client should handle the commands it receives.

===== Client-side support =====
Sound support is activated by issuing a 'setup sound2 x' command, with x a combination of:
  * 1 for sounds
  * 2 for background music

When sound is activated, the server will send 'sound2' commands to client.

The format of the command is:
<code>    sound2 <x><y><dir><volume><type><len of action>action<len of name>name</code>

with
  * 'x' and 'y' are bytes, position of the sound relative to the player.
  * 'dir' is a byte from 0 to 8, the direction the sound is moving to.
  * 'volume' is a byte from 1 to 100, arbitrary intensity of the sound.
  * 'type' is a byte, the major sound type.
  * 'len of action' is a byte, length of action.
  * 'action' is a string, specifying an arbitrary filename.
  * 'len of name' is a byte, length of name.
  * 'name' is the name of the sound emitter, that can be used to find a specific sound.

Using the type, action and name, the client can determine what sound to play:
  * 'type' gives a base directory
  * 'action' is the actual sound to play, without the extension
  * 'name' specifies a subdirectory in type's directory, in which client should first search

If no sound can be found in 'name', client should search in the base directory.

This enables to override sounds for specific monsters or races.

'type' can be:
  * 1: living sound (moving, dying, ...)
  * 2: spell casting sound
  * 3: item sound (potion, weapon ...)
  * 4: ground sound (door, trap opening, ...)
  * 5: hit something
  * 6: hit by something

Each type will have an associated subdirectory, in which will be the sound files.

Examples:
(<x> indicates a byte of value x)

<code>sound2 <3><2><5><40><1><8>fireball<4>wand</code>
Something cast (<1>) a spell from a 'wand', at position (3,2) relative to the player,
in direction south (<5>).
The spell is a 'fireball'.
Client will first look for a 'cast/wand/fireball' file. If not found,
it will look for 'cast/fireball'.

<code>sound2 <0><0><0><80><2><5>apply<17>potion</code>
player applies a potion of something.
Client should first look for 'item/apply/potion', then 'item/apply'.


===== Conventions for 'action' field =====
For living sounds, the 'action' will be things like 'move', 'death', ...

For spell casting, 'action' will be the spell name. This enables to have spell-specific sounds.

For item sounds, 'action' will be things like 'apply', 'burn' and such.

Ground sounds will have actions like 'hole open', 'trap spring' and such.

For 'hit' and 'hit by' types, the 'action' will be the skill name used to attack.


===== Name meaning =====
Name will be the base name of the emitter, so 'wand', 'mouse', 'door'.

For players, it will be the player's race.

===== Server-side support =====
Objects have a 'sound_chance' field, 0 to 100, that is the probability of sending a sound.

The volume will be randomly determined at each sound for more variability.

Players receive a maximum of MAX_SOUNDS_TICK sounds per tick, to not send too many.

Server doesn't really care of the actions, that are arbitrary.


===== Existing sounds =====
Please update this section as you add sounds.

living:
  * push: something is pushed
  * death: something dies

spell:
  * fumble: spell failure
  * learn: learnt a spell

item:
  * explode
  * evaporate
  * fire: arrow or equivalent is fired
  * poof: wand has no more charges
  * tick: clock sound
  * turn handle: handle is activated
  * apply

ground
  * open: door opens
  * fall hole: something falls in a hole
  * poison: someone drank poison

hit something:
  * one per attack skill
  * low: inflict low damage
  * medium: inflict medium damage
  * high: inflict high damage
  * kill: killed something

hit by something:
  * one per attack skill
  * low: took low damage
  * medium: took medium damage
  * high: took high damage


====== Fix and revamp sound ======

==== Ideas ====
  * Fix brokenness in current sound system
    * Spellcasting sounds broken since the move of spells away from spellnumbers
    * Will often choose oss over alsa, unless one specifies otherwise on the client commandline
  * Send which sound to play, as a string instead of number.
    * Or send numbers, but first let the client fetch a table of which numbers correspond to which sound names.
    * Eliminate the need for the ~/.crossfire/sounds file
  * Make new sounds
  * Allow data-centric elements in the game control playing of sounds and remove code-centric sound triggers:
    * Archetypes could specify a sound to associate with particular items. The sound might need to be played only under certain conditions. For example, maybe when a fountain/drink is applied, a water splashing or drinking sound is played, or when a save bed is applied someone booes/hisses ;-), etc. Different sounds might be played when different doors are opened - some doors might creak, others squeak, whereas the current system is restricted to one sound for all doors.
      * Imagine that not only the sound is identified, but some use flag is also required. IE. If the item is applied, one sound is played, but if it is dropped, another, etc. Damage to items could trigger special sounds.
      * Also, imagine that an audio cue indicating acid damage to an item may more effectively warning that the player may need to consider not meleeing this particular monster.
      * When a player steps in a puddle... etc... a special sound might be played.
    * Sounds could be associated with connections made inside inside the map files.
    * Sounds could be associated with skills.
      * For example, lockpicking, find traps, disarm traps, opening a chest, etc. could trigger a special sound. Depending on the capabilities of the system, the sound might be restricted or changed based on whether the skill was used successfully or not.
      * This might be a bit more delicate than it initially seems as some skills are combative and some are for detecting attributes of items, etc.
    * Sounds could be associated with commands.
      * When a player issues a communication command like burp, cackle, sneeze, etc., an associated sound could be played.
      * Sounds could be associated with other commands: IE ready_skill, killpets, usekeys, peaceful, etc.
      * Probably to prevent hard-coding symptoms, all commands could have a sound association capability, but many would be set NULL where it is up to the developers whether a particular command should or should not have a sound mapped to it.
    * Perhaps system events could be mapped to sounds as appropriate.
      * For example, death of another player signals a sound.
    * Sounds could announce changes in core statistics or protections. This might make it easier for players to accept clients that have these stats hidden on tabbed notebooks and might serve as a clue that something critical changed (stat/level loss) that might mean they might want to change tactics if fighting a monster that steals XP etc.
    * The ability to map sounds to particular spells should be retained.
    * Magic mouths could support sound playing. For example, in the red town tower, there is an invisible key in one room. A magic mouth says "Klang" as a clue that the player might want to cast detect invisible... An audio cue could be played in addition to the textual cue.
    * Along the lines of the current ~/.crossfire/sounds (client/sound-src/sounds.dist) file, sounds would be given a logical name/code rather than a file name so that a player could customize their sound preferences by changing the location/name of a sound.
    * Some care must be taken to make sure that playing sound did not get to be out of hand as it would be bad to drown the player in audio clutter or cause sounds to no longer be synchronous with game play in the event that sounds take a long time to play. In this vein, perhaps the sound server could selectively ignore the playing of a particular sound if it is played too closely in succession.
    * Certainly some design work may be needed, but the point of the request is to move sound closer to the data-domain rather than the code-domain so that it is easier for mapmakers to enhance the game experience without requiring coding skills.
  * Some form of allowing the client to download sounds from the server and cache
    * So sounds can be added on the server, without having to have a new client sound package release
    * Include a full sound cache on clients by default, so this only has to be used for new sounds or updates to sounds
    * Given how sound files are not small, might it lag the server too much to send a sound to a client?
      * Use threads?
      * Have clients fetch over http?
  * Send the coords of where the sound came from (or where the character would perceive it to come from)
    * Could allow clients to do stereo and/or surroundsound as well as volume adjustments in general which isn't needed, but could add depth to it.
      * Probably not worth implementing surroundsound however no harm in giving the client enough info to do it if anyone ever wanted to try implementing it.

  * In game playable instruments (may be impractical though)

==== Proposal ====

FIXME Make detailed proposal

==== More information ====
  * Also see: [[music|Ambient Music]]