Como atualizar scripts de modificação (API) para D&D 2024/Beacon

7 de Novembro de 2025 18:33

Devido às diferenças entre a infraestrutura da folha legada & e a infraestrutura da folha Beacon, nem todos os Mod Scripts existentes são compatíveis imediatamente. Felizmente, reunimos a documentação abaixo para auxiliá-lo a atualizar os seus scripts para que possam funcionar com as folhas Beacon (por exemplo, D&D 2024). Também atualizámos os scripts principais para que haja exemplos disponíveis e scripts prontos para utilizar com os seus jogos. Scripts que foram atualizados:

Iniciativa do Grupo
TokenMod
Verificação de Grupo
Informações de estado

Para muitos scripts, atualizá-los para serem compatíveis com a folha de 2024 resume-se a alterar duas coisas: como você obtém e define atributos e como você analisa modelos de rolagem/mensagens de chat. Este documento irá guiá-lo através de ambos, bem como resolver alguns problemas comuns para que possa atualizar qualquer script para ser compatível com a folha D&D2014 e a folha D&D2024.

Quando o seu script for atualizado desta forma, em jogos com folhas Beacon, como D&D2024, os GMs precisarão utilizar o servidor API Experimental para utilizar todos os recursos mais recentes. O servidor Experimental possui todas as funcionalidades do servidor Padrão, portanto, essa alteração não deve afetar outros scripts. No entanto, é recomendável mencionar isso na descrição do script para que os seus utilizadores estejam cientes. Caso não exista uma folha Beacon, o servidor padrão continuará a funcionar com estas funções, uma vez que recorrerá às funções herdadas de obtenção e definição de atributos.

Atualização da configuração/obtenção

A principal alteração entre o acesso aos dados da folha de 2014 e da folha de 2024, em termos de código, é a forma como se obtêm e definem os atributos. Existe agora um novo conjunto de funções assíncronas denominadas getSheetItem e setSheetItem. Aqui está um exemplo de utilização das novas funções:

const getDeathSaveSuccess = async (id) => {
const firstSuccess = await getSheetItem(characterId, "deathsave_succ1");
log(`Primeiro sucesso é ${firstSuccess}`)
}

Caso deseje obter o valor máximo de um atributo (se houver um máximo), é possível passar a propriedade max, como getSheetItem(characterId, "deathsave_succ1", “max”);.

Você observará no código acima que getDeathSaveSuccess está marcado como async. Todas as funções que utilizam getSheetItem deverão empregar este padrão async/await ou utilizar promessas. Aqui está a mesma função acima, reescrita como uma promessa:

const getDeathSaveSuccess = (id) => {
  getSheetItem(characterId, "deathsave_succ1").then((firstSuccess) => {
    log(`Primeiro sucesso é ${firstSuccess}`);
  });
}

Se estiver a tentar obter vários valores de uma só vez ou um após o outro e o restante do seu código depende desses dados, pode aguardar cada valor individualmente ou utilizar Promise.all para resolver todas as promessas de uma só vez e obter o valor final. Caso não faça isso, o valor que receberá será apenas uma promessa pendente, e não o valor real do atributo.

const getSuccesses = (id) => {
  const promises = [];
  promises.push(getSheetItem(characterId, "deathsave_succ1"));
  promises.push(getSheetItem(characterId, "deathsave_succ2"));
  promises.push(getSheetItem(characterId, "deathsave_succ3"));
  Promise.all(promises).then((results) => {
    log(`O primeiro sucesso é ${results[0]}, o segundo sucesso é ${results[1]}, o terceiro sucesso é ${results[2]}`);
  }
}

O código assíncrono pode ter várias implicações na forma como escreve um script, dependendo de como o estruturou. Por exemplo, se houver um script atualmente utilizando getAttrByName dentro de um replace ou map, ele precisará ser dividido em um loop mais compatível com assíncrono, pois essas funções não aguardarão o retorno de um valor antes de continuar.

Vamos voltar ao momento em que escrevi: "Se você está a tentar obter vários valores de uma só vez ou um após o outro e o resto do seu código depende desses dados". O restante do seu código nem sempre depende desse valor. Na maioria das vezes, ele dependerá desse valor se estiver a utilizar getSheetItem, porque desejará realizar alguma ação com o atributo que estiver a obter. No entanto, muitas vezes, para o inverso, setSheetItem, não é necessário aguardar a conclusão. Nesse caso, pode ignorar as ramificações dessas funções serem assíncronas e simplesmente chamá-las normalmente. O atributo será atualizado em segundo plano enquanto o seu script continua a ser executado.

A função setSheetItem funciona da mesma forma que getSheetItem, mas inclui um argumento adicional para determinar o valor a ser atribuído ao atributo.

setSheetItem(characterId, "hp", 10);
setSheetItem(characterId, "hp", 20, "max");

Atualização da análise de rolos

Outro aspecto que muitos scripts 5e realizam e que necessita de atualização é a análise de jogadas. Os rolos enviados para o chat são formatados de maneira completamente diferente e precisarão ser analisados de forma distinta para obter resultados ou obter detalhes sobre o conteúdo. A equipa de desenvolvimento adicionou alguns atributos de dados ao HTML que minimizarão a necessidade de uma análise HTML extensa. No entanto, caso necessite de dados mais complexos, poderá ainda ser necessário analisá-los a partir da mensagem enviada para o chat. Descrevemos abaixo algumas necessidades comuns para o auxiliar a começar.

Para obter o resultado de um lançamento no nosso modelo padrão de lançamento:

const rollResultMatch = msg.content.match(/data-result="(.+?)"/);

Para verificar que tipo de rolo é com base no título:

const deathSaveMatch = msgContent.match(/header__title">Insira o cabeçalho aqui<\/div>/);

Para verificar a legenda do rolo e descobrir informações como nível de feitiço ou tipo de dano:

const spellLevelMatch = msgContent.match(/header__subtitle">Level (.+?) /);

Como a folha de 2024 ainda está em desenvolvimento ativo, existe a possibilidade de que ocorram alterações nos modelos de rolo, o que exigirá atualizações adicionais nos seus scripts. Não podemos garantir que a análise de cadeias de caracteres do HTML permanecerá estável para sempre, mas estamos a trabalhar para criar modelos mais padronizados à medida que desenvolvemos a folha. Os exemplos acima são um pouco rígidos em suas expressões regulares para simplificar, mas recomendamos o uso de correspondência aproximada e curingas para tornar sua correspondência mais robusta enquanto os modelos de rolo ainda estão em fluxo.

Problemas comuns

Erro: Não foi encontrado nenhum atributo ou campo de folha para character_id (SEU ID AQUI) denominado (SEU ATRIBUTO AQUI)

Causa provável: provavelmente está a utilizar a API padrão em vez da API experimental e está a tentar aceder a uma propriedade computada do Beacon. Ao clicar em «Reiniciar servidor», certifique-se de que a mensagem de reinício da API inclui a palavra EXPERIMENTAL e não DEFAULT. Se o menu suspenso estiver definido como Experimental, mas os registos de reinicialização indicarem DEFAULT, volte para Default, reinicie e, em seguida, volte para Experimental e reinicie novamente. Este é um problema conhecido relacionado à alternância entre Padrão e Experimental, que estamos atualmente a investigar.

O resultado de getSheetItem está a registar um objeto vazio em vez de um valor.

Causa provável: não aguardar ou utilizar .then na função getSheetItem. É necessário aguardar o retorno do valor antes de prosseguir com o código.