API Reference

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

Playback runs on one client: 3DS-ATLAS picks the primary GM, and only that client starts and stops tracks. Other clients read the API but cannot drive playback.

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. Registered sections appear in the Music Configuration window alongside the built-in ones and compete in the same priority ordering.

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 is validated; it is rejected, logged, 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. When a section’s sources throw while resolving, it is skipped and logged; the other sections still resolve.

Priority 0 is a deliberate value; the module does not treat it as unset.

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 that covers the built-in area and combat contexts and any registered section’s context key. The scene control toggles and the Calendaria indicator write the same set.

The API layers 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

The built-in sections seed these default priorities into the Configure Section prompt:

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

You can override the priority per assignment in the prompt.

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.