Modelli

Puoi generare un nuovo progetto da un template eseguendo:

npm create pixi-vn@latest

Demo interattiva

Come usare un template

Se stai leggendo questa pagina, probabilmente hai già un progetto generato da un template. Le sezioni seguenti ti guideranno attraverso i primi passi per farlo funzionare.

Configurazione iniziale

Apri la cartella del progetto con il tuo IDE. Gli esempi seguenti utilizzano Visual Studio Code.

Una volta aperto il progetto, VS Code suggerirà automaticamente alcune cose:

• Installa le estensioni consigliate — apparirà una notifica che ti chiederà di installare le estensioni consigliate per il workspace. Si consiglia vivamente di accettare. Se la notifica non appare, puoi installarle manualmente dal pannello Estensioni filtrando per estensioni consigliate.
• Esegui le attività di avvio — VS Code potrebbe chiederti di eseguire le attività di avvio configurate, che installeranno tutte le dipendenze del progetto. Se preferisci farlo manualmente, esegui:

npm install

Esegui il progetto

Il template include un insieme di configurazioni di avvio (launch configurations) preconfigurate per VS Code. Se non le conosci: le configurazioni di avvio sono scorciatoie che indicano a VS Code come avviare il tuo progetto (e opzionalmente collegare un debugger), così non devi digitare comandi nel terminale ogni volta. Puoi accedervi dal pannello Run and Debug (l’icona a forma di play nella barra laterale sinistra, oppure premi F5). Seleziona la configurazione desiderata dal menu a discesa in alto nel pannello e premi il bottone verde di play.

Sono disponibili le seguenti configurazioni:

• Debug Game: questa è la configurazione che utilizzerai più spesso durante lo sviluppo — ogni volta che salvi un file, il browser si aggiorna automaticamente. Tieni presente che in questa modalità le animazioni potrebbero non essere perfettamente fluide e il caricamento delle risorse potrebbe essere più lento rispetto alla build finale pubblicata.
• Debug Game Preview: simula fedelmente come si comporterà il gioco una volta pubblicato: le animazioni sono fluide, i tempi di caricamento sono realistici e le ottimizzazioni sono attive. Usa questa configurazione quando vuoi verificare che tutto appaia e funzioni correttamente prima della pubblicazione.
• Run as Desktop App (Dev): compila il backend Rust/Tauri e avvia il gioco come una finestra desktop nativa. Se il tuo template non ha come target piattaforme desktop o mobile, questa configurazione non sarà presente.

Personalizza lo stile

L’UI del template è costruita interamente con shadcn/ui, il che significa che puoi personalizzare il tema dei colori senza toccare alcun codice dei componenti.

Apri il theme builder di shadcn/ui, regola i colori secondo i tuoi gusti, poi vai alla sezione Copy della pagina per copiare il comando CSS generato. Esegui quel comando dalla radice del tuo progetto:

npx shadcn@latest add <paste-the-generated-command-here>

Una volta applicato, si consiglia di riformattare i file sorgente:

npm run format

Per ulteriori personalizzazioni — font, stili globali e altro — vedi Stili e font.

Struttura del progetto

Schermate del template

Il template è dotato di un insieme di schermate predefinite che coprono le parti essenziali di una visual novel. Ogni schermata è un componente React collegato a una route gestita da TanStack Router.

• Menu principale (/) — la prima schermata che il giocatore vede quando avvia il gioco. Fornisce il punto di ingresso per iniziare una nuova partita, continuare una partita salvata e aprire le impostazioni.
• Schermata di narrazione (/game/narration) — la schermata principale di gioco in cui viene mostrata la storia. Renderizza dialoghi, sprite dei personaggi, sfondi e scelte.
• Impostazioni — il pannello delle impostazioni non ha una propria route dedicata. Utilizza invece i Search Params per sovrapporsi a qualsiasi schermata attualmente attiva. Questo approccio mantiene l’URL pulito, consentendo comunque al giocatore di aprire le impostazioni da qualsiasi punto del gioco e di navigare tra le sezioni delle impostazioni (audio, schermo, lingua, ecc.) senza perdere il punto in cui si trovava.
• Schermata di navigazione (/game/navigation) — solo per Point & Click. Permette al giocatore di navigare tra le stanze ed eseguire le varie azioni disponibili nella posizione attuale.
• Schermata della mappa (/game/map) — solo per Point & Click. Mostra la mappa e permette al giocatore di spostarsi da una posizione all’altra. Supporta inoltre la gestione di più mappe.