Per molti script, l'aggiornamento per essere compatibili con il foglio 2024 si riduce a cambiare due cose: il modo in cui ottiene e imposta gli attributi e il modo in cui analizza i modelli di rotolo/messaggi di chat. Questo documento la guiderà in entrambi i casi, oltre a risolvere alcuni problemi comuni, in modo che possa aggiornare qualsiasi script per essere compatibile sia con il foglio D&D2014 che con il foglio D&D2024.
Quando il suo script viene aggiornato in questo modo, nei giochi con fogli Beacon come D&D2024, i GM dovranno utilizzare il server API sperimentale per utilizzare tutte le ultime funzionalità. Il server Sperimentale ha tutte le stesse funzionalità del server Predefinito, quindi non dovrebbe interrompere nessun altro script per fare questo passaggio, ma potrebbe volerlo segnalare nella descrizione dello script in modo che i suoi utenti lo sappiano. Se non c'è un foglio Beacon, il server Default continuerà a lavorare con queste funzioni, poiché tornerà alle funzioni legacy di ottenimento e impostazione degli attributi.
Aggiornamento Impostazione/ottenimento
Il cambiamento principale tra l'accesso ai dati per il foglio 2014 e il foglio 2024, dal punto di vista del codice, è il modo in cui si ottengono e si impostano gli attributi. Ora c'è una nuova serie di funzioni asincrone chiamate getSheetItem e setSheetItem. Ecco un esempio di utilizzo delle nuove funzioni:
const getDeathSaveSuccess = async (id) => {
const firstSuccess = await getSheetItem(characterId, "deathsave_succ1");
log(`First success is ${firstSuccess}`)
}
Se desidera ottenere il valore massimo di un attributo (se esiste un massimo), può inserire la proprietà max, come getSheetItem(characterId, "deathsave_succ1",
" max");.
Noterà che nel codice qui sopra, getDeathSaveSuccess è contrassegnato come async. Ogni funzione che utilizza getSheetItem dovrà utilizzare questo schema async/await, oppure utilizzare le promesse. Ecco la stessa funzione precedente, riscritta come promessa:
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 si basa sull'avere questi dati, può attendere ogni valore individualmente, oppure utilizzare Promise.all per risolvere ogni promessa in una volta e ottenere il valore finale. Se non lo fa, il valore che otterrà sarà solo 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(`Primo successo è ${risultati[0]}, secondo successo è ${risultati[1]}, terzo successo è ${risultati[2]}`);
}
}
Il codice asincrono può avere molte ramificazioni sul modo in cui scrive uno script, a seconda di come lo ha strutturato. Per esempio, se c'è uno script che attualmente utilizza getAttrByName all'interno di una replace o di una map, dovrà essere suddiviso in un ciclo più asincrono, perché queste funzioni non aspetteranno il ritorno di un valore prima di continuare.
Torniamo indietro a quando ho scritto: "Se sta cercando di ottenere più valori contemporaneamente o uno dopo l'altro e il resto del suo codice si basa sulla disponibilità di questi dati". Il resto del suo codice non si basa sempre sulla presenza di questo valore. Nella maggior parte dei casi, si baserà su quel valore se utilizza getSheetItem, perché vorrà fare qualcosa con qualsiasi attributo ottenuto. Tuttavia, spesso per l'operazione inversa, setSheetItem, non è necessario attendere che finisca del tutto. In questo caso, può ignorare le ramificazioni del fatto che queste funzioni siano asincrone e chiamarle normalmente. L'attributo si aggiornerà in background mentre il suo script va avanti.
La funzione setSheetItem funziona come getSheetItem, ma include un argomento aggiuntivo per determinare a cosa impostare l'attributo.
setSheetItem(characterId, "hp", 10);
setSheetItem(characterId, "hp", 20, "max");
Aggiornamento del parsing dei rotoli
L'altra cosa che molti script della 5e fanno e che deve essere aggiornata è l'analisi dei tiri. I rotoli inviati alla chat sono formattati in modo completamente diverso e dovranno essere analizzati in modo diverso per ottenere risultati o conoscere i dettagli del contenuto. Il team di sviluppo ha aggiunto alcuni attributi di dati all'HTML che ridurranno al minimo la necessità di un'analisi approfondita dell'HTML, ma se ha bisogno di dati più complessi, potrebbe comunque doverli analizzare nel messaggio inviato alla chat. Di seguito abbiamo delineato alcune esigenze comuni per aiutarla a iniziare.
Per ottenere il risultato di un lancio nel nostro modello di lancio standard:
const rollResultMatch = msg.content.match(/data-result="(.+?)"/);
Per verificare che tipo di rotolo è in base al titolo:
const deathSaveMatch = msgContent.match(/header__title">Inserire l'intestazione qui<\/div>/);
Per controllare il sottotitolo del lancio per scoprire cose come il livello dell'incantesimo o il tipo di danno:
const spellLevelMatch = msgContent.match(/header__subtitle">Level (.+?) /);
Poiché il foglio 2024 è ancora in fase di sviluppo attivo, c'è la possibilità che le cose cambino con i modelli di rotolo che richiederanno ulteriori aggiornamenti ai suoi script. Non possiamo promettere che il parsing delle stringhe dell'HTML rimarrà stabile per sempre, ma stiamo lavorando per ottenere modelli più standardizzati, man mano che sviluppiamo ulteriormente il foglio. Gli esempi precedenti sono un po' rigidi nella loro regex per semplicità, ma consigliamo di utilizzare la corrispondenza fuzzy e i caratteri jolly per rendere la corrispondenza più robusta mentre i modelli di rotolo sono ancora in evoluzione.
Problemi comuni
"Errore: Non è stato trovato alcun attributo o campo del foglio per il personaggio_id (IL TUO ID QUI) chiamato (IL TUO ATTRIBUTO QUI)".
Causa probabile: Probabilmente si trova nell'API predefinita anziché nell'API sperimentale e sta cercando di accedere a una proprietà calcolata da Beacon. Quando clicca su "Riavvia il server", si assicuri che il messaggio di riavvio dell'API includa la parola EXPERIMENTAL e non DEFAULT. Se il menu a tendina è impostato su Experimental ma i registri di riavvio dicono DEFAULT, torni a Default, riavvii, quindi torni a Experimental e riavvii di nuovo. Si tratta di un problema noto che riguarda lo scambio tra Default ed Experimental e che stiamo attualmente esaminando.
Il risultato di getSheetItem sta registrando un oggetto vuoto invece di un valore
Causa probabile: non attendere o utilizzare .then sulla funzione getSheetItem. Deve attendere il ritorno del valore prima di procedere con il codice.