====== Jouer (son, musique) ======

Cette instruction permet de jouer des sons et musiques qui se trouvent dans les ressources du jeu.

===== Exemple complet =====
<code donjon>
PARTIE "Paramètres".
  -- activer l’audio (requis pour que l’audio fonctionne dans votre jeu)
  activer l’audio.
  -- afficher les lieux qui n’ont pas encore été visités
  activer l'affichage des lieux inconnus.

PARTIE "Description des lieux".
  Le hall est un lieu.
  Le salon est un lieu au nord du hall.
  La salle d’armes est un lieu au sud du hall.
  Le futur est un lieu à l’est du hall.
    
  -- gérer l’audio quand le joueur se déplace entre les lieux
  après aller vers ceci ou commencer le jeu:
    -- salon: jouer de la musique en boucle
    si le joueur se trouve dans le salon:
      jouer la musique musique_classique.mp3 en boucle;
    -- salle d’armes: jouer 1 son à 3 reprises en arrivant
    sinonsi le joueur se trouve dans la salle d’armes:
      jouer le son coup_d_epee.flac 3 fois;
    -- futur: jouer 2 sons différents (à la suite) en arrivant
    sinonsi le joueur se trouve dans le futur:
      jouer le son charge.ogg;
      jouer le son bulle.mp3;
    fin si
    
    -- terminer l’action normalement
    continuer l’action après.
    
  -- en quittant le salon, baisser la musique et l’arrêter
  avant aller vers ceci:
    si le joueur se trouve dans le salon:
       -- enlever le mot clé « progressivement » pour l’arrêter d’un coup
       arrêter la musique progressivement;
    fin si.

PARTIE "emplacement des ressources du jeu".
-- Définition du dossier qui contient les ressources du jeu (ici « mon_donjon »):
Les ressources du jeu se trouvent dans le dossier mon_donjon.

</code>
[[djnb>ex_audio| tester cet exemple]] 

===== Activer l'audio, exemples et fichiers manquants =====

Afin que l'audio fonctionne pour votre jeu, vous devez l'activer. Cela permet de prévenir le joueur qu'il va y avoir des effets audio dans votre jeu. Il lui sera possible de tester son matériel et de couper le son.

<code donjon>
-- mention à placer dans votre scénario
activer l'audio.
</code>

Les fichiers repris dans les exemples de cette page sont disponibles de base dans Donjon afin que vous puissiez faire des tests.

//Si un fichier est manquant//, votre jeu s'exécutera sans souci mais la mention du fichier manquant s'affichera afin de vous prévenir.

//Si vous n'activez pas l'audio//, votre jeu s'exécutera sans souci mais sans son ni musique.

===== Sons =====

À priori il s'agit d'//effets assez courts// qu'on peut jouer lorsque le joueur effectue une action en particulier.
Les sons peuvent être joués par dessus une musique. Un seul son peut-être joué à la fois mais on peut en jouer plusieurs à la suite.

==== Jouer un son ====

<code donjon>
jouer le son coup_d_epee.flac;
</code>

=== Jouer un son plusieurs fois ===

<code donjon>
jouer le son coup_d_epee.flac 3 fois;
</code>

=== Jouer plusieurs sons différents à la suite ===

<code donjon>
jouer le son charge.ogg;
jouer le son bulle.mp3;
</code>

===== Musiques =====

Généralement utilisé pour //créer une ambiance//, les musiques durent plus longtemps que les sons et peuvent être jouées en boucle.

==== Jouer une musique ====

<code donjon>
jouer la musique musique_classique.mp3;
</code>

=== Jouer une musique en boucle ===

Avec cette option, lorsque la musique se termine, elle est jouée à nouveau jusqu'à ce qu'on l'arrête.

<code donjon>
jouer la musique musique_classique.mp3 en boucle;
</code>

==== Arrêter la musique ====

<code donjon>
arrêter la musique;
</code>

=== Arrêter la musique progressivement ===

Cet effet diminue le son progressivement avant d'arrêter la musique afin que la coupure soit plus discrète.

<code donjon>
arrêter la musique progressivement;
</code>


===== Emplacement des fichiers audio =====

Le //nom des fichiers// ressources ne peut contenir que des lettres non-accentuées, des chiffres et des tirets.

==== Par défaut ====

Par défaut, vous devez placer les ressources du jeu dans le dossier ''./assets/ressources'' :
  * ''./assets/ressources/sons/test.mp3''  (pour ''jouer le son test.mp3;'')
  * ''./assets/ressources/musiques/test.flac'' (pour ''jouer la musique test.flac;'' )

==== Sous-dossier ====

Si vous mettez plusieurs jeux sur le même site web, vous pouvez définir un dossier spécifique pour chacun des jeux. Un même dossier peut-être réutilisé pour plusieurs jeux.

<code donjon>
-- Définition du dossier qui contient les ressources du jeu (ici « mon_donjon »):
Les ressources du jeu se trouvent dans le dossier mon_donjon.
</code>

Vous devez alors placer les ressources du jeu dans ce dossier ''./assets/ressources/mon_donjon'':
  * ''./assets/ressources/mon_donjon/sons/test.mp3''  (pour ''jouer son test.mp3;'')
  * ''./assets/ressources/mon_donjon/musiques/test.flac'' (pour ''jouer musique test.flac;'')