Il Template

Il template di partenza

In questo capitolo esploreremo il template che utilizzeremo come base per sviluppare il nostro videogioco con Phaser 3. Il template è un progetto già configurato con tutti gli strumenti necessari: TypeScript, Webpack e la libreria PhaserJS 3.9.

Prima di procedere, assicurati di aver completato l'installazione di Node.js come descritto nel capitolo precedente.

JSON (JavaScript Object Notation)

Molti dei dati che andremo ad utilizzare saranno strutturati come oggetti JSON. È fondamentale comprendere questo formato prima di procedere.

JSON (JavaScript Object Notation) è un formato di testo leggero per lo scambio di dati. Viene utilizzato spesso per trasmettere dati in formato testuale da un server a un'applicazione web o viceversa.

Un file JSON consiste in una sequenza di coppie chiave:valore, separate dai due punti : e racchiuse tra parentesi graffe {}. Ogni coppia è separata dalla successiva dalla virgola ,.

{
  "name": "Francesco Raimondo",
  "yearBornDate": 1972,
  "city": "Salerno",
  "interests": ["making", "retrogaming", "3d printing"]
}

In questo esempio le chiavi sono name, yearBornDate, city e interests. I rispettivi valori sono "Francesco Raimondo", 1972, "Salerno" e l'array ["making", "retrogaming", "3d printing"].

I valori assegnati alle chiavi possono essere:

• Stringhe: "testo"
• Numeri: 42, 3.14
• Booleani: true, false
• Array: [1, 2, 3]
• Altri oggetti JSON: { "nested": "object" }

Riferimenti utili:

• json.org — Specifica ufficiale
• jsonlint.com — Tool online per validare JSON

Il file package.json

Il file package.json, posizionato nella cartella principale del template, è un file di configurazione fondamentale per ogni progetto Node.js. Descrive le dipendenze del progetto e altre informazioni come il nome, la versione e i dati sull'autore.

{
  "name": "phaser3-project-template",
  "version": "1.0.0",
  "description": "Phaser 3.9 starter template with TypeScript and webpack.",
  "scripts": {
    "start": "webpack serve --open --config webpack/webpack.dev.js",
    "build": "rimraf public && webpack --config webpack/webpack.prod.js"
  },
  "dependencies": {
    "phaser": "3.9.0"
  }
}

Questo file viene utilizzato da npm quando eseguiamo il comando npm install.

Comandi npm essenziali

Tre comandi npm saranno fondamentali per lo sviluppo del nostro gioco:

Struttura del template

Una volta scompattato il template in una cartella del computer, aprendo la folder con VS Code troverai la seguente struttura:

template/
├── src/
│   ├── assets/
│   │   ├── fonts/
│   │   ├── icons/
│   │   ├── images/
│   │   ├── sounds/
│   │   └── map/
│   ├── pwa/
│   ├── scenes/
│   │   ├── Boot.ts
│   │   ├── Preloader.ts
│   │   ├── Intro.ts
│   │   ├── GamePlay.ts
│   │   ├── Hud.ts
│   │   └── GameOver.ts
│   ├── scss/
│   ├── favicon.ico
│   ├── GameData.ts
│   ├── index.html
│   ├── index.ts
│   └── style.ts
├── typings/
├── webpack/
├── package.json
└── tsconfig.json

La cartella src

Questa è la cartella principale dove risiede tutto il codice sorgente:

assets/

Contiene tutte le risorse multimediali del gioco:

scenes/

In questa cartella troviamo le scene che compongono il nostro gioco. Ogni scena è un file TypeScript separato che "estende" la classe Phaser.Scene.

Il flusso delle scene è:

Boot → Preloader → Intro → GamePlay → GameOver
                    ↕
                   Hud (overlay parallelo)

• Boot: carica solo il logo iniziale
• Preloader: carica tutti gli assets e mostra la barra di caricamento
• Intro: schermata titolo/splash
• GamePlay: la logica principale del gioco
• Hud: scena overlay per elementi UI (punteggio, vite, ecc.)
• GameOver: schermata di fine partita

File principali

La cartella typings

Contiene il file custom.ts con le interfacce TypeScript che descrivono la struttura degli oggetti utilizzati nel progetto.

La cartella webpack

Contiene i file di configurazione per Webpack:

• webpack.common.js — Configurazione condivisa
• webpack.dev.js — Configurazione per lo sviluppo
• webpack.prod.js — Configurazione per la build di produzione

GameData.ts — Il registro degli assets

Il file GameData.ts è il cuore della configurazione del nostro gioco. Tutti gli assets vengono dichiarati qui e caricati automaticamente dal Preloader.

export let GameData: gameData = {
  globals: {
    gameWidth: 1280,
    gameHeight: 800,
    bgColor: "#ffffff",
    debug: false
  },

  preloader: {
    bgColor: "ffffff",
    image: "logo",
    imageX: 1280 / 2,
    imageY: 800 / 2,
    loadingText: "Caricamento...",
    loadingTextComplete: "Tappa/clicca per iniziare!!",
  },

  spritesheets: [
    { name: "player", path: "assets/images/player.png", width: 82, height: 70, frames: 50 },
  ],

  images: [
    { name: "phaser", path: "assets/images/logo-phaser.png" },
    { name: "bg-1", path: "assets/images/bg/1.png" },
  ],

  sounds: [],
  fonts: [],
  webfonts: [{ key: 'Roboto' }, { key: 'Press+Start+2P' }],
};

Installazione del template

Passo 1: Aprire il terminale

Per eseguire i comandi npm, dobbiamo aprire il terminale integrato di VS Code. Clicca con il tasto destro sul file package.json e seleziona "Open in Integrated Terminal".

Passo 2: npm install

Nel terminale, digita:

npm install

Questo comando leggerà il file package.json e scaricherà tutti i pacchetti necessari nella cartella node_modules, incluso Phaser 3.9.

Passo 3: npm run start

Una volta completata l'installazione, avvia il server di sviluppo:

npm run start

La prima esecuzione richiederà qualche secondo. Webpack compilerà il progetto e aprirà automaticamente una nuova finestra del browser all'indirizzo http://localhost:9000/ con la pagina di benvenuto del template.

La Console JavaScript

Per visualizzare messaggi di debug e output del gioco, dobbiamo accedere alla Console JavaScript del browser.

1. Premi F12 (o fn+F12 su alcuni laptop)
2. Oppure clicca con il tasto destro sulla pagina e seleziona "Ispeziona"
3. Seleziona il tab "Console"

La console permette di:

• Visualizzare messaggi di log con console.log()
• Vedere errori e warning
• Eseguire codice JavaScript direttamente

// Nel tuo codice TypeScript
console.log("Hello World");

Hot Reload

Una delle funzionalità più utili di Webpack è l'Hot Reload: ogni volta che salvi un file (Ctrl+S), la finestra del browser si aggiorna automaticamente mostrando le modifiche.

Questo accelera enormemente il ciclo di sviluppo, permettendoti di vedere immediatamente l'effetto delle tue modifiche senza dover riavviare manualmente il server.

Creare la build di produzione

Quando il gioco è pronto per essere pubblicato, usa il comando:

npm run build

Webpack compatterà tutti i file sorgente e creerà una cartella public/ contenente i file ottimizzati per la pubblicazione online.

Riepilogo

In questo capitolo abbiamo:

• ✅ Compreso la struttura JSON
• ✅ Esplorato il file package.json
• ✅ Analizzato la struttura delle cartelle del template
• ✅ Scoperto il ruolo di GameData.ts
• ✅ Installato le dipendenze con npm install
• ✅ Avviato il server di sviluppo
• ✅ Imparato a creare la build di produzione

Nel prossimo capitolo inizieremo a esplorare le basi di TypeScript, il linguaggio che utilizzeremo per scrivere il codice del nostro gioco.

Sh4rk0

Ok, ho sentito girare gli occhi quando hai visto quella struttura di cartelle. Lo so. Sembra tantissima roba.

Ma ti svelo un segreto: nel 90% dello sviluppo userai solo tre cose — npm run start, il file GameData.ts per aggiungere assets, e il metodo create() della scena GamePlay. Il resto è lì, ma puoi ignorarlo finché non ti serve.

L'unica cosa davvero fondamentale: esegui sempre npm install la prima volta che apri il progetto. Dimentichi quello e ti ritrovi a fissare errori misteriosi per mezz'ora.

Il server si avvia, il browser si apre, vedi la schermata del template — sei a posto. A presto! 🚀