# Evony Scout V4 — escaneo headless por protobuf directo

V4 = **misma captura/UI que V3, pero el motor de escaneo NO mueve la cámara**: sintetiza
`__request_worldmap` por región y lo envía con `SendProtobufMessage`, dejando que la captura
SML (heredada de V3) coseche la respuesta. Objetivo: más rápido, headless de verdad, sin freezes.

> **V3 queda INTACTA** (carpeta `../evony-scout-v3-research`, respaldada en GitHub). V4 es código
> y carpeta separados. Comparten emuladores/cuentas (6000=W / 6002=E) pero **no pueden correr a la
> vez sobre el mismo emulador** (dos scripts frida en el mismo proceso chocan).

## Por qué esto es viable (confirmado en vivo)
Medición del tráfico real de V3: **`__request_worldmap` = 93% de todos los up-messages** durante el
barrido (≈9.388 envíos/ventana), con `__request_worldmap_reply` de vuelta. Es decir: el "barrido por
cámara" de V3 por debajo no hace otra cosa que enviar `request_worldmap` una vez por región. V4 lo
manda **directamente**, sin la cámara.

## Cómo funciona el agente (agent_v4.ts)
1. **Bootstrap por cámara (corto):** al arrancar deja que el barrido normal de V3 dé unos saltos
   reales. Eso hace que el cliente emite `request_worldmap`, que el agente **captura como plantilla**
   y cuyos campos refleja (PROBE B). Auto-detecta los campos de coords casando los valores de la
   plantilla con las coords del salto.
2. **Modo directo:** **congela la cámara** y envía `request_worldmap{server_id,wx,wy,width,ignore_march}`
   por región recorriendo la rejilla. ✅ **VALIDADO en vivo: el server responde a regiones arbitrarias
   sin la cámara allí** (no hay interest-management que lo bloquee).
3. **Parseo del reply (clave):** los objetos vienen DENTRO de `request_worldmap_reply` (no por los sinks
   SML, que solo ingieren la región de la cámara real). El agente engancha `DecodeCallback`, y de cada
   reply extrae las 4 listas — `__mapinfo` (monstruos/farms), `__map_target_info` (marchas/ataques),
   `__userinfo` (players), `__sub_city` (subcities) — a los MISMOS accs de V3 → kinds batch/marches/
   players/subcities. **Paridad total con V3, headless.** Verificado: 69k objetos + attacks + players,
   mapa entero, 0 errores.

Flag en `agent_v4.ts`: `const V4_DIRECT = true`. Ponlo en `false` para fallback a barrido por cámara
(comportamiento idéntico a V3) si el protobuf directo no funcionara.

## Arranque
```bash
cd evony-scout-v4
./build_agents_v4.sh         # compila agent_v4.ts -> agent_W.js / agent_E.js (toolchain de V3)
./run_v4.sh both             # para V3, reinicia Evony (limpia script V3), lanza backend V4 local
# UI: http://100.127.215.100:8772   (login = mismo users.json que V3)
tail -f /tmp/evony_v4.log
```
`run_v4.sh W` o `E` para un solo emulador.

## Qué mirar en el log (decide TODO)
- `[v4][PROBE-B] request_worldmap campos: …` → la struct (¿qué campos lleva?).
- `[v4][PROBE-B] PLANTILLA … CAPTURADA` + `coords auto-detectadas -> x='…' y='…'` → confirma que
  capturó un request real y qué campos son las coords. Si x/y salen vacíos, hay que fijar los campos
  de coords a mano (mirar el volcado de campos).
- `[v4][PROBE-D] +1.5s: objetos entrantes=N`:
  - **N > 0 → DESACOPLE OK** ✅: el server respondió a una región sin la cámara allí. **V4 viable** —
    los datos deberían poblarse en el backend (http://100.127.215.100:8772) sin mover la cámara.
  - **N = 0 → el server ata el dato al viewport**: V4-por-región no funciona; el server ignora coords
    arbitrarias. En ese caso poner `V4_DIRECT=false` (fallback cámara) — V3 sigue siendo el techo.
- `[v4] vuelta DIRECTA k …` → escaneo directo en marcha.

## Volver a V3
```bash
cd ../evony-scout-v3-research && ./restart_v3_lowpower.sh
```

## Riesgos (honesto)
- **Rate-limit / ToS / ban:** enviar muchos `request_worldmap` seguidos es un patrón no-humano; el ToS
  de Evony prohíbe manipular el protocolo. `V4_CADENCE_MS=220` arranca conservador; subir solo tras
  medir. Riesgo de cuenta real — aunque V4 usa las cuentas de V3 por decisión explícita.
- **Campos de sesión:** el clone-replay copia la plantilla real para no romper validaciones; si aun
  así el server descarta requests sintéticos, PROBE-D saldrá 0.
- **Ganancia real:** si el server capa el reply a su cadencia de push (~95ms/región), V4 no será más
  rápido que V3. Medir regiones-útiles/seg antes de dar V4 por bueno.

Ver memoria del proyecto: `project_v4_research.md`.