Scripts de modificação: Depuração

Sempre que estiver a escrever programas (desde os mais simples aos mais avançados), irá inevitavelmente deparar-se com erros que provocam o mau funcionamento do programa. Devido à natureza da sandbox, pode ser um pouco difícil perceber exatamente o que se está a passar. Aqui ficam, portanto, algumas sugestões que pode utilizar para o ajudar a diagnosticar problemas nos seus scripts.

Depuração «à moda dos homens das cavernas»

Uma vez que não tem acesso direto ao ambiente em que os scripts estão a ser executados, pode recorrer a um grande número de chamadas à função log() para saber o que se está a passar com o seu programa. Por exemplo, se não tiver a certeza do motivo pelo qual um token não está a funcionar corretamente e pretender compreender melhor os valores que estão a ser utilizados, poderá proceder da seguinte forma:

on("change:graphic:left", function(obj) {
  //Qual é o valor da coluna «esquerda» do objeto que está a ser passado para esta função?
  log(obj.get("left"));
  obj.set("left", obj.get("left") + 70);
  //Qual é o valor agora?
  log(obj.get("left"));
  //Também é possível depurar objetos na íntegra para visualizar uma lista dos seus atributos atuais
  log(obj);
});

Encontrará os resultados dos seus comandos log() na Consola de Saída do Mod, que se encontra na página de Configurações dos Scripts do Mod da sua campanha.

Apenas para o Mod Script Sandbox v1.5. Sempre que possível, as mensagens de erro incluem um objeto de contexto, para que possa ver qual o objeto do Roll20 que esteve envolvido (tipo e ID):

ERRO: a função toBelow() deve ser chamada com um objeto gráfico, de texto ou de percurso do Roll20. Chamado com [Personagem do Roll20 -NM0tVij02hIfnoTdihc].

Bloqueios por erro

O ambiente de teste irá recuperar-se automaticamente de pequenos erros no seu script, reiniciando-o sempre que necessário. No entanto, caso detete um erro grave do qual não consiga recuperar, em vez de simplesmente reiniciar o seu script repetidamente, apenas para que este continue a apresentar erros, o sistema aplicará um «bloqueio por erro» à sua Campanha, o que fará com que os seus scripts de modificação não sejam executados até que o erro seja resolvido. Se os seus scripts tiverem sido bloqueados devido a erros, irá ver uma mensagem como esta na página «Definições de scripts de mod»:

Não se preocupe! Basta introduzir alterações nos seus scripts para tentar resolver o problema e, em seguida, clicar no botão «Guardar Script ». Quando o fizer, o bloqueio devido ao erro será eliminado e a sandbox tentará executar os seus scripts novamente. Caso ocorra outro erro, o bloqueio de erros será reaplicado. Pode repetir este processo tantas vezes quantas forem necessárias para corrigir o erro; nunca lhe será impedido de eliminar os bloqueios de erro por ter falhado demasiadas vezes.

Pilha de chamadas específica do script

As pilhas de chamadas mostram os nomes dos scripts e os números das linhas.

Os erros incluem uma pilha de chamadas reescrita que indica o nome do script e a linha, e não o ficheiro da sandbox concatenado. Os scripts manuais são identificados com a indicação «SCRIPT», seguida do nome que atribuiu ao separador, do número do separador, da linha em que ocorreu o erro e do deslocamento da coluna:

Exemplo: SCRIPT: Script «Bad Actor» [Separador 85]:3

Os scripts da biblioteca «com um clique» são os mesmos, mas a designação é «1-CLICK»:

A pilha de chamadas completa será traduzida; assim, caso tenha vários scripts a chamar outros scripts, poderá identificar onde tudo isso está a ocorrer.

Detetado possível ciclo infinito – Detalhes adicionais

Se a sandbox deixar de enviar sinais de atividade, encerra-se, podendo entrar num ciclo infinito. Poderá ver o evento e onde foi registada a função de retorno que estava a ser executada. Isto contribui significativamente para identificar onde ocorre um problema e deverá acelerar consideravelmente a procura de soluções.

• Evento: alteração:gráfico
• Chamada de retorno: na linha 37 do script «Bad Actor»

Erros comuns

Abaixo estão alguns erros mais comuns:

myvar não está definido

on("ready", function() {
  var myVar;
  log(myvar);
});

Embora a mensagem de erro indique «não definido», o que realmente aconteceu foi que a variável não foi declarada. Uma das causas mais comuns para isso é um erro ortográfico no nome de uma das suas variáveis, como a falta de uma letra maiúscula.

Não é possível ler a propriedade «myProperty» ou não é possível chamar o método «myMethod»

on("ready", function() {
  var myVar;
  log(myVar.myProperty);
  log(myVar.myMethod());
});

myVar não está definida, pelo que o script não consegue determinar como lidar com a sua tentativa de aceder a uma propriedade de myVar. Isso provavelmente se deve a um dos seguintes motivos:

• Tentou encontrar um objeto com getObj ou findObjs, mas o resultado foi indefinido. Realize algumas verificações de erros para garantir que a sua variável esteja definida antes de aceder às suas propriedades.
• A sua variável está a ser definida condicionalmente (através de uma série de instruções «if» ou algo semelhante) e nenhuma das suas condições foi satisfeita; por isso, a sua variável ficou declarada, mas nunca foi definida. Certifique-se de que possui condições para todas as possibilidades, crie uma opção padrão ou execute uma verificação de erros para garantir que a sua variável esteja definida antes de aceder às suas propriedades.

Os objetos do Roll20 também necessitam de métodos «get » e «set». obj.left não corresponde à posição do tampo da mesa; utilize obj.get("left").

Token inesperado

Está a faltar um caractere ou há um caractere a mais. Isso pode ocorrer devido à omissão de uma vírgula entre uma lista de propriedades em um objeto ou elementos em uma matriz, ou devido ao excesso ou falta de parênteses de fechamento no final de uma chamada de método aninhado complexo.

_displayname devolve «undefined», enquanto que get("_displayname") devolve um nome

A maioria das propriedades dos objetos do Roll20 tem de ser acedida através dos métodos get() e set(). Ao utilizar o método get(), pode omitir o sublinhado inicial nas propriedades de apenas leitura: obj.get("displayname") equivale a obj.get("_displayname"). obj._displayname não é.

Se continuar a ter problemas, não hesite em criar uma publicação no nosso Fórum de Scripts de Mods. Inclua o texto do erro apresentado na consola e uma breve descrição do resultado que esperava.