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 music catalog for character creation, contextual gameplay, and trigger overrides."

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, a family is picked by its cues (fixed moments such as combat or travel) or its matchTags (mood and scene words); the families Voyage ships use one or the other. 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, and every variant URL must be an HTTPS address. 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, 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. Every variant needs a URL, and each URL must use HTTPS.

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

cues

The fixed moments a family is eligible for. Each entry is one of character-creation, combat, travel, near-death, dying, dead, or recovery. Optional: most of the families Voyage ships have no cues and are chosen by their matchTags instead.

matchTags

Mood and scene words, such as ominous or triumphant, that make a family eligible during normal play. Voyage's own mood families (Calm, Apprehensive, Triumphant and the rest) rely on these alone.