Esquemas de IA

Un esquema = una IA completa: una carpeta + un manifiesto scheme.json + código. Cada instancia del juego elige un esquema; en Farsight se cambia con un clic, y también en la partida en curso: el nuevo esquema toma el control al instante.

Los esquemas que comparten otros se importan en un espacio aparte, sin afectar a los tuyos; si quieres modificar uno, usa “Copiar a los míos”.

schemes/
  mine/<id>/          mis esquemas: escritos por ti o copiados de otro para modificarlos (cámbialos a tu gusto; se aplican en la siguiente partida)
  installed/<id>/     instalados: aquí se descomprimen los zip que comparten otros (antes de la primera ejecución hay que confirmar la confianza)
brains/xwar3/         integrado: cerebro de referencia (IA completa)
brains/examples/      integrados: cuatro ejemplos didácticos hello / rush / macro / micro, el ejemplo de compañero buddy y dos mods de juego (Roguelike de héroe, Defensa sin fin)

Un esquema no tiene por qué ser una IA que juega por ti: un esquema kind: mod es un conjunto de reglas de juego; juegas tú y él plantea el reto. Ver Mods de juego.

Usarlos en Farsight

Página “Esquemas de IA” (barra lateral izquierda “Sistema → Esquemas de IA”):

Acción	Qué hace
Importar esquema (zip)	Lo instala en `installed/`; si ya hay uno instalado con el mismo id, pregunta si quieres sustituirlo (tras sustituirlo hay que volver a confirmar la confianza)
Usar en instancia…	Elige la instancia + “Aplicar ahora” (detiene la IA actual y el nuevo esquema toma el control de esta partida) o “Aplicar en la próxima prueba”
Copiar a los míos	Hace una copia en `mine/`, con autor “yo” y versión 0.1.0, y anota de qué esquema y de qué versión se copió
Exportar zip	Lo empaqueta como `<id>-<versión>.zip`; enviárselo a alguien es compartirlo
Abrir carpeta	Abre el directorio del esquema en el Explorador de archivos para editar el código directamente
Confiar	Obligatorio antes de ejecutar por primera vez un esquema de otra persona (ver “Confianza y seguridad” más abajo)
Resultados recientes	Victoria o derrota, duración y motivo del final de cada partida de este esquema
Eliminar	Solo se pueden eliminar los “míos” y los “instalados”; no se puede eliminar uno que esté usando alguna instancia

La tarjeta de cada instancia también tiene una fila nueva, “Esquema de IA”: eliges el esquema en el desplegable → “Cambiar (aplicar ahora)”. Si la instancia no está en marcha, el botón se llama “Seleccionar”, y el siguiente “Iniciar prueba” arrancará la IA con ese esquema.

El manifiesto scheme.json

{
  "format": 1,
  "id": "fast-rush",
  "name": "Rush de tres minutos",
  "version": "1.2.0",
  "author": "Fulano",
  "description": "Una frase que explica qué estrategia sigue esta IA",
  "entry": "rush_bot.py",
  "class": "RushBot",
  "fair": true,
  "hz": 5,
  "races": ["human", "orc"],
  "license": "MIT"
}

Campo	Obligatorio	Descripción
`id`	✔	Minúsculas, dígitos, `-` y `_`; de 2 a 41 caracteres
`entry`	✔	Un archivo `.py` del directorio del esquema (no se admiten rutas absolutas ni `..`)
`kind`		Por defecto `bot` (subclase de `openwar3.Bot`, juega por ti); `mod` = mod de juego (subclase de `openwar3.Mod`; nunca usa el modo justo y el resultado no se decide con las reglas de las partidas competitivas)
`class`		Nombre de la subclase de Bot (o de Mod) en el archivo de entrada; si no se indica, se toma la última subclase de `openwar3.Bot` del archivo de entrada
`fair`		Por defecto `true`: solo ve lo que está en su visión, la misma regla que en la Arena. `false` = ve todo el mapa, y solo así puede usar el canal JASS (el compañero lo necesita)
`judge`		Por defecto `true`: el resultado se decide con las reglas de las partidas competitivas. Los esquemas de RPG / de compañero ponen `false`
`hz`		Cuántas veces por segundo se llama a `on_tick`; 5 por defecto
`format`		Versión del formato del manifiesto, actualmente 1; si es más nueva que el OpenWar3 instalado, se rechaza y se pide actualizar
El resto		`name`, `version`, `author`, `description`, `races`, `license`, `homepage` y `forked_from` solo se usan para mostrarlos

El directorio del esquema se añade a la ruta de búsqueda de módulos de Python, así que el archivo de entrada puede hacer import de otros archivos del mismo directorio. Los paquetes de terceros (numpy, torch…) no se instalan solos: indica claramente en description qué hace falta.

El esquema más pequeño cabe en dos archivos:

# my_bot.py
from openwar3 import Bot

class MyBot(Bot):
    def on_tick(self, g):
        for w in g.idle_workers():
            mine = g.nearest(g.gold_mines(), w)
            if mine:
                g.gather(w, mine)

{"id": "my-first", "name": "Mi primera IA", "entry": "my_bot.py"}

Ponlo en schemes/mine/my-first/, refresca Farsight y ya aparece. Un punto de partida aún más cómodo: elige un ejemplo en “Integrados” y pulsa “Copiar a los míos”.

Ejecución y resultados

Los esquemas los ejecuta el ejecutor de esquemas (es lo que arrancan “Iniciar prueba / Cambiar” en Farsight):

python tools/run_scheme.py --inst 20 --scheme builtin/micro --hours 6

Cada instancia tiene un proceso supervisor permanente, y cada partida arranca un subproceso que ejecuta el esquema: si el código del esquema falla, no arrastra al supervisor; si cambias el código de uno de “mis esquemas”, la siguiente partida ya usa el nuevo.
Al terminar cada partida se anota una línea de resultados: esquema, versión, autor, victoria o derrota, motivo, duración de la partida y número de errores. El porcentaje de victorias de Farsight se calcula a partir de aquí.

Cómo se decide el resultado:

Situación	Se registra como
El rival se queda sin edificios	Victoria
Nos quedamos sin edificios (aunque queden tropas vivas: así se pierde en una partida competitiva)	Derrota
Nos quedamos sin unidades	Derrota
Se termina / detiene a mano desde Farsight	Sin decidir
Al cambiar de esquema, la partida ya llevaba más de 60 segundos de juego (relevo a mitad de partida)	Se cuenta aparte, no entra en el porcentaje de victorias
El reloj de juego lleva mucho tiempo parado	Sin decidir

Cuando hay resultado, el ejecutor cierra la pantalla de resultados, abre la siguiente partida según “Siguiente partida” y el esquema vuelve a tomar el control, así que puedes dejarlo toda la noche acumulando resultados. La pausa no cuenta como final: durante la pausa el Bot sigue funcionando y solo se para el reloj de juego.

Confianza y seguridad

Un esquema es código y se ejecuta con los mismos permisos que tú (puede leer y escribir archivos, puede conectarse a la red). Por eso:

Los esquemas de installed/ no son de confianza por defecto: Farsight y el ejecutor se niegan a ejecutarlos hasta que pulses “Confiar”;
Sustituir la instalación de un esquema con el mismo id restablece la confianza (una versión nueva es código nuevo);
Al importar se comprueba que el zip no pase de 50 MB ni de 2000 archivos; no se admiten rutas absolutas ni .. (para impedir escribir fuera del directorio del esquema); si el manifiesto no es válido o el archivo de entrada no existe, se rechaza directamente.

Antes de confiar, pulsa “Abrir carpeta” y lee el código. Acepta esquemas solo de gente de la que te fíes.

API (para scripts)

Endpoint	Descripción
`GET /api/schemes`	Lista de esquemas + resultados + el esquema elegido y el que se está ejecutando en cada instancia
`GET /api/schemes/results?ref=`	Las últimas 30 partidas de un esquema
`POST /api/schemes/import`	Importar un zip
`GET /api/schemes/export?ref=`	Descargar el zip
`POST /api/schemes/fork`	Copiar a los míos
`POST /api/schemes/trust`	Confiar
`DELETE /api/schemes?ref=`	Eliminar (se rechaza si alguna instancia lo está usando)
`POST /api/instances/{n}/scheme`	Cambiar el esquema de una instancia: toma el control de esta partida al instante, o se aplica en la próxima prueba

En Python se usa directamente la biblioteca: from openwar3 import schemes (list_schemes, install_zip, export_zip, fork, trust, stats…).

Más adelante: web de esquemas

El zip exportado es la unidad que se comparte, así que la web solo tiene que añadir una capa por fuera: subir con un clic desde Farsight; descargar desde la web, con exactamente las mismas comprobaciones que “Importar esquema” y la misma confirmación de confianza; y, si quieres, enviar los resultados para que la web agregue el porcentaje de victorias por versión. En Farsight ya está reservado el sitio del botón “Compartir en la web de esquemas”. El avance está en la hoja de ruta.