Documentación de Pantalla de carga

Pantalla de carga

Que hace

ov_loading es una pantalla de carga completa para FiveM: un video a pantalla completa con tipografía grande, un contador de progreso real, consejos y normas que rotan, una consola para controlar la música y el video, y un espectro de audio que late con la canción.

Todo es editable desde un archivo: logo, video, canciones, color principal, enlaces, consejos, normas y cada texto de la pantalla se cambian en web/config.json, sin tocar código.
Una o varias canciones: si pones varias, suenan en orden y en bucle.
Progreso real: usa el avance de carga de FiveM y, al final, muestra el último recurso que está arrancando.
Se cierra sola en el momento correcto: con loadscreen_manual_shutdown, evita que el jugador vea el paisaje por defecto mientras los recursos aún arrancan.
Color y música por jugador (opcional): puede leer el tema y el silencio de música que el jugador guardó en tu selector de personaje.
Funciona sin base de datos: el servidor solo se usa para los ajustes del jugador y se desactiva con una línea.

Requisitos

FiveM (FXServer reciente) y Lua 5.4.
oxmysql: el server.lua carga su librería. Se usa solo para los ajustes por jugador (Config.AjustesDelJugador.activo); si no usas esa función y no tienes oxmysql, quita las líneas server_scripts del fxmanifest.lua.
No necesita ningún framework: cierra con eventos configurables y funciona con QBCore, ESX o scripts propios.

Instalacion

Copia la carpeta ov_loading en tu carpeta resources.
Añade ensure ov_loading en el server.cfg, antes de los recursos pesados para que sea lo primero que se vea.
Revisa config.lua y, si tu servidor usa otro selector de personaje o un script de spawn propio, añade su evento en Config.EventosDeCierre (ver más abajo).
Edita web/config.json con tu logo, tu video, tu música y tus textos.
Reinicia el servidor. Para cambios posteriores en config.json basta con restart ov_loading.

El recurso viene protegido con Asset Escrow de Cfx.re: se descarga desde tu Portal con la cuenta Cfx del comprador y solo funciona en servidores del comprador. Los archivos de configuración (config.lua) y todo lo de la carpeta web/ (interfaz, config.json, logo, video, música) no van cifrados, para que puedas editarlos. Solo el código Lua de client.lua y server.lua va cifrado.

Configuracion

`config.lua`

Clave	Valor por defecto	Para que sirve
`Config.TopeSegundos`	`240`	Segundos máximos que la pantalla puede quedarse abierta si ningún evento la cierra antes.
`Config.NombreServidor`	`''`	Nombre que se muestra. Si está vacío se usa la convar `sv_projectName`.
`Config.EventosDeCierre`	lista de 5 eventos	Eventos de cliente que cierran la pantalla; el primero que llegue la cierra.
`Config.AjustesDelJugador.activo`	`true`	Lee el color y la música guardados por el jugador. Ponlo en `false` si tu selector no los guarda.
`Config.AjustesDelJugador.tabla`	`'santabria_multichar_settings'`	Tabla donde se guardan los ajustes del jugador.
`Config.AjustesDelJugador.columnaLicencia`	`'identifier'`	Columna con la licencia del jugador.
`Config.AjustesDelJugador.columnaAjustes`	`'settings'`	Columna con un JSON `{ "theme": "...", "mutedMusic": true }`.

Eventos de cierre por defecto: ov_loading:client:cerrar, qs-loadingscreen:client:shutdown, QBCore:Client:OnPlayerLoaded, esx:playerLoaded y playerSpawned.

`web/config.json`

Clave	Que cambia
`colorPrincipal`	Color de acento en formato `#RRGGBB` (barra, cifras, líneas, botones).
`textos.titulo`	Título de la pestaña del navegador interno.
`textos.etiquetaSuperior`	Texto de la etiqueta de la esquina superior izquierda ("Early Access"). Vacío la oculta.
`textos.etiqueta`	Texto sobre el consejo ("ENTRANDO A LA CIUDAD").
`textos.sonando`, `textos.video`, `textos.activarSonido`	Rótulos de la consola de medios y del botón de activar sonido.
`textos.cargando`, `textos.iniciando`, `textos.preparando`	Textos de la barra de progreso.
`textos.cargaCompleta`, `textos.bienvenido`	Textos finales cuando llega al 100%.
`textos.enlaces`	Nombre de los tres botones: `discord`, `guias`, `tienda`.
`enlaces`	Dirección de cada botón. Un enlace vacío oculta ese botón.
`logo.hero`	Imagen grande del logo (ruta dentro de `web/`, por ejemplo `media/mi_logo.png`).
`logo.monograma`	Logo pequeño de la barra de progreso.
`logo.alt`	Texto alternativo del logo.
`logo.mostrarHero`	`false` oculta el logo grande.
`video.fichero`	Video de fondo (mp4 o webm). `video.activo: false` lo desactiva y deja un fondo de respaldo.
`musica.volumenPorDefecto`	Volumen inicial de 0 a 1.
`musica.pistas`	Lista de canciones: `titulo`, `fuente` (autor o etiqueta) y `fichero`.
`consejos`	Lista de frases que rotan abajo a la izquierda; la primera se ve al abrir.
`normas`	Lista de frases que recorren la cinta inferior.

Comandos y permisos

No tiene comandos ni permisos de administrador. Ofrece:

Export de cliente Cerrar(motivo): exports.ov_loading:Cerrar('mi selector') cierra la pantalla. Es seguro llamarlo varias veces.
Evento de cliente ov_loading:client:cerrar: hace lo mismo desde cualquier script con TriggerEvent.

Como se usa

El jugador entra y ve la pantalla con el video, el logo, el contador y el primer consejo.
Abajo a la derecha puede subir o bajar el volumen, silenciar la música y pausar o apagar el video. Sus elecciones se recuerdan.
Si el navegador del juego bloquea el sonido al arrancar, aparece el botón Activar sonido.
Al llegar al 100% la barra dice el texto de textos.cargaCompleta y la etiqueta cambia a textos.bienvenido.
La pantalla se cierra sola cuando llega un evento de cierre, y como último recurso al pasar Config.TopeSegundos.

Para administradores

Cambiar el logo, el video o la canción: copia tus archivos a web/media/, apunta a ellos en web/config.json y haz restart ov_loading. Usa mp3, ogg o wav para audio y mp4 o webm para video; evita archivos muy pesados porque se descargan en cada conexión.
Hacer que el cierre coincida con tu selector de personaje: busca el evento que tu script lanza justo cuando aparece el selector y añádelo a Config.EventosDeCierre, o llama al export Cerrar.
Si la pantalla se cierra por tiempo: en la consola del cliente (F8) aparece se cerro por tiempo. Significa que ningún evento de cierre llegó: revisa Config.EventosDeCierre.
Sin selector con ajustes por jugador: pon Config.AjustesDelJugador.activo = false.
Ver errores: la consola del cliente muestra líneas con el prefijo [ov_loading].

Preguntas frecuentes

¿Funciona con ESX? Sí. Al no depender de ningún framework, solo necesita que se lance un evento de cierre; esx:playerLoaded ya viene en la lista.

¿Necesita base de datos? Solo para la función opcional del color y la música por jugador. Si la tabla no existe, el recurso lo avisa en la consola y usa siempre el tema del config.json.

¿Puedo poner varias canciones? Sí, en musica.pistas. Suenan en orden y vuelven a empezar al terminar la última.

El video se ve entrecortado o tarda en cargar. Usa un video más ligero (menos de unos 8 MB suele ir bien) o desactívalo con video.activo: false.

¿Cómo cambio los consejos y las normas? Edita las listas consejos y normas de web/config.json y reinicia el recurso.

¿Por qué no se cierra al terminar de cargar? Con loadscreen_manual_shutdown la pantalla solo se cierra con los eventos de Config.EventosDeCierre, el export Cerrar o el tope de tiempo.

Actualizaciones y soporte

Las versiones nuevas aparecen en tu Portal de Cfx.re y en la tienda. Antes de actualizar, guarda una copia de tu web/config.json, de tu carpeta web/media/ y de config.lua. Soporte: [enlace de soporte].