Audio

Audioebenen pro Spieler, Ambient-Zonen, Soundsequenzen, Dialogstimmen und ein Lautstärkemenü.

Privatv0.1.0Hilfsmittel

BenötigtTypeWriter0.9GUIProtectionoptional

Für das BornToCraft-Netzwerk entwickelt. Diese Erweiterung ist zu Referenzzwecken dokumentiert und wird nicht verteilt.

Support

Überblick

Audio fügt den Minecraft-Sounds ein kleines Mischpult hinzu. Jeder über die Erweiterung abgespielte Sound gehört zu einer von fünf Ebenen (Layers): MASTER, MUSIC, AMBIENT, SFX und VOICE. Jeder Spieler hat für jede Ebene eine Lautstärke (von 0.0 bis 1.0), und die Erweiterung multipliziert die Ebenenlautstärke beim Abspielen eines Sounds mit der Master-Lautstärke. Lautstärken werden pro Spieler gespeichert, sodass eine Einstellung eine erneute Verbindung überdauert.

Zusätzlich zum Mischpult erhältst du Umgebungsklangzonen, die an Protection-Regionen gebunden sind, zeitlich gesteuerte Soundsequenzen, einen dynamischen Musiktrack, der auf einen Fact reagiert, ein Profil für „Tippstimmen“ in Dialogen und ein Menü im Spiel, in dem Spieler ihre eigenen Lautstärken anpassen.

Die Erweiterung läuft auf dem BTC-Build von TypeWriter (BTC Core, Paper/Folia) und ist hier als Referenz dokumentiert. Die Menü-Entries bauen auf der GUI-Erweiterung auf.

Funktionen

• Fünf Audio-Ebenen — MASTER, MUSIC, AMBIENT, SFX und VOICE, jede mit eigener Lautstärke pro Spieler.
• Gespeicherte Lautstärken — ein Player Audio Volume-Artifact speichert die Einstellungen jedes Spielers.
• Umgebungsklangzonen — spiele einen Sound, solange der Spieler in einer Protection-Region steht, mit einer Priorität bei überlappenden Zonen.
• Soundsequenzen — löse mit einer einzigen Action mehrere Sounds mit gewählten Verzögerungen aus.
• Dynamische Musik — starte einen Basistrack und schalte zusätzliche Ebenen anhand des Werts eines Facts ein und aus.
• Dialogstimmen — spiele pro getipptem Zeichen einen Sound, mit separaten Sounds für Vokale, Satzzeichen und Leerzeichen und einer zufälligen Tonhöhenschwankung.
• Lautstärke-Action — setze die Lautstärke einer Ebene für einen Spieler, sofort oder mit schrittweiser Änderung.
• Einstellungsmenü — eine GUI, in der Spieler jede Ebene lauter, leiser oder stumm stellen, nutzbar als eigenes Menü oder als Buttons in jeder GUI-Seite.

Installation

1. Installiere die GUI-Erweiterung: Die Audio-Erweiterung wird gegen sie gebaut und nutzt ihr Menüsystem für den Einstellungsbildschirm.
2. Wenn du Umgebungsklangzonen möchtest, installiere die Protection-Erweiterung und erstelle damit Regionen.
3. Lege die Audio-JAR in plugins/Typewriter/extensions/ ab und starte den Server neu.
4. Spiele deine eigenen Sounds wie gewohnt ab: Eigene Sounds stammen aus deinem Resource Pack, und die Erweiterung spielt sie nur über ihre Sound-ID ab.

Erste Schritte

So fügst du einer Waldregion eine Dauerschleifen-Atmosphäre hinzu und gibst Spielern ein Lautstärkemenü:

1. Erstelle im TypeWriter-Web-Panel mit der Protection-Erweiterung eine Region und notiere ihre Entry-ID.
2. Öffne eine Static-Seite und füge einen Ambient Sound Zone-Entry hinzu.
3. Setze protectionRegionId auf die ID des Region-Entrys, wähle den sound und lass layer auf AMBIENT.
4. Füge auf einer Manifest-Seite ein Player Audio Volume-Artifact hinzu, damit Lautstärken gespeichert werden.
5. Füge eine Audio Settings Menu-Action hinzu. Baue ihr Layout in layoutPool, setze mainLayoutId und platziere Items, deren Tag audio_button:AUDIO_LAYER:MASTER, audio_button:AUDIO_LAYER:MUSIC und so weiter ist (der Ebenenname wird in Großbuchstaben geschrieben).
6. Füge eine Open Audio Settings-Action hinzu, die in menu auf das Menü zeigt, und löse sie über eine NPC-Dialogoption, einen Befehl oder ein Item aus.
7. Veröffentliche, betritt die Region, öffne dann das Menü und teste die Lautstärken.

Keine Fades, keine Wiederholung

Fades werden nicht unterstützt. Minecraft kann die Lautstärke eines bereits laufenden Sounds nicht ändern, daher haben fadeIn und fadeOut keine Wirkung: Ein Sound startet mit voller Lautstärke und endet sofort. Die Felder bleiben an Zonen, Sequenzen und Dialogprofilen erhalten, aber ihr Wert ändert nichts. Ebenso ist looping nicht implementiert: Der Sound wird einmal abgespielt und nicht wiederholt, verwende also einen Sound, der für die Zone lang genug ist.

So funktioniert es

Umgebungszonen, Soundsequenzen, Dialogprofile und der Dynamic Music Track laufen alle über den Mixer und folgen daher der Lautstärke des Spielers für ihre Ebene. Ein Sound startet direkt mit seiner endgültigen Lautstärke: der Lautstärke des Sounds, mal der Ebenenlautstärke (mit der Master-Lautstärke), mal einem Multiplikator des jeweiligen Entrys (zoneVolume einer Umgebungszone, volumeOverride eines Sequenzsegments). Da Minecraft die Lautstärke eines bereits laufenden Sounds nicht ändern kann, gilt eine nachträglich geänderte Ebenenlautstärke nur für Sounds, die nach der Änderung gestartet werden.

Menüs

Das Audio Settings Menu ist ein GUI-Entry. Seine Felder (inventoryTitle, inventoryRows, guiType, layoutPool, mainLayoutId, audio) funktionieren wie in der GUI-Erweiterung. Audio fügt spezielle Buttons hinzu: Gib einem Layout-Item das Tag audio_button: gefolgt von einem Button-Typ.

Button-Typ	Was er tut
AUDIO_LAYER:<LAYER>	Zeigt die Ebene (zum Beispiel AUDIO_LAYER:MASTER) mit ihrem Icon, Prozentwert und einem Balken mit zehn Stufen. Linksklick fügt 10 Prozent hinzu, Rechtsklick entfernt 10 Prozent, Shift + Linksklick schaltet die Ebene stumm oder stellt sie wieder her.
AUDIO_CLOSE	Schließt das Menü.

Das Tag wird als audio_button:<TYPE>:<LAYER> gelesen. In der Praxis ist AUDIO_LAYER:<LAYER> der zu verwendende Button. Die Typen AUDIO_VOLUME_UP, AUDIO_VOLUME_DOWN und AUDIO_LAYER_MUTE werden ebenfalls erkannt, wirken aber nur, wenn die Ebene auf dieselbe Weise angegeben wird (zum Beispiel audio_button:AUDIO_VOLUME_UP:MUSIC), und werden dann genau wie AUDIO_LAYER:MUSIC dargestellt: Alle drei Klicks sind immer verfügbar.

Die Buttons sind für jede GUI-Seite registriert, du kannst sie also in einem allgemeinen „Einstellungen“-Menü platzieren und nicht nur im Audio Settings Menu. Die erzeugten Ebenen-Items verwenden französische Anzeigenamen und Lore („Volume general“, „Musique“, „Clic gauche“); diese Texte sind in der Erweiterung fest vorgegeben.

Spieler ändern Lautstärken über einen internen Befehl namens audio_button, der beim Start registriert wird. Er ist nicht dafür gedacht, von Hand eingegeben zu werden, und hat keine eigene Berechtigungsprüfung.

Konfiguration

Die Erweiterung hat keine Konfigurationsdatei. Lautstärken werden über das Player Audio Volume-Artifact gespeichert (artifactId ist standardmäßig player_audio_volumes). Änderungen werden etwa fünf Sekunden nach der letzten Änderung geschrieben und erneut, wenn TypeWriter entlädt. Ohne dieses Artifact auf einer veröffentlichten Seite leben Lautstärken nur im Speicher und gehen verloren, wenn der Spieler den Server verlässt.

Entries

8 Einträge, aus dem Quellcode der Erweiterung generiert.

Aktionen5

• Audio Settings MenuAudio Settings Menu
• Dynamic Music TrackMusic track that reacts to game facts
• Open Audio SettingsOpen Audio Settings Menu
• Set Master VolumeSet the master or layer volume for a player
• Sound SequenceA sequence of sounds to play

Artefakte1

• Player Audio Volume ArtifactStores per-player audio layer volumes

Definitionen2

• Ambient Sound ZonePlay ambient sound in a region
• Dialogue Audio ProfileAudio profile for dialogue typing sounds

Fehlerbehebung

Die Umgebungszone spielt nichts. Die Zone wird mit protectionRegionId abgeglichen, der ID einer Region aus der Protection-Erweiterung. worldGuardRegionId wird nur gelesen, wenn protectionRegionId leer ist, und benötigt das WorldGuard-Plugin; eine Zone mit keinem von beiden passt nie. Prüfe außerdem, ob sound nicht leer ist und ob der Spieler innerhalb der Region tatsächlich eine Blockgrenze überschreitet, da Zonen geprüft werden, wenn sich der Spieler zu einem anderen Block bewegt.

Die Dialogstimme spielt nie. Der Listener startet nur, wenn der sound des Sprechers auf einen Entry zeigt, dessen ID die ID des Profils ist und der auch als Sound-ID-Entry gefunden wird. Der Dialogue Audio Profile-Entry ist ein einfacher statischer Entry, teste ihn also mit einem kurzen Dialog, bevor du dich darauf verlässt. Ein Dialog mit leerem Text oder der Dauer null wird übersprungen.

Lautstärkeänderungen gehen nach einer erneuten Verbindung verloren. Füge einer veröffentlichten Seite ein Player Audio Volume-Artifact hinzu. Ohne es wird nichts gespeichert.

Ein Menü-Button bewirkt nichts und zeigt das einfache Item. Das Tag muss mit audio_button: beginnen und mit einem in Großbuchstaben geschriebenen Ebenennamen enden, zum Beispiel audio_button:AUDIO_LAYER:SFX. Ohne gültige Ebene bleibt das Item so, wie du es konfiguriert hast.

Das Einstellungsmenü öffnet sich nicht. Das Menü baut auf der GUI-Erweiterung auf. Stelle sicher, dass sie installiert ist und dass bei der Open-Audio-Settings-Action das Feld menu gesetzt ist.

Verwandte Erweiterungen

• GUI — Menü-Layouts und -Items, die das Einstellungsmenü verwendet.
• Protection — Regionen, die die Umgebungsklangzonen steuern.