Convierte un recurso de FiveM mapeando sus dependencias de framework, inventario y base de datos, luego prueba un flujo de juego a la vez. Renombrar eventos de ESX a eventos de QBCore no es una conversión completa. Una migración de personajes a nivel de servidor es un proyecto aparte.
Antes de cambiar el código
Trabaja en un servidor de desarrollo aislado con una copia del recurso y una base de datos desechable. Registra las versiones exactas del framework de origen y destino, el inventario, la biblioteca de targeting, la biblioteca de UI y la licencia del recurso. Los archivos protegidos requieren una versión compatible del autor; la configuración editable por sí sola puede no ser suficiente.
1. Inventaría los puntos de integración
Busca en los archivos de recursos ESX, QBCore, qbx_core, exports, RegisterNetEvent, MySQL y nombres de tablas SQL. Clasifica cada coincidencia como de servidor, cliente o compartida. Enumera las entradas esperadas, los valores de retorno y el comportamiento en caso de fallo antes de reemplazarlo.
Por ejemplo, un flujo de tienda incluye abrir su interfaz de usuario, verificar el acceso, leer precios, cobrar el pago, añadir inventario y guardar el resultado. Convertir solo su notificación deja el comportamiento importante sin cambios.
2. Mapea el comportamiento explícitamente
Resuelve el jugador del framework de destino en el servidor en el momento de la acción. Los identificadores de ESX y los IDs de personaje de QBCore/Qbox tienen significados diferentes; no generes IDs de personaje a partir de hashes truncados ni sobrescribas identificadores de cuenta. Mantén un mapeo revisado cuando los datos existentes deban moverse.
Elige la integración de inventario deliberadamente. Los nombres de los ítems, las unidades de peso, el manejo de ranuras, los metadatos y las comprobaciones de capacidad difieren. No recurras silenciosamente entre sistemas de inventario. Decide cómo se mapean el efectivo, los saldos bancarios y cualquier mecánica de moneda ilícita sin tratar cuentas no relacionadas como equivalentes.
3. Implementa un pequeño adaptador
Mantén las llamadas específicas del framework para el jugador, el trabajo, el dinero y el inventario en un módulo solo de servidor. Las notificaciones del cliente y las devoluciones de llamada de la interfaz de usuario pertenecen a un módulo de cliente separado. Declara las dependencias reales en fxmanifest.lua e inícialas antes del recurso.
Para Qbox, consulta las exportaciones del servidor y su guía de compatibilidad. Un puente de compatibilidad puede ayudar a los recursos QB existentes, pero no garantiza la compatibilidad con todos los inventarios, consultas de base de datos o núcleos modificados.
4. Preserva el límite de confianza
El servidor debe determinar los ítems permitidos, los precios, los saldos, los permisos de trabajo y la finalización de las tareas recompensadas. Trata cada argumento de evento del cliente como no confiable. Un nombre de trabajo por sí solo no prueba que se haya realizado una entrega; un evento repetido no debe pagar repetidamente. Verifica tanto los resultados del débito como de la entrega de ítems, y define una compensación cuando la segunda acción falla.
5. Convierte el almacenamiento propiedad del recurso
Compara el esquema de origen y destino instalado antes de escribir una migración. Utiliza un script separado y versionado para ese esquema exacto. Mantén los identificadores originales, las matrículas, los metadatos y una tabla de correspondencias persistente. Informa de las filas duplicadas o no mapeadas en lugar de ignorarlas. No modifiques los saldos propiedad del framework a través de SQL mientras el framework los tenga cargados en memoria.
6. Verifica y lanza
- Prueba un personaje nuevo y uno existente: inicio de sesión, la acción convertida, reconexión y reinicio del servidor. Verifica la persistencia después de cada uno.
- Prueba los permisos denegados, fondos insuficientes, inventario lleno, entrada inválida, solicitudes repetidas y desconexiones durante la operación. Confirma que no se crean dinero o ítems no deseados.
- Compara las filas de la base de datos y los saldos antes y después de las acciones de prueba conocidas. Investiga cada diferencia inesperada.
- Despliega los archivos revisados y cualquier migración requerida durante una ventana de mantenimiento. Mantén copias de seguridad de archivos/bases de datos coincidentes y un procedimiento de reversión que tenga en cuenta las escrituras realizadas después del lanzamiento.
Si la conversión falla
Una exportación ausente suele apuntar a un recurso/versión o un orden de inicio incorrectos. Una devolución de llamada que nunca regresa necesita una inspección tanto del registro como de la invocación, incluidos los argumentos y el lado de la ejecución. Los ítems que faltan pueden reflejar metadatos de inventario o reglas de capacidad. Diagnostica el límite que falla en lugar de añadir parches de compatibilidad amplios.
Documentación de referencia
Cfx.re — manifiesto de recursos · Cfx.re — seguridad del servidor