Scripts

Los scripts (.vs) son el lenguaje con el que el juego programa la IA, las habilidades, las condiciones de victoria y el comportamiento de edificios y unidades. Un mod puede traer los suyos y usar las funciones nuevas (Mod_...) de Imperivm Resurrected.

Ejemplo para copiar: ejemplos/scripts-ejemplo. Ojo: ese ejemplo cambia el equilibrio (los hastatus hacen el doble de daño y se curan al matar), así que no lo actives en una partida en serio.

Cómo es un script

Un archivo de texto .vs. La primera línea es un comentario con la firma: lo que devuelve y los parámetros que recibe. Cada sitio donde se usa un script espera una firma concreta. Los comportamientos de una clase (<behavior script="...">) son la excepción: el juego los carga siempre como void, Obj This, lleven la línea o no.

// void, Obj This

Sleep(rand(500) + 100);
Mod_Log("Ha entrado en el mapa un hastatus romano");
while(true) Sleep(50000);

Para ver cómo escribe el juego los suyos, vuélcalos con Dump= (ver Parches; hay que dar cada archivo por su nombre, sin comodines) o míralos en la carpeta DATA que saca extraer-datos.js: data/subai/*.vs (comportamientos y habilidades), data/ai/*.vs (IA) y data/GameScripts/*.vs (victoria). Todas las funciones del lenguaje, con su firma, están en funciones-del-juego.txt.

Dónde se engancha un script

ondie y onkill son métodos (<method sig=...>), no atributos. Si escribes ondie="..." en la clase no pasa nada, y el juego no avisa.

Un script de comportamiento no debe terminar: acábalo con while(true) Sleep(50000);.

Una clase solo admite 8 <behavior>.

Eventos

Pon un script en events\<Evento>.vs dentro de tu mod y el juego lo ejecuta cuando ocurre el evento, en todos los PCs a la vez. Si varios mods tienen el mismo evento, se ejecutan todos. Para probar sin crear un mod, ponlo en <juego>\mod\events\<Evento>.vs.

Salvo OnGameStart, los eventos se ejecutan al momento y no pueden esperar: nada de Sleep. OnAttackResolved y OnObjectDie saltan muchas veces por segundo en una batalla. Filtra pronto lo que no te interesa (if (!victim.IsValid) return;, victim.IsMilitary, victim.player, victim.IsHeirOf("RHastatus")…) y no hagas trabajo caro.

En OnSettlementCaptured, building es un Obj. Para llegar a su asentamiento pasa por AsBuilding: building.AsBuilding.settlement.

Con OnObjectKill se hacen habilidades pasivas. Un hastatus que se cura al matar:

// void, Obj killer, Obj victim
if (!killer.IsValid) return;
if (!killer.IsHeirOf("RHastatus")) return;
if (!victim.IsMilitary) return;
killer.Heal(25);

Con varios mods en OnAttackResolved, damage es siempre el daño original: se calcula una vez. Dos mods que hagan Mod_SetAttackDamage(damage * 2) no se acumulan. Si quieres sumarte a lo que ya cambió otro mod, parte de Mod_AttackDamage().

Reaccionar a que aparezca un objeto

No hay un evento para esto (los objetos se crean en decenas de sitios, también al cargar un mapa o una partida). Se hace con un comportamiento: un <behavior> añadido con un parche a una clase base (Military para todos los soldados, Unit para todas las unidades) lo heredan todas las clases que cuelgan de ella, y corre una vez con cada objeto cuando aparece. Mira patches\data\classes\Military.sc.xml y data\mod\soldier.vs en el ejemplo.

Funciones Mod_

La versión actual de la API es la 7. Mod_ApiVersion() te la da, y un mod puede exigir una mínima.

Las funciones nuevas se añaden al final y las que ya existen no cambian. Si tu mod usa alguna, necesita una versión de Imperivm Resurrected que la traiga. La versión de la API entra en la comprobación de multijugador cuando hay mods de jugabilidad: todos tienen que tener la misma.

Variables de mods

Una tabla de nombre → entero para que tu mod se acuerde de cosas (contadores, marcas, tiempos):

Mod_AddInt("capturas", 1);
if (Mod_GetInt("capturas") >= 3) ...

• Se guardan con la partida (también con los autoguardados) y vuelven al cargarla. Una partida nueva empieza sin variables.
• Son iguales en todos los PCs porque los scripts de partida corren igual en todos. Cámbialas solo desde scripts de partida, nunca según algo local.
• Nombres de hasta 64 letras, hasta 1.024 variables, enteros de 32 bits.
• Son de la partida entera, no de un jugador. Para una por jugador, ponle el jugador al nombre ("oro1", "oro2").
• Se comparten entre todos los mods activos: usa un prefijo propio ("mimod_capturas").

Multijugador

Los scripts forman parte de la simulación: se ejecutan en todos los PCs, en el mismo momento, y tienen que hacer lo mismo en todos.

• Lee solo cosas iguales para todos: los objetos del mapa, el tiempo de juego, el rand() del juego.
• No leas nada local: la cámara, el jugador que mira, la música, el ratón, la hora del sistema. Si el script cambia la partida según algo local, la partida se desincroniza.
• Si algo nace de una tecla o de la interfaz, tiene que ir como una orden del juego, que viaja por la red. Ver Teclas de los mods.

Partidas guardadas

Una partida guardada lleva dentro el código de los scripts que estaban corriendo. Por eso las funciones del SDK no cambian de número y solo se añaden al final: lo guardado sigue cargando. No reutilices nombres de funciones del juego (Run, Write…) como si fueran tuyos.

Errores

• Un script que no compila deja el error (archivo, línea y columna) en Logs\imperivm\imperivm-mod.log, como script: compilation error: … (nivel E), y también en Logs\comp_out.txt y Logs\vxlog.log. El juego sigue, pero ese script no se ejecuta.
• Los errores al ejecutarse el juego casi nunca los registra. En los eventos sí: el log apunta Event X (…): the script ended with an error, hasta 5 veces por script. Para lo demás, usa Mod_Log y mira el registro.