Documentación de Estudio de libreas 3D

OV Librea

Estudio de libreas dentro del juego: pinta la textura real de un vehículo viendo su modelo en 3D y exporta un recurso listo para ensure, con soporte para libreas animadas.

Que hace

OV Librea es una herramienta para administradores y creadores de contenido. Con /librea se abre un estudio a pantalla completa con:

Visor 3D del vehículo (arrastrar para girar, rueda para acercar).
Lienzo de textura con capas, pincel, relleno, texto, formas e imágenes (también desde un enlace).
Vista de partes (UV) que dibuja las piezas del modelo sobre la textura.
Libreas animadas por código: 26 efectos incluidos (flow, plasma, neon, fire, hue, aurora, lava, smoke, ripple, caustics, holo, checker, speed, chevron, bubbles, network, rain, waves, lightning, stars, radar, hex, glitch, siren, embers, circuit). Se exportan con un client.lua que reemplaza la textura en vivo mediante un navegador interno (DUI), solo cuando hay un vehículo de ese modelo cerca.
Proyectos: guardar con Ctrl+S crea un proyecto en la carpeta proyectos/.
Exportación: genera un recurso ov_librea_<nombre> con stream/<modelo>.ytd en formato Legacy.
Catálogo (con el servicio satélite activo): lista los vehículos de tu servidor con un sello de compatibilidad, escanea cuando añades vehículos nuevos e importa los que elijas.

Importante antes de comprar o instalar: el estudio abre con solo copiar la carpeta, pero para exportar libreas e importar vehículos necesita una herramienta de conversión y un pequeño servicio "satélite" que se preparan aparte (ver "Requisitos" e "Instalación"). La guía completa de esta preparación está en el archivo LEEME.md incluido con el recurso.

Requisitos

Dependencias declaradas en el fxmanifest.lua: ninguna (no declara dependencies). Tampoco usa oxmysql ni base de datos, ni qb-core, ni ox_lib.

Para el funcionamiento completo (según el LEEME.md del recurso):

Requisito	Para qué
FiveM Legacy (Linux o Windows)	El estudio exporta texturas en formato Legacy.
Node.js 18 o superior	Ejecuta el servicio satélite.
SDK de .NET 8	Compila la herramienta de conversión `ovlibrea`.
`CodeWalker.Core.dll` (proyecto de terceros)	La herramienta lo usa para leer y escribir `.yft` y `.ytd`. No se incluye: lo obtienes y compilas tú, respetando su licencia.
PM2 o systemd	Mantiene el satélite encendido (recomendado).
Puerto 30170/TCP accesible	El estudio de cada administrador se conecta al satélite.

Lua 5.4 (lua54 'yes'). Sin la herramienta de conversión el estudio abre, pero avisa de que no encuentra la herramienta y no se puede exportar ni importar.

Instalacion

Descarga el recurso desde el Portal de Cfx.re con la cuenta Cfx con la que lo compraste. Viene protegido con Asset Escrow de Cfx.re y funciona solo en servidores de tu cuenta.
Copia la carpeta ov_librea en resources.
Prepara la herramienta de conversión y el satélite siguiendo el LEEME.md (secciones "Antes de empezar", "Instalación" y, si tu servidor es Windows, "Si tu servidor es Windows").
Añade en server.cfg:

   set ov_librea_token "el-token-de-tu-satelite"
   ensure ov_librea
   add_ace group.admin ov_librea.admin allow

El recurso lee la convar ov_librea_token con GetConvar. Debe coincidir con el token de la configuración del satélite. Reinicia el servidor después de ponerlo.

Revisa shared/config.lua: Config.Satelite.url (dirección del satélite), Config.Satelite.public (dirección que ven los administradores desde su juego), Config.ToolPath y Config.OutputDir. Los valores que trae por defecto son rutas y direcciones de ejemplo: cámbialos por los de tu servidor.
Abre /librea. Si ves el botón Catálogo, el satélite está bien conectado.

Base de datos: no usa. Los proyectos se guardan como archivos .json en la carpeta proyectos/ del recurso.

Protección y edición: según el fxmanifest.lua, quedan sin cifrar (escrow_ignore) shared/config.lua y la carpeta web/ (la interfaz). El resto del código está cifrado.

Configuracion

Todo se edita en shared/config.lua.

Clave	Valor por defecto	Para qué sirve
`Config.Command`	`'librea'`	Nombre del comando que abre el estudio.
`Config.AdminAce`	`'ov_librea.admin'`	Permiso ACE necesario para usarlo.
`Config.FreezePlayer`	`true`	Congela al jugador y oculta el mapa mientras el estudio está abierto.
`Config.ToolPath`	ruta de ejemplo	Ruta absoluta del ejecutable `ovlibrea` (herramienta de conversión). Cámbiala por la tuya.
`Config.Satelite.url`	`http://127.0.0.1:30170`	Dirección a la que el servidor FiveM habla con el satélite.
`Config.Satelite.public`	dirección de ejemplo	Dirección (idealmente HTTPS) por la que los administradores alcanzan el satélite. Ponla en la tuya.
`Config.OutputDir`	ruta de ejemplo	Carpeta donde se crean los recursos exportados. Si es `nil`, usa `exports/` dentro del recurso.
`Config.ExportTimeout`	`180`	Segundos de espera a que termine una exportación.
`Config.MaxProjectBytes`	40 MB	Tamaño máximo de un proyecto subido.
`Config.MaxImageBytes`	6 MB	Tamaño máximo de una imagen cargada por enlace.
`Config.Chunk` / `Config.MaxChunks` / `Config.Window`	`12000` / `3600` / `4`	Troceado y control de las subidas.
`Config.AnimPresets`	26 efectos	Efectos animados permitidos (deben existir en `web/anim.js`).
`Config.Text`	textos en español	Mensajes mostrados al usuario.

Comandos y permisos

Comando	Permiso	Qué hace
`/librea`	ACE `ov_librea.admin`	Abre el estudio. Si estás dentro de un vehículo (o junto a uno) ya importado, se abre con ese modelo.

El nombre del comando se puede cambiar en Config.Command. No registra teclas ni exports. Los eventos del recurso son internos del estudio; no están pensados para que otros scripts los llamen.

Concede el permiso con:

add_ace group.admin ov_librea.admin allow

Atajo dentro del estudio: Ctrl+S para guardar el proyecto.

Como se usa

Entra al servidor con el permiso ACE y escribe /librea.
Si el vehículo aún no está importado, pulsa Catálogo, Escanear ahora, marca los vehículos Aptos o Adaptables y pulsa Importar seleccionados. El estudio se reinicia solo para publicarlos; vuelve a abrir /librea.
Pinta sobre la textura: capas, pincel, relleno, texto, formas e imágenes. Usa "Ver partes (UV)" para ver dónde cae cada pieza.
Opcional: añade capas animadas con los efectos disponibles.
Guarda el proyecto (Ctrl+S) y pulsa Exportar.
El recurso exportado aparece en la carpeta de salida como ov_librea_<nombre>/. Añádelo al server.cfg después del recurso que trae el vehículo, y reinicia (o refresh + ensure).

Qué significa cada sello del catálogo

Sello	Significado
Apto	Tiene una textura propia de librea sobre la pintura de la carrocería.
Adaptable	El modelo tiene la ranura de librea pero está vacía o falta en el `.ytd`: se crea un lienzo nuevo de 2048 px. Experimental.
Experimental	Librea pequeña o texturas dentro del `.yft`: la calidad puede ser baja.
Pintura plana	No tiene textura de carrocería: no hay dónde pintar.
No compatible	Modelo Gen9/Enhanced o ilegible.

Las piezas sueltas (alerones, parachoques, props) se ignoran.

Para administradores

El estudio solo lo pueden abrir quienes tengan el ACE ov_librea.admin; dalo únicamente a quien lo vaya a usar.
El recurso no incluye vehículos de GTA V (los archivos pertenecen a Rockstar). El estudio edita los vehículos que tú tengas instalados. Para editar uno vainilla, extrae su .yft y .ytd de tu propia copia del juego, colócalos en un recurso de tu servidor y escanea.
Un nombre de proyecto o de exportación solo admite letras, números, _ y -, entre 2 y 32 caracteres.
Los recursos exportados deben cargarse después del recurso del vehículo original.
No pongas en el server.cfg un recurso exportado de un modelo que quieras conservar con su pintura original: reemplazará la librea de todos los vehículos de ese modelo. Para una librea de marca, usa un modelo aparte.
Texturas muy pesadas (4096 px) pueden causar problemas de memoria a los clientes.
Seguridad: el token del satélite (ov_librea_token) nunca debe publicarse ni ir en archivos que compartas.

Tabla de problemas frecuentes:

Síntoma	Causa y solución
No aparece el botón Catálogo	Falta `set ov_librea_token` en el `server.cfg` o el satélite no está corriendo. Reinicia tras poner el token.
"El estudio no alcanza el satélite desde tu juego"	El puerto 30170/TCP está cerrado o la dirección no es alcanzable: ábrelo o define `Config.Satelite.public`.
"La herramienta de conversión falló"	Vuelve a compilarla y comprueba que el satélite corre con el mismo usuario que FXServer.
La exportación no crea archivos	Permisos: el satélite y FXServer deben ser el mismo usuario del sistema.

Preguntas frecuentes

¿Funciona en servidores Enhanced? No. Exporta texturas en formato Legacy. Los vehículos Gen9/Enhanced se marcan como "No compatible".

¿Necesito base de datos? No. Los proyectos son archivos .json dentro del recurso.

¿Puedo editar vehículos de GTA V originales? Sí, extrayendo sus archivos de tu propia copia del juego y colocándolos en un recurso (ver "Para administradores").

¿Por qué no puedo exportar? Normalmente falta la herramienta de conversión o el satélite. Revisa la tabla de problemas y el LEEME.md.

¿Puedo usar el estudio sin el satélite? El estudio abre y puede trabajar con los vehículos ya importados, pero el catálogo y la importación necesitan el satélite, y la exportación necesita la herramienta de conversión.

¿Dónde veo los errores? En la consola del servidor y en F8; la interfaz envía sus pasos y errores a F8 con el prefijo [ov_librea][ui].

Actualizaciones y soporte

Las versiones nuevas aparecen en el Portal de Cfx.re y en la tienda. Conserva tu shared/config.lua y la carpeta proyectos/ al actualizar. Para soporte, usa el Discord de la tienda: [enlace de soporte].