TikXanderTikXander Developers
← docs

Transportes — un contrato, tres caminos

El evento JSON es idéntico en los tres transportes. El manifest declara cuál usa tu app (transport). El SDK elige el correcto por ti.

1. local-ws — WebSocket local (web, GTA V, escritorio)

ws://127.0.0.1:8767/events/v1?app=<appId>
  • El servidor es el agente local del streamer.
  • Handshake: el primer mensaje del servidor es init; luego el stream de eventos declarados en el manifest. ping/pong cada 30 s.
  • Permisos: la primera conexión de un appId desconocido dispara un prompt en el agente ("Este juego quiere recibir: chat, gifts, joins — ¿Permitir?"), con opción de recordar.
  • Cliente de referencia: @tikxander/live-events (conectar, reconectar con backoff, deduplicar por id, on('chat', cb)).

2. local-poll — HTTP long-poll local (GTA San Andreas y engines viejos)

Para entornos sin WebSocket viable (scripts CLEO/Lua):

GET http://127.0.0.1:8767/events/v1/poll?app=<appId>&cursor=<c>&wait=25
→ 200 { "cursor": "c124", "events": [ {…}, {…} ] }
  • cursor opaco; la primera llamada sin cursor devuelve init + el cursor actual.
  • wait: long-poll hasta N segundos (máx 25); responde antes si hay eventos.
  • Buffer de ~60 s por app: una ráfaga de gifts no se pierde entre polls.
  • Sirve para cualquier lenguaje con HTTP; curl basta para probar.

3. cloud-relay — HTTPS polling cloud (Roblox, obligatorio)

Los juegos Roblox corren en servidores de Roblox y no ven el 127.0.0.1 del streamer. Su camino es un relay en agent-controller:

GET https://agentcontroller.tikxander.com/relay/v1/events?cursor=<c>
Authorization: Bearer <relay-token del streamer para esa app>
→ 200 { "cursor": "c88", "events": [ {…} ] }
  • El relay-token se genera en la ficha del juego (por streamer + app, revocable) y el streamer lo pega en la config de su experiencia Roblox.
  • Cola FIFO consumida por HttpService, con cursor + buffer corto.

Matriz plataforma → transporte

PlataformaTransporteSDKPor qué
Juego web (HTML)local-ws@tikxander/live-events (npm)Corre en el browser/OBS, localhost OK.
Mod GTA Vlocal-wsSDK C# (ScriptHookVDotNet).NET tiene WebSocket nativo.
Mod GTA SAlocal-pollhelper CLEO/LuaSin WebSocket viable.
Robloxcloud-relayModuleScript LuaLos servers de Roblox no ven localhost.
Otro (Python, Unity…)local-ws o local-pollprotocolo crudoCualquier lenguaje con HTTP se integra.

Simulador

El panel de simulación (en este portal y en la pestaña Desarrollador del agente) inyecta eventos falsos en el MISMO canal: tu juego no distingue (salvo el campo opcional sim: true). Presets: chat suelto, gift x1, streak de gifts, ráfaga de joins, live start/end, caos aleatorio N eventos/s.