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.
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 :
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
endAppelez-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.
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.
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 mAjoutez-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
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 loadedCe 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.
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.
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'utilisersrc = 0. - Lisez
GetBassau 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.