Scrivere un file di incantesimi personalizzati

Cos’è il file

Un file JSON nel formato di Locanda con i tuoi incantesimi in customSpells, senza grimori e senza impostazioni: lo stesso tipo di file che salva “Esporta incantesimi personalizzati”.

Contiene al massimo 1000 incantesimi e pesa al massimo 5 MB.

L’importazione è tutto o niente: se un incantesimo non rispetta una regola non viene aggiunto nulla, e l’importazione elenca cosa correggere e dove. Per un incantesimo il cui id è già su questo dispositivo scegli tu se sostituirlo o tenerli entrambi.

Un esempio

Un file completo con un trucchetto, scritto in inglese e in italiano. Copialo come punto di partenza.

{
  "format": "locanda",
  "schemaVersion": 1,
  "exportedAt": "2026-10-25T12:00:00Z",
  "appVersion": "0.0.0",
  "dataVersion": "custom",
  "spellbooks": [],
  "customSpells": [
    {
      "id": "custom:6c49a5ff-2c31-4316-b0ce-0ebd82a9d04d",
      "source": "custom",
      "level": 0,
      "school": "illusion",
      "classes": [
        "bard",
        "sorcerer",
        "wizard"
      ],
      "castingTime": {
        "unit": "action",
        "amount": 1
      },
      "ritual": false,
      "range": {
        "type": "ranged",
        "distance": 30,
        "unit": "feet",
        "area": null
      },
      "components": {
        "v": false,
        "s": true,
        "m": null
      },
      "duration": {
        "type": "timed",
        "amount": 1,
        "unit": "hour"
      },
      "concentration": false,
      "damageTypes": [],
      "savingThrows": [],
      "text": {
        "en": {
          "name": "Lantern Moth",
          "castingCondition": null,
          "material": null,
          "description": "A moth of soft light appears at a point you can see within range. It sheds dim light in a 10-foot radius and follows the path you trace with one finger.",
          "higherLevels": null,
          "cantripUpgrade": "You create one more moth when you reach levels 5, 11 and 17."
        },
        "it": {
          "name": "Falena lanterna",
          "castingCondition": null,
          "material": null,
          "description": "Una falena di luce tenue appare in un punto entro gittata che puoi vedere. Emana luce fioca in un raggio di 3 metri e segue il percorso che tracci con un dito.",
          "higherLevels": null,
          "cantripUpgrade": "Crei una falena in più quando raggiungi il 5°, l'11° e il 17° livello."
        }
      },
      "reference": null,
      "tags": [
        "Homebrew"
      ],
      "createdAt": "2026-10-25T12:00:00Z",
      "updatedAt": "2026-10-25T12:00:00Z"
    }
  ]
}

I campi

Scrivi ogni campo delle tabelle, in qualsiasi ordine. Dove un campo non ha nulla da dire, scrivi null o [] come indica la tabella; non toglierlo mai. I campi che non sono nelle tabelle vengono rifiutati. Gli a capo e le tabulazioni sono ammessi solo nei campi in Markdown.

Il file

Ogni incantesimo

Valori ammessi

Questi campi accettano solo le chiavi qui sotto, scritte esattamente così, in inglese qualunque sia la lingua del testo. Le parole dopo una chiave sono come Locanda la mostra.

Schemi JSON

Per controllare un file prima di importarlo, o per dare a uno script o a un assistente IA le regole esatte, scarica i tre schemi JSON (draft 2020-12):

• Schema del file di esportazione (urn:locanda:schema:export:1)
• Schema dell’incantesimo personalizzato (urn:locanda:schema:custom-spell)
• Schema dell’incantesimo (urn:locanda:schema:spell)

Carica tutti e tre nello stesso validatore, poi convalida il file con urn:locanda:schema:export:1: gli schemi si richiamano a vicenda con questi id urn:, non con un indirizzo web. Le parole chiave format sono solo informative, perché un pattern controlla gli stessi campi. Con Ajv, per esempio:

import Ajv2020 from 'ajv/dist/2020.js';

const ajv = new Ajv2020({ allErrors: true, validateFormats: false });
ajv.addSchema([exportSchema, customSpellSchema, spellSchema]);
const valid = ajv.validate('urn:locanda:schema:export:1', file);
console.log(valid ? 'Valid' : ajv.errors);

Alcune regole le controlla solo Locanda durante l’importazione: un nome in almeno una lingua; il testo per i livelli superiori solo sugli incantesimi di livello 1 o superiore, e quello dei trucchetti solo sui trucchetti; il testo del materiale solo con una componente materiale; date di calendario esistenti; nessuna etichetta uguale a un’altra; e ogni id una sola volta nel file.

Un prompt per un assistente IA

Per trasformare i tuoi appunti in un file, dai a un assistente IA questo prompt con allegati i tre schemi e il file di esempio, poi incolla i tuoi appunti dopo il prompt. Controlla ciò che restituisce: gli assistenti sbagliano.

Incollerò degli appunti su incantesimi che ho scritto io per il mio gioco. Trasformali in un unico file di incantesimi personalizzati di Locanda che segua gli schemi JSON allegati (export.schema.json, custom-spell.schema.json e spell.schema.json) e somigli al file di esempio allegato.

Regole:
- Il file è un unico oggetto JSON con "format": "locanda", "schemaVersion": 1, "exportedAt" impostato all’ora attuale in RFC 3339 (UTC), "appVersion": "0.0.0", "dataVersion": "custom", "spellbooks": [] e "customSpells" con un oggetto per incantesimo.
- Dai a ogni incantesimo un nuovo id casuale: "custom:" seguito da un UUID versione 4 in minuscolo.
- Usa solo le chiavi inglesi ammesse dagli schemi (scuole, classi, unità, tipi di gittata, forme dell’area, tipi di danno, caratteristiche), anche se i miei appunti sono in italiano.
- Metti le parole di ogni incantesimo in "text", nella lingua dei miei appunti ("it" per l’italiano, "en" per l’inglese). Scrivi null per ciò che i miei appunti non dicono. Scrivi le descrizioni in Markdown, senza HTML.
- Indica le distanze in piedi: 1,5 metri sono 5 piedi.
- Imposta "createdAt" e "updatedAt" alla stessa ora di "exportedAt", "tags" a [] e "reference" a null, a meno che i miei appunti non li indichino.
- Non inventare incantesimi, regole o testo che non siano nei miei appunti. Se manca o non è chiaro qualcosa che gli schemi richiedono, chiedimelo invece di tirare a indovinare.

Rispondi solo con il file JSON.

I miei appunti:

Copia il prompt

Prima di importare

• Ogni incantesimo ha un id nuovo tutto suo (custom: e un UUID appena creato), non uno copiato dall’esempio.
• Ogni valore dei campi qui sopra è una delle chiavi ammesse, in inglese, anche quando il testo è in italiano.
• Il file supera un validatore con gli schemi qui sopra. Oppure importalo e basta: Locanda controlla prima tutto il file e, se qualcosa non va, non aggiunge nulla e dice cosa correggere.

Di chi sono gli incantesimi

Metti nel file solo incantesimi che hai scritto tu o che hai il diritto di usare, come le regole della casa del tuo gruppo. Locanda non controlla da dove viene il testo, e il file resta sul tuo dispositivo a meno che tu non lo condivida.