Documentación de Control de NPC

Control de NPC (ov_npc_control)

Control de NPC desde el «ojito» (target) con una interfaz moderna: detener, arrodillar, seguir, robar, subir al coche, tomar de rehén y cargar, con frases graciosas sobre la cabeza del NPC.

Que hace

• Añade la opción Controlar al apuntar a un NPC con el ojito (y Controlar ocupante al apuntar a un vehículo con gente dentro). También puedes abrir el panel con el comando /npc, que elige el NPC controlable más cercano.
• El panel muestra el nombre del NPC, su estado y las acciones disponibles: Detente, Arrodillarse, Seguirme, Robar, Subir al coche (o Bajar del coche), Tomar de rehén (o Soltar), Cargar (o Soltar) y Dejar ir. Si el NPC va dentro de un coche y está libre, solo aparece Sacar del coche.
• Cada acción tiene un requisito (llevar un arma, haber sometido ya al NPC o ninguno). Si no se cumple, el botón se muestra apagado con el motivo escrito.
• El robo entrega dinero en efectivo y, con cierta probabilidad, objetos. El servidor valida distancia, enfriamientos y topes.
• Rehén entre jugadores: con un arma con balas puedes tomar de rehén a otro jugador que tenga las manos arriba. Es una opción distinta del ojito sobre jugadores («Tomar de rehén»); el servidor decide quién es captor y quién es rehén, y el captor puede soltarlo o ejecutarlo.
• Los NPC dicen frases al azar (con burbuja de texto). Opcionalmente se puede reproducir audio.
• Puedes controlar a varios NPC a la vez (por defecto 3 por jugador). Si el NPC se aleja demasiado, se libera solo.
• Interfaz y textos editables: colores del panel, idiomas (español e inglés incluidos) y frases.

Requisitos

En modo standalone no hay dinero ni inventario que entregar. Para ver cómo se comporta el robo en ese caso, consulta el archivo de configuración y los eventos descritos más abajo.

Instalacion

1. Copia la carpeta ov_npc_control dentro de la carpeta resources de tu servidor.
2. Añade ensure ov_npc_control en tu server.cfg, después de tu framework, tu inventario y tu recurso de target.
3. Abre config.lua y revisa, como mínimo, Config.Framework, Config.Target, Config.Idioma, Config.Comando y la sección Config.Robo.
4. Reinicia el servidor o ejecuta ensure ov_npc_control.

El recurso no lee convars propios; toda la configuración está en config.lua.

Protección. El recurso viene PROTEGIDO con Asset Escrow de Cfx.re. Se descarga desde el Portal de Cfx.re con la cuenta Cfx del comprador y solo funciona en servidores asociados a esa cuenta. config.lua, los idiomas (locales/) y la interfaz web (html/) quedan sin cifrar para que puedas editarlos. El código Lua (bridge, client y server) va cifrado.

Licencia. Licencia comercial de uso en un servidor (consulta LICENSE.txt).

Configuracion

Todas las opciones están en config.lua. Valores por defecto leídos del archivo:

General

Quién se puede controlar y límites

Requisitos por acción

Config.Requisitos acepta 'arma' (arma en la mano), 'sometido' (NPC ya sometido o arma en la mano) o 'ninguno'.

Config.PermitirArmaCuerpoACuerpo = false: cuchillos, bates y similares no cuentan como arma.

Animaciones y posición

Config.Anims (cambiables sin tocar el código): manosArriba, arrodillado, robarJugador, rehenAgresor, rehenVictima, cargarAgresor y cargarVictima, cada una con dict, clip y flag. Config.Pegado define la posición del NPC pegado a ti (rehén y cargar). Config.TeclaSoltar = 38 (E) y Config.TeclaSoltarAlt = 73 (X) sueltan al NPC.

Rehén entre jugadores (Config.Jugadores)

Seguir y subir al coche

Robo (botín, enfriamientos y topes)

Ajusta los nombres de objetos de Config.Robo.objetos a los que existan en tu inventario: el servidor solo entrega los que existen.

Voces

El recurso no incluye archivos de audio: debes alojar los tuyos con esa estructura de nombres.

Interfaz, registro y nombres

• Config.Tema: colores del panel (acento, acentoAlto, acentoBajo, fondo, fondo2, fondo3, texto, textoSuave), en formato hexadecimal.
• Config.Webhook = '': URL de Discord para registrar los robos (opcional).
• Config.Nombres: lista de nombres que se asignan a los NPC en el panel.

Comandos y permisos

Los comandos son para todos los jugadores; el recurso no define permisos ni ACE propios.

Eventos

• ov_npc_control:alertaPolicia (servidor): se dispara con (src, coords) cuando un robo activa el aviso. Engancha aquí tu despacho de policía:

AddEventHandler('ov_npc_control:alertaPolicia', function(src, coords)
    -- llama a tu sistema de despacho con coords
end)

• ov_npc_control:reproducirVoz (cliente): con Config.Voz.audio.activo = true y proveedor 'evento' recibe una tabla con url, pos, volumen, distancia, voz y accion para que tu audio 3D lo reproduzca.
• ov_npc_control:rehenTomado (servidor): se dispara con (captor, rehen) cuando empieza una retención entre jugadores.
• ov_npc_control:rehenTerminado (servidor): se dispara con (captor, rehen, modo) al terminar; modo es 'soltar', 'matar' o 'cancelar'. Útil para tus registros o para otros scripts.
• ov_npc_control:robar (servidor, interno): lo envía el cliente tras la animación; no lo uses desde otros scripts.

Exports de cliente

• exports.ov_npc_control:abrirPanel(ped): abre el panel para un NPC concreto.
• exports.ov_npc_control:estaControlado(ped): devuelve true si ese NPC está bajo control.

Textos e idiomas. Edita locales/es.lua o locales/en.lua (interfaz, mensajes y frases por acción en voces). Los textos del rehén entre jugadores están en msg: rehenTomar («Tomar de rehén»), rehenSinArma, rehenSinManos, rehenOcupado, rehenLejos, rehenTomado («¡TE TOMARON DE REHÉN!»), rehenLiberado («¡Te soltaron!»), rehenAyuda y rehenAyudaSolo (ayuda en pantalla, con las teclas E o Retroceso). Para añadir un idioma, copia uno de los archivos a locales/<codigo>.lua con Locales.<codigo> = { ... } y pon ese código en Config.Idioma.

Como se usa

1. Acércate a un NPC (menos de Config.TargetDistancia metros) y usa el ojito, o escribe /npc.
2. Elige la acción con el ratón o con las teclas 1 a 9. Las flechas mueven el foco y Esc cierra el panel.
3. Los botones apagados indican el motivo (por ejemplo «Necesitas un arma en la mano» o «Primero somete al NPC»).
4. Con Tomar de rehén o Cargar aparece el botón Soltar; también sueltas con E, Retroceso o /soltar. Mientras llevas a alguien se bloquean correr, saltar, disparar, apuntar y entrar a vehículos.

Rehén entre jugadores

1. Lleva un arma con balas en la mano (los cuchillos y armas cuerpo a cuerpo no cuentan).
2. Apunta con el ojito a otro jugador que tenga las manos arriba (a menos de distanciaTarget) y elige Tomar de rehén. La opción solo aparece si ya tienes arma, no estás ocupado y la víctima tiene las manos arriba.
3. El servidor comprueba que ninguno de los dos esté ya en una retención y que estén a menos de distanciaServidor. Si requiereManosArriba está activo, le pregunta a la propia víctima si tiene las manos arriba; tiene confirmacionSeg segundos para responder. Si no confirma o ya no está cerca, no pasa nada (y el captor recibe el aviso de manos arriba).
4. Cuando se confirma, el captor ve los botones Soltar (E, o Retroceso, o /soltar) y Ejecutar (Z, si permitirEjecutar está activo). El rehén queda pegado al captor con la animación de rehén y recibe el aviso «¡TE TOMARON DE REHÉN!». Mientras dura se bloquean varios controles de ambos (correr, saltar, disparar, apuntar...) y el rehén no puede moverse ni, si bloquearSalirVehiculo está activo, bajarse de un vehículo.
5. Soltar libera al rehén con un empujón y el aviso «¡Te soltaron!». Ejecutar mata al rehén.
6. La retención se cancela sola si el rehén muere o deja de estar disponible, si el captor muere (se suelta) o si cualquiera de los dos se desconecta. Un mismo jugador no puede estar en dos retenciones a la vez, ni tener a un NPC y a un jugador de rehén al mismo tiempo.
7. Subir al coche usa el vehículo en el que vas o el más cercano; Bajar del coche lo devuelve a pie. Dejar ir lo libera y huye.

Reglas por defecto

• Detente, Arrodillarse y Tomar de rehén exigen un arma en la mano.
• Seguirme, Robar, Subir al coche y Cargar exigen que el NPC ya esté sometido o que lleves un arma.
• Robar además exige que el NPC esté detenido o arrodillado.
• Sacar del coche exige arma.
• Tomar de rehén a un jugador exige arma con balas y que la víctima tenga las manos arriba (configurable).
• Si vas a controlar más NPC que el máximo permitido, el panel avisa del límite.

Para administradores

Validaciones del servidor en el robo. El servidor comprueba que el NPC exista y que el jugador esté a menos de distanciaMaxServidor; aplica el enfriamiento por jugador, el tope por hora y el enfriamiento por NPC; calcula el botín y entrega dinero y objetos. Estas comprobaciones corren en el servidor, no en el cliente.

Validaciones del servidor en el rehén entre jugadores. El servidor asigna los roles: comprueba que el objetivo sea un jugador válido y distinto del captor, que ninguno esté ya retenido o retenga a alguien, y la distancia (distanciaServidor). Con requiereManosArriba la confirmación la da la víctima, no el captor, y caduca a los confirmacionSeg segundos. Para aceptar tus animaciones de rendición como válidas, añádelas a Config.Jugadores.animsManosArriba. Usa los eventos rehenTomado y rehenTerminado para registros o integraciones. Para desactivar la función entera, pon Config.Jugadores.activo = false.

NPC no controlables. Jugadores, NPC muertos, no humanos, los tipos de Config.TiposProhibidos (policía, SWAT, animales y ejército por defecto) y los modelos de Config.ModelosProhibidos.

Conectar el despacho de policía. Escucha el evento de servidor ov_npc_control:alertaPolicia (ver ejemplo en «Comandos y permisos») y llama a tu recurso de despacho. La frecuencia se controla con Config.Robo.probAlertaPolicia.

Registro en Discord. Pon la URL en Config.Webhook. Si lo dejas vacío, no se registra nada.

Apariencia. Cambia los colores en Config.Tema para adaptar el panel a tu servidor.

Preguntas frecuentes

¿Funciona sin framework? Sí, en modo standalone arranca y el panel funciona. El dinero y los objetos dependen del framework y del inventario; consulta el archivo de configuración.

No me aparece «Controlar» al apuntar a un NPC. Comprueba que tu recurso de target esté iniciado antes que este, o fija Config.Target. Mientras tanto puedes usar /npc. Recuerda que policías, animales y los modelos prohibidos no se pueden controlar.

Todos los botones salen apagados. Es normal sin arma o sin haber sometido al NPC. El motivo aparece escrito en cada botón; los requisitos se cambian en Config.Requisitos.

No recibo objetos al robar. El servidor solo entrega objetos que existen en tu inventario. Revisa los nombres de Config.Robo.objetos.

No puedo tomar de rehén a otro jugador. Necesitas un arma con balas en la mano y que el jugador tenga las manos arriba con una de las animaciones de Config.Jugadores.animsManosArriba. Si tu servidor usa otra animación de rendición, añádela ahí.

¿Qué pasa si el captor o el rehén mueren o se desconectan? La retención termina sola y el rehén queda libre.

¿Puedo cambiar las frases o añadir un idioma? Sí, en locales/ (sin cifrar). Ver «Comandos y permisos».

¿Puedo usar mis propios audios? Sí: activa Config.Voz.audio, define base con la estructura <base>/<voz>/<accion>_<n>.mp3 o escucha el evento ov_npc_control:reproducirVoz.

Actualizaciones y soporte

Las actualizaciones se publican en el Portal de Cfx.re, desde donde puedes volver a descargar el recurso con tu cuenta. Antes de actualizar, guarda una copia de tu config.lua y de tus archivos de locales/ para conservar tus ajustes. Para soporte, dudas o sugerencias: [enlace de soporte].