Considerate le differenze tra l'infrastruttura classica dei fogli & e l'infrastruttura dei fogli Beacon, non tutti gli script Mod esistenti sono immediatamente compatibili. Fortunatamente, abbiamo raccolto la documentazione riportata di seguito per assistervi nell'aggiornamento dei vostri script in modo che possano funzionare con le schede Beacon (ad esempio D&D 2024). Abbiamo inoltre aggiornato gli script principali, pertanto sono disponibili esempi e script pronti per l'utilizzo con i vostri giochi. Script aggiornati:
- Iniziativa di gruppo
- TokenMod
- Controllo di gruppo
- Informazioni sullo stato
Per molti script, l'aggiornamento per renderli compatibili con la scheda 2024 comporta essenzialmente due modifiche: il modo in cui si ottengono e si impostano gli attributi e il modo in cui si analizzano i template di tiro/messaggi di chat. Questo documento illustra entrambe le procedure e fornisce soluzioni ad alcuni problemi comuni, consentendo di aggiornare qualsiasi script per renderlo compatibile sia con la scheda D&D2014 che con la scheda D&D2024.
Quando lo script viene aggiornato in questo modo, nei giochi con schede Beacon come D&D2024, i GM dovranno utilizzare il server API sperimentale per poter usufruire di tutte le funzionalità più recenti. Il server sperimentale presenta tutte le funzionalità del server predefinito, pertanto il passaggio non dovrebbe causare problemi agli altri script; tuttavia, si consiglia di indicarlo nella descrizione dello script per informare gli utenti. Se non è presente una scheda Beacon, il server predefinito continuerà a funzionare con queste funzioni, poiché ricorrerà alle funzioni classiche di acquisizione e impostazione dell'attributo.
Aggiornamento delle impostazioni/Acquisizione
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 nuova 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(`Primo successo è ${firstSuccess}`)
}
Se desiderate ottenere il valore massimo di un attributo (qualora esista un valore massimo), potete inserire la proprietà max, come getSheetItem(characterId, "deathsave_succ1",
"max");.
Si noterà nel codice sopra riportato che getDeathSaveSuccess è contrassegnato come async. Ogni funzione che utilizza getSheetItem dovrà utilizzare questo modello async/await o ricorrere alle promesse. Di seguito è riportata la stessa funzione sopra, riscritta come promessa:
const getDeathSaveSuccess = (id) => {
getSheetItem(characterId, "deathsave_succ1").then((firstSuccess) => {
log(`Primo successo è ${firstSuccess}`);
});
}
Se si sta cercando di ottenere più valori contemporaneamente o uno dopo l'altro e il resto del codice si basa su tali dati, è possibile attendere ogni valore singolarmente oppure utilizzare Promise.all per risolvere tutte le promesse contemporaneamente e ottenere il valore finale. Se non si esegue questa operazione, il valore restituito 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(`Il primo successo è ${results[0]}, il secondo successo è ${results[1]}, il terzo successo è ${results[2]}`);
}
}
Il codice asincrono può avere molte implicazioni sul modo in cui si scrive uno script, a seconda di come lo si è strutturato. Ad esempio, se uno script utilizza attualmente getAttrByName all'interno di un replace o di una mappa, sarà necessario suddividerlo in un ciclo più compatibile con l'asincronia, poiché tali funzioni non attendono il ritorno di un valore prima di continuare.
Torniamo indietro a quando ho scritto: "Se si sta cercando di ottenere più valori contemporaneamente o uno dopo l'altro e il resto del codice si basa su tali dati". Il resto del codice non dipende sempre dalla presenza di quel valore. Nella maggior parte dei casi, se si utilizza getSheetItem, si farà affidamento su quel valore, poiché si desidererà eseguire un'operazione con qualsiasi attributo si ottenga. Tuttavia, spesso per l'operazione inversa, setSheetItem, non è necessario attendere che venga completata. In tal caso, è possibile ignorare le implicazioni dell'asincronia di queste funzioni e richiamarle normalmente. L'attributo verrà aggiornato in background mentre lo script prosegue.
La funzione setSheetItem funziona allo stesso modo di getSheetItem, ma include un argomento aggiuntivo per determinare il valore da assegnare all'attributo.
setSheetItem(characterId, "hp", 10);
setSheetItem(characterId, "hp", 20, "max");
Aggiornamento dell'analisi dei roll
Un altro aspetto che molti script 5e devono aggiornare è l'analisi dei tiri di dado. I roll inviati alla chat sono formattati in modo completamente diverso e richiedono un'analisi diversa per ottenere risultati o acquisire dettagli sul 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 avete bisogno di dati più complessi potrebbe essere comunque necessario analizzarli dal messaggio inviato alla chat. Di seguito abbiamo elencato alcune esigenze comuni per assistervi in questa fase iniziale.
Per ottenere il risultato di un lancio nel nostro template di tiro standard:
const rollResultMatch = msg.content.match(/data-result="(.+?)"/);
Per verificare il tipo di ruolo in base al titolo:
const deathSaveMatch = msgContent.match(/header__title">Inserire intestazione qui<\/div>/);
Per verificare il sottotitolo del tiro per determinare aspetti 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, è possibile che vi siano modifiche ai template di tiro che potrebbero richiedere ulteriori aggiornamenti ai vostri script. Non possiamo garantire che l'analisi delle stringhe HTML rimarrà stabile in futuro, ma stiamo lavorando per ottenere modelli più standardizzati man mano che sviluppiamo ulteriormente la scheda. Gli esempi sopra riportati sono piuttosto rigidi nella loro espressione regolare per motivi di semplicità, ma si consiglia di utilizzare la corrispondenza approssimativa e i caratteri jolly per rendere la corrispondenza più robusta mentre i template di tiro sono ancora in fase di cambiamento.
Problemi comuni
Errore: non è stato individuato alcun attributo o campo della scheda per character_id (INSERIRE IL PROPRIO ID QUI) denominato (INSERIRE IL PROPRIO ATTRIBUTO QUI)
Probabile causa: è possibile che si stia utilizzando l'API predefinita anziché l'API sperimentale e si stia tentando di accedere a una proprietà calcolata di Beacon. Quando si fa clic su "Riavvia server", è necessario assicurarsi che il messaggio di riavvio dell'API includa la parola EXPERIMENTAL e non DEFAULT. Se il menu a tendina è impostato su Sperimentale ma i registri di riavvio indicano PREDEFINITO, si prega di tornare a Predefinito, riavviare, quindi tornare a Sperimentale e riavviare nuovamente. Questo è un problema noto relativo al passaggio dalla modalità predefinita a quella sperimentale, che stiamo attualmente esaminando.
Il risultato di getSheetItem registra un oggetto vuoto invece di un valore.
Probabile causa: mancata attesa o utilizzo di .then nella funzione getSheetItem. È necessario attendere il ritorno del valore prima di procedere con il codice.