Scripts Mod (API): Guía de uso avanzado

Para editar los scripts de su juego, haga clic en el enlace «Scripts Mod (API)» en la página Detalles del juego (en el mismo lugar donde se encuentran opciones como «Registro de chat» y «Copiar/Ampliar juego»). Se le presentarán varias funciones:

• Una lista de pestañas en la parte superior. Su juego puede tener varios guiones para facilitar la organización. Tenga en cuenta que todos los scripts se seguirán ejecutando en el mismo contexto, lo que significa que no debe tener varios scripts intentando sobrescribir los mismos valores al mismo tiempo, ya que podría obtener resultados no deseados.
• Un editor de código de script. Puede utilizar este editor o editar sus scripts en un editor externo de su elección y luego pegarlos aquí.
• Una «Consola Mod (API)» situada en la parte inferior (véase más abajo).

Cada vez que haga clic en el botón «Guardar scripts», sereiniciaráel entorno de pruebas de su juego (perdiéndose cualquier dato en memoria que no se haya conservado en el objetode estadoo en los objetos Roll20). Esto también se aplica si añade un nuevo script, elimina un script o activa/desactiva un script.

La consola Mod (API)

La consola Mod (API) es la «ventana» a sus scripts. Dado que los scripts Mod (API) se ejecutan en un entorno aislado, no tiene acceso directo a ellos mientras se están ejecutando para ver información sobre los resultados o errores del script. La consola Mod (API) muestra esta información fuera del entorno de pruebas para que pueda verla mientras edita sus scripts. Aquí se mostrarán todos los comandos log(), así como cualquier error que se produzca durante la ejecución de sus scripts. Para obtener más información, consulte el artículo sobre Depuración de scripts.

Scripts reactivos: escuchar eventos, modificar objetos

El primer tipo (y el más sencillo) de uso de Mod (API) consiste en reaccionar ante los cambios que se producen en el tablero y, a continuación, responder con funcionalidades adicionales a los objetos modificados. Este tipo de script se compone de una serie de funciones que escuchan los eventos que ocurren durante el juego. A continuación, modificará los objetos que se pasan durante esos eventos, lo que cambiará lo que ocurre en la mesa.

Un script básico que mueve una pieza 5 pies adicionales (suponiendo que se utilizan los ajustes predeterminados de la página) sería:

        on("change:graphic", function(obj) {
  obj.set({
    left: obj.get("left") + 70    
  });
});

Como puede ver, hemos creado una función simple que se ejecutará cada vez que se detecte el evento change:graphic. La función recibe el objeto gráfico obj. Para realizar un cambio, solo tenemos que modificar obj utilizando la función set: cualquier propiedad que cambiemos se detectará y modificará en la mesa.

Una nota sobre las funciones de utilidad

Por supuesto, el ejemplo anterior no es muy útil porque siempre añade 70 píxeles a la ubicación del token. Pero, ¿qué pasa si el usuario ha cambiado la escala de modo que 5 pies equivalen a 140 píxeles? La API de Roll20 ofrece varias funciones útiles para ayudar con este (y otros) escenarios comunes. Modifiquemos nuestro ejemplo anterior para utilizar lafunción distanceToPixels, que nos indicará cuántos píxeles equivalen a «cinco pies» (o pulgadas, metros o cualquier otra unidad de distancia que se haya establecido) sobre la mesa.

on("change:graphic", function(obj) {    
  obj.set({        
    left: obj.get("left") + distanceToPixels(5);    
  });
});

Ahora bien, si la página actual está configurada para utilizar el tamaño de cuadrícula predeterminado,distanceToPixels(5);seguirá devolviendo 70 píxeles, pero si la página está configurada para tener una escala dos veces mayor que la normal, devolvería 140.

Siempre es buena idea utilizar funciones de utilidad cuando estén disponibles para evitar que su script se rompa si cambian los ajustes de una página o un token.

Scripts proactivos: hacer cosas sin la intervención del usuario

Además de reaccionar a los eventos de los usuarios, también puede hacer cosas con la API automáticamente que no están vinculadas a un evento específico de los jugadores. Por ejemplo, supongamos que tenemos un token que patrulla de un lado a otro del mapa.

Nota: Aunque este tipo de script no depende de la interacción del usuario, los scripts Mod (API) de su juego solo se ejecutarán cuando al menos una persona esté conectada a su juego.

on("ready", function() {
   //Esperar hasta que se active el evento «ready» para saber que el juego se ha cargado por completo.
   Obtenga una referencia a nuestro token de patrulla.
   var patroltoken = findObjs({_type: "graphic", name: "Guard A"})[0]; //Sabemos que hay un token en el juego llamado «Guard A».
   var dirección = -1*distanciaAPíxeles(5); //Caminar 70 píxeles hacia la izquierda.
   var stepstaken = 0; //¿Cuántos pasos han caminado en la dirección actual?
   setInterval(función() {
     si(pasosdados > 3) {
       //¡Cambie de dirección!
       dirección = dirección * -1; //«invertirá» la dirección en la que estamos caminando
       pasos dados = 0; //restablecerá los pasos a 0.
     }
     patroltoken.set("left", patroltoken.get("left") + direction); //¡caminar!
     stepstaken++;
   }, 5000); //realizar una acción cada 5 segundos
});

Un tratado sobre funciones asíncronas

Una función asíncrona es aquella que devuelve inmediatamente el hilo de control al ámbito de llamada y realiza alguna tarea en segundo plano. Aquí tiene un ejemplo muy sencillo y fácil de entender que puede pegar en la pestaña de scripts Mod (API):

on('load',function(){
  log('Ámbito principal: antes de llamar a la función asíncrona.');

  setTimeout(function(){
    log('Ámbito de la función asíncrona: ejecutando la función asíncrona.');
  },10 /* 10 milisegundos */);

  log('Ámbito principal: después de llamar a la función asíncrona.');
});

En el registro Mod (API), verá algo como esto:

Ámbito del padre: antes de llamar a la función asíncrona.
«Ámbito del padre: después de llamar a la función asíncrona».
Ámbito de la función asíncrona: realizar el trabajo de la función asíncrona.

Al ver ese código, usted piensa: «Por supuesto que sucederá más tarde, le dijo que se ejecutara en 10 milisegundos, ¿no?». Aquí hay un ejemplo menos obvio que tendrá los mismos mensajes de registro:

on('load',function(){
  log('Ámbito principal: antes de llamar a la función asíncrona.');

  sendChat('Async Function','Evaluate this: [[1d6]]',function(msg){
    log('Ámbito de la función asíncrona - Realizando la función asíncrona.');
  });

  log('Ámbito principal - Después de llamar a la función asíncrona.');

Las funciones asíncronas son necesarias para evitar que la API se cuelgue constantemente. Si cada lanzamiento de dados se gestionara de forma sincrónica, la API sería muy lenta y no respondería. Casi cualquier función que vea que toma una devolución de llamada es asíncrona. (Excepción para algunas de las funciones _.map, _.reduce, etc., que son ejemplos de programación funcional en contraste con la programación procedimental a la que la mayoría de ustedes están acostumbrados).