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.

One pinned family at a time

The party has a single slot for a pinned family, not one per trigger. A second music-track-set replaces whatever was pinned, and music-track-clear releases whatever is pinned rather than only the family your own trigger set.

Two triggers that pin music in different circumstances therefore share that slot, and a clear written for one of them releases the other's track as well. Nothing records which trigger did the pinning, so a clear cannot be made to release only its own. Pair each set with the clear that ends it.

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.

While a family is playing, the running game records which of its variants is current and how many turns it has been current. That state belongs to the game rather than to your world: nothing you author picks a variant or sets how long it plays.

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.

Music

#Schema

#Example

#Overview

#One pinned family at a time

#Fields

#characterCreationTrackId

#tracks

#variants

#cues

#matchTags