FF SUITEArma 3 addons
Docs/Developer/Internals/Music director

Catalogues, pools, priorities, timed overrides

Music director internals

A server-side scheduler that picks tracks from catalogues and pools, honours priority events and timed forced selections, and publishes one synchronized descriptor stream that local followers play.

FF_Cinematic 5 related functions

1. Registering and following

// server
["operation", createHashMapFromArray [
    ["tracks", [
        ["a", "First track", "musicClassA", 120, 0.2],
        ["b", "Second track", "musicClassB", 90, 0.3]
    ]],
    ["pools", [["calm", ["a", "b"]]]]
]] call FF_cinematic_fnc_musicDirectorStart;
["operation", "select", ["calm", "quiet", 0]] call FF_cinematic_fnc_musicDirectorControl;

// interface clients, including JIP: opt into the local follower
["operationPlayback", createHashMapFromArray [
    ["source", {["operation"] call FF_cinematic_fnc_musicDirectorState}]
]] call FF_cinematic_fnc_musicStart;

Catalogue entries are [key, label, CfgMusic class, measured duration, volume]. At most 256 tracks and 64 pools of 64 members are accepted; duplicate keys, unknown or duplicate pool members and invalid entries are filtered out. Start fails with no valid tracks, a duplicate director ID, or more than 32 directors, and registering a director does not seize anyone's audio — clients opt in through their own follower.

An optional source callback runs on the server every 0.25 s and may return [key, mode, rank, volumeOverride]. It receives [directorID], must be unscheduled and cheap, and must only read state. A valid but unknown key resolves to silence; invalid results leave the explicit base selection in place.

2. Controls

[id, operation, value, duration] call FF_cinematic_fnc_musicDirectorControl, duration bounded 0–3600 s:

OperationValueEffect
select[key, mode, rank, volume?]Base selection; a valid source callback can supersede it
eventtrack keyPlays that exact track once, with priority; a new event restarts it under a new token
force[key, mode, rank, volume?]Overrides the base selection until duration expires, or indefinitely at 0
clearForce—Removes the forced selection, keeps priority
stopTrack—Ends priority early, keeps force and base
clear—Removes priority and force
sourceOn / sourceOff—Enables or silences base/automatic selection; priority and force still apply
stopAll—Clears priority and force, disables base and source

Precedence is priority → force → enabled base/source. A force issued while priority plays waits and then receives its full duration; an already-counting force is not extended by a later event. Expired overrides are removed server-side and clients can never finish or extend them.

3. Selection and timing

  • Pool choices rotate without immediate repetition when alternatives exist; a priority event always selects its exact key.
  • Normal selection starts 2.5 s ahead; loop rollover uses 1.5 s and picks up to 3.5 s before the old track ends.
  • Descending nonnegative ranks schedule a twelve-second transition, preserving slow combat-to-calm moves.
  • Handoff after a natural priority completion uses 0.5 s. Silence is rank -1; unranked one-shot priority is -2.
  • Short tracks cap rollover lead at a quarter of their duration and shorten local fades so repeated snapshots cannot postpone playback forever.
  • Completion is judged from the shared scheduled start plus measured duration and a one-second grace.

4. Curator controls

With ZEN, FF: Zeus > Music director lists the registered native directors with the selected key and its source (priority, override, source or disabled), then offers: play an exact track once, force a playlist or track with optional duration and volume, set the base mood, enable or disable base selection, stop the priority track, clear force, clear both, or stop everything for that director. Duration zero keeps a forced mood until cleared; without a volume override the catalogue volume is kept.

The curator request validates the network owner and assigned curator, then re-validates after deferring the mutation and re-checks the director incarnation, so an old dialog cannot control a replacement registered under the same ID. Requests are throttled to one accepted queue slot per quarter second and normalized by the same command helper as the server API. FF_cinematic_musicDirectorCatalogs publishes [id, track key/label pairs, pool keys, incarnation] — metadata only, no callbacks.

5. Relation to the atmosphere system

Horror keeps the thematic half: zombie and player sensing, horde phases, mood policy, volume curves, whispers, overlay frames and its FFATM snapshots. It delegates catalogue validation, override timing and track selection here. The Atmosphere Control dialog is Horror's themed policy interface and does not register a second native director implicitly.

6. State and lifecycle

  • FF_cinematic_musicDirectorStates — rows of [id, followerDescriptor, selectedKey, source, revision], published only when a primitive changes.
  • FF_cinematic_musicDirectorState(id) returns a copied descriptor for local followers and UI.
  • One server worker advances all directors; removing the last director removes the worker; mission end removes all.
  • An absent ID resolves to stable silence, so a follower fades out its owned track; stop the follower separately when finished.

7. Limits

Verified offline: catalogue and pool filtering, no-repeat rotation, volume-only changes without restarts, descending-rank timing, pending-force duration, expiry, priority handoff, short-track scheduling, and the command normalizer including bounds and malformed or executable payloads. Not verified: server workers under load, random distribution, publish ordering, independent loading, hosted and dedicated playback, actual audio handovers and ZEN menu interaction.

Related functions

↑ Back to top