API Reference

The API is published as the global VGMUSIC and at game.modules.get('vgmusic').api. Both point to the same object.

Only the primary GM’s client, chosen by 3DS:ATLAS, starts and stops tracks. Other clients can call the API but do not drive playback. No client plays anything while Minstrel is active.

registerSection

const handle = VGMUSIC.registerSection({
  id: 'my-module.weather',
  label: 'MYMODULE.WeatherMusic',
  priority: 10,
  types: ['Scene'],
  predicate: (controller) => game.myModule.isStormy,
  contextKey: 'weather'
});

Registers a playlist section and refreshes playback. Registered sections appear in the Music Configuration window and compete in the same priority ordering as the built-in ones. A section draws music from the active scene, the default music, and each combatant’s token and actor in the current encounter, filtered by types.

Property	Type	Description
id	string	Required. Unique registry id.
label	string	Localization key for the section name. Used verbatim when it resolves to nothing.
priority	number	Default sort priority, prefilled in the Configure Section prompt. Defaults to 0.
types	string[]	Document type names the section applies to: Scene, Actor, Token, DefaultMusic.
predicate	Function	Activation test, called with the music controller once per playlist refresh. A falsy return keeps the section silent.
hint	string	Localization key describing when the section plays, shown under the section select in the prompt.
contextKey	string	Context key used for flags, suppression, and playback. Defaults to the id.

Registration logs a warning and returns null when:

• id is missing or not a string.
• id is already registered.
• types is not an array, or contains a name outside Scene, Actor, Token, DefaultMusic.
• predicate is defined but not a function.
• The context key is area or combat, or is already claimed by another registered section.

A successful call returns a handle:

Member	Description
id	The registered id.
contextKey	The resolved context key.
unregister()	Removes the section and refreshes playback.
refresh()	Re-runs playlist selection.

A predicate that throws disables its section for that refresh. A section whose sources throw while resolving is skipped and logged, and the other sections still resolve.

Registry functions

Function	Returns	Description
VGMUSIC.unregisterSection(id)	boolean	Removes a registered section. True when a section was removed.
VGMUSIC.getRegisteredSections()	object[]	Every registered section definition.
VGMUSIC.refreshSections()	Promise<void>	Re-runs playlist selection, for when a predicate would now answer differently. Resolves once the transition has run.

Suppression

GM suppression is a world-scoped set of context keys covering area, combat, and any registered section’s context key. The scene control toggles and the Calendaria indicator write the same set.

The API adds reference-counted suppression on top of it:

Function	Returns	Description
VGMUSIC.requestSuppression(context)	object | null	Suppresses a context until the returned token is released. Primary GM only; called from any other client it logs and returns null.
VGMUSIC.releaseSuppression(token)	boolean	Releases a token. True if the token was live.

A context stays silent while any token holds it or the GM suppression set contains it. Tokens live in the primary GM client’s memory and do not persist across reloads.

Hooks

vgmusic.trackChanged

Fires on every client when the playing track changes.

Hooks.on('vgmusic.trackChanged', ({ prev, current, context }) => {});

Field	Type	Description
prev	PlaylistSound | null	The track that stopped.
current	PlaylistSound | null	The track now playing.
context	string | null	The playing context key.

vgmusic.suppressionChanged

Fires on every client when the GM suppression set changes. The payload is the new Set of suppressed context keys.

Hooks.on('vgmusic.suppressionChanged', (contexts) => {});

Built-in section priorities

Default priorities prefilled in the Configure Section prompt:

Section	Priority
Token combat	5
Actor combat	0
Scene combat	-10
Default combat	-15
Scene area	-20

Other members

Member	Description
VGMUSIC.musicController	The controller singleton driving playlist selection and playback.
VGMUSIC.VGMusicConfig	The Music Configuration application class.
VGMUSIC.PlaylistContext	A resolved playlist candidate, exposed for consumers building their own.