Script di mod: Documentazione sulle funzioni

28 settembre 2026 14:51

Roll20 mette a disposizione una serie di funzioni che non fanno parte del JavaScript di base né di altre librerie.

I giochi potrebbero utilizzare Mod Script sandbox v1.0 (Campaign().sandboxVersion === "1.0") o v1.5 ("1.5"). Funzionalità disponibili esclusivamente nella versione Mod Script sandbox v1.5. non funzionano nella versione 1.0.

Variabili globali

Variabile	Descrizione
`_`	Questo è l'oggetto dello spazio dei nomi della libreria Underscore.js.
`stato/Provincia`	Le proprietà dell'oggetto di stato rimarranno invariate tra una sessione di gioco e l'altra.

_ (trattino basso)

Questo è l'oggetto dello spazio dei nomi relativo alla libreria Underscore.js. Underscore offre numerose funzioni per la manipolazione delle raccolte.

stato/Provincia

Le proprietà dell'oggetto di stato rimarranno invariate tra una sessione di gioco e l'altra. Lo stesso oggetto di stato è condiviso anche tra tutti gli script Mod di una campagna; pertanto, si raccomanda vivamente, quando si scrivono valori nello stato, di ridurre al minimo l’ingombro possibile al fine di evitare conflitti di nomi. Nota: lo stato viene serializzato con JSON, pertanto non è possibile memorizzare funzioni o oggetti con riferimenti ciclici.

Funzioni globali

Tipo di ritorno	Funzione	Descrizione
`Oggetto Roll20`	`Campagna`	Ottiene l'oggetto singleton Campaign Roll20.
`Oggetto Roll20`	`creaOggetto`	Crea un nuovo oggetto Roll20.
`Array di oggetti Roll20`	`filtraObj`	Ottiene tutti gli oggetti Roll20 che superano un test predicato.
`Array di oggetti Roll20`	`trovaOggetti`	Ottiene tutti gli oggetti Roll20 con proprietà che corrispondono a un determinato insieme di attributi.
`Array di oggetti Roll20`	`recuperaTuttiGliOggetti`	Ottiene tutti gli oggetti Roll20 nella campagna.
`varia`	`getAttrByName`	Ottiene il valore corrente o massimo di un oggetto attributo Roll20.
`varia`	`getComputed`	Solo per Mod Script sandbox v1.5. Ottiene una proprietà calcolata di tipo Beacon.
`varia`	`getSheetDefaultValue`	Recupera il valore predefinito della scheda dei personaggi per un determinato nome di attributo.
`varia`	`getSheetItem`	Recupera un articolo della scheda (attributo; nella versione 1.5 anche Beacon / `user.*`).
`Oggetto Roll20`	`getObj`	Ottiene un oggetto Roll20 specifico.
	`registro`	Registra un messaggio nella console di output del modulo.
	`il`	Registra un gestore di eventi.
	`onSheetWorkerCompleted`	Registra un gestore di eventi una tantum da eseguire al termine dell’esecuzione di un’intera serie di script degli sviluppatori di schede.
	`eseguireAzione`	Solo per Mod Script sandbox v1.5. Esegue un'azione della scheda Beacon.
`Booleano`	`giocatoreÈGM`	Verifica se un giocatore dispone attualmente dei privilegi GM.
	`playJukeboxPlaylist`	Iniziare a riprodurre una playlist dal jukebox.
`Numero`	`numero intero casuale`	Genera un valore intero casuale.
	`inviaChat`	Invia un messaggio di chat.
	`inviaPing`	Invia un ping simile a quello che si ottiene tenendo premuto il pulsante sinistro del mouse.
	`setAttrs`	Imposta uno o più attributi su un personaggio.
	`setComputed`	Solo per Mod Script sandbox v1.5. Imposta una proprietà calcolata Beacon scrivibile.
	`setSheetItem`	Imposta un articolo della scheda (attributo; nella versione 1.5 anche Beacon / `user.*`).
	`spawnFx`	Genera un emettitore di particelle.
	`generazione di effetti tra punti`	Genera un emettitore di particelle che si sposta da un punto all'altro.
	`spawnFxWithDefinition`	Genera un emettitore di particelle che non è rappresentato da un oggetto FX Roll20.
	`Interrompere la riproduzione della playlist del jukebox`	Interrompe tutte le playlist attualmente in riproduzione sul jukebox.
	`Torna all'inizio`	Solo per Mod Script sandbox v1.5. Posiziona un oggetto immediatamente sopra un altro sullo stesso livello.
	`Indietro`	Sposta un elemento grafico, un testo, un tracciato o un tracciato v2 sotto gli altri oggetti presenti sul proprio livello.
	`aSotto`	Solo per Mod Script sandbox v1.5. Posiziona un oggetto immediatamente sotto un altro sullo stesso livello.
	`al fronte`	Sposta un elemento grafico, un testo, un tracciato o un tracciato v2 sopra gli altri oggetti presenti sul proprio livello. Si passi l'oggetto, non un identificatore.
	`Ausili per le carte`	`shuffleDeck`, `cardInfo`, `recallCards`, `dealCardsToTurn`, `drawCard`, `pickUpCard`, `takeCardFromPlayer`, `playCardToTable`, `giveCardToPlayer` — si veda la sezione " Oggetti: Mazzo".

Campagna

Parametri

Nessun parametro

Resi

L'oggetto Roll20 della campagna singleton.

Esempi

var currentPageID = Campaign().get('playerpageid'),
  currentPage = getObj('pagina', currentPageID);

Campaign().sandboxVersion è "1.0" o "1.5". Campaign().nodeVersion è la stringa che indica la versione di Node.js. Solo per Mod Script sandbox v1.5. sheetName, computedSummary e actionSummary. Si veda la sezione “Oggetti: Campagna”.

`creaOggetto`

Parametri

TYPE (Stringa) Il tipo di oggetto Roll20 da creare. È possibile creare i seguenti elementi : "grafica ", "testo ", "percorso", "percorso v2" , "personaggio ", "abilità", "attributo", "materiale di gioco", "tabella a rotazione ", " voce di tab ella " , "macro", "carta", "mazzo", "effetto personalizzato ", "finestra", "porta" e "pin". Solo per Mod Script sandbox v1.5. 'pageFolder'.

ATTRIBUTI (Oggetto) I valori iniziali da utilizzare per le proprietà dell’oggetto Roll20.

Resi

L'oggetto Roll20 che è stato creato.

Esempi

Quando si crea un oggetto Roll20 che ha un oggetto padre (ad esempio, quando si crea un oggetto Roll20 di tipo “attributo”, che è un oggetto figlio di un oggetto Roll20 di tipo “personaggio”), è necessario specificare l’ID dell’oggetto padre nella sezione “attributi”.

on('ready', function() {
  on('add:character', function(obj) {
    createObj('attribute', {
      name: 'Strength',
      current: 0,
      max: 30,
      characterid: obj.id
    });
  });
});

Quando si crea un percorso, si devono specificare il percorso (memorizzato come _path) e l'ID pagina. Il percorso senza il trattino basso corrisponde al nome assegnato al momento della creazione. Da quel momento in poi sarà di sola lettura.

createObj('path', {
  pageid: Campaign().get('playerpageid'),
  left: 7000,
  top: 140,
  width: 140,
  height: 140,
  livello: 'objects',
  path: JSON.stringify([['M', 0, 0], ['L', 70, 0], ['L', 0, 70], ['L', 0, 0]])
});

Quando si crea un oggetto "di gioco" in Roll20, non è possibile impostare il testo o le note del master al momento della creazione.

var handout = createObj('handout', {
  name: 'Una lettera indirizzata a Lei',
  inplayerjournals: 'all',
  archived: false
});
handout.set('notes', 'Le note possono essere inserite solo dopo la creazione del foglio informativo.');
handout.set('gmnotes', 'Impostare le gmnotes in una chiamata separata rispetto alle note.');

filtraObj

Parametri

CALLBACK (Funzione) Una funzione predicato con cui verificare tutti gli oggetti di Roll20. La funzione di callback riceve un oggetto Roll20 come parametro e deve restituire true (per gli oggetti Roll20 che saranno inclusi nel valore restituito da filterObjs) oppure false (per tutti gli altri oggetti Roll20).

Resi

Una serie di oggetti Roll20 che hanno superato il test del predicato.

trovaOggetti

Parametri

ATTRIBUTI (Oggetto) Una raccolta di coppie chiave-valore da associare agli oggetti Roll20 presenti nella campagna.

OPTIONS (Oggetto, facoltativo)

caseInsensitive — se il valore è true, i confronti tra stringhe non tengono conto delle maiuscole e delle minuscole.
startsWith — se vero, i valori delle stringhe devono corrispondere come prefisso.
tagMatch — durante la corrispondenza dei tag: 'all' (impostazione predefinita; l'oggetto possiede tutti i tag elencati), 'any' (almeno uno), 'only' (esattamente l'insieme elencato).

Resi

Un array di oggetti Roll20 le cui proprietà corrispondono agli attributi. Le chiavi possono omettere il trattino basso iniziale: sia “type” che “_type” sono validi.

Esempi

var npcs = findObjs({ type: 'personaggio', controlledby: '' });
var knights = findObjs({ type: 'personaggio', name: 'Sir' }, { startsWith: true });

recuperaTuttiGliOggetti

Parametri

Nessun parametro

Resi

Una serie di tutti gli oggetti Roll20 presenti nella campagna.

getAttrByName

Parametri

CHARACTER_ID (Stringa) L'ID del personaggio. ATTRIBUTE_NAME (Stringa) Il nome dell'attributo. VALUE_TYPE (Stringa, facoltativo) "current" o "max" (il valore predefinito è "current").

Resi

La proprietà " current " o " max". Se non viene specificato, viene utilizzato l’impostazione predefinita della scheda dei personaggi (se presente).

getComputed

Solo per Mod Script sandbox v1.5. (Nella versione 1.0 questo nome corrisponde a uno stub che non esegue alcuna operazione.)

Parametri

Un oggetto: { characterId, property, args?, playerId? }.

Quando si utilizza una scheda dei personaggi di Beacon, recupera il valore di una proprietà calcolata. Elenchi i nomi utilizzando Campaign().computedSummary. playerId è facoltativo; alcune funzionalità di Beacon (ad esempio le query di roll) lo richiedono.

getSheetDefaultValue

Parametri

ATTRIBUTE_NAME (stringa), VALUE_TYPE (stringa, facoltativo) "current" o "max".

Resi

Il valore predefinito della scheda per quel campo, non il valore effettivo del personaggio.

getSheetItem

Parametri

getSheetItem(characterId, property, valtype?, options?) — asincrono (Promise).

Nella versione 1.0, questa funzione racchiude getAttrByName. Solo per Mod Script sandbox v1.5. Nelle schede Beacon vengono letti anche le proprietà calcolate e gli attributi personalizzati denominati user.*.

getObj

Parametri

TIPO (stringa), ID (stringa)

Resi

L'oggetto Roll20 specificato.

on('chat:message', function(msg) {
  var sendingPlayer = getObj('player', msg.playerid);
});

registro

Parametri

MESSAGGIO (variabile) Visualizzato nella console di output del modulo. Convertito con JSON.stringify.

Solo per Mod Script sandbox v1.5. I messaggi di errore includono spesso un oggetto di contesto, ad esempio [Personaggio Roll20 -id].

il

Parametri

EVENTO (Stringa) Esistono cinque tipi di evento: ready, change, add, destroy, chat. Ad eccezione di " ready", associi l'evento a un tipo di oggetto. Per la chat, quel tipo è sempre " messaggio". Gli eventi di modifica possono inoltre indicare una proprietà, un ID oggetto o entrambi: change:graphic:left, change:graphic:ID, change:graphic:ID:left. Anche gli elementi grafici generano eventi di sottotipo quali change:token e change:dicetoken. Si veda la sezione "Eventi".

Gli eventi "ready " della funzione CALLBACK non presentano parametri di callback. Gli eventi di modifica dispongono di un parametro `obj` (l'oggetto Roll20 successivo alla modifica) e di un parametro `prev` (un oggetto JavaScript semplice contenente le proprietà precedenti alla modifica). Gli eventi "add" dispongono di un parametro "obj " (il nuovo oggetto). Gli eventi di distruzione dispongono di un parametro "obj" (l'oggetto che non esiste più). Gli eventi di chat dispongono di un parametro "msg " (dettagli del messaggio).

Resi

(Nullo)

Gli eventi vengono attivati nell'ordine in cui sono stati registrati, dal più specifico al meno specifico. In questo esempio, una modifica alla proprietà “left” di un oggetto grafico di Roll20 determinerà l’attivazione della funzione 3, seguita dalla funzione 1 e poi dalla funzione 2.

on('change:graphic', function1);
on('change:graphic', function2);
on('change:graphic:left', function3);

L'evento "aggiungi eventi" tenterà di attivarsi per gli oggetti Roll20 già presenti nella campagna all'avvio di una nuova sessione. Per evitare che ciò accada, può attendere che si verifichi l'evento "ready" prima di registrare l'evento "add".

on('add:graphic', function(obj) {
  // All'inizio della sessione, questa funzione verrà chiamata per ogni elemento grafico della campagna
});
on('ready', function() {
  on('add:graphic', function(obj) {
    // Questa funzione verrà chiamata *solo* quando viene creato un nuovo oggetto grafico Roll20
  });
});

Il parametro "prev " per gli eventi di modifica non è un oggetto Roll20. Non è possibile utilizzare i metodi get o set, né omettere i trattini bassi iniziali nelle proprietà di sola lettura. Utilizzi prev._id, non prev.id.

Per i campi "blob" relativi ai personaggi e ai materiali di gioco (biografia, note, note del GM) e per il campo _defaulttoken dei personaggi, il valore "prev" non è un testo. La variabile " gmnotes " di Graphic è una stringa normale. Se ne avete bisogno, memorizzate voi stessi nella cache i valori precedenti dei blob.

onSheetWorkerCompleted

Parametri

CALLBACK (Funzione) Viene richiamata al termine dell'esecuzione della pila corrente di script di sviluppatori di schede. È previsto che venga chiamato prima di setWithWorker. Viene eseguito una sola volta. La funzione di callback può ricevere { workersExecuted: boolean }.

eseguireAzione

Solo per Mod Script sandbox v1.5. (Nella versione 1.0 questo nome è uno stub che non esegue alcuna operazione.)

Parametri

{ characterId, action, args?, playerId? }

Esegue un'azione della scheda Beacon. Elencare i nomi utilizzando Campaign().actionSummary. playerId è facoltativo; alcune funzionalità di Beacon lo richiedono. Se il nome non corrisponde a un'azione Beacon, la versione 1.5 potrebbe ricorrere a un'abilità del personaggio con lo stesso nome tramite sendChat.

giocatoreÈGM

Parametri

PLAYER_ID (stringa)

Resi

vero se il giocatore dispone attualmente dei permessi di GM.

Particolarmente utile per limitare l'uso dei comandi Mod Script ai soli GM. Mantenete " msg.type !== 'api' " così come è scritto: si tratta del tipo di messaggio di comando.

playJukeboxPlaylist

Parametri

PLAYLIST_ID (Stringa) L'ID della playlist di cui avviare la riproduzione.

numero intero casuale

Parametri

MAX (Numero) Massimo inclusivo.

Resi

Un numero intero casuale compreso tra 1 e max. Si consiglia di utilizzare questa funzione anziché Math.random() per ottenere intervalli simili a quelli dei dadi.

sendChat asincrono

Parametri

SPEAKINGAS (Stringa) Un nome, oppure giocatore|id_giocatore / personaggio|id_personaggio. MESSAGGIO (Stringa). CALLBACK (Funzione, facoltativa) — i risultati vengono trasmessi alla funzione di callback anziché apparire nella chat. OPZIONI (Oggetto, facoltativo) noarchive, use3d.

Si veda la sezione “Mod Scripts: Chat” per i pulsanti di comando ([label](!command)).

inviaPing

Parametri

SINISTRA, IN ALTO, PAGE_ID, PLAYER_ID (facoltativo), MOVEALL (facoltativo), VISIBLETO (facoltativo). Se si omette player_id, il ping è giallo. Se moveAll è impostato su true, le viste vengono centrate sul punto di ping. "visibleTo" può essere un ID giocatore, un array di ID o una stringa delimitata da virgole.

setAttrs

Parametri

CHARACTER_ID (stringa), ATTRIBUTE_OBJ (oggetto del tipo nome → valore). I nomi che terminano con _max impostano il valore massimo. Sono supportati i $n sono supportati. options.silent utilizza set anziché setWithWorker.

setComputed

Solo per Mod Script sandbox v1.5.

{ characterId, property, args?, playerId? } — imposta una proprietà calcolata Beacon scrivibile. Si veda Campaign().computedSummary.

setSheetItem

setSheetItem(characterId, property, value, valtype?, options?) — asincrono. Nella versione 1.0 vengono impostati gli attributi. Solo per Mod Script sandbox v1.5. Inoltre, le proprietà calcolate di Beacon e gli attributi personalizzati user.*. Le opzioni disponibili sono: createAttr, withWorker e allowThrow.

spawnFx

Parametri

SINISTRA (Numero) La coordinata x in cui posizionare l'emettitore di particelle. TOP (Numero) La coordinata y. TIPO (Stringa) Per gli effetti predefiniti, "tipo-colore", dove "tipo" può essere uno dei seguenti: bomba, gorgoglio, bruciatura, esplosione, bagliore, missile o nova, e "colore" può essere uno dei seguenti: acido, sangue, incantesimo, morte, fuoco, gelo, sacro, magia, melma, fumo o acqua. Per gli effetti personalizzati, l'ID di un oggetto custfx. Nota: le funzioni beam, breath e splatter non possono essere utilizzate con spawnFx — si veda spawnFxBetweenPoints. PAGE_ID (stringa, facoltativo): il valore predefinito è Campaign().get('playerpageid').

spawnFx(1400, 1400, 'acido ribollente');

generazione di effetti tra punti

Parametri

START (Oggetto) { x, y }. END (Oggetto) { x, y }. TYPE (String) come spawnFx, oltre a beam, breath e splatter. PAGE_ID (stringa, facoltativo).

spawnFxBetweenPoints({ x: 1400, y: 1400 }, { x: 2100, y: 2100 }, 'beam-acid');

Solo per Mod Script sandbox v1.5. Gli effetti di tipo “trave” puntano direttamente verso il punto finale (è stato corretto un errore nel calcolo dell’angolo).

spawnFxWithDefinition

Parametri

SINISTRA, IN ALTO, DEFINIZIONE (oggetto che descrive l’emettitore), PAGE_ID (facoltativo). Per i nomi delle proprietà, si veda l'articolo “Effetti personalizzati sugli oggetti”.

spawnFxWithDefinition(1400, 1400, {
  maxParticles: 200,
  size: 15,
  sizeRandom: 3,
  lifeSpan: 20,
  lifeSpanRandom: 5,
  speed: 7,
  speedRandom: 2,
  gravity: { x: 0.01, y: 0.65 },
  angle: 270,
  angleRandom: 35,
  emissionRate: 1,
  startColour: [0, 35, 10, 1],
  startColourRandom: [0, 10, 10, 0.25],
  endColour: [0, 75, 30, 0],
  endColourRandom: [0, 20, 20, 0]
});

Interrompere la riproduzione della playlist del jukebox

Interrompe tutte le playlist della Jukebox attualmente in riproduzione.

interrompereJukeboxPlaylist();

Ausili per le carte

Disponibile su entrambe le versioni sandbox. Tutte le informazioni sono disponibili nella sezione “Mod Scripts: Oggetti (Ponte)”.

shuffleDeck(idMazzo, mazzoScartato, nuovoOrdine)
cardInfo(impostazioni)
recallCards(deckid, type)
dealCardsToTurn(deckid)
drawCard(idMazzo, idCarta)
pickUpCard(cardid, fromDiscard)
takeCardFromPlayer(playerid, options)
playCardToTable(cardid, impostazioni)
giveCardToPlayer(cardid, playerid)

impostaTokenPredefinitoPerPersonaggio

CARATTERE (oggetto carattere), TOKEN (oggetto grafico). Entrambe devono già esistere. Scrive il blob _defaulttoken del personaggio a partire dal segnalino. Questo è il modo corretto per impostare quel campo; la funzione set() non lo fa.

Torna all'inizio

Solo per Mod Script sandbox v1.5.

Parametri

OBJ (grafica, testo, tracciato o pathv2), TARGET (oggetto o ID).

Posiziona l’oggetto immediatamente sopra l’elemento di destinazione sullo stesso livello.

Indietro / Avanti

OBJ deve essere un elemento grafico, un testo, un percorso o un percorso v2. Si passi l'oggetto, non un identificatore. Nella versione 1.5 questi sono notevolmente più veloci e tali tipi dispongono inoltre dei metodi di istanza toFront() e toBack().

a Sotto

Solo per Mod Script sandbox v1.5.

Posiziona l’oggetto immediatamente sotto il bersaglio (oggetto o ID) sullo stesso livello.