FiveM/Lua
WebSocket
Gemini Live

LSA NPC

Análisis en Tiempo Real

Dashboard completo de análisis estático para el proyecto Los Santos Alive — un mod de FiveM que habilita conversaciones por voz en tiempo real con NPCs impulsados por inteligencia artificial mediante Google Gemini Live.

0
Total de Archivos Analizados
Archivos fuente
0+
Líneas de Código
Lua + JS + HTML
0
Bugs Encontrados
3 críticos · 4 medios · 5 menores
0+
Acciones Soportadas
Acciones físicas del NPC
01
Arquitectura del Sistema

Flujo de Datos en Tiempo Real

El pipeline completo desde la captura de voz del jugador hasta la respuesta del NPC con audio 3D y acciones físicas.

Jugador FiveM
Cliente GTA V
Push-to-Talk (F9)
NUI / CEF Browser
HTML + JS + Web Audio
WebSocket
lsa-bridge
Node.js Server
Gemini Live API
Google Gemini Live
IA Multimodal
← Audio 24kHz + Transcripción + Acciones →
Micrófono 16kHz
Audio 3D HRTF
Subtítulos In-Game
45+ Acciones
02
Flujo de Audio

Pipeline de Audio en Tiempo Real

El flujo completo de datos de audio desde la captura del micrófono hasta la reproducción 3D espacial en el NPC.

Jugador →← NPC
01
Captura de Voz
F9 PTT · Micrófono
Audio crudo
02
PCM 16kHz
AudioWorklet
int16 PCM
03
Base64
Codificación
base64 string
04
WebSocket
lsa-bridge
JSON msg
05
Gemini Live
API Multimodal
Multimodal
06
Respuesta IA
Texto + Audio
Transcripción
07
Audio 24kHz
Respuesta PCM
24kHz PCM
08
Reproducción 3D
HRTF Espacial
3D HRTF
09
Subtítulos
In-game Text
Subtitles
INPUTOUTPUT
FiveM (Cliente)
Transporte
Servidor / IA
Respuesta
Sample Rate In
16 kHz
Captura
Sample Rate Out
24 kHz
Reproducción
Formato
int16 PCM
16-bit signed
Protocolo
WebSocket
Tiempo real
03
12 Problemas Encontrados

Auditoría Completa de Bugs

Cada vulnerabilidad documentada con severidad, ubicación exacta, descripción detallada y código de corrección propuesto.

3
Críticos
4
Medios
5
Menores
4
Archivos Afectados
100%
Fix Rate
25%
Riesgo Alto
Distribución por Archivo
client.lua
7
app.js
3
clientState.js
1
server.lua
1
12Bugs
Críticos3
Medios4
Menores5

Bugs Críticos

— Requieren corrección inmediata
CRÍTICO
#1División por cero en healthPct
client.lua
·
Línea 340

La expresión math.floor((health / (maxHealth - 100)) * 100) puede dividir por cero si maxHealth es exactamente 100. Esto provocaría un crash del cliente con un error de Lua "attempt to perform arithmetic on a nil value (division by zero)".

CRÍTICO
#2Acciones duplicadas: surrenderfully
client.lua
·
Línea 772 y 1027

La acción "surrenderfully" está definida dos veces en la cadena de elseif de executeAction. La segunda definición (línea 1027) es código muerto que nunca se ejecutará porque la primera (línea 772) ya captura el caso. Esto puede indicar un merge conflict no resuelto o un error de copia-pega.

CRÍTICO
#3Acciones duplicadas: handsonhead
client.lua
·
Línea 766 y 971

Misma situación que surrenderfully. La acción "handsonhead" aparece dos veces en la cadena de elseif. La segunda definición es código muerto. Ambas duplicaciones sugieren que se añadieron acciones en dos lugares distintos durante el desarrollo y nunca se limpiaron.

Bugs Medios

— Deberían corregirse pronto
MEDIO
#4ctx.pedId || ctx.pedId redundante
bridge/clientState.js
·
Línea 74

La expresión String(ctx.pedId || ctx.pedId || "unknown") usa ctx.pedId dos veces, lo cual es claramente un error. Probablemente la intención era usar ctx.pedId || ctx.handle como fallback para obtener el identificador del ped.

MEDIO
#5AudioWorklet URL hardcodeada
app.js
·
Línea 286

La URL del AudioWorklet PCM está hardcodeada como "https://cfx-nui-lsa_npc/html/pcm-worklet.js". Si el recurso FiveM se renombra (ej. de lsa_npc a mi_npc_voice), la URL será incorrecta y el procesamiento de audio fallará silenciosamente. Se debería usar GetParentResourceName() de FiveM para construir la URL dinámicamente.

MEDIO
#6int16ToBase64 Stack Overflow Risk
app.js
·
Línea 494

La función usa String.fromCharCode.apply(null, bytes.subarray(i, i + chunk)) con chunk=0x8000 (32768 elementos). Esto puede exceder el tamaño máximo del call stack en algunos navegadores, provocando "RangeError: Maximum call stack size exceeded". Reducir el chunk a 0x4000 (16384) es una solución segura y comprobada.

MEDIO
#7Acciones no implementadas en client.lua
client.lua
·
Línea executeAction

Las acciones v4 (giveitem, givemoney, setreputation, setnotes) y las acciones sociales (gossip, tellstory, laughwithothers) están definidas en actions.js como parte del schema enviado a Gemini, pero no tienen un handler correspondiente en la función executeAction del client.lua. Gemini puede generar estas acciones pero el NPC no las ejecutará.

Bugs Menores

— Mejoras de calidad
MENOR
#8Backstories idénticas para NPCs del mismo tipo
client.lua
·
Línea generateBackstory

La función generateBackstory genera el mismo backstory para todos los NPCs del mismo arquetipo en la misma zona y hora. Esto significa que dos vendedores ambulantes en la misma calle tendrán exactamente la misma historia, rompiendo la inmersión. Se debería añadir variabilidad usando el pedId como semilla.

MENOR
#9Validación de amount en giveMoney
server.lua
·
Línea 63

La función giveMoney del servidor no valida el valor recibido del cliente. Un cliente malicioso podría enviar cantidades negativas (para robar dinero) o extremadamente grandes. Se debería aplicar clamping: math.min(math.max(amount, 0), 10000).

MENOR
#10Animación de crawl posiblemente inexistente
client.lua
·
Línea 1068

La animación dict "move_crawl/onback_fwd" puede no existir en todas las versiones de GTA V. Aunque se ejecuta como best-effort (no crashea si falla), debería documentarse claramente que es una animación no estándar y podría no funcionar en todos los builds del juego.

MENOR
#11OnFootOnly no configurable en caliente
fxmanifest.lua / config.lua
·
Línea

La configuración tiene un parámetro OnFootOnly pero el README indica que no se puede cambiar en caliente. Se debería poder togglear con un comando de chat como /lsatoggle para que los administradores puedan activar/desactivar el sistema sin reiniciar el recurso.

MENOR
#12Heartbeat de WebSocket sin verificar conexión
app.js
·
Línea 514

El intervalo del heartbeat se ejecuta cada 25 segundos aunque la conexión WebSocket esté cerrada, desperdiciando recursos del navegador. Se debería verificar si el WebSocket está en estado OPEN antes de enviar el ping, y limpiar el intervalo al desconectar.

04
Métricas de Calidad

Estadísticas del Proyecto

Resumen cuantitativo de la base de código, cobertura de funcionalidades y estado de documentación.

Distribución de Severidad de Bugs

12 total
3 Críticos(25%)
4 Medios(33%)
5 Menores(42%)
38 / 45
Cobertura de Acciones
84% implementadas
38 de 45 acciones tienen handler
~1,750
Líneas de Lua
client.lua + server.lua + config
~1,200
Líneas de JS (Bridge)
server.js + clientState.js + actions.js
~520
Líneas de NUI
app.js + index.html + styles
67
Archetype Mapping
Modelos de ped mapeados
40+
Arquetipos Únicos
Personalidades de NPC distintas
40+ arquetipos con descripción de personalidad
22
Voice Bank
Voces Gemini deterministas
15+
Idiomas Soportados
Inglés, Español, Francés, Alemán...
05
60 Acciones del Sistema

Catálogo Completo de Acciones

Todas las acciones que Gemini puede generar para controlar NPCs, con su categoría, descripción y estado de implementación.

53 Implementadas
7 Sin Handler
AcciónCategoríaEstado
FollowTargetMovimientoImplementada
WaitHereMovimientoImplementada
WalkAwayFromTargetMovimientoImplementada
StopAndFaceTargetMovimientoImplementada
FleeFromTargetMovimientoImplementada
LeadTheWayMovimientoImplementada
AttackTargetCombateImplementada
PutHandsUpCombateImplementada
PutHandsDownCombateImplementada
KneelCombateImplementada
GetUpCombateImplementada
IntimidateTargetWithWeaponCombateImplementada
EnterTargetVehicleVehículoImplementada
EnterDriverSeatOfTargetVehicleVehículoImplementada
EnterBackOfTargetVehicleVehículoImplementada
DriveTargetToDestinationVehículoImplementada
DriveFastVehículoImplementada
DriveEvasiveVehículoImplementada
DriveNormalVehículoImplementada
ExitVehicleVehículoImplementada
DanceSocialImplementada
SitDownSocialImplementada
StandUpSocialImplementada
SaluteSocialImplementada
HandsOnHeadSocialImplementada
HandsBehindBackSocialImplementada
WaveSocialImplementada
CheerSocialImplementada
SmokeSocialImplementada
DrinkSocialImplementada
LeanOnWallSocialImplementada
BegSocialImplementada
WorkOutSocialImplementada
TakeModelPhotoSocialImplementada
SelfieWithTargetSocialImplementada
CallPolicePremiumImplementada
SurrenderFullyPremiumImplementada
CrawlToTargetPremiumImplementada
HandsOnHipsPremiumImplementada
PrayKneelingPremiumImplementada
HelpTargetPremiumImplementada
PointAndLaughPremiumImplementada
LookAroundNervousPremiumImplementada
ShooAwayPremiumImplementada
GangSignPremiumImplementada
BackAwayPremiumImplementada
RobTargetPremiumImplementada
DropMoneyPremiumImplementada
TakeTargetWeaponArmas/ItemsImplementada
GiveTargetWeaponArmas/ItemsImplementada
PutAwayWeaponArmas/ItemsImplementada
BecomeAccompliceEspecialImplementada
InitiateDirectedInteractionEspecialImplementada
GiveItemEconomíaSin Handler
GiveMoneyEconomíaSin Handler
SetReputationEconomíaSin Handler
SetNotesEconomíaSin Handler
GossipSocialSin Handler
TellStorySocialSin Handler
LaughWithOthersSocialSin Handler
Mostrando 60 de 60 acciones
06
14 Características

Funcionalidades Soportadas

El proyecto implementa un amplio conjunto de funcionalidades para NPCs con IA conversacional en FiveM.

Core

Conversación por Voz en Tiempo Real

Captura de audio del micrófono del jugador y envío en streaming al bridge mediante WebSocket.

Core

Audio 3D Posicional (HRTF)

El audio del NPC se reproduce con posición 3D basada en la ubicación del ped en el mundo del juego.

Subtítulos sobre la Cabeza del NPC

Transcripción en tiempo real mostrada como UI in-game sobre el NPC usando NUI scaleform.

45+ Acciones Físicas del NPC

Saludar, rendirse, cruzar brazos, apuntar, sentarse, caminar, y muchas más animaciones.

67+ Modelos de Ped Mapeados

Mapeo automático de modelos GTA V a arquetipos (policía, médico, vendedor, etc.).

22 Voces Gemini Deterministas

Selección de voz basada en el género y arquetipo del NPC para consistencia en la conversación.

15+ Idiomas Soportados

Inglés, Español, Francés, Alemán, Portugués, Italiano, Japonés, Coreano, Chino, y más.

Lip Sync (Best-Effort)

Sincronización de labios del NPC con el audio usando facials de GTA V cuando están disponibles.

VAD (Barge-in)

Detección de actividad de voz que permite interrumpir al NPC cuando el jugador habla.

Sesiones Reanudables (10 min)

Mantener el contexto de conversación durante hasta 10 minutos de inactividad.

Conducción por Waypoints

El NPC puede conducir vehículos hacia waypoints especificados por la IA.

Contexto Rico

Arma, salud, wanted level, zona, clima, hora, multitud, vehículo cercano y más.

Soporte QBox/ESX

Integración opcional con frameworks QBox y ESX para inventario, dinero y reputación.

Premium

Sincronización Multijugador

Sincronización de animaciones y audio entre jugadores en el servidor (premium).

07
Protocolo WebSocket

Documentación del Protocolo

16 mensajes intercambiados entre el cliente NUI y el bridge servidor mediante WebSocket — 6 salientes, 10 entrantes.

NUI → Bridge6 mensajes
TipoDescripción
micStartIniciar turno de voz con un NPC. Incluye contexto completo: pedId, modelo, arquetipo, ubicación, hora, clima, estado del jugador.
audioChunk PCM 16kHz mono del micrófono codificado en base64. Se envía periódicamente (~100ms) mientras el jugador habla.
micStopEl jugador soltó el push-to-talk. Indica al bridge que el turno de voz terminó y debe esperar la respuesta del NPC.
contextUpdateActualizar el contexto del NPC durante una conversación (ej: cambio de zona, arma equipada, hora del día).
testPromptEnviar un turno de texto directamente (modo testing, sin micrófono). Útil para depuración y desarrollo.
pingHeartbeat para mantener la conexión WebSocket activa. El NUI envía un ping cada 25 segundos.
Bridge → NUI10 mensajes
TipoDescripción
connectedConfirmación de conexión al bridge. Incluye la versión del servidor para validación de compatibilidad.
micReadyLa sesión Gemini Live se abrió correctamente. El NUI puede empezar a enviar chunks de audio.
npcAudioSpeakerIndica qué ped (NPC) va a hablar a continuación. El NUI configura el AudioContext 3D con la posición del ped.
npcAudioChunk PCM 24kHz mono de la respuesta de voz del NPC en base64. Se reproduce con posicionamiento 3D (HRTF).
transcriptSubtítulo en tiempo real del texto del NPC. Las tags de acción [Acción] ya están removidas del texto mostrado.
npcActionAcción física para el NPC (saludar, apuntar, rendirse, etc.). Incluye nombre, parámetro y destino cuando aplica.
speechEndedEl turno completo del NPC terminó. El cliente debe limpiar el subtítulo y reiniciar estados de animación.
micStoppedEl drain del micrófono del navegador terminó. Todos los chunks pendientes fueron enviados al bridge.
interruptedEl NPC fue interrumpido por un barge-in del jugador (VAD detectó voz mientras el NPC hablaba).
errorError en el bridge o en la API de Gemini. Incluye un mensaje descriptivo para depuración.
08
System Prompt

Prompt de Personalidad del NPC

El system prompt de ~25KB que define la personalidad, reglas y comportamiento de cada NPC en la conversación con Gemini Live.

systemPrompt.txt
2476 chars
You are a believable person living in Los Santos.
You are NOT an assistant.
You are NOT an AI helper.
You are NOT a game tutorial.
You are NOT waiting around for the player to speak to you.
You already existed before this interaction began.
You have:
* a personality
* current emotions
* opinions
* habits
* fears
* frustrations
* insecurities
* confidence levels
* social tendencies
* interests
* personal biases
* a financial situation
* things currently occupying your mind
* a reason for being where you are
* a reason for doing what you are doing
You are living your own life.
The player is simply another person interacting with you.

... 55 líneas más

Prompt del sistema enviado a Gemini Live API
09
Stack Tecnológico

Pipeline de Tecnologías

El flujo completo de datos, desde la captura de voz del jugador hasta la respuesta del NPC, atravesando 6 capas tecnológicas.

FiveM Client (GTA V / CEF)

Capa 1

El motor del juego y el navegador embebido Chromium (CEF) que renderiza la interfaz NUI. Todos los peds, animaciones y el mundo 3D se ejecutan aquí.

↓ datos

NUI (HTML/CSS/JS)

Capa 2

La capa de interfaz invisible sobre el juego. Captura audio del micrófono del jugador y reproduce respuestas del NPC sin interferir con el gameplay.

↓ datos ↓ audio/control

Web Audio API (AudioWorklet + PannerNode)

Capa 3

Procesamiento de audio a nivel de navegador. AudioWorklet captura a 16kHz mono para envío eficiente. PannerNode posiciona el audio del NPC en 3D basándose en coordenadas del mundo.

↓ datos ↓ PCM/base64

WebSocket (wss://)

Capa 4

Comunicación bidireccional en tiempo real entre NUI y el bridge. Protocolo binario para audio (Base64 PCM) y JSON para mensajes de control (micStart, npcAction, etc.).

↓ datos ↓ mensajes

lsa-bridge (Node.js + ws)

Capa 5

Servidor relay que gestiona sesiones, estado de cada NPC, conexiones WebSocket y la comunicación con la API de Gemini. Orquesta todo el pipeline de datos.

↓ datos ↓ API calls

Google Gemini Live API

Capa 6

API multimodal en tiempo real de Google. Procesa audio entrante, genera respuestas con voz nativa y decide acciones del NPC. Soporta VAD, barge-in y sesión persistente.

Jugador
IA (Gemini)
10
22 Voces · 12 Idiomas

Explorador de Voces e Idiomas

LSA NPC utiliza las voces de Google Gemini Live API para dar vida a los NPCs. Cada voz se asigna determinísticamente según el pedId, ordenadas de aguda a grave para sesgar la edad del personaje.

22 voces disponibles (11 masculinas + 11 femeninas)

Voces Masculinas

11
01PuckDEFAULT
AgudaAgudaGrave
02Orus
AgudaAgudaGrave
03Fenrir
AgudaMedia-agudaGrave
04Charon
AgudaMedia-agudaGrave
05Achird
AgudaMediaGrave
06Algieba
AgudaMediaGrave
07Rasalgethi
AgudaMedia-graveGrave
08Schedar
AgudaMedia-graveGrave
09Iapetus
AgudaGraveGrave
10Umbriel
AgudaGraveGrave
11Algenib
AgudaGraveGrave

Voces Femeninas

11
01Aoede
AgudaAgudaGrave
02Leda
AgudaAgudaGrave
03Zephyr
AgudaMedia-agudaGrave
04Kore
AgudaMedia-agudaGrave
05Despina
AgudaMediaGrave
06Erinome
AgudaMediaGrave
07Gacrux
AgudaMedia-graveGrave
08Pulcherrima
AgudaMedia-graveGrave
09Sulafat
AgudaGraveGrave
10Vindemiatrix
AgudaGraveGrave
11Callirrhoe
AgudaGraveGrave

Idiomas Soportados

Config.Language determina el idioma del NPC. El valor predeterminado esespañol. Configurado como auto, el NPC refleja el idioma que hable el jugador.

Español
es
PREDETERMINADO
English
en
Français
fr
Deutsch
de
Português
pt
Italiano
it
Русский
ru
日本語
ja
中文
zh
العربية
ar
한국어
ko
Auto-detectar
auto

Especificaciones de Audio

Frecuencia Micrófono
16 kHz
MIC_RATE = 16000
Frecuencia Salida
24 kHz
GEMINI_OUTPUT_RATE = 24000
Modelo de IA
gemini-2.5-flash
native-audio-preview
Formato de Audio
PCM int16
Lineal 16-bit
11
40+ Arquetipos NPC

Explorador de Arquetipos

Cada NPC en LSA tiene un arquetipo que define su personalidad, comportamiento y forma de hablar. Explora los 40+ arquetipos del proyecto.

59 arquetipos encontrados
TOURIST
Civiles

Turista perdido en Los Santos. Lleva cámara, mapa, y ropa de vacation. Habla de lugares para visitar y pregunta direcciones con acento extranjero.

BEACH
Civiles

Persona que disfruta del día en la playa de Vespucci. Relajada, bronceada, con ropa de playa. Habla de olas, clima y vida al aire libre.

SURFER
Civiles

Surfero de Venice Beach o vespucci. Apasionado por las olas, usa jerga de surf, relajado pero entusiasta. Conoce los mejores spots de la costa.

SUNBATHE
Civiles

Persona tomando el sol en la playa. Somnolienta, contenta, con gafas de sol. Responde de forma corta y relajada, no quiere moverse mucho.

BAYWATCH
Civiles

Lifeguard de la playa de Vespucci. Atento, en forma, responsable. Habla de seguridad acuática, corrientes, y rescates. Puede ser estricto con las normas.

FITNESS
Civiles

Entusiasta del fitness, encontrado en el gimnasio de Vespucci o corriendo por el paseo marítimo. Habla de rutinas, proteínas, y metas personales.

RUNNER
Civiles

Corredor que entrena por las calles y parques de Los Santos. Focused, con auriculares, habla de maratones y rutas de running.

BEVHILLS
Civiles

Residente adinerado de Beverly Hills. Elegante, pretencioso, con gustos caros. Habla de tiendas de lujo, restaurantes exclusivos y eventos sociales.

BUSINESS
Civiles

Ejecutivo de negocios en traje. Ocupado, profesional, mira el reloj. Habla de reuniones, inversiones y el mercado de Los Santos.

DOWNTOWN
Civiles

Trabajador o residente del centro financiero de LS. Práctico, orientado a resultados, conoce los atajos por la ciudad.

HIPSTER
Civiles

Hipster de Vinewood o Echo Park. Alternativo, irónico, colecciona vinilos y café de especialidad. Desprecia lo mainstream.

AIRHOSTESS
Civiles

Azafata de vuelo, probablemente en transición entre el aeropuerto y su hotel. Educada, profesional, amable. Conoce vuelos, destinos y hoteles.

SHOPKEEP
Civiles

Dueño de una tienda pequeña. Conoce su inventario al dedillo, amable con clientes regulares, protector de su negocio. Habla de precios, productos y tendencias.

POLYNESIAN
Civiles

Residente de origen polinésico en Los Santos. Cálido, con conexiones culturales fuertes, habla de tradiciones y la comunidad insular en LS.

HASJEW
Civiles

Residente judío ortodoxo de la zona de Hasidic en LS. Habla con sabiduría, valores tradicionales, y referencia a la comunidad y costumbres.

KOREAN
Civiles

Residente de Little Seoul. Orgulloso de su herencia coreana, habla de comida, K-dramas, y la comunidad coreana en Los Santos.

AFRIAMER
Civiles

Afroamericano de Los Santos. Consciente de la cultura y la historia del barrio, habla de comunidad, música y las realidades de la vida en LS.

FATWHITE
Civiles

Hombre blanco de mediana edad, con sobrepeso. Casual, relajado, probablemente en un bar o restaurante. Opina sobre comida y deportes.

GENFAT
Civiles

Persona con sobrepeso genérico. Amable, hogareña, podría estar haciendo recados. Habla de rutinas diarias y temas cotidianos sin pretensiones.

FATLATIN
Civiles

Latino con sobrepeso. Cálido, familiar, probablemente cerca de la comunidad latina. Habla de comida casera, familia y tradiciones.

CONSTRUCT
Trabajadores

Obrero de construcción en una obra de Los Santos. Fuerte, prático, algo rudo. Habla de trabajo pesado, maquinaria y plazos de construcción.

AUTOSHOP
Trabajadores

Mecánico de taller mecánico. Experto en motores, sucio de grasa, honesto o estafador según el día. Habla de coches, piezas y precios.

DOCKWORK
Trabajadores

Trabajador portuario del puerto de LS. Rudo, fuerte, acostumbrado al trabajo físico. Habla de contenedores, barcos y turnos largos.

TRUCKER
Trabajadores

Conductor de camión de larga distancia. Conoce todas las rutas de San Andreas, cansado del asfalto. Habla de rutas, gasolineras y vida en la carretera.

GENTRANSPORT
Trabajadores

Conductor de transporte público o taxi. Conoce cada calle de Los Santos, puede ser amable o gruñón. Opina sobre el tráfico y pasajeros.

LATHANDY
Trabajadores

Trabajador de mantenimiento o reparaciones varias. Práctico, resolutivo, con herramientas siempre a mano. Habla de fontanería, electricidad y presupuestos.

ROADCYC
Trabajadores

Ciclista de ruta o mensajero en bicicleta. Veloz, consciente del tráfico, ecológico. Conoce los carriles bici y atajos peatonales.

UPS
Trabajadores

Repartidor de paquetes. Apurado, eficiente, cargado de cajas. Conoce todas las direcciones y horarios de entrega del barrio.

SECURITY
Trabajadores

Guardia de seguridad. Vigilante, algo aburrido, sigue el protocolo al pie de la letra. Habla de turnos, incidentes y procedimientos.

SCRUBS
Trabajadores

Personal médico con uniforme de hospital. Profesional, estresado, ocupado. Habla de turnos, pacientes y la presión del trabajo en el hospital.

FIREMAN
Trabajadores

Bombero de Los Santos. Valiente, en forma, con camaradería. Habla de incendios, rescates, la estación y la importancia del trabajo en equipo.

RSRANGER
Trabajadores

Guardabosques del parque nacional. Conoce la flora y fauna de San Andreas, amante de la naturaleza. Habla de senderos, animales y conservación.

COP
Trabajadores

Oficial de policía del LSPD. Autoritario, observador, con un sentido del deber. Habla de la ley, patrullas y la realidad del crimen en LS.

GENSTREET
Calles

Habitante de la calle genérico. Conoce el código de la calle, desconfiado de extraños, sobrevive día a día en Los Santos.

STBLA
Calles

Afroamericano del barrio de Strawberry. Conectado con la comunidad, habla de la vida del barrio, respeto territorial y supervivencia.

STLAT
Calles

Latino del este de Los Santos. Orgulloso de sus raíces, leal a su comunidad, habla de familia, barrio y las dificultades de la vida.

EASTSA
Calles

Residente del East Side de Los Santos. Conoce las pandillas del área, es cauteloso con desconocidos, habla de lealtad territorial.

SOUCENT
Calles

Persona del South Central. Realista, conoce las reglas no escritas del barrio. Habla de sobrevivir en una zona difícil.

STWHI
Calles

Hombre blanco de clase trabajadora del sur de LS. Directo, algo cínico, habla de la economía, los cambios del barrio y sus frustraciones.

FATBLA
Calles

Afroamericano con sobrepeso del barrio. Amable pero cansado, probablemente en una tienda de barrio. Habla de comida, precios y la vida local.

SKIDROW
Calles

Sin techo o habitante de Skid Row. Desesperado, sabio por necesidad, habla de la vida en las calles, recursos y supervivencia diaria.

TRAMP
Calles

Vagabundo de Los Santos. Errante, con historias que contar, algo incoherente. Habla de sus viajes, filosofía de vida y experiencias.

ZOMBIE
Calles

Persona en estado de crisis o adicción severa, encontrada en zonas marginales. Desorientada, habla de forma fragmentada y confusa.

DEALER
Peligrosos

Vendedor de drogas callejero. Desconfiado, paranoico, siempre atento a la policía. Habla en código, negocia con cautela y se mueve rápido.

MEXGOON
Peligrosos

Matón de la mafia mexicana. Intimidante, leal a la organización, usa lenguaje duro. Habla de respeto, territorios y consecuencias.

FAMDNF
Peligrosos

Miembro de los Families de Danforths. Leal a su set, street-smart, habla de la vida en la pandilla, protección del territorio y hermandad.

FAMCA
Peligrosos

Miembro de los Chamberlain Gangster Families. Conocido en el barrio, envuelto en la economía callejera. Habla de lealtad, supervivencia y el juego.

BALLAORIG
Peligrosos

Miembro original de los Ballas. Rival histórico de los Families, agresivo, territorial. Habla de dominio del barrio y la guerra contra los Families.

BALLASCOUT
Peligrosos

Explorador/reconocimiento de los Ballas. Joven, observador, ágil. Actúa como los ojos de la pandilla en territorio rival.

POLOGOON
Peligrosos

Matón polaco de la mafia del este de Europa. Imponente, discreto, profesional en su trabajo. Habla de negocios, deudas y "resolución de problemas".

STRPUNK
Peligrosos

Punk callejero de Strawberry. Joven, rebelde, buscando pelea o problemas. Habla de vandalismo, música y desafiar la autoridad.

HOOKER
Peligrosos

Trabajadora sexual de las calles de Los Santos. Cautelosa, sobrevive en los márgenes, habla de precios, zonas y clientes problemáticos.

VINEWOOD
Exclusivos

Estrella o aspirante a estrella de Vinewood. Vanidoso, carismático, siempre buscando su próximo papel. Habla de casting, fama y el estilo de vida de Los Santos.

VINDOUCHE
Exclusivos

Celebridad o figura de la alta sociedad de Vinewood Hills. Pretenciosa, rica, con opiniones fuertes sobre todo. Habla de fiestas, yates y exclusividad.

SALTON
Exclusivos

Residente del área de Salton Sea. Aislado, peculiar, con una realidad alternativa sobre el área. Habla del lago, las ruinas y la vida en el desierto.

AMMUCOUNTRY
Exclusivos

Cliente o empleado de una tienda de armas en el campo. Experto en firearms, politikmente cargado, defiende la segunda enmienda.

MEXCNTRY
Exclusivos

Campesino o trabajador rural mexicano en los campos de Blaine County. Humilde, trabajador, conectado con la tierra. Habla de cosechas, clima y familia.

KTOWN
Exclusivos

Residente de Koreatown en Los Santos. Conectado con la cultura coreana-estadounidense, habla de negocios, comida y la vida multicultural.

GAY
Exclusivos

Persona de la comunidad LGBTQ+ en Los Santos. Abierta, expresiva, con personalidad vibrante. Habla de la vida nocturna, cultura queer y aceptación.

12
Modelos de Ped

Galería de Modelos de Ped

Explora los 184 modelos de ped del mod LSA NPC organizados por 58 arquetipos únicos. Cada chip muestra el nombre del modelo con un código de color por género.

184

Modelos de Ped

58

Arquetipos Únicos

123

Masculinos

53

Femeninos

8

Adultos Mayores

Género:MasculinoFemeninoAdulto Mayor

184 modelos en 58 arquetipos

13
Evaluación

Calidad del Código

Evaluación multidimensional basada en análisis estático

20%40%60%80%100%Cobertura de Código72%Densidad de Bugs65%Documentación85%Modularidad78%Mantenibilidad58%Seguridad52%
68de 100

Puntuación General

68/100

Bueno — Mejorable

Desglose por Dimensión

Cobertura de Código72%
Densidad de Bugs65%
Documentación85%
Modularidad78%
Mantenibilidad58%
Seguridad52%
≥ 75% Excelente
50–74% Aceptable
< 50% Crítico
14
Complejidad

Mapa de Complejidad

Análisis de complejidad ciclomática por archivo del proyecto

Complejidad Promedio

38.2

Archivos de Alto Riesgo

2

Total Líneas

5282

client.lua
92
1750 loc7 🐛Alto
app.js
78
517 loc3 🐛Alto
server.js
65
385 loc0Medio
geminiSession.js
55
210 loc0Medio
actions.js
48
290 loc0Medio
promptBuilder.js
42
180 loc0Medio
pcm-worklet.js
28
45 loc0Bajo
clientState.js
30
130 loc1 🐛Bajo
ped_models.lua
22
420 loc0Bajo
server.lua
35
180 loc1 🐛Bajo
config.lua
12
85 loc1 🐛Bajo
archetypes.js
15
350 loc0Bajo
constants.js
8
120 loc0Bajo
systemPrompt.txt
5
620 loc0Bajo
Alto riesgo (complejidad > 70)
Medio riesgo (complejidad 30–70)
Bajo riesgo (complejidad < 30)
15
Arquitectura

Grafo de Dependencias

Relaciones entre módulos del recurso FiveM y el bridge Node.js

lsa_npc (FiveM Resource)lsa-bridge (Node.js)client.luaped_models.luaconfig.luaserver.luaapp.jspcm-worklet.jsserver.jsgeminiSession.jsconstants.jssystemPrompt.txtclientState.jsactions.jspromptBuilder.jsarchetypes.jsDependencia internaConexión WebSocketlsa_npclsa-bridge
16
Guía Rápida

Inicio Rápido

Configura LSA NPC en tu servidor FiveM en menos de 5 minutos siguiendo estos pasos.

01

Prerrequisitos

Asegúrate de tener instalado un servidor FiveM (build cerulean o superior), Node.js 18+ y una clave de API de Google Gemini con acceso a Gemini Live.

02

Instalar el Bridge

Clona o descarga el proyecto y configura las dependencias del bridge:

Terminal
cd lsa-bridge && npm install && cp .env.example .env
03

Configurar API Key

Edita el archivo .env del bridge y añade tu clave de Gemini:

Terminal
GEMINI_API_KEY=tu_clave_aqui
04

Instalar el Recurso

Arrastra la carpeta lsa_npc/ al directorio resources/ de tu servidor FiveM y añade la línea de ensure al server.cfg:

Terminal
ensure lsa_npc
05

Configurar URL del Bridge

Edita config.lua dentro de lsa_npc/ y cambia la URL del WebSocket para que apunte a tu bridge:

Terminal
Config.bridgeUrl = "wss://tu-servidor.com:8443"
06

¡A Jugar!

Inicia el servidor FiveM y el bridge. En el juego, acércate a cualquier NPC, mantén pulsada la tecla F9 para hablar y suéltala para escuchar la respuesta.

17
Historial

Historial de Desarrollo

Evolución del dashboard a través de 6 ciclos de mejora continua

Ciclo 1

Análisis Inicial

Análisis completo del código fuente. Identificación de 12 bugs y creación del dashboard inicial con 7 secciones.

7 secciones12 bugsAnálisis estático18 archivos
Ciclo 2

Datos Reales & Exploradores

Corrección de datos ficticios. Secciones reales de protocolo y estructura de archivos. Nuevo explorador de arquetipos y preview del system prompt.

10 seccionesArquetiposDiff viewer14 archivos
Ciclo 3

Catálogo de Acciones & Timeline

Catálogo completo de 48 acciones con filtros. Timeline de tecnologías. Guía de inicio rápido. Contadores animados en el hero.

13 secciones48 accionesQuick Start16 archivos
Ciclo 4

Voces, Peds & Búsqueda Global

Explorador de 22 voces Gemini y 128+ modelos de ped. Buscador global ⌘K. Visor diff ANTES/DESPUÉS para bugs.

15 secciones22 voces⌘K Search16 archivos
Ciclo 5

Radar de Calidad & Grafo de Dependencias

Radar SVG de calidad del código (68/100). Grafo de dependencias de 14 módulos. TOC flotante. Filtros de severidad en bugs.

17 seccionesRadar ChartDep Graph19 archivos
Ciclo 6

Timeline de Desarrollo

Timeline visual del desarrollo. Exportación de reportes de bugs. Mejoras de estilismo avanzadas. Panel de atajos de teclado.

19 seccionesExport MDAtajos21 archivos
18
Configuración

Explorador de Configuración

Parámetros configurables del recurso LSA NPC con explicaciones detalladas.

Conexión

2 parámetros
BridgeURLstring
ws://localhost:3001

URL del puente WebSocket entre el cliente NUI y el servicio de IA.

HeartbeatIntervalnumber
5000

Intervalo en milisegundos entre latidos de conexión para mantener activo el canal.

Interacción

4 parámetros
PTTKeystring
F9

Tecla de push-to-talk para activar el micrófono durante la conversación con NPCs.

MaxDistancenumber
15

Distancia máxima en metros para que un NPC pueda ser interactuado por el jugador.

SubtitleDistancenumber
30

Distancia en metros dentro de la cual se muestran los subtítulos de la conversación.

OnFootOnlyboolean
true

Restringe la interacción con NPCs a cuando el jugador está a pie (no en vehículos).

IA y Voz

3 parámetros
VoiceNamestring
Puck

Nombre de la voz predeterminada de Gemini utilizada para la síntesis de audio del NPC.

Languagestring
es

Código de idioma en el que los NPCs generan sus respuestas de texto y voz.

Modelstring
gemini-2.0-flash-exp

Modelo de Gemini utilizado para la generación de respuestas en tiempo real.

Sistema

2 parámetros
DebugModeboolean
false

Activa el registro detallado de depuración en la consola del cliente y servidor.

MemoryEnabledboolean
true

Habilita la memoria persistente para que los NPCs recuerden conversaciones previas.

Archivo: config.lua — Modifica estos valores antes de iniciar el recurso
19
Estructura del Proyecto

Árbol de Archivos

Organización de los dos repositorios principales que conforman el proyecto LSA NPC — recurso FiveM y bridge Node.js.

lsa_npc/ + lsa-bridge/2 proyectos · 18+ archivos principales
lsa_npc/
├── fxmanifest.lua                 ← Manifiesto del recurso FiveM
├── config.lua                     ← Configuración (bridge URL, PTT key, distancias)
├── README.md
├── lsa_npc_memory.sql             ← Schema SQL para memoria persistente
├── client/
│   ├── client.lua                 ← ~1,750 líneas — Core: PTT, contexto, acciones, subtítulos
│   └── ped_models.lua             ← 67+ modelos GTA V → arquetipos y género
├── server/
│   └── server.lua                 ← Server: memoria, rewards, sync multijugador
└── html/
    ├── index.html                 ← Página NUI (invisible, audio + WS)
    ├── app.js                     ← ~520 líneas — Mic, WebSocket, audio 3D (HRTF), VAD
    ├── style.css                  ← Estilos del status overlay
    └── pcm-worklet.js             ← AudioWorklet para captura PCM 16kHz

lsa-bridge/
├── package.json
├── .env.example                   ← Configuración (API key, puerto, modelo)
├── server.js                      ← WebSocket server + flujo de turnos (~385 líneas)
└── src/
    ├── constants.js               ← Config, constantes de audio, voice banks (22 voces)
    ├── archetypes.js              ← 40+ arquetipos con descripciones de personalidad
    ├── actions.js                 ← 45+ acciones + 100+ alias, parsing de tags [Action]
    ├── clientState.js             ← Estado por jugador (sesiones, nonce, voice assign)
    ├── geminiSession.js           ← Sesiones Gemini Live + reanudación (10 min TTL)
    ├── promptBuilder.js           ← System instruction dinámica con contexto
    └── systemPrompt.txt            ← ~25KB prompt de personalidad para el NPC
21
Visualizador de Correcciones

Visualizador de Correcciones

Comparación lado a lado del código original y el código corregido para cada bug identificado.

12 Fixes
3
CRÍTICO
4
MEDIO
5
MENOR
22
Proyección

Evolución de Calidad Proyectada

Impacto estimado de aplicar las 12 correcciones identificadas en las métricas de calidad del código.

Proyección
0de 100Actual
+19 puntos
0de 100Proyectado

Mejora por Dimensión

Cobertura de Código
7288+16
Densidad de Bugs
6592+27
Documentación
8590+5
Modularidad
7885+7
Mantenibilidad
5882+24
Seguridad
5285+33
Valor Actual
Valor Proyectado

Bugs Críticos

3/3 Corregidos

100%

Bugs Medios

4/4 Corregidos

100%

Bugs Menores

5/5 Corregidos

100%
+28% mejora global estimada

Basado en el análisis estático de las 12 correcciones propuestas

23
Interactivo

Flujo de Mensajes WebSocket

Visualización interactiva del flujo de datos en tiempo real entre el cliente FiveM, el bridge Node.js y la API de Gemini.

Interactivo

FiveM Client

Conectado

Cliente del juego con captura de audio y reproducción HRTF

lsa-bridge

Conectado

Servidor Node.js que gestiona sesiones WebSocket

Gemini Live API

Conectado

API de IA multimodal con streaming en tiempo real

Controles de Simulación

websocket-message-log

Esperando mensajes... Presiona "Simular Conversación" para comenzar

ProtocoloWebSocket (WSS)
Latencia Estimada~50-120ms
Formato AudioPCM 16kHz / 24kHz
LSA NPC

Dashboard de análisis estático para el mod LSA NPC de FiveM

Stack Tecnológico

FiveM / LuaWebSocketNode.jsGemini LiveReact / Next.js

Info

v1.0.0 · Análisis Estático
Powered by Z.ai

© 2025 LSA NPC Project