Events

S3maphore's public events live in the OpenMW Player scope. They are useful when a mod already communicates through events; for direct calls, the I.S3maphore interface is usually clearer.

Control events

Events sent to the player should use the player's object as the target. The exact call varies with the script context that sends it; from a player script:

local self = require 'openmw.self'

self.sendEvent(self, 'S3maphoreSetPlaylistActive', {
    playlist = 'my-mod/storm-explore',
    state = true,
})

See Death Track for the complete set/reset and save/load contract.

Notifications

S3maphoreTrackChanged

S3maphorePlaybackChangeEventData = {
    fadeOut?: number,
    cellId?: string,
    playbackEpoch?: integer,
    playlistId: string,
    reason: S3maphoreStateChangeReason,
    trackName: string,
}

Emitted when S3maphore accepts a normal or special track change. trackName is the VFS path. playlistId identifies the playlist that supplied the track. fadeOut is the requested transition duration.

For normal changes, cellId and playbackEpoch describe the request generation. Treat them as read-only metadata; consumers that defer work can use them to reject stale events. Special-track events do not necessarily carry normal playback sequencing fields.

local I = require 'openmw.interfaces'

I.S3maphore.addTrackChangedHandler(function(event)
    print(('%s: %s'):format(event.playlistId, event.trackName))
end)

S3maphoreMusicStopped

{ reason: S3maphoreStateChangeReason }

Emitted when playback stops because music was disabled or no playlist was valid during resolution.

Shared actor polling

S3maphoreCheckCombat

Despite its name, S3maphoreCheckCombat is not a combat notification or a request for a combat result. It is a scheduler hook: S3maphore emits it while its player-side, round-robin traversal visits selected nearby actors. An actor-local script can use that visit to refresh lightweight actor-owned state without installing its own per-actor onUpdate handler. The name comes from S3maphore's primary use for the hook: checking each actor's AI combat targets.

The expensive operation here is asking every actor's AI system for its combat targets. Putting that query in an onUpdate handler on every actor scales with the number of loaded actors. S3maphore already provides the player-side polling and batching:

1. The player script walks the nearby.actors collection from openmw.nearby in a round-robin cycle.
2. It sends S3maphoreCheckCombat to only a bounded batch of actors.
3. The local actor script checks its AI targets.
4. The actor sends OMWMusicCombatTargetsChanged to nearby players only when its target list changes.

The batch size is calculated from the player's dt and clamped between 4 and 16 actors. The target is to revisit the actor list roughly every one-third of a second. A downstream mod does not send these requests or implement another scheduler. Add a S3maphoreCheckCombat handler to an actor-local script and S3maphore will invoke it when that actor is visited:

local AI = require('openmw.interfaces').AI

local inCombat = false

local function updateCombatState()
    local newInCombat = #AI.getTargets('Combat') > 0
    if newInCombat ~= inCombat then inCombat = newInCombat end
end

return {
    eventHandlers = {
        S3maphoreCheckCombat = updateCombatState,
    },
}

The actor-local systems that care about this state can read inCombat or react when that value changes. The event handler's return value is discarded; replace the local variable with the state or notification your mod actually needs.

Use this as a replacement for per-actor onUpdate only when the work can tolerate a bounded, approximate cadence. It is not a generic timer and does not prove that an actor has entered or left combat.

For its built-in use, the S3maphore actor script skips unnecessary AI queries for dead, out-of-range, idle, or unarmed actors. When a query is needed, it uses AI.getTargets('Combat') and reports changes through OMWMusicCombatTargetsChanged:

return {
    eventHandlers = {
        OMWMusicCombatTargetsChanged = function(data)
            local actor = data.actor
            local targets = data.targets
        end,
    },
}

data.actor is the actor that was checked and data.targets is its current combat-target array. Treat both the payload and target array as read-only; the actor script owns the underlying table. The event is sent to nearby players, so a player script can maintain its own combat projection without re-querying every actor.

This contract requires S3maphore's local actor script to be loaded for the actors being checked. The event carries no custom request data, no return value, and no per-dispatch combat payload. Use I.S3maphore or the documented state/events when you need combat information; use a separate event name when you need unrelated actor work.

State reevaluation

S3maphoreStateChanged

The payload is an integer bitmask. It requests playlist reevaluation after one or more of these changes:

Use bitwise checks when handling a combined value. Most playlist authors should not send this event; S3maphore's own state producers send it when appropriate.

State-change reasons

event.reason uses I.S3maphore.const.STATE:

Internal synchronization events

These events exist between S3maphore's global and player scripts. They are not a supported integration surface:

Do not send these events or depend on their payloads. Use PlaylistState and the public interface instead.