Documentación de Whitelist con recepción y Discord

Whitelist con recepción y Discord

Que hace

ov_whitelist decide quién entra a tu ciudad. Quien no está aprobado no ve el mundo ni crea personaje: entra a una recepción en su propia dimensión, donde una cámara recorre tu ciudad mientras lee una guía y hace un examen. Al mismo tiempo, un módulo para tu bot de Discord abre un canal privado y una llamada de entrevista, recoge sus datos y le da al staff botones para decidir.

Cualquiera puede conectarse para que la ciudad vaya cargando, pero la salida de la recepción y la creación de personaje quedan cerradas hasta que lo aprueben.
Examen difícil de copiar: el servidor sortea las preguntas del banco, mezcla las opciones y corrige; el cliente nunca recibe la respuesta correcta.
Todo editable dentro del juego: preguntas, guía, ajustes, escenas y la conexión con Discord.
Marca tuya: nombre, color y logos se cambian en la configuración.

Requisitos

FiveM con QBCore. La puerta que cierra el selector de personajes es una opción de qb-core (Config.LoginGate); con tu core debes activarla (ver instalación).
oxmysql.
Para la parte de Discord: un bot con discord.js 14 y permisos de Gestionar canales y Gestionar roles. Se entrega el módulo ov-whitelist.js, que se enchufa al bot con dos líneas.
El servidor de Discord debe tener activada la función Comunidad para usar las reglas de pantalla («Acepta las normas»).

Instalacion

Copia ov_whitelist a resources y añade al server.cfg, antes de qb-core:

   ensure ov_whitelist
   add_ace group.admin ov_whitelist.admin allow
   add_ace group.admin ov_whitelist.bypass allow
   set ov_whitelist_http_key "UNA_CLAVE_LARGA_Y_ALEATORIA"

En qb-core, config_multichar.lua: Config.LoginGate = { Enabled = true, Resource = 'ov_whitelist' }.
Reinicia el servidor una vez. Las tablas se crean solas.
Con /escena coloca los planos del recorrido en tus lugares. Con /wladmin revisa la guía y las preguntas: vienen de ejemplo y debes adaptarlas a tu reglamento.
Discord: copia ov-whitelist.js a tu bot, añade las variables al .env y las dos líneas de uso del LEEME del módulo.

El recurso viene protegido con Asset Escrow de Cfx.re. La configuración (shared/config.lua) y la interfaz (web/) no van cifradas.

Configuracion

Servidor de juego (`shared/config.lua`)

Clave	Para que sirve
`Config.Brand`	`Name`, color `Accent` e imágenes de `web/img` (logo, sellos, esquina).
`Config.Recepcion`	Segundos antes de cerrar la conexión tras enviar la solicitud, tras un rechazo y por inactividad.
`Config.RetryHours`	Horas de espera tras un rechazo (24).
`Config.Recordatorio`	`DespuesMin` y `CadaMin` del aviso al staff conectado (30 y 10).
`Config.Exam`	Valores iniciales del examen: 20 preguntas, 85 %, 2 intentos, 24 h, 45 s de lectura. Después se cambian en `/wladmin`.

Bot de Discord (variables del módulo)

Variable	Para que sirve
`OVWL_API_KEY`	La misma clave que `ov_whitelist_http_key`.
`OVWL_STAFF_ROLE_IDS`	Rol de los entrevistadores. Ven el email: no uses un rol amplio.
`OVWL_STAFF_CHANNEL_ID`	Canal privado donde llegan las solicitudes.
`OVWL_WHITELISTED_ROLE_ID`	Rol que se da al aprobar.
`OVWL_MIN_ACCOUNT_DAYS`	Edad mínima de la cuenta de Discord (180; 0 lo desactiva). El staff puede dar excepciones con un botón.
`OVWL_REMINDER_AFTER_MINUTES` / `OVWL_REMINDER_EVERY_MINUTES`	Cuándo y cada cuánto se recuerda una solicitud sin atender.
`OVWL_PREGUNTAS_JSON`	Tus propias preguntas de desarrollo sobre tu ciudad (hasta 5).

Comandos y permisos

Permiso ov_whitelist.admin para el staff; ov_whitelist.bypass entra sin pasar por la whitelist.

Comando	Para que sirve
`/wl lista`	Solicitudes pendientes y cuánto llevan esperando.
`/wl info <id>`	Estado y concepto de un jugador.
`/wl aprobar <id>` / `rechazar <id> <motivo>` / `reiniciar <id>`	Decidir desde el juego.
`/wladmin`	Panel: preguntas, guía, ajustes, importar y exportar, conexión con Discord.
`/escena`	Cámara libre: `Enter` guarda el plano, `Tab` lista y prueba, `Retroceso` sale.
`/recorrido punto <clave> ...`	Guarda un plano donde estás mirando.

Cómo funciona por dentro

El jugador acepta las normas en Discord y el bot crea su canal privado y su llamada.
Rellena el formulario y responde las preguntas de desarrollo; el bot avisa al juego (POST /solicitud) y publica el panel del staff.
Se conecta: el juego une su Discord vinculado con la solicitud y le muestra el estado.
El entrevistador decide con un botón (POST /decision). Al aprobar, la recepción se abre sola y el bot da el rol.

El email solo se guarda en la tabla ov_whitelist_solicitudes y nunca se envía al jugador. La ruta HTTP exige una clave, limita el cuerpo y bloquea diez minutos a quien falle diez veces seguidas.

Probado

Se probó con simulación: servidor, examen, solicitudes, cliente, editor de escenas y módulo del bot (más de 480 pruebas automáticas).

Aviso importante

El examen y la guía que vienen incluidos son de ejemplo. Hay que adaptarlos al reglamento de tu servidor desde /wladmin antes de abrir.