Documentation ZeroDev Sound

API développeur de ZeroDev Sound

ZeroDev Sound a une API ouverte pour les autres resources : lire ce qui est joué, piloter un système d'enceintes ou un autoradio pour un joueur depuis votre propre menu, suivre les changements, placer vos propres enceintes et ateliers d'installation, et animer des lumières avec les vraies basses. Tout ce qui figure ici est tiré de ZeroDev Sound 3.0.5. Les fichiers de l'API ne sont pas sous escrow, vous pouvez donc lire le contrat vous-même : server/devapi.lua et client/devapi.lua.

Pour ZeroDev Sound 3.0.66 min de lectureMis à jour le

ZeroDev Sound vérifie chaque valeur qu'on lui donne et continue de fonctionner quand votre resource est absente, arrêtée ou défaillante. Les heures calmes, la coupure par la police et le plafond de volume du propriétaire s'appliquent à tout ce qui est joué.

Trouver la resource

La resource porte le marqueur de manifeste audio_extensions 'v1'. Trouvez-la grâce à lui, pas à son nom de dossier, car les serveurs peuvent renommer le dossier :

Lua
local function soundResource()
    for i = 0, GetNumResources() - 1 do
        local res = GetResourceByFindIndex(i)
        if res and GetResourceState(res) == 'started' and GetResourceMetadata(res, 'audio_extensions', 0) == 'v1' then return res end
    end
end

Appelez-la avec exports[res]:.... Les noms d'événements commencent par le nom de la resource : res .. ':session'.

Une session est un flux de morceau : un groupe d'enceintes reliées dans le monde (kind = 'speakers') ou l'autoradio d'une voiture (kind = 'car', clé car:<plate>). Un morceau est choisi par une référence : library:<n> (un morceau de Config.Library), file:<name> (un fichier de web/library) ou request:<n> (une demande de morceau ajoutée par le propriétaire).

Exports serveur

Export Renvoie
GetSessions() toutes les sessions du serveur
GetSession(key) une session, ou nil
GetCarSession(vehicle) la session d'un véhicule (entité ou texte de plaque), ou nil
Targets(src) ce que ce joueur peut lancer maintenant : { key, kind, label, canPlay, why }
Control(src, key, action, data) ok, reason
Ready() true une fois Sound chargé
ApiVersion() 2

Control exécute une action avec les mêmes règles que la télécommande de Sound : toute personne dans la voiture pilote son autoradio ; un système posé suit son propriétaire et son réglage de groupe ou public, et le joueur doit être à portée. Passez src = 0 pour agir avec l'autorité de votre propre script, une fois que votre script a décidé qui peut le faire.

Action Données
play { text = reference } (sans text : reprise)
queue { text = reference }
resume, pause, next, previous, stop aucune
volume { value = 0.0 - 1.0 }
seek { at = seconds }
mode { value = 'studio' }, ou bass, club, vocal, concert, night, chipeo
eq { low, mid, high } en dB, de -12 à 12
repeatMode { value = 'off' }, ou one, all

Quand ok est false, reason vaut l'un de no_session, bad_action, no_player, not_inside, out_of_range, not_allowed, mixer_alone, no_text, catalogue_only ou error.

Exemple : les enceintes du club jouent le morceau house quand le DJ prend son service.

Lua
RegisterNetEvent('myclub:clockIn', function()
    local src = source
    for _, t in ipairs(exports[res]:Targets(src)) do
        if t.kind == 'speakers' then
            exports[res]:Control(src, t.key, 'play', { text = 'library:3' })
            exports[res]:Control(src, t.key, 'mode', { value = 'club' })
        end
    end
end)

Enceintes fixes et ateliers d'installation

Un script de boutique, de club ou de garage peut mettre ses propres enceintes et un atelier d'installation dans son bâtiment. Elles n'ont ni propriétaire ni item, ne sont jamais enregistrées, et disparaissent quand votre resource s'arrête. Les joueurs ne peuvent ni les déplacer ni les ranger ; la police peut toujours les couper.

Lua
local id, key = exports[res]:AddFixedSpeaker({
    id = 'radio_1',              -- yours to name; adding the same id again moves it
    item = 'zds_room_ceiling',   -- any placed Sound speaker item
    coords = vector3(x, y, z), heading = 90.0,
    pitch = -90.0,               -- on a ceiling, grille down; 0 on a floor or wall
    label = 'Store radio',
    group = 'store',             -- same group = one system
})
exports[res]:RemoveFixedSpeaker('radio_1')
exports[res]:GetFixedSpeakers()  -- { { id, speaker, key } } of your resource

exports[res]:AddBay({ id = 'garage', label = 'Garage audio bay', coords = vector3(x, y, z), radius = 6.0, blip = true })
exports[res]:RemoveBay('garage') -- up to 8 bays per resource, radius 3 to 15 m

Ajoutez-les au démarrage de votre resource, et de nouveau sur <res>:ready, au cas où Sound démarrerait après vous.

Événements serveur

Lua
AddEventHandler(res .. ':session', function(key, session) end)   -- any change: song, pause, volume, mode, queue
AddEventHandler(res .. ':songStarted', function(session) end)    -- a different song started
AddEventHandler(res .. ':sessionRemoved', function(key) end)     -- speakers packed up, a car session ended
AddEventHandler(res .. ':ready', function() end)                 -- Sound started and loaded

Ce sont des événements locaux au serveur, jamais envoyés depuis un client, donc un client ne peut pas les simuler.

Exports client (lecture seule)

Export Renvoie
GetSessions() les sessions que ce client connaît : proches et la sienne
GetCarSession(vehicle) la session de la voiture, ou nil
GetBass(key) de 0.0 à 1.0 : les basses du vrai morceau à cette frame, 0 en silence
CarAudioState(vehicle) l'état de l'autoradio, pour les écrans de voiture

Exemple : un néon sous la caisse qui pulse avec les caissons de la voiture.

Lua
CreateThread(function()
    while true do
        local veh = GetVehiclePedIsIn(PlayerPedId(), false)
        local s = veh ~= 0 and exports[res]:GetCarSession(veh)
        if s and s.title and not s.paused then
            SetVehicleNeonLightsColour(veh, 255, math.floor(40 + 200 * exports[res]:GetBass(s.key)), 255)
            Wait(0)
        else
            Wait(500)
        end
    end
end)

Exemples de config

Les réglages se trouvent dans zerodev-sound/config/config.lua, et chacun peut être modifié en jeu dans /soundadmin.

Lua
Config.Framework = 'auto'        -- or 'esx', 'qb', 'qbox', 'standalone'
Config.Inventory = 'auto'        -- or 'ox', 'qb', 'qs', 'codem', 'core', 'origen', 'tgiann', 'esx', 'none'
Config.MaxPlacedPerPlayer = 8
Config.QuietHours = { enabled = true, from = 23, to = 7, maxVolume = 0.35 }

Règles pour les intégrations

  • Ne modifiez pas les fichiers de ZeroDev Sound ; utilisez l'API. Un fichier sous escrow modifié empêche la resource de se charger.
  • Transmettez le vrai source à Control, ou vérifiez vous-même la permission avant d'utiliser src = 0.
  • Lisez GetBass au plus une fois par frame, et mettez-vous en veille quand rien n'est joué.
  • L'API est versionnée (audio_extensions 'v1', ApiVersion() 2). Un changement incompatible reçoit une nouvelle version et une ligne dans le changelog.

Questions fréquentes

Comment trouver ZeroDev Sound depuis mon script ?

Cherchez la resource dont le manifeste contient audio_extensions 'v1', comme dans le premier exemple. Le dossier peut porter un autre nom sur certains serveurs.

Mon script peut-il jouer de la musique sur les enceintes d'un joueur ?

Oui, avec Control(src, key, 'play', { text = 'library:1' }). Les mêmes règles que la télécommande de Sound s'appliquent : le joueur doit être autorisé à lancer ce système et être à portée.

Des lumières ou des props peuvent-ils suivre la musique ?

Oui. L'export client GetBass(key) donne les basses du morceau en cours, à chaque frame, de 0 à 1.

Traduit de l'anglais. En cas de désaccord entre cette page et la page en anglais, c'est la page en anglais qui fait foi. English