Documentación de ZeroDev Sound
API para desarrolladores de ZeroDev Sound
ZeroDev Sound tiene una API abierta para otros resources: leer lo que suena, manejar un sistema de altavoces o el equipo de un coche para un jugador desde tu propio menú, seguir los cambios, colocar altavoces y talleres de instalación propios y mover luces con los graves reales. Todo lo de aquí sale de ZeroDev Sound 3.0.5. Los archivos de la API no están protegidos con escrow, así que puedes leer el contrato tú mismo: server/devapi.lua y client/devapi.lua.
ZeroDev Sound comprueba cada valor que recibe y sigue funcionando cuando tu resource falta, está detenido o falla. Las horas de silencio, el silenciado de la policía y el límite de volumen del dueño se aplican a todo lo que suena.
Cómo encontrar el resource
El resource lleva la marca de manifest audio_extensions 'v1'. Encuéntralo por ella, no por el nombre de su carpeta, porque los servidores pueden renombrarla:
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
endLlámalo con exports[res]:.... Los nombres de evento empiezan por el nombre del resource: res .. ':session'.
Una sesión es una transmisión de canciones: un grupo de altavoces enlazados en el mundo (kind = 'speakers') o el equipo de un coche (kind = 'car', clave car:<plate>). Una canción se elige con una referencia: library:<n> (una canción de Config.Library), file:<name> (un archivo de web/library) o request:<n> (una petición de canción que añadió el dueño).
Exports de servidor
| Export | Devuelve |
|---|---|
GetSessions() |
todas las sesiones del servidor |
GetSession(key) |
una sesión, o nil |
GetCarSession(vehicle) |
la sesión de un vehículo (entidad o texto de matrícula), o nil |
Targets(src) |
lo que este jugador puede manejar ahora mismo: { key, kind, label, canPlay, why } |
Control(src, key, action, data) |
ok, reason |
Ready() |
true cuando Sound se ha cargado |
ApiVersion() |
2 |
Control ejecuta una acción con las mismas reglas que el mando propio de Sound: cualquiera dentro del coche maneja su equipo; un sistema colocado sigue a su dueño y a su ajuste de grupo o público, y el jugador debe estar al alcance. Pasa src = 0 para actuar con la autoridad de tu propio script, después de que tu script haya decidido quién puede.
| Acción | Datos |
|---|---|
play |
{ text = reference } (sin text: reanudar) |
queue |
{ text = reference } |
resume, pause, next, previous, stop |
ninguno |
volume |
{ value = 0.0 - 1.0 } |
seek |
{ at = seconds } |
mode |
{ value = 'studio' }, o bass, club, vocal, concert, night, chipeo |
eq |
{ low, mid, high } en dB, de -12 a 12 |
repeatMode |
{ value = 'off' }, o one, all |
Cuando ok es false, reason es uno de no_session, bad_action, no_player, not_inside, out_of_range, not_allowed, mixer_alone, no_text, catalogue_only o error.
Ejemplo: los altavoces del club ponen la canción house cuando el DJ ficha.
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)Altavoces fijos y talleres de instalación
Un script de tienda, club o garaje puede poner sus propios altavoces y un taller de instalación en su edificio. No tienen dueño ni item, nunca se guardan y desaparecen cuando tu resource se detiene. Los jugadores no pueden moverlos ni recogerlos; la policía sí puede silenciarlos.
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 mAñádelos cuando arranque tu resource, y otra vez en <res>:ready, por si Sound arranca después de ti.
Eventos de servidor
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 loadedSon eventos locales del servidor, nunca enviados desde un cliente, así que un cliente no puede falsificarlos.
Exports de cliente (solo lectura)
| Export | Devuelve |
|---|---|
GetSessions() |
las sesiones que conoce este cliente: las cercanas y la suya |
GetCarSession(vehicle) |
la sesión del coche, o nil |
GetBass(key) |
de 0.0 a 1.0: los graves de la canción real en este frame, 0 en silencio |
CarAudioState(vehicle) |
el estado del equipo principal, para pantallas de coche |
Ejemplo: luces bajo el chasis que laten con los subs del coche.
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)Ejemplos de configuración
Los ajustes están en zerodev-sound/config/config.lua, y cada uno se puede cambiar en el juego en /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 }Reglas para integraciones
- No cambies los archivos de ZeroDev Sound; usa la API. Un archivo protegido con escrow que se modifique impide que el resource cargue.
- Pasa el
sourcereal aControl, o comprueba el permiso tú mismo antes de usarsrc = 0. - Lee
GetBasscomo máximo una vez por frame, y duerme cuando no suene nada. - La API tiene versiones (
audio_extensions 'v1',ApiVersion()2). Un cambio que rompa la compatibilidad recibe una versión nueva y una línea en el registro de cambios.
Preguntas frecuentes
¿Cómo encuentro ZeroDev Sound desde mi script?
Busca el resource cuyo manifest tenga audio_extensions 'v1', como en el primer ejemplo. La carpeta puede tener otro nombre en algunos servidores.
¿Puede mi script reproducir música en los altavoces de un jugador?
Sí, con Control(src, key, 'play', { text = 'library:1' }). Se aplican las mismas reglas que al mando propio de Sound: el jugador debe poder manejar ese sistema y estar al alcance.
¿Pueden las luces o los props seguir la música?
Sí. El export de cliente GetBass(key) da los graves de la canción que suena, en cada frame, de 0 a 1.