Storie ramificate senza spaghetti

Ogni storia interattiva comincia allo stesso modo: un bivio pulito a pagina tre. Al capitolo quattro il diagramma di flusso sembra un piatto di spaghetti, metà delle vignette sono copie di altre vignette con una sola battuta cambiata, e nessuno osa più toccare il grafo. Questo articolo spiega come evitarlo. Presuppone che tu conosca le basi dell’editor (vedi Primi passi con PanelWave CMS) e va dritto alle scelte di progettazione che decidono se un’opera ramificata resta modificabile.

In breve: PanelWave ti dà tre strumenti distinti, e gli spaghetti nascono quando ne usi uno solo. Il flusso sta nel grafo del capitolo. Lo stato sta nelle variabili. I contenuti reagiscono allo stato tramite varianti di vignetta e condizioni di visibilità. Tieni piccolo il grafo, lascia che siano le variabili a portare le conseguenze e lascia che le vignette le rispecchino.

Tecnica 1: per ogni differenza, lo strumento giusto

Prima di disegnare un bivio, chiediti che cosa cambia davvero tra i due percorsi. Le risposte possibili sono tre, e ognuna corrisponde a un meccanismo diverso del formato:

La documentazione riassume pro e contro in una tabella in Variants vs. other conditional mechanisms. La maggior parte dei grafi a spaghetti sono varianti e condizioni di visibilità disegnate come bivi.

• I lettori vedono vignette diverse. È una differenza di flusso: usa collegamenti condizionali nel Graph Editor; il riferimento del grafo elenca ogni proprietà.
• I lettori vedono la stessa vignetta con contenuti diversi. Uno sfondo diverso, un livello in più, una battuta cambiata. È una variante di vignetta: stesso nodo nel grafo, contenuto alternativo scelto da una condizione. Il flusso della storia non cambia.
• Un singolo elemento si attiva o si disattiva. Un hotspot che compare solo quando il lettore ha la chiave, un balloon visibile solo dopo una scelta. È una condizione di visibilità su quell’elemento, impostata con il Condition Builder; il resto della vignetta resta com’è.

Tecnica 2: dichiara lo stato prima di ramificare

Le variabili sono la memoria della storia: hanno un tipo e si dichiarano in anticipo. Dai loro id con namespace separati da punti, che dicano a che cosa appartengono: story.choice, stats.trust, inventory.hasKey, prefs.hints. Per ogni scelta con un insieme fisso di esiti usa un enum: così un errore di battitura in una condizione salta subito all’occhio, invece di non corrispondere mai senza che nessuno se ne accorga.

L’ambito è la decisione che molti saltano. Stabilisce quando un valore si azzera: page, chapter, global, session o persistent. La regola pratica della guida alle variabili: le decisioni che tutta l’opera deve ricordare vanno in global o persistent, lo stato di breve durata di un enigma in chapter o page, e i flag che valgono solo per la visita in corso, come un suggerimento chiuso, in session. Le variabili persistenti sopravvivono da una visita all’altra, ed è questo che rende possibili contenuti sbloccabili e indicatori di completamento (salvare i progressi nel player).

Nel CMS tutto questo avviene nel Variables designer: apri il Backstage di un’opera, scegli Variables e dichiara ogni variabile una sola volta, con id, tipo, ambito e valore predefinito. Prima di salvare, la finestra controlla id, liste enum e valori predefiniti; la stessa lista confluisce poi nel manifest, nelle sostituzioni della pagina Preview e nel player. Se curi un manifest a mano, Export JSON ti dà le definizioni come frammento da incollare, e importando un manifest la sua sezione delle variabili si conserva. La guida alle variabili illustra il designer; lo schema delle variabili riporta il formato esatto.

Tecnica 3: costruisci ogni scelta come una triade

In PanelWave una scelta non è mai un oggetto singolo. Sono tre elementi legati a una variabile: un hotspot che la imposta, un collegamento per ogni esito che la verifica e un collegamento incondizionato come ripiego. Costruiscili sempre tutti e tre e i lettori non resteranno mai bloccati.

Sulla vignetta della scelta disegna un hotspot per ogni opzione e assegna a ciascuno un’azione Set Variables: story.choice impostata su left, story.choice impostata su right. Nel Graph Editor seleziona la vignetta di origine, premi C, scegli la destinazione e premi Invio per disegnare i collegamenti; poi seleziona ogni collegamento e scrivi la sua condizione. Le condizioni sono in JSON Logic: un operatore, un riferimento a una variabile, un valore. La sezione Edge conditions ha esempi da copiare e adattare per uguaglianza, maggiore di e regole combinate.

Il terzo collegamento è la rete di sicurezza: se il lettore va avanti senza cliccare nessuna delle due porte, il player segue il collegamento incondizionato. Quando più collegamenti corrispondono, il campo priority stabilisce l’ordine, come descritto in Branching. Il player valuta tutto questo a ogni passo; l’algoritmo è spiegato in How the player walks the graph.

Un dettaglio di denominazione che trae in inganno molti: su un collegamento le scritture delle variabili vanno nella lista action, su un hotspot invece in mutations. Il riferimento del grafo lo segnala esplicitamente. Nel CMS raramente tocchi direttamente l’una o l’altra, ma conta quando leggi un manifest esportato.

Tecnica 4: ramifica, poi riconvergi

La forma classica di una storia ramificata gestibile è il diamante: un bivio, due o tre vignette per percorso, poi tutto riconverge su una vignetta comune. Ogni bivio che non riconverge raddoppia i disegni da fare e i percorsi da provare. Fai riconvergere presto e spesso.

Ma la convergenza sembra amnesia se la storia dimentica che cosa è successo. Qui torna in gioco lo stato. La scelta è già in story.choice: le vignette comuni dopo il punto di convergenza possono rispecchiarla con una variante di vignetta, la cui condizione when verifica la variabile e i cui override sostituiscono livelli o dialoghi. Un solo nodo nel grafo, due versioni della stessa scena, nessuna vignetta duplicata. La documentazione lo chiama riflesso della scelta e mostra un esempio completo in The choice pattern.

Due regole sulle varianti che ti risparmiano debug più avanti. Le varianti vengono valutate nell’ordine dell’array e vince la prima che corrisponde: quando le condizioni possono sovrapporsi, ordinale dalla più specifica alla meno specifica (Selection order). E un array layers di override sostituisce l’intera pila, quindi ripeti i livelli di base che vuoi tenere. Nell’editor le vignette con varianti hanno un badge V nell’albero della struttura, e la barra dei filtri dell’albero può mostrare solo quelle (Pages and Panels).

Tecnica 5: hub, cicli e contatori

I cicli sono ammessi in un grafo PanelWave, ed è così che si costruiscono gli hub: una stanza in cui il lettore torna tra un’esplorazione e l’altra, una mappa, un menu di dialogo. Il pannello di validazione del grafo segnala i cicli con un avviso, ma solo come promemoria: un ciclo voluto va benissimo (Validation).

A impedire che un hub diventi un ciclo infinito è un contatore. Dai a ogni missione secondaria un hotspot che incrementa stats.visits o inverte un booleano come story.metCourier, e metti il collegamento di uscita dell’hub dietro una condizione come stats.visits maggiore o uguale a tre. Le operazioni di mutazione sono set, increment, toggle, append e remove (Mutation). I lettori esplorano nell’ordine che vogliono, l’uscita si sblocca quando hanno finito, e il grafo resta una stella ordinata invece di diventare l’elenco di tutti gli ordini possibili.

Tecnica 6: condiziona gli elementi, non duplicare le vignette

Quando in una vignetta dipende dallo stato una sola cosa, metti la condizione su quella cosa. Hotspot e balloon hanno nell’inspector una sezione Visibility Condition: clicca Build Condition e il Condition Builder scrive l’espressione per te (variabile, tipo, operatore, valore, combinati con AND oppure OR). L’esempio classico è una porta chiusa a chiave: in un altro punto della storia l’hotspot A imposta inventory.hasKey su true, e l’hotspot B sulla porta diventa cliccabile solo quando inventory.hasKey è uguale a true (Conditions on hotspots).

Le mutazioni degli hotspot fanno un passo in più: un trigger When Variable Changes può animare opacità, scala, posizione o colore nel momento in cui lo stato cambia, così le illustrazioni reagiscono a una scelta senza cambiare vignetta. Nell’opera pubblicata i lettori vedono gli hotspot come aree con un leggero contorno pulsante, pienamente accessibili da tastiera (la vista del lettore); della tua logica di condizioni non vedono nulla.

Tecnica 7: mantieni leggibile la mappa

Un grafo che non riesci a leggere è un grafo che prima o poi romperai. Alcune abitudini lo tengono leggibile mentre l’opera cresce:

• Un capitolo, un grafo. Ogni capitolo ha il proprio grafo e la propria vignetta d’ingresso. Considera il capitolo l’unità della ramificazione: dovrebbe contenere un bivio completo di riconvergenza, non solo metà.
• Dai un nome alle vignette. Assegna alle vignette un Friendly ID come courier-door-left nelle Basic Properties dell’inspector (Pages and Panels); il Graph Editor etichetta i nodi con i titoli delle vignette, e il manifest può contenere etichette dei nodi visibili ai lettori per le mappe dei capitoli.
• Lascia l’impaginazione alla macchina. Auto-Layout (L) dispone il grafo da sinistra a destra secondo la profondità nella storia e riduce al minimo gli incroci; le posizioni vengono ricordate per ogni capitolo. L’interruttore List mostra lo stesso grafo come struttura annidata, adatta agli screen reader, con badge per ingresso e fine (Moving around).
• Nascondi ciò che deve restare nascosto. Se il capitolo usa la tela infinita, imposta i rami segreti su Hidden until visited nelle modalità di rivelazione, così la panoramica con lo zoom non li svela; la stessa impostazione è consigliata per le vignette dietro paywall.

Tecnica 8: prova ogni percorso, poi misura quelli reali

I bug delle ramificazioni si nascondono nel percorso che non hai cliccato. PanelWave offre tre livelli di verifica, e ognuno risponde a una domanda diversa.

Quando l’opera è online, le Analisi ti dicono quali rami prendono davvero i lettori. Il funnel di lettura mostra le sessioni per vignetta nell’ordine di lettura: un calo brusco subito dopo un bivio di solito significa che la scelta non era chiara. La heatmap dei clic mostra dove toccano i lettori, sugli hotspot e fuori; un gruppo di clic fuori da ogni hotspot vuol dire che si aspettavano una scelta che non hai offerto. Tutte e due costano meno che tirare a indovinare.

• Struttura: la modalità Simulate del Graph Editor percorre il grafo dall’ingresso, elenca sotto Where to next ogni collegamento in uscita con la sua condizione e segnala i vicoli ciechi. Percorre solo la struttura, senza valutare le condizioni (Simulating the flow). Premi V per rieseguire la validazione: segnala nodi irraggiungibili, nodi isolati e vignette d’ingresso mancanti, con correzioni in un clic per i casi più comuni.
• Logica: Preview elenca ogni variabile con un campo di input tipizzato. Forza story.choice su ciascun valore e rileggi il capitolo; salva la combinazione come scenario per il giro successivo (Variable overrides). Secondo la documentazione, il bug di ramificazione più comune è una condizione che non può mai essere vera perché nessuno imposta mai la variabile. Prova entrambi i lati di ogni ramo.
• Release: il controllo pre-pubblicazione verifica l’intera opera, compresi i problemi di flusso come vignette irraggiungibili dall’ingresso del capitolo e collegamenti con riferimenti rotti (Validation and Preflight). Gli errori bloccano la pubblicazione.

Un esempio completo: il corriere

Ecco un capitolo intero progettato con queste tecniche. Sette vignette, un bivio, un hub, nessun disegno duplicato.

Dalla vignetta 3 escono tre collegamenti, ripiego compreso; tre cicli passano per l’hub; l’uscita è una sola. Il grafo sta in una schermata, Simulate lo percorre in meno di un minuto, e ogni conseguenza delle scelte del lettore vive in tre variabili che puoi ispezionare in Preview.

• Variabili: story.choice (enum: left, right, none; ambito chapter), stats.visits (integer, ambito chapter), inventory.hasKey (boolean, ambito global).
• Vignette da 1 a 3: lineari. La vignetta 3 è la scelta: due hotspot sulle porte, ciascuno con un’azione Set Variables su story.choice e un’azione Navigate verso la vignetta 4.
• Vignetta 4: una vignetta, due varianti. La variante left aggiunge un livello e la battuta «Hai preso le scale a sinistra»; la variante right sostituisce lo sfondo. La vignetta di base fa da ripiego per chi è andato avanti senza scegliere.
• Vignetta 5: l’hub, un cortile con tre hotspot. Ognuno porta a una vignetta laterale (6a, 6b, 6c), il cui collegamento di ritorno incrementa stats.visits; quella con la chiave imposta anche inventory.hasKey su true. L’hotspot di uscita dell’hub ha la condizione di visibilità stats.visits maggiore o uguale a due.
• Vignetta 7: il finale. Il collegamento dall’hub è incondizionato, e una variante verifica inventory.hasKey per mostrare la versione sbloccata.

Per approfondire

• Graph Navigation: perché un grafo invece di un ordine delle pagine, e come lo percorre il player.
• Variables: il modello di stato dietro ogni condizione.
• State and conditions in the player: come il runtime valuta JSON Logic e memorizza lo stato.
• Hotspots in the format: le azioni goTo, setVariables, openExtras, openModal e pluginEvent.
• Monetization: dove collocare il confine del paywall in un capitolo ramificato, e come vedere l’anteprima da lettore gratuito o premium.