Priority and Interruption

You are in the right place when two playlists can both play and you need to decide which one wins. Priority determines which valid playlist is preferred. Interrupt mode determines whether that newly preferred playlist may replace the track that is already playing.

You do not need to memorize the numbers. Start with a named PlaylistPriority value, then choose a named INTERRUPT value only when the default behavior is not what you want. Lower priority numbers are considered first.

Every PlaylistPriority value

The priority value also determines which resolution deck a playlist enters: Explore, Battle, or Special. Keep a playlist in the band that matches its purpose. See Playlist Specification for the other fields and PlaylistEnvironment for the injected PlaylistPriority value.

When two playlists have the same priority, registration order breaks the tie. For playlists loaded from files, that means the VFS file order followed by the order of the playlist tables returned by each file. Do not rely on that as a hidden override; use a more specific priority when one playlist should reliably win.

Automatic interrupt modes

If interruptMode is omitted, S3maphore assigns it from the priority band:

This default is a convenience, not a rule. Set interruptMode explicitly when the playlist's interruption behavior matters. Override is never assigned automatically.

Every INTERRUPT value

INTERRUPT.Override is for deliberate moments such as quest stages, boss entrances, and one-shot cues. It bypasses the interruption gate, but the playlist must still be active, have tracks, pass its callback, and win normal priority resolution. In other words, Override is a permission to interrupt, not a shortcut around playlist selection.

Keep the journal lookup outside the callback. The same rule tables are used as cache keys by S3maphore. Playlist callbacks use the Playback binding from the PlaylistEnvironment.

local QuestStages = {
    MyQuest = { min = 10 },
}

return {
    {
        id = 'my-mod/boss-entrance',
        priority = PlaylistPriority.Special,
        interruptMode = INTERRUPT.Override,
        playOneTrack = true,
        tracks = {
            'music/my-mod/boss-entrance.mp3',
        },
        isValidCallback = function()
            return Playback.rules.journal(QuestStages)
        end,
    },
}