Manual de Instrucciones y Guía de Uso — ZerØ Target

Versión: 1.0.0 | Autor: ZerØ Network (Core Overextended) | Frameworks: QBCore, Qbox, ESX Legacy, OX Core, Standalone
Rendimiento: 0.00 ms (CPU en reposo) / 0.01 ms (Escaneo continuo) | Compatibilidad: Híbrida Universal (ox_target, qb-target, qtarget)

Índice

1. Descripción General
2. Requisitos del Sistema
3. Instalación Paso a Paso
4. Configuración General (shared/config.lua)
5. Guía de Uso para el Jugador
   • Modo Tecla (Clásico)
   • Modo Continuo (Innovador)
   • Menú de Personalización (/targetmenu)
   • Controles de Interacción (Rueda y Tecla E)
6. Compatibilidad Universal de Scripts
7. Resolución de Problemas Frecuentes (FAQ)

1. Descripción General

ZerØ Target es una solución integral y de alto rendimiento que fusiona la robustez de ox_target con la total compatibilidad retroactiva de qb-target y qtarget.

A diferencia de otros sistemas de interacción:

• Compatibilidad 100% Nativa: Asume y responde de forma transparente a cualquier llamada de exportación o evento dirigida a ox_target, qb-target o qtarget. No requiere renombrar ni modificar scripts de terceros.
• Rendimiento Ultraligero: Optimizado a fondo para mantener 0.00 ms en reposo y un consumo máximo de 0.01 ms durante escaneo activo mediante throttling inteligente de raycast.
• Doble Modo de Operación: Permite alternar libremente entre el modo clásico de mantener presionada una tecla (ALT) y el modo continuo moderno (siempre activo al centrar la vista).
• Personalización en Tiempo Real: Interfaz NUI interactiva accesible mediante el comando /targetmenu donde cada jugador puede cambiar colores, formas (diamante, círculo, cuadrado), tipografías y modos de control, guardando sus preferencias de forma persistente en KVP local.
• Faros 3D de Proximidad Opcionales: Proyector DirectX con textura aislada para marcar puntos de interacción cercanos sin colisionar con otros recursos.

2. Requisitos del Sistema

• FXServer: Versión recomendada 7290 o superior (mínimo Cerulean / OneSync activado).
• Dependencias Obligatorias:
  • ox_lib (necesario para cálculos matemáticos de zonas y locales).
• Frameworks Soportados:
  • QBCore (Detección automática de trabajos, bandas y citizenid).
  • Qbox (qbx_core, soporte nativo de grupos, trabajos, bandas y citizenid).
  • ESX Legacy (Detección automática de trabajos primarios/secundarios).
  • OX Core (Compatibilidad completa).
  • Standalone (Funciona sin framework mediante entidades y coordenadas nativas de GTA V).
• Inventarios Soportados:
  • ox_inventory (Búsqueda reactiva instantánea mediante export Search('count') y evento itemCount).
  • qb-inventory (Sincronización en tiempo real por evento OnPlayerUpdated y export nativo HasItem).
  • Inventarios clásicos de ESX y QBCore (Caché universal automática PlayerData.items y PlayerData.inventory).

3. Instalación Paso a Paso

Paso 1: Ubicación del recurso

Coloca la carpeta zero_target dentro de tu directorio de recursos (por ejemplo, en resources/[zero]/zero_target).

Paso 2: Retirar recursos sustituidos

Dado que zero_target incluye las directivas provide 'ox_target', provide 'qb-target' y provide 'qtarget':

1. Detén y elimina (o deshabilita) cualquier versión previa de qb-target, ox_target o qtarget para evitar colisiones de nombres o puertos en el servidor.
2. No necesitas editar tus scripts de trabajos, tiendas o vehículos: seguirán llamando a sus exports habituales y zero_target los procesará automáticamente.

Paso 3: Configurar en server.cfg

Asegúrate de iniciar ox_lib antes de zero_target:

ensure ox_lib
ensure zero_target

4. Configuración General (shared/config.lua)

El archivo shared/config.lua permite ajustar el comportamiento por defecto del servidor:

Config = {}

-- Detección de Framework ('auto', 'qbcore', 'esx', 'ox', 'standalone')
Config.Framework = "auto"

-- Controles iniciales por defecto
Config.Control = {
    useKey = true,        -- true = Inicia en modo tecla (ALT), false = Inicia en modo continuo
    key = 'LMENU',        -- Tecla por defecto (ALT Izquierdo). El jugador puede reasignarla en FiveM
    toggle = false        -- false = Mantener pulsado para abrir el ojo, true = Alternar con un toque
}

-- ==========================================
-- 🕹️ MODO DE INTERACCIÓN / SELECCIÓN
-- ==========================================
-- Define cómo interactúa el jugador con las opciones del target:
-- "hold"  = Mantener presionada la tecla 'E' hasta completar el círculo de progreso (800ms)
-- "press" = Al tacto: una sola pulsación de 'E' activa la opción de inmediato sin esperas
-- "click" = Clic de ratón: muestra el icono de la mano con dedo índice y se confirma con clic izquierdo
Config.InteractionType = 'hold'

-- Comando de Configuración in-game (editable por programadores)
Config.SettingsCommand = 'targetmenu' -- Abre el menú (/targetmenu)

-- Distancias de Interacción y Proximidad
Config.Interactions = {
    drawDistance = 7.0,      -- Distancia máxima para dibujar las opciones del objetivo
    interactDistance = 2.0,  -- Distancia máxima de interacción
    proximityDistance = 7.0  -- Rango de detección para los faros 3D de proximidad
}

-- 👁️ FAROS 3D DE PROXIMIDAD (Sprites en el mundo)
Config.Visual = {
    drawSprite = true,        -- true = Proyectar faro 3D sobre entidades cercanas, false = Desactivado (0.00ms)
    sprite = 'pin.png',       -- 'pin.png' (Esfera blanca luminosa) o 'pin2.png' (Rombo Chevron)
    size = { width = 0.009, height = 0.016 }, -- Tamaño compacto calibrado para relación 16:9
    color = { r = 255, g = 255, b = 255, a = 215 }, -- Color y opacidad del sprite
    pulse = true              -- Animación sutil de respiración/pulso para destacar el objetivo
}

-- Personalización de la Interfaz Web (NUI)
Config.UI = {
    MainColor = '#ffffff',   -- Color hexadecimal por defecto
    Shape = 'diamond',       -- Forma geométrica: 'diamond', 'circle', 'square'
    Font = 'Outfit'          -- Tipografía por defecto ('Outfit', 'Roboto', 'Montserrat', etc.)
}

5. Guía de Uso para el Jugador

Modo Tecla (Clásico)

• Mantén presionada la tecla ALT Izquierdo (o la asignada en Config.Control.key).
• Apunta con la retícula o cursor hacia el vehículo, peatón, objeto o zona de interacción.
• Cuando haya opciones disponibles, el objetivo se expandirá mostrando el listado de acciones.
• Suelta la tecla para cerrar el target inmediatamente.

Modo Continuo (Innovador)

• En este modo no necesitas mantener pulsada ninguna tecla.
• El indicador central permanece discretamente en la pantalla.
• Al mirar directamente a una entidad interactuable dentro del rango de distancia, las opciones emergen de inmediato.
• Diseñado para máxima inmersión y comodidad en servidores de rol activo.

Menú de Personalización (/targetmenu)

Cualquier jugador puede ejecutar en el chat o consola:

/targetmenu

Se desplegará la interfaz modal interactiva basada en el ZerØ Network Design System (con la misma estética premium que zero_rent):

1. Modo de Escaneo: Alternar entre Pulsar (ALT) (mantener pulsado ALT para escanear) o Continuo (automático al mirar entidades).
2. Color de Acento: Paleta rápida de tonos ZerØ (Crimson, Azul, Esmeralda, Ámbar, Púrpura) o selector libre HEX.
3. Tipografía: Cambio en vivo entre fuentes optimizadas (Outfit, Roboto, Montserrat).
4. Forma del Indicador: Alternar entre Rombo estilizado, Círculo minimalista o Cuadrado táctico.
5. Previsualización en Vivo: Un panel dinámico en tiempo real que simula el ojo con su onda de radar y las opciones del menú.

[!NOTE] El método de confirmación (hold, press o click) es administrado centralmente por los desarrolladores en config.lua (Config.InteractionType) para mantener la coherencia del servidor. Los jugadores pueden consultar el modo activo directamente en el distintivo informativo del menú. Todas las preferencias personales del jugador (modo de escaneo, color, forma y tipografía) se guardan automáticamente en la memoria del cliente (KVP) y persistirán tras reiniciar el juego o salir del servidor.

Controles de Interacción (Según la configuración del servidor)

• Navegación: Utiliza la rueda del ratón (Scroll Arriba / Abajo) para desplazarte por la lista de opciones.
• Confirmación según Config.InteractionType:
  • Modo Mantener ('hold'): Mantén pulsada la tecla E (barra circular de progreso de 800ms) para ejecutar la acción.
  • Modo Al Tacto ('press'): Pulsa la tecla E una sola vez para activar la opción al instante sin retardo.
  • Modo Clic ('click'): El indicador muestra una mano con el dedo índice y puedes activar la acción directamente haciendo Clic Izquierdo con el ratón (o tecla E).

6. Compatibilidad Universal de Scripts

zero_target está diseñado para sustituir sin fricción tanto a servidores basados en QBCore como en Qbox o ESX:

7. Resolución de Problemas Frecuentes (FAQ)

1. ¿Cómo cambio la tecla asignada si prefiero otra diferente a ALT?

Cada jugador puede cambiar la asignación sin tocar código abriendo el menú del juego: Pausa (ESC) > Ajustes > Asignación de Teclas > FiveM > Interactuar con el Ojo (Target).

2. ¿Por qué un script de trabajo de QBCore no muestra las opciones?

Asegúrate de que el trabajo del jugador coincida exactamente con el configurado en la opción (job). Si el script requiere un grado mínimo, zero_target verificará automáticamente que el grado del jugador sea igual o superior al exigido.

3. ¿El recurso consume recursos mientras estoy conduciendo o lejos de zonas?

No. El consumo en reposo es de 0.00 ms. El raycast utiliza un temporizador de reposo adaptativo (de 60 ms a 200 ms) cuando no hay entidades interactuables en pantalla, activando el renderizado a 0 ms únicamente cuando el jugador apunta a un objetivo real con opciones disponibles.

4. ¿Puedo activar los faros de proximidad 3D?

Sí. En shared/config.lua, cambia Config.Visual.drawSprite = true. Los faros marcarán con un pin 3D los objetos y peatones cercanos interactuables. Si prefieres máxima pureza visual o minimizar llamadas de renderizado, mantenlo en false.