UnofficialWIKI
Builder
Edit / Suggest changeSuggest deletion

Music

gameplayMusicSettings

Defines the world's music: track families with their audio variants, the cues that select them in play, and the family used during character creation.

In the editor

"Creator-owned character creation and gameplay music, including external HTTPS tracks."

Editor location
Files → Other → Music
API endpoint
/sections/gameplayMusicSettings.json/sections/gameplayMusicSettings.md
Size limits

No character-length caps for this section.

Schema

json
{
  "gameplayMusicSettings": {
    "characterCreationTrackId": "string",
    "tracks": {
      "<key>": {
        "variants": [
          {
            "url": "string",
            "narrationUrl": "string",
            "gameplayUrl": "string"
          }
        ],
        "matchTags": [
          "string"
        ],
        "cues": [
          "character-creation | combat | travel | near-death | dying | dead | recovery"
        ]
      }
    }
  }
}

Example

json
{
  "gameplayMusicSettings": {
    "characterCreationTrackId": "OpeningTheme",
    "tracks": {
      "OpeningTheme": {
        "cues": ["character-creation"],
        "variants": [
          { "url": "https://example.com/audio/opening.mp3" }
        ]
      },
      "BattleTheme": {
        "cues": ["combat"],
        "matchTags": ["siege", "boss"],
        "variants": [
          {
            "narrationUrl": "https://example.com/audio/battle-narration.ogg",
            "gameplayUrl": "https://example.com/audio/battle-gameplay.ogg"
          }
        ]
      }
    }
  }
}

Overview

Each key in tracks is a track family: a named group of audio the engine can switch to. A family holds one or more variants (the audio itself) and, optionally, the cues and matchTags that let the engine pick it during play.

Music is selected two ways. Contextually, the engine matches the current situation against a family's cues and matchTags. Explicitly, a trigger pins a family with the music-track-set effect and releases it again with music-track-clear; a pinned family overrides contextual selection until it is cleared. Both effects are listed on the Triggers page.

Audio is hosted by you: each variant URL points at an HTTPS .mp3, .ogg, or .wav file. Voyage does not host creator audio, and creator-provided sound effects and ambience are not supported -- this section covers music only.

Fields

characterCreationTrackId

Names the family in tracks used while the player builds their character. It must match a key in tracks exactly -- a name that resolves to nothing is rejected on load, so the validator flags it.

tracks

A map of family id to family. The key is the id you reference from characterCreationTrackId and from a music-track-set trigger effect, so keep it stable once triggers point at it.

variants

The audio a family can play, as a list. A variant either carries a single url used in every context, or a narrationUrl and gameplayUrl pair so narration and active play get different versions of the same piece. Each URL is an HTTPS .mp3, .ogg, or .wav.

A family with no variants has nothing to play, so Voyage rejects a track entry without this field.

cues

The moments a family is eligible for. Each entry is one of character-creation, combat, travel, near-death, dying, dead, or recovery. A family with no cues is never chosen contextually, which is what you want for one a trigger pins explicitly.

matchTags

Free-form tags that refine contextual selection, letting several families share a cue and be told apart by situation. Optional: a family with cues but no tags is simply eligible whenever its cue is active.