Come aggiornare gli script delle mod per D&D 2024/Beacon

28 settembre 2026 14:52

A causa delle differenze tra l’infrastruttura delle schede classiche e quella delle schede Beacon, non tutti gli script Mod esistenti funzionano con le schede Beacon così come sono. Le note riportate di seguito La aiuteranno ad aggiornare gli script affinché funzionino con le schede Beacon (ad esempio D&D 2024). Abbiamo inoltre aggiornato diversi script fondamentali, in modo da mettere a vostra disposizione esempi e script pronti all’uso per i vostri giochi. Script che sono stati aggiornati:

Iniziativa di gruppo
TokenMod
Verifica di gruppo
Informazioni sullo stato

Per molti script, renderli compatibili con la scheda 2024 si riduce a due modifiche: il modo in cui si recuperano e si impostano gli attributi e il modo in cui si analizzano i template di tiro e i messaggi di chat. Il presente documento illustra entrambe le versioni e tratta anche i problemi più comuni, in modo da consentirLe di aggiornare uno script affinché funzioni sia con la scheda D&D 2014 sia con la scheda D&D 2024.

Le proprietà calcolate di Beacon e gli attributi personalizzati user.* richiedono Mod Script Sandbox v1.5 (Campaign().sandboxVersion === "1.5"). La versione 1.5 è l'attuale sandbox predefinita. I metodi getSheetItem e setSheetItem sono presenti sia nella versione 1.0 che nella versione 1.5. Nella versione 1.0 si ricorre alle funzioni get/set degli attributi classici, pertanto i giochi privi di una scheda Beacon continuano a funzionare. Nella versione 1.5 leggono e scrivono anche le proprietà calcolate di Beacon e i campi user.*. Solo per Mod Script sandbox v1.5. getComputed, setComputed e performAction (vedere “Mod Scripts: Documentazione sulle funzioni”).

Se il menu a tendina della sandbox di un gioco presenta ancora le etichette “Predefinito” e “Sperimentale”, verifichi la sandbox in esecuzione tramite Campaign().sandboxVersion anziché in base all’etichetta. Le proprietà calcolate di Beacon richiedono il valore "1,5".

Aggiornamento delle funzioni get/set

La principale differenza tra l'accesso ai dati della scheda 2014 e quella della scheda 2024, dal punto di vista del codice, riguarda il modo in cui si ottengono e si impostano gli attributi. È ora disponibile una serie di funzioni asincrone denominate getSheetItem e setSheetItem. Di seguito è riportato un esempio di utilizzo delle nuove funzioni:

const getDeathSaveSuccess = async (id) => {
  const firstSuccess = await getSheetItem(characterId, "deathsave_succ1");
  log(`Il primo successo è ${firstSuccess}`);
}

Se desiderate ottenere il valore massimo di un attributo (qualora esista), potete specificare la proprietà "max", ad esempio: getSheetItem(characterId, "deathsave_succ1", "max");.

Noterete nel codice sopra riportato che la funzione ` getDeathSaveSuccess ` è contrassegnata come asincrona. Tutte le funzioni che utilizzano getSheetItem dovrebbero adottare questo modello async/await oppure ricorrere alle promesse. Ecco la stessa funzione riscritta come promise:

const getDeathSaveSuccess = (id) => {
  getSheetItem(characterId, "deathsave_succ1").then((firstSuccess) => {
    log(`Il primo successo è ${firstSuccess}`);
  });
}

Se sta cercando di ottenere più valori contemporaneamente (o uno dopo l’altro) e il resto del suo codice dipende da tali dati, può attendere ogni valore singolarmente oppure utilizzare `Promise.all` per risolvere tutte le promesse in una sola volta e ottenere i valori finali. In caso contrario, il valore che otterrà sarà una promessa in sospeso, non il valore effettivo dell’attributo.

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(`Il primo successo è ${results[0]}, il secondo successo è ${results[1]}, il terzo successo è ${results[2]}`);
  });
}

Il codice asincrono può avere diverse implicazioni sul modo in cui si scrive uno script, a seconda di come lo si è strutturato. Ad esempio, se uno script utilizza attualmente la funzione `getAttrByName` all’interno di un’istruzione `replace` o `mappa`, sarà necessario suddividerlo in un ciclo più compatibile con l’asincronia, poiché tali funzioni non attendono il ritorno di un valore prima di proseguire.

Torniamo alla frase: «Se state cercando di ottenere più valori contemporaneamente o uno dopo l’altro e il resto del vostro codice dipende da tali dati». Il resto del Suo codice non dipende sempre da quel valore. Nella maggior parte dei casi sarà così se utilizza la funzione `getSheetItem`, poiché intende utilizzare l’attributo che sta recuperando. Per quanto riguarda l'operazione inversa, setSheetItem, spesso non è necessario attendere che venga completata. In tal caso, può ignorare le implicazioni relative all'asincronia e richiamarla semplicemente come di consueto. L'attributo verrà aggiornato in background mentre lo script continua a essere eseguito.

La funzione setSheetItem funziona allo stesso modo di getSheetItem, ma include un argomento aggiuntivo per il valore da impostare:

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

Aggiornamento dell’analisi dei ruoli

Un altro aspetto che molti script per la 5e presentano e che necessita di un aggiornamento è l'analisi dei tiri di dado. I roll inviati nella chat hanno una formattazione diversa e devono essere analizzati in modo diverso per ottenere risultati o dettagli sul contenuto. Il team di sviluppo ha aggiunto alcuni attributi di dati al codice HTML che riducono la necessità di un’analisi approfondita del codice HTML. Se avete bisogno di dati più complessi, potrebbe comunque essere necessario estrarli dal messaggio inviato alla chat. Di seguito sono riportate alcune esigenze comuni.

Per ottenere il risultato di un lancio nel template di tiro standard:

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

Per verificare di che tipo di rotolo si tratti in base al titolo:

const deathSaveMatch = msgContent.match(/header__title">Inserisca qui l'intestazione<\/div>/);

Per verificare la descrizione del tiro e trovare informazioni quali il livello dell'incantesimo o il tipo di danno:

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

Poiché la scheda 2024 è ancora in fase di sviluppo attivo, i template di tiro potrebbero subire modifiche e richiedere ulteriori aggiornamenti dello script. Non possiamo garantire che l’analisi sintattica delle stringhe HTML rimarrà stabile per sempre, ma stiamo lavorando per ottenere modelli più standardizzati man mano che la scheda si evolve. Gli esempi sopra riportati presentano espressioni regolari piuttosto rigide per motivi di semplicità; Le consigliamo di utilizzare criteri di corrispondenza più flessibili e caratteri jolly per rendere la corrispondenza più robusta, fintanto che i modelli sono ancora in fase di definizione.

Problemi comuni

Errore: non è stato trovato alcun attributo o campo della scheda per character_id (IL VOSTRO ID QUI) denominato (IL VOSTRO ATTRIBUTO QUI)

Probabile causa: sta utilizzando Mod Script sandbox v1.0 anziché la v1.5 e sta tentando di accedere a una proprietà calcolata di Beacon. Verifichi che Campaign().sandboxVersion sia "1.5". Se il menu a tendina della sandbox riporta ancora le diciture “Predefinita” e “Sperimentale”, è possibile che l’etichetta non sia aggiornata; si raccomanda di riavviare il sistema e verificare il valore di sandboxVersion (nonché il log di riavvio), anziché fare affidamento esclusivamente sul menu a tendina.

Il risultato di getSheetItem registra un oggetto vuoto invece di un valore.

Probabile causa: mancata attesa o mancato utilizzo di .then nella funzione getSheetItem. È necessario attendere il ritorno del valore prima di procedere con il codice.