Skip to main content

Audio

Per-player audio layers, ambient zones, sound sequences, dialogue voices and a volume menu.

Privatev0.1.0Utilities
RequiresTypeWriter0.9GUIProtectionoptional

Built for the BornToCraft network. This extension is documented for reference and is not distributed.

Support

Overview​

Audio adds a small mixer on top of Minecraft sounds. Every sound played through the extension belongs to one of five layers: MASTER, MUSIC, AMBIENT, SFX and VOICE. Each player has a volume for every layer (from 0.0 to 1.0), and the extension multiplies the layer volume by the master volume when it plays a sound. Volumes are saved per player, so a setting survives a reconnection.

On top of the mixer you get ambient sound zones tied to Protection regions, timed sound sequences, a dynamic music track that reacts to a fact, a "typing voice" profile for dialogues, and an in-game menu where players adjust their own volumes.

The extension runs on the BTC build of TypeWriter (BTC Core, Paper/Folia) and is documented here for reference. The menu entries are built on the GUI extension.

Features​

  • Five audio layers — MASTER, MUSIC, AMBIENT, SFX and VOICE, each with its own per-player volume.
  • Saved volumes — a Player Audio Volume artifact stores every player's settings.
  • Ambient sound zones — play a sound while the player stands in a Protection region, with a priority when zones overlap.
  • Sound sequences — fire several sounds at chosen delays from a single action.
  • Dynamic music — start a base track and switch extra layers on and off from the value of a fact.
  • Dialogue voices — play one sound per typed character, with separate sounds for vowels, punctuation and spaces and a random pitch jitter.
  • Volume action — set a layer volume for a player, instantly or with a progressive change.
  • Settings menu — a GUI where players raise, lower or mute each layer, usable as its own menu or as buttons inside any GUI page.

Installation​

  1. Install the GUI extension: the Audio extension is built against it and uses its menu system for the settings screen.
  2. If you want ambient sound zones, install the Protection extension and create regions with it.
  3. Put the Audio JAR in plugins/Typewriter/extensions/ and restart the server.
  4. Play your own sounds as usual: custom sounds come from your resource pack, and the extension only plays them by their sound id.

Getting started​

Add an ambience to a forest region and give players a volume menu:

  1. In the TypeWriter web panel, create a region with the Protection extension and note its entry ID.
  2. Open a static page and add an Ambient Sound Zone entry.
  3. Set protectionRegionId to the ID of the region entry, choose the sound, and keep layer on AMBIENT.
  4. Add a Player Audio Volume artifact on a manifest page, so volumes are saved.
  5. Add an Audio Settings Menu action. Build its layout in layoutPool, set mainLayoutId, and place items whose tag is audio_button:AUDIO_LAYER:MASTER, audio_button:AUDIO_LAYER:MUSIC and so on (the layer name is written in capitals).
  6. Add an Open Audio Settings action pointing at the menu in menu, and trigger it from an NPC dialogue option, a command or an item.
  7. Publish, walk into the region, then open the menu and test the volumes.
No fades, no looping

Fades are not supported. Minecraft cannot change the volume of a sound that is already playing, so fadeIn and fadeOut do nothing: a sound starts at its full volume and stops at once. The fields stay on zones, sequences and dialogue profiles, but whatever their value, nothing changes. Likewise looping is not implemented: the sound is played once and is not repeated, so use a sound that is long enough for the zone.

How it works​

Ambient zones, sound sequences, dialogue profiles and the Dynamic Music Track all go through the mixer, so they follow the player's volume for their layer. A sound starts directly at its final volume: the volume of the sound, times the layer volume (with the master volume), times a multiplier that depends on the entry (zoneVolume of an ambient zone, volumeOverride of a sequence segment). Because Minecraft cannot change the volume of a sound that is already playing, a layer volume changed afterwards only applies to the sounds started after the change.

The Audio Settings Menu is a GUI entry. Its fields (inventoryTitle, inventoryRows, guiType, layoutPool, mainLayoutId, audio) work as in the GUI extension. Audio adds special buttons: give a layout item the tag audio_button: followed by a button type.

Button typeWhat it does
AUDIO_LAYER:<LAYER>Shows the layer (for example AUDIO_LAYER:MASTER) with its icon, percentage and a ten-step bar. Left click adds 10 percent, right click removes 10 percent, Shift + left click mutes or restores the layer.
AUDIO_CLOSECloses the menu.

The tag is read as audio_button:<TYPE>:<LAYER>. In practice AUDIO_LAYER:<LAYER> is the button to use. The types AUDIO_VOLUME_UP, AUDIO_VOLUME_DOWN and AUDIO_LAYER_MUTE are also recognised, but they only act when the layer is given the same way (for example audio_button:AUDIO_VOLUME_UP:MUSIC), and they then render exactly like AUDIO_LAYER:MUSIC: all three clicks are always available.

The buttons are registered for every GUI page, so you can place them in a general "Settings" menu and not only in the Audio Settings Menu. The generated layer items use French display names and lore ("Volume general", "Musique", "Clic gauche"); these texts are fixed in the extension.

Players change volumes through an internal command named audio_button, registered at startup. It is not meant to be typed by hand, and it has no permission check of its own.

Configuration​

The extension has no configuration file. Volumes are stored through the Player Audio Volume artifact (artifactId defaults to player_audio_volumes). Changes are written about five seconds after the last change, and again when TypeWriter unloads. Without this artifact in a published page, volumes only live in memory and are lost when the player leaves.

Entries​

8 entries, generated from the extension source.

Actions5
Artifacts1
Definitions2

Troubleshooting​

The ambient zone plays nothing. The zone is matched against protectionRegionId, the ID of a region from the Protection extension. worldGuardRegionId is read only when protectionRegionId is empty, and needs the WorldGuard plugin; a zone with neither never matches. Also check that sound is not empty and that the player actually crosses a block boundary inside the region, because zones are checked when the player moves to another block.

The dialogue voice never plays. The listener starts only when the speaker's sound points to an entry whose ID is the profile's ID and that entry is also found as a sound ID entry. The Dialogue Audio Profile entry is a plain static entry, so test it with a short dialogue before relying on it. A dialogue with an empty text or a zero duration is skipped.

Volume changes are lost after a reconnection. Add a Player Audio Volume artifact to a published page. Without it nothing is saved.

A menu button does nothing and shows the plain item. The tag must start with audio_button: and end with a layer name written in capitals, for example audio_button:AUDIO_LAYER:SFX. Without a valid layer, the item is left as you configured it.

The settings menu does not open. The menu is built on the GUI extension. Make sure it is installed and that the Open Audio Settings action has its menu field set.

  • GUI — menu layouts and items used by the settings menu.
  • Protection — regions that drive the ambient sound zones.