Superheroes_Incremental/docs/audio.md

Audio

Le système est local à chaque joueur : AudioController expose mixer par injection Flamework. Le catalogue src/client/audio/catalog.ts sépare les assets SFX et Music. Il est volontairement vide ; ajouter des assets audio autorisés pour l'expérience avant de les utiliser.

// Inside a Flamework controller with AudioController injected:
this.audioController.mixer.playSfx("Confirm");
this.audioController.mixer.playMusic("Lobby");
this.audioController.mixer.stopMusic();

Chaque SFX crée une lecture indépendante, ce qui permet leur superposition. La fin du son ou le handle stop() libère le lecteur, son Wire et sa connexion. Une seule musique joue à la fois, en boucle ; sélectionner à nouveau la même piste ne la redémarre pas. Une clé inconnue retourne undefined sans interrompre la musique courante. Le contrôleur libère tous les lecteurs et abonnements à sa destruction.

Raccordement de Settings

Le producer Reflex audioSettings est la source des réglages pour l'interface et le mixer. Les abonnements sont appliqués à la frame suivante. Utiliser getState() pour lire, subscribe() pour observer (et appeler sa fonction de désabonnement au démontage), et ces actions pour modifier :

import { audioSettings } from "client/audio/settings";

audioSettings.setVolume("SFX", 0.8);
audioSettings.setVolume("Music", 0.4);
audioSettings.setVolume("Master", 1);
audioSettings.setMuted("Music", true);
audioSettings.reset();

Les sliders utilisent des valeurs entre 0 et 1. Les valeurs finies sont bornées ; NaN et les infinis sont ignorés. Le mute conserve la valeur du slider et laisse la musique avancer. Le volume audible vaut clip.volume × channel.volume × Master.volume, ou zéro si le canal ou Master est muet. Les sons démarrés après un changement utilisent également ces réglages. Les réglages durent la session ; une future persistance peut charger et sauvegarder les valeurs via ces mêmes actions. Aucune page Settings ni sauvegarde serveur n'est ajoutée ici.

Choix technique

• Objets audio Roblox : AudioPlayer → AudioFader (SFX/Music) → AudioFader (Master) → AudioDeviceOutput. Ce graphe préserve le mixage propre à chaque asset et suit la recommandation actuelle du moteur.
• @rbxts/reflex 4.3.1 (documentation) gère l'état réactif ; @rbxts/trove 1.3.0 (documentation) gère le nettoyage. Les déclarations installées ont été contrôlées.
• @rbxts/sound-manager 2.3.4 (mainteneur) a été comparé au moteur et son code installé inspecté. Ses registres non spatiaux utilisent Sound, désormais déconseillé par Roblox, et setCategoryVolume remplace les volumes des assets. Ses méthodes globales parcourent également les registres voisins. Il reste installé pour compatibilité avec le template mais n'est pas utilisé pour ce nouveau système.

Le graphe actuel couvre la musique et les effets 2D (interface, notifications). Les sons spatiaux nécessiteront un routage avec AudioEmitter et AudioListener conservant ces mêmes réglages de canaux.