> For the complete documentation index, see [llms.txt](https://docs.realcity.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realcity.dev/script-docs/rc-pvpsystem/instalacion.md). # Instalación *** ### 1. Requisitos previos Antes de empezar, asegúrate de tener instalados en tu servidor: | Dependencia | Obligatoria | Notas | | ----------------------------------------------------------------- | ----------- | ----------------------------------------------------------- | | [**ox\_lib**](https://github.com/overextended/ox_lib) | ✅ Sí | Librería de utilidades (notificaciones, callbacks, etc.) | | [**oxmysql**](https://github.com/overextended/oxmysql) | ✅ Sí | Driver MySQL para FiveM | | **Framework** (uno de estos) | ✅ Sí | **QBCore**, **QBox** o **ESX** — se detecta automáticamente | | [**ox\_inventory**](https://github.com/overextended/ox_inventory) | ❌ Opcional | Para gestión de inventario/loadouts avanzada | | **MySQL / MariaDB** | ✅ Sí | Base de datos del servidor | > **Nota:** El recurso detecta tu framework automáticamente (`Config.framework = 'auto'`). No necesitas configurar nada extra si usas QBCore, QBox o ESX. *** ### 2. Instalar el recurso 1. **Descarga** o clona el recurso. 2. **Copia la carpeta** `rc-pvpsystem` dentro de tu directorio `resources/`: ``` resources/ └── [tu-carpeta]/ └── rc-pvpsystem/ ├── fxmanifest.lua ├── config/ ├── client/ ├── server/ ├── web/ └── ... ``` 3. Comprueba que la estructura del recurso está completa (debe contener `fxmanifest.lua`, carpetas `client/`, `server/`, `config/`, `web/`, `sql/`, etc.). *** ### 3. Importar la base de datos El recurso crea las tablas automáticamente al iniciar por primera vez gracias al sistema de migraciones integrado. **No necesitas importar SQL manualmente.** Sin embargo, si prefieres importarlo a mano o si tienes problemas: 1. Abre tu herramienta de base de datos (HeidiSQL, phpMyAdmin, DBeaver, etc.). 2. Selecciona la base de datos de tu servidor FiveM. 3. Importa el archivo `sql/schema.sql`. #### Tablas que se crean Todas las tablas usan el prefijo `rcpvp_` para evitar conflictos con otros recursos. | Tabla | Descripción | | ----------------------------- | --------------------------------------- | | `rcpvp_meta` | Metadatos internos del recurso | | `rcpvp_users` | Jugadores registrados en el sistema PvP | | `rcpvp_friends` | Sistema de amigos | | `rcpvp_lobbies` | Lobbies/salas creadas | | `rcpvp_lobby_members` | Miembros de cada lobby | | `rcpvp_matches` | Historial de partidas | | `rcpvp_match_events` | Eventos durante partidas (kills, etc.) | | `rcpvp_redzone_deaths` | Muertes en la Redzone | | `rcpvp_redzone_stats` | Estadísticas de Redzone por jugador | | `rcpvp_ratings` | ELO/rating por jugador y modo | | `rcpvp_arena_stats` | Estadísticas de Arena por jugador | | `rcpvp_leaderboard_snapshots` | Snapshots de la tabla de clasificación | | `rcpvp_settings` | Ajustes por jugador | | `rcpvp_sanctions` | Bans y sanciones | *** ### 4. Configurar el server.cfg Añade las siguientes líneas a tu `server.cfg`. El **orden importa**: las dependencias deben arrancar antes que `rc-pvpsystem`. ```cfg # --- Dependencias (deben estar ANTES) --- ensure oxmysql ensure ox_lib # --- Tu framework --- ensure qb-core # o es_extended / qbox-core según tu caso # ensure ox_inventory # Solo si lo usas # --- El recurso PvP --- ensure rc-pvpsystem ``` > ⚠️ **Importante:** `rc-pvpsystem` debe ir **después** de `oxmysql`, `ox_lib` y tu framework en el `server.cfg`. *** ### 5. Configuración principal (config.lua) El archivo de configuración principal está en `config/config.lua`. A continuación se explican las secciones más importantes. #### 5.1 Framework e inventario ```lua Config.framework = 'auto' -- auto | esx | qbcore | standalone Config.inventoryAdapter = 'auto' -- auto | ox | qb | esx Config.notifications = 'auto' -- auto | nui ``` * **`auto`** es el valor recomendado. El recurso detecta qué tienes instalado. * Si por algún motivo la detección falla, ponlo manualmente (`'qbcore'`, `'esx'`, etc.). #### 5.2 Branding (personalización del nombre) ```lua Config.branding = { name = 'TuServidor', -- Nombre que aparece en la interfaz subtitle = 'PvP', -- Subtítulo fullName = 'TuServidorPVP', -- Para logs y notificaciones coinsName = 'Coins', -- Nombre de tu moneda primaryColor = 'FF3072FF', -- Color principal (hex ARGB) accentColor = 'FF00B3FF', -- Color de acento (hex ARGB) } ``` #### 5.3 Hub (punto central) El Hub es el lugar donde los jugadores acceden a la tablet/NUI y esperan partidas. ```lua Config.hub = { location = vector4(187.95, -952.99, 29.09, 331.80), -- Coordenadas del hub npc = { enabled = true, -- ¿Mostrar NPC interactivo? model = 's_m_m_bouncer_01', -- Modelo del NPC coords = vector4(187.95, -952.99, 29.09, 331.80), -- Posición del NPC scenario = 'WORLD_HUMAN_CLIPBOARD', -- Animación idle label = 'Abrir lobby', -- Texto de interacción icon = 'fa-solid fa-people-group' -- Icono } } ``` Cambia las coordenadas a la ubicación que quieras en tu servidor. #### 5.4 Tecla para abrir la NUI ```lua Config.nui = { openKey = 'F5', -- Tecla para abrir la tablet perfMode = true, -- Modo rendimiento language = 'es' -- Idioma de la interfaz (es / en) } ``` #### 5.5 Relleno con bots Si no tienes suficientes jugadores, el sistema puede rellenar partidas con bots IA: ```lua Config.botFill = { enabled = true, -- Activar/desactivar bots waitSeconds = 30, -- Segundos de espera antes de meter bots model = 's_m_y_blackops_01', weapon = 'WEAPON_CARBINERIFLE', accuracy = 80, -- Precisión (0-100) health = 220, armour = 120, modes = { arena = true, -- Bots en Arena deathmatch = true, -- Bots en Deathmatch escalation = true -- Bots en Escalation } } ``` #### 5.6 Modos de juego Activa o desactiva cada modo: ```lua Config.modes = { arena = true, -- 1v1, 2v2, etc. por rondas deathmatch = true, -- FFA Deathmatch escalation = true, -- Escalation (armas progresivas) custom = true -- Partidas personalizadas } ``` #### 5.7 Redzone (zona PvP libre) ```lua Config.redzone = { enabled = true, -- Activar la Redzone walls = { enabled = true, -- Paredes visuales en los bordes }, zones = { { id = 'airport', name = 'Aeropuerto', enabled = true, -- ... polígono, centro, blip, etc. }, -- Puedes añadir más zonas aquí }, death = { ... }, -- Config de muerte en redzone loot = { ... }, -- Config de looteo de cadáveres extraction = { ... }, -- Config de extracción (tecla G) } ``` #### 5.8 Munición ```lua Config.ammo = { infinite = false, -- true = munición infinita defaultAmount = 200, -- Munición al spawnear respawnRefill = true, -- Recargar al respawnear refillAmount = 200 -- Cantidad al respawnear } ``` #### 5.9 Admin Define qué grupos de permisos pueden usar comandos admin: ```lua Config.admin = { groups = { 'god', 'admin' } } ``` *** ### 6. Configuración de Discord (discord.lua) El archivo `server/config/discord.lua` permite integrar avatares y datos de Discord. ```lua local DiscordConfig = { enabled = true, -- Activar integración Discord required = true, -- ¿Obligar Discord vinculado para entrar? kickMessage = 'Debes tener Discord vinculado para entrar.', botToken = 'TU_BOT_TOKEN', -- Token de tu bot de Discord guildId = 'TU_GUILD_ID', -- ID de tu servidor de Discord useAvatars = true, -- Mostrar avatares de Discord en la UI webhookUrl = '' -- (Opcional) Webhook para logs } ``` #### Cómo obtener el bot token y guild ID 1. Ve a [Discord Developer Portal](https://discord.com/developers/applications). 2. Crea una aplicación (o selecciona una existente). 3. En la sección **Bot**, copia el **Token**. 4. Activa los **Privileged Gateway Intents** → **Server Members Intent**. 5. Invita el bot a tu servidor de Discord con el scope `bot` y permiso `View Members`. 6. Para obtener el **Guild ID**: activa el modo desarrollador en Discord (Ajustes → Avanzado), haz clic derecho en tu servidor → "Copiar ID del servidor". > Si no quieres usar Discord, simplemente pon `enabled = false`. *** ### 7. Sistema de muerte — Compatibilidad con ambulancejob El recurso incluye su propio sistema de muerte/downed. **Si ya usas `qb-ambulancejob`, `esx_ambulancejob` u otro sistema de muerte, debes desactivarlo.** En `config/config.lua`: ```lua Config.death = { enabled = false, -- ← false = el framework/ambulancejob maneja la muerte global } ``` | `enabled` | Comportamiento | | --------- | ---------------------------------------------------------------------------------------------------------------------- | | `true` | RC-PVP gestiona toda la muerte (mundo, redzone, partidas) | | `false` | RC-PVP solo gestiona la muerte **dentro** de partidas y redzone. Fuera de estos contextos, tu ambulancejob se encarga. | > **Recomendación:** Si tienes `qb-ambulancejob` o similar, usa `enabled = false`. *** ### 8. Configurar mapas y zonas Los mapas de partida se definen en `config/maps.lua`. El recurso viene con mapas preconfigurados: | Mapa | Modo | Descripción | | -------------------------------- | ---------- | ----------------------------- | | `arena_training` | Arena | Hangar de entrenamiento (2v2) | | `docks_dm` | Deathmatch | Terminal portuario | | *(y más según la configuración)* | | | Para añadir un mapa nuevo, sigue la estructura existente: ```lua mi_mapa = { id = 'mi_mapa', label = 'Mi Mapa Personalizado', mode = 'deathmatch', -- arena | deathmatch | escalation teams = 1, -- 1 para FFA, 2+ para equipos teamSize = 8, capacity = 12, minPlayers = 2, spawns = { free = { -- Para FFA vector4(x, y, z, heading), vector4(x, y, z, heading), -- ... } }, rules = { scoreLimit = 30, timeLimit = 600, loadout = { { weapon = 'WEAPON_CARBINERIFLE', ammo = 200 }, } } } ``` *** ### 9. Frontend (NUI) La interfaz web ya viene **pre-compilada** en `web/build/`. **No necesitas hacer nada** para que funcione. #### Solo si quieres modificar la interfaz: El frontend usa **SvelteKit + Vite**. Necesitarás [Node.js LTS](https://nodejs.org/) instalado. ```bash cd web/ npm install npm run dev # Desarrollo local en navegador npm run build # Compilar para FiveM (genera web/build/) ``` Tras hacer `npm run build`, reinicia el recurso en el servidor para que los cambios se apliquen. *** ### 10. Primer arranque y verificación 1. **Arranca tu servidor** de FiveM. 2. **Comprueba la consola** del servidor. Deberías ver mensajes del recurso creando las tablas de la base de datos. Si ves errores de conexión MySQL, revisa tu `server.cfg` (connection string de `oxmysql`). 3. **Entra al servidor** con un personaje. 4. **Ve al Hub** — dirígete a las coordenadas configuradas en `Config.hub.location` y verifica que: * El NPC aparece (si `npc.enabled = true`). * Al interactuar o pulsar la tecla (`F5` por defecto), se abre la tablet/NUI. 5. **Prueba la Redzone** — entra en una de las zonas configuradas (aeropuerto, Grove Street, etc.) y comprueba que: * Aparece la notificación de entrada. * Las paredes de zona se muestran. * El PvP funciona correctamente. 6. **Crea una partida** — desde la tablet, crea una partida de Deathmatch o Arena y verifica que el matchmaking y los spawns funcionan. #### Comandos útiles para admin Desde la consola del servidor o el chat (si eres admin): | Comando | Descripción | | ---------------------- | ---------------------------- | | `ensure rc-pvpsystem` | Iniciar/reiniciar el recurso | | `restart rc-pvpsystem` | Reiniciar el recurso | *** ### 11. Solución de problemas #### "No supported framework detected" * Comprueba que tu framework (`qb-core`, `es_extended` o `qbox-core`) arranca **antes** que `rc-pvpsystem` en el `server.cfg`. #### Las tablas no se crean en la base de datos * Verifica que `oxmysql` está correctamente configurado y arrancado. * Revisa que la cadena de conexión en tu `server.cfg` es correcta: ```cfg set mysql_connection_string "mysql://user:password@localhost/tu_base_de_datos?charset=utf8mb4" ``` * Prueba importar `sql/schema.sql` manualmente. #### La NUI no se abre / se ve en blanco * Comprueba que la carpeta `web/build/` contiene archivos (`index.html`, carpeta `_app/`, etc.). * Si falta contenido, recompila: ```bash cd web/ npm install npm run build ``` #### Error con ox\_lib * Asegúrate de tener la última versión de `ox_lib`. * Debe arrancar antes que `rc-pvpsystem` en el `server.cfg`. #### Los bots no aparecen * Verifica que `Config.botFill.enabled = true`. * Los bots solo se activan tras esperar `Config.botFill.waitSeconds` segundos si no hay suficientes jugadores. #### Discord: "Debes tener Discord vinculado" * Si no quieres obligar Discord, pon `DiscordConfig.required = false` en `server/config/discord.lua`. * Si quieres desactivar completamente Discord, pon `DiscordConfig.enabled = false`. #### La muerte no funciona correctamente fuera de partidas * Si usas `qb-ambulancejob` o similar, asegúrate de que `Config.death.enabled = false`. * Si **no** usas ambulancejob, ponlo a `true` para que RC-PVP gestione la muerte global. *** ### Resumen rápido (checklist) * [ ] `oxmysql` y `ox_lib` instalados y arrancados * [ ] Framework (QBCore / ESX / QBox) arrancado antes del recurso * [ ] Recurso copiado en `resources/` * [ ] `ensure rc-pvpsystem` en `server.cfg` (después de las dependencias) * [ ] `config/config.lua` ajustado (hub, branding, modos, redzone) * [ ] `server/config/discord.lua` configurado (o Discord desactivado) * [ ] `Config.death.enabled` ajustado según tu sistema de muerte * [ ] Servidor arrancado y tablas creadas correctamente * [ ] NUI funcional (carpeta `web/build/` presente) *** *rc-pvpsystem v1.0.1 — xByMarcos · RealCity Developments*