La sintassi, in una panoramica.

Per scrivere una storia hai tre strade, dalla più immediata alla più completa.

Nel browser, subito. La pagina «Programma» di questo sito è il motore vero di FAVELLA, che gira nel tuo browser: scrivi a sinistra, premi «Compila e gioca», provi a destra. Non devi installare niente, e la storia te la porti via come file .fav.

Sul tuo computer, con l'installer. Dalle Release su GitHub scarichi l'installer per il tuo sistema — .exe per Windows, .dmg per macOS, .AppImage per Linux. Ti dà un unico comando, favella1:

• favella1 gioca storia.fav — avvia l'avventura nel terminale.
• favella1 compila storia.fav — controlla la storia e ne segnala errori e avvisi.
• favella1 playground — apre un editor col motore, in locale e senza rete.
• favella1 esporta storia.fav — crea una pagina HTML autoportante da condividere.

Il codice aperto. Se vuoi il motore Python — per studiarlo, estenderlo o usarlo come libreria — il repository è pubblico su GitHub.

Una stanza è un luogo; una cosa è un oggetto con cui interagire.

La Grotta di Cristallo è una stanza.
La descrizione della grotta è "Stalattiti luminose pendono dal soffitto.".

Una spada antica è una cosa.
La spada antica è nella grotta.
La spada antica è prendibile.

Il posto iniziale (dalla 1.2)

Se vuoi presentare un oggetto dentro la scena, invece che nell'elenco «Puoi vedere qui», dagli un posto. La frase compare sotto la descrizione della stanza finché nessuno sposta l'oggetto; alla prima presa sparisce.

Il posto della spada antica è "Conficcata nella roccia, una SPADA ANTICA manda riflessi azzurri.".

Collegare le stanze

FAVELLA crea da sé il collegamento di ritorno.

La grotta collega nord a la Sala del Trono.

Una proprietà è un aggettivo di stato; le proprietà opposte si escludono.

La porta di ferro è chiusa.
Accesa e spenta sono opposte.

Per la logica più ricca ci sono stati e contatori:

Il semaforo è uno stato.
Il punteggio è un contatore.
La forza è un contatore.
La forza parte da 3.

Una regola intercetta un'azione del giocatore e la sostituisce. Il verbo va all'imperativo, come lo digiterebbe il giocatore (apri, non aprire).

Invece di prendi la statua: dire "È troppo pesante.".

Regole condizionali

Si attivano solo se la condizione è vera (e hanno priorità sulle semplici):

Invece di apri la porta di ferro se il giocatore ha la chiave: dire "La porta si apre!".

Le condizioni si combinano con e / oppure / non e le parentesi:

Invece di esci se non ( il giocatore ha la chiave e la torcia è accesa ): dire "Ti manca qualcosa.".

Una regola può cambiare il mondo aggiungendo e adesso …:

Invece di usa la chiave su la porta: dire "Click!" e adesso la porta è aperta.

Tra le conseguenze: spostare un oggetto (e adesso la chiave è in inventario), mutare uno stato o un contatore (e adesso aumenta il punteggio di 5), teletrasportare il giocatore (e adesso il giocatore è in la Sala del Trono; dalla 1.5 va in mostra sempre la stanza d'arrivo e si ritrova in mai) e chiudere la partita con un testo (e adesso vinci "Sei libero!").

Sentinelle che sorvegliano il mondo a ogni turno e scattano da sole:

La tensione è un contatore.
Ogni 1 turno: dire "La tensione cresce." e adesso aumenta la tensione.
Quando la tensione è almeno 8: dire "Il portale ti risucchia." e adesso perdi.

«Quando» scatta ogni volta che la condizione diventa vera: se torna falsa e poi di nuovo vera, scatta ancora. Per un evento che deve accadere una volta sola in tutta la partita, dalla 1.5 basta aggiungere per la prima volta: Quando la tensione è almeno 8 per la prima volta: ….

L'Anziano è un personaggio.
Il dialogo dell'Anziano comincia con "saluto".
L'Anziano al nodo "saluto" dice "Sei tu, finalmente.".
Al nodo "saluto" l'opzione "Chi sei?" conduce al nodo "verità".
Al nodo "saluto" l'opzione "Addio." chiude il dialogo.

La 1.5 aggiunge frasi per le storie lunghe. Sono tutte facoltative: le storie scritte prima girano identiche.

Prima di sintonizza qualcosa se la protezione è attiva: dire "PROTEZIONE VITALE." e basta.
La protezione è attiva quando l'aria è meno di 30.
Invece di usa oppure accendi il faro per la prima volta: dire "Il faro si accende." e adesso il faro è acceso; altrimenti dire "È già acceso.".
Invece di respira: dire "Respiri." e adesso diminuisci l'aria di 15 e poi dire "Aria: [aria].".
La plancia collega giù a la cantina se la botola è aperta; altrimenti "La botola è chiusa.".
Quando il giocatore entra nella stiva per la prima volta: dire "Fa freddo.".
I ganci si chiamano anche "uncini", "rampini" e "arpioni".
Il testo "allarme" è "Una voce: aria al [aria] per cento.".
"esamina" non fa passare il tempo.
La riga di stato è "Aria: [aria] · Turno [turno]".

- `e basta` chiude una regola «Prima di» e ferma l'azione: un divieto che vale per tutto si scrive una volta sola.

- Stati calcolati: … è attiva quando … dà allo stato il valore della prima condizione vera, da solo.

- `oppure` fra i verbi fa una regola per più azioni; `per la prima volta` vale una volta, poi tocca all'altrimenti.

- `e poi dire` parla dopo le conseguenze, quindi legge i valori nuovi.

- Un'uscita con `se` c'è solo mentre la condizione è vera; con un testo dopo altrimenti, chi prova a passare lo legge.

- `Quando il giocatore entra in …` scatta all'arrivo, prima della descrizione.

- Un testo con un nome si richiama con [allarme] in qualunque altro testo.

- `non fa passare il tempo` rende gratis i verbi che guardano senza toccare; la riga di stato compare in cima allo schermo (nel sito e nella pagina esportata).

Il resto (segnala, l'IFID, I demoni guardano la fine del turno.) è nel manuale, con la spiegazione di ogni frase.

La 1.6 apre capacità nuove, sempre facoltative e additive: le storie della 1.5 (e della 1.4) girano identiche.

Relazioni di prima classe

Una relazione binaria nominata collega due parti — entità o il giocatore — con una locuzione d'uso. La dichiari, la asserisci d'autore, la cambi nelle regole e la interroghi.

"si fida di" è una relazione molti a molti.
"apre" è una relazione uno a molti ed è reciproca.
Il giocatore si fida di Saverio.
La chiave di ottone apre la cella.
Invece di tradisci Vito: dire "Fatto." e adesso il giocatore non si fida più di Vito.
Invece di esci se qualcuno si fida del giocatore: dire "Qualcuno conta su di te.".

L'arietà (uno a uno / uno a molti / molti a molti) governa gli sfratti delle coppie in conflitto; la reciprocità è facoltativa. [chi si fida del giocatore] rende l'elenco dei soggetti. In questa prima versione le relazioni sono d'autore e interrogabili, non ancora azionabili dal giocatore.

Procedure nominate

Una sequenza di conseguenze dichiarata una volta e richiamata dove serve — anche da un'altra procedura, con una guardia contro i cicli:

Definisci "far passare la notte" come: aumenta la sete di 10 e adesso aumenta la stanchezza di 5 e adesso la lampada è spenta.
Invece di dormi: dire "Dormi fino all'alba." e adesso esegui far passare la notte.

Oggetti contabili

Una cosa tenuta in più copie, con la concordanza dichiarata dall'autore (il motore non pluralizza da sé):

La pozione, plurale "pozioni", è contabile.
Il giocatore ha 3 pozioni.
Ci sono 5 frecce in la faretra.

Il giocatore ne prende, lascia o consuma quante vuole (prendi 2 pozioni, prendi una pozione, prendi tutte le pozioni, consuma una pozione), e la stanza, l'inventario e i contenitori mostrano le copie concordate (3 pozioni, 1 pozione). Condizioni sulle scorte: se il giocatore ha almeno 2 pozioni (anche esatto / più di / meno di) e se non restano pozioni; interpolazione [quante pozioni].

Invariante di clamp

Tenere un contatore dentro un intervallo si dichiara una volta sola, e il motore la rispetta dopo ogni modifica (e sul valore iniziale):

La sete resta sempre fra 0 e 100.

Gli estremi possono essere un numero o un altro contatore (… fra 0 e [soglia]). ANNULLA riavvolge anche i clamp.

Connessioni a senso unico

A collega D a B crea da sé anche il ritorno B → A; il suffisso senza ritorno, in ultima posizione, lo sopprime:

La botola collega giù a il pozzo senza ritorno.

Domande raccolte da chi sta davvero scrivendo storie con FAVELLA. Riferite alla v1.6.0.

Il giocatore può salvare la partita?

Sì, dalla versione 1.2, e tu non devi scrivere niente. salva mette da parte la partita, salva mattina le dà un nome; carica o carica mattina la riprende esattamente dov'era, anche a metà di una conversazione. Nel terminale il salvataggio è un file (mattina.salvataggio) nella cartella da cui si gioca; nel browser resta nella memoria del browser. Se nella tua storia carica è un comando tuo ("carica" è un comando. per un fucile), vince il tuo.

Come controllo che la mia storia non si rompa da qualche parte?

Con favella1 esplora storia.fav: gioca decine di partite a caso, con giocatori che sbagliano a scrivere e annullano, e ti elenca i punti in cui qualcosa non va (un [nome] rimasto nel testo, un'uscita elencata che non si apre, un oggetto che il parser non vede), con i comandi per riprodurli. favella1 collaudo storia.fav --finali ti dice invece quali finali si raggiungono. Per le storie lunghe dagli la soluzione in un file, un comando per riga: --percorso soluzione.txt.

Posso far comparire un messaggio quando voglio, senza legarlo a un comando del giocatore?

Sì. FAVELLA ha tre modi per mostrare testo durante il gioco senza agganciarlo a un verbo o a un oggetto:

Al turno 3: dire "Qualcuno ti osserva da lontano.".
Ogni 5 turni: dire "Da qualche parte un orologio batte le ore.".
Quando lo smascheramento è sì diventa vera: dire "Adesso sei tu la talpa!".

Il primo scatta a un turno preciso, il secondo a intervalli regolari, il terzo quando si avvera una condizione che decidi tu (basta accendere uno stato).

Uno stato può prendere il valore di un altro stato?

Sì, dalla v0.34.0. Uno stato può copiare il valore corrente di un altro stato, ed essere confrontato con un altro stato — utile per impersonare un personaggio o ricordare una scelta:

e adesso il corteggiato diventa il preferito.
Invece di esamina lo specchio se il corteggiato è come il preferito: dire "Sono la stessa persona.".

La copia usa diventa; il confronto usa il marcatore è come (se X è come Y), per non confonderlo con è + un valore scritto a mano (se il corteggiato è anna resta il confronto con la parola «anna»). Vale solo fra stati: per copiare/confrontare due contatori usa il valore fra parentesi (il punteggio diventa [bonus], se la vita è [soglia]). Mescolare uno stato e un contatore è segnalato come errore.

Lo stato è una «variabile», come negli altri linguaggi?

Sì, e ne esistono due tipi. Lo stato è una variabile simbolica: contiene un valore di una sola parola, confrontabile solo per uguaglianza (come un'etichetta o un enum). Il contatore è la variabile numerica: ci fai aritmetica (aumenta, diminuisci, … diventa 5) e confronti d'ordine (almeno, più di, meno di, al massimo).

Ricevo «Entità sconosciuta» su una riga che mi sembra corretta. Perché?

Quasi sempre l'errore vero è nella riga precedente: una descrizione con il punto messo dentro le virgolette. Scrivi "…testo". (punto fuori), non "…testo.". Il punto interno viene rimosso insieme al testo, la frase si fonde con quella successiva e quest'ultima «sparisce», facendo scattare l'errore più in basso.

I nomi degli stati vanno messi tra virgolette?

No. Le virgolette "…" servono solo ai testi mostrati al giocatore (descrizioni, dialoghi). Un nome di stato si scrive nudo: Il nome di Backy è uno stato. — non Il "nome di Backy" è uno stato.

Che valori può avere uno stato?

Una sola parola, senza spazi né /. Quindi Nord Italia diventa NordItalia (oppure settentrionale), e non tatuato diventa nontatuato. Se ti serve un numero, usa un contatore.

Come faccio un combattimento a turni, con un nemico che attacca da solo?

Modella il combattimento come presenza nella stanza: il nemico ha un contatore di vita, e un demone lo fa colpire a ogni turno finché è vivo e tu sei lì. Tu attacchi con un verbo tuo.

La vita del troll è un contatore.
La vita del troll parte da 6.
La forza è un contatore.
La forza parte da 2.
"attacca" è un comando.
Invece di attacca il troll: dire "Lo colpisci!" e adesso diminuisci la vita del troll di [forza].
Ogni turno se il giocatore è in la cripta e la vita del troll è più di 0: dire "Il troll ti colpisce!" e adesso diminuisci la vita di 2.
Quando la vita del troll è al massimo 0: dire "Il troll crolla!" e adesso aumenta l'esperienza di 10.

Due accorgimenti: usa al massimo 0 (non è 0) per la morte, così regge anche se l'ultimo colpo «sfonda» lo zero; e ricorda che fuggire dalla stanza ti sottrae ai colpi. Lo vedi all'opera nella demo «La Cripta del Lich» su GitHub.

Il danno può variare a caso, o dipendere dalla forza del personaggio?

Sì, dalla v0.31.0. Una quantità (di …) può essere un numero scritto a mano, il valore di un contatore fra parentesi quadre, oppure un'estrazione casuale:

Invece di attacca il drago: dire "Colpisci!" e adesso diminuisci la vita del drago di [forza].
Invece di incanta il drago: dire "Magia!" e adesso diminuisci la vita del drago di un numero fra 2 e 6.

Le parentesi [forza] significano «il valore di questo contatore» — proprio come quando interpoli [forza] dentro un testo. Così il danno scala con la statistica (sali di livello → colpisci più forte) e i dadi sono finalmente possibili. L'estrazione casuale è riproducibile e ANNULLA la riavvolge.

Posso confrontare due contatori fra loro? (es. «se la mia vita è meno di quella del nemico»)

Sì, dalla v0.31.0. Il termine di confronto, oltre a un numero, può essere un altro contatore fra parentesi quadre:

Quando la vita del troll è meno di [vita] diventa vera: dire "Il troll esita: è più malconcio di te.".
Ogni turno se l'oro è almeno [prezzo]: dire "Te lo puoi permettere.".

Il confronto è dinamico: se la cella di destra cambia, cambia anche il risultato. Abilita soglie relative (gelosie, difficoltà che si adatta) senza batterie di regole a numero fisso.

Come gestisco una scorta (3 pozioni, le munizioni, le razioni…)?

In due modi, secondo che cosa è la scorta.

Con un contatore, quando è una quantità astratta (le munizioni, i punti vita, le razioni): un numero che cala quando consumi, e il testo lo scrivi tu ([pozioni] interpola la quantità, così resta in italiano corretto).

Le pozioni sono un contatore.
Le pozioni partono da 3.
"bevi" è un comando.
Invece di bevi se le pozioni è almeno 1: dire "Bevi una pozione. (Ne restano [pozioni].)" e adesso aumenta la salute di 5 e adesso diminuisci le pozioni.
Invece di bevi se le pozioni è 0: dire "Non hai più pozioni.".

Con un oggetto contabile (dalla v1.6.0), quando è una cosa vera del mondo che il giocatore prende e lascia in più copie. FAVELLA non pluralizza da sé — lo spirito del progetto resta quello — quindi il plurale lo dichiari tu, una volta sola:

La pozione, plurale "pozioni", è contabile.
Il giocatore ha 3 pozioni.
Ci sono 5 frecce in la faretra.

Poi prendi 2 pozioni, lascia una pozione, consuma una pozione e prendi tutte le pozioni funzionano da soli, e gli elenchi mostrano «3 pozioni» o «1 pozione» con la concordanza che hai dichiarato. Condizioni sulle scorte: se il giocatore ha almeno 2 pozioni e se non restano pozioni; interpolazione [quante pozioni].

Posso far cambiare il meteo (o un altro stato) a caso?

Sì, dalla v0.32.0. Oltre a dare a uno stato un valore fisso, puoi farglielo pescare a caso da un elenco:

Il meteo è uno stato.
Il meteo è sereno.
Ogni 3 turni: il meteo diventa uno fra sereno, pioggia, nebbia.

A ogni scatto il meteo diventa uno fra i valori elencati, scelto a sorte. È la casualità simbolica (valori di stato), gemella dell'estrazione numerica un numero fra 2 e 6 dei contatori. Come per quella, la scelta è riproducibile e ANNULLA la riavvolge.

Posso far succedere qualcosa solo «ogni tanto», con una probabilità?

Sì, dalla v0.32.0, con la condizione càpita (N su M) — vera N volte su M:

Ogni turno se càpita (1 su 4): dire "Un'auto sbuca dal nulla!" e adesso diminuisci la salute di 1.
Invece di scava se càpita (1 su 3): dire "Hai trovato una moneta!" e adesso aumenta l'oro.

1 su 4 scatta circa una volta ogni quattro; 3 su 3 sempre, 0 su 5 mai. Si combina con e/oppure/non come ogni altra condizione, e si usa in regole, demoni e dialoghi. Anche qui la pesca è seedata e ANNULLA la riavvolge: un imprevisto disfatto si ripresenta identico. È ciò che rende un simulatore (guida, sopravvivenza, GDR) davvero rigiocabile.

Posso far scendere la notte e spegnere la luce delle stanze?

Sì, dalla v0.33.0. Oltre al buio dichiarato all'avvio (La grotta è buia. + un oggetto che illumina), ora puoi commutarlo in scena: una stanza diventa buia o si rischiara a metà partita.

Al turno 5: dire "Cala la notte." e adesso la cantina diventa buia.
Quando l'alba arriva diventa vera: dire "Sorge il sole." e adesso la cantina diventa illuminata.

diventa buia spegne la luce (senza una torcia accesa, «È buio pesto.»); diventa illuminata (o chiara) la riaccende. È stato del mondo, quindi ANNULLA lo riavvolge. Nota: per uno spazio all'aperto la notte spesso non è buio pesto (ci sono le stelle, e vuoi mostrare le uscite): lì conviene ancora uno stato momento con descrizioni condizionali. Usa il buio commutabile quando la luce deve davvero mancare (una cantina, una torcia che si spegne).

La battuta di un personaggio può cambiare in base a quello che è successo?

Sì, dalla v0.33.0. Come le descrizioni, anche la battuta di un nodo di dialogo ammette varianti se: vince la prima la cui condizione è vera, e quella senza se fa da ripiego.

Anna al nodo "incontro" dice "Sei tornato, finalmente." se l'affinità di Anna è almeno 4.
Anna al nodo "incontro" dice "Oh. Ciao.".

Prima dovevi sdoppiare l'opzione (due righe con la stessa etichetta); ora puoi far variare direttamente ciò che il personaggio dice, senza toccare le scelte del giocatore.

Il gioco si chiude di colpo con un errore su un «carattere» (codec/charmap). Perché?

Capita su Windows se in un testo mostrato al giocatore metti un carattere «fantasia» fuori dal set occidentale standard — per esempio ★, ─, certe frecce o emoji. La console di Windows non riesce a stamparlo e la partita si interrompe. Soluzione: nelle stringhe usa lettere accentate, «», trattini — (questi vanno bene) ed evita simboli decorativi esotici; in alternativa >>, ===, *. (Nei commenti # puoi scrivere qualsiasi cosa: non vengono mai stampati.)

Come do un nome a una direzione? «"sinistra" è come est.» non funziona.

è come serve per i verbi ("ghermisci" è come prendi.), non per le direzioni: con una direzione dà solo un avviso e non fa nulla. Per le direzioni l'idioma — più pulito — è dichiarare una coppia di opposte, che il motore tiene in coppia (andata e ritorno automatici):

Sinistra e destra sono direzioni opposte.
La piazza collega sinistra al vicolo.

Da quel momento il giocatore può digitare sinistra per muoversi, e destra lo riporta indietro.

Una regola «Invece di» deve sempre «dire» qualcosa?

No (dalla v0.30.0). Se una regola cambia solo lo stato del mondo, puoi omettere il testo, esattamente come per eventi e demoni:

Invece di riposa: aumenta le forze di 2.

Niente riga vuota a schermo: il gesto agisce in silenzio. Se invece vuoi una risposta, la metti come prima: … : dire "Ti riposi." e adesso aumenta le forze di 2..

Ho usato un carattere strano in un nome (es. «doppio/gioco») e il compilatore protesta. Cosa posso usare?

Nei nomi (di stanze, oggetti, stati, contatori) puoi usare solo lettere — anche accentate — cifre, spazi e l'apostrofo. Caratteri come /, -, % non sono ammessi: dalla v0.30.0 il compilatore te lo dice con un messaggio chiaro, riga e colonna del carattere incriminato (prima dava un errore interno oscuro). Scrivi doppiogioco o doppio gioco.

Questa è solo la punta dell'iceberg. Il Manuale di Programmazione completo (113 pagine, in PDF) tratta ogni costrutto nel dettaglio; codice, specifica della grammatica e la demo «Il Relitto Silente» sono tutti pubblici su GitHub.