PhaserPluginFx 🎮

Una libreria di effetti visuali (FX) modulare, estensibile e performante per Phaser 3, progettata per aggiungere micro-interazioni dinamiche a qualsiasi GameObject (Sprite, Image, Testi, Forme geometriche).

🚀 Installazione

npm install phaserpluginfx

🛠️ Configurazione

È possibile configurare ed utilizzare la libreria in due modi: tramite la classe madre PhaserPluginFx (approccio raccomandato per accedere a tutti i sottomoduli in modo centralizzato), oppure importando le classi separate se si desidera importare solo parti specifiche.

Opzione A: Classe Madre Centralizzata (Raccomandata)

Inizializzando PhaserPluginFx a livello di scena, si ha accesso immediato a tutti i sottomoduli (effetti sui target, effetti globali di scena, creazione prefabbricati) tramite un'unica istanza:

import * as Phaser from "phaser";
import { PhaserPluginFx } from "phaserpluginfx";

class GameScene extends Phaser.Scene {
    create() {
        // 1. Inizializza il plugin madre passandogli la scena
        this.fx = new PhaserPluginFx(this);

        // 2. Crea un oggetto di gioco
        this.sprite = this.add.image(400, 300, "myTexture");

        // 3. Associa ed esegue effetti sul target (crea l'istanza fx al volo se non presente)
        this.fx.target(this.sprite).ShakeFx(500, 10);

        // 4. Esegue effetti globali della scena
        this.fx.system.ScreenShotFx();

        // 5. Crea un elemento UI prefabbricato (es. Button)
        this.btn = this.fx.add.Button(400, 500, 150, 50, "Gioca");
    }
}

Opzione B: Classi Separate (Compatibilità e Isolamento)

Se preferisci mantenere i moduli isolati o se hai già un codice esistente configurato con le vecchie versioni:

import * as Phaser from "phaser";
import fx, { fxSystem, Add } from "phaserpluginfx";

class GameScene extends Phaser.Scene {
    create() {
        this.sprite = this.add.image(400, 300, "myTexture");

        // Associazione manuale dell'istanza fx all'oggetto di gioco
        this.sprite.fx = new fx(this.sprite);
        this.sprite.fx.ShakeFx(500, 10);

        // Istanziazione dei gestori della scena e della creazione di prefab
        this.fxSystem = new fxSystem(this);
        this.addObjects = new Add(this);
    }
}

💡 Supporto Doppia Firma

Tutti gli effetti accettano parametri posizionali oppure un oggetto di configurazione:

this.sprite.fx.ShakeFx(500, 10);
this.sprite.fx.ShakeFx({ duration: 500, intensity: 10 });

🔗 Concatenamento Sequenziale

Tutti gli effetti restituiscono un oggetto ChainFx che permette il concatenamento automatico temporizzato tramite il getter .chain:

this.sprite.fx.GlowFx(800)
    .chain.ShakeFx(600, 10)
    .chain.ClickFx()
    .chain.GetBiggerFx(1.4, null, 400);

Cambio Target nella Catena

È possibile cambiare il GameObject target all'interno di una stessa catena utilizzando i metodi .target(nuovoGameObject) o .changeTarget(nuovoGameObject). Gli effetti successivi della catena verranno applicati al nuovo target a partire dal momento in cui sono pianificati.

this.sprite1.fx.ShakeFx(500)
    .chain.target(this.sprite2).PulseFx(1000, 1, 5)
    .chain.changeTarget(this.sprite1).RotateFx(500, 15, 2);

Callback al Completamento (OnComplete)

È possibile registrare una funzione di callback personalizzata da eseguire al termine di un effetto o al completamento dell'intera catena. Questo è ideale per eseguire logiche di gioco personalizzate (es. avviare una nuova scena o attivare eventi di gioco) non appena le animazioni finiscono.

I metodi supportati sono .onComplete(callback), .onCompleted(callback) e .OnCompleted(callback).

this.fx.target(logo).FadeInFx().chain.FadeOutFx().OnComplete(goToNextScene);

function goToNextScene() {
    this.scene.start("scena2");
}

🎨 Catalogo Effetti per GameObject (.fx)

1. Shake (Vibrazione)

Fa vibrare rapidamente l'oggetto attorno alla sua posizione iniziale. Supporta la modalità loop infinito.

• Firme: ShakeFx(duration, intensity) · ShakeFx({ duration, intensity, loop })
• Parametri: duration (ms, default 500) · intensity (px, default 5) · loop (boolean, default false)
• Esempi:

  this.sprite.fx.ShakeFx(500, 10);
  this.sprite.fx.ShakeFx({ intensity: 8, loop: true }); // shake infinito
  // Da fermare con:
  this.sprite.fx.Stop('shake');

2. Rotate (Oscillazione Rotatoria)

Fa oscillare l'oggetto a destra e sinistra rispetto al suo angolo iniziale.

• Firme: RotateFx(duration, intensity, speed) · RotateFx({ duration, intensity, speed })
• Esempio: this.sprite.fx.RotateFx(500, 15, 2);

3. Pulse (Pulsazione Continua di Scala)

Ingrandisce e rimpicciolisce l'oggetto in modo ciclico e fluido.

• Firme: PulseFx(duration, intensity, speed) · PulseFx({ duration, intensity, speed })
• Esempio: this.sprite.fx.PulseFx(1300, 2, 5);

4. DamageNumber (Numero di Danno Fluido)

Crea un testo fluttuante temporaneo che sale verso l'alto ruotando e sfumando.

• Firme: DamageNumberFx(number, size, color) · DamageNumberFx({ number, size, color })
• Esempio: this.sprite.fx.DamageNumberFx(99, 28, "ff0000");

5. Glow (Bagliore Neon Pulsante)

Crea un clone temporaneo dietro all'oggetto che si ingrandisce e sfuma, con supporto loop.

• Firme: GlowFx(duration, size, loop) · GlowFx({ duration, size, loop })
• Esempio: this.sprite.fx.GlowFx(1000, 2, true);

6. GetBigger / GetSmaller (Ingrandimento / Rimpicciolimento)

Alterna rapidamente la scala dell'oggetto (e opzionalmente la sua texture) tra le dimensioni normali e quelle modificate.

• Firme: GetBiggerFx(size, texture, duration, speed) · GetSmallerFx(size, texture, duration, speed)
• Esempi:

  this.sprite.fx.GetBiggerFx(1.3, "alt_texture", 500);
  this.sprite.fx.GetSmallerFx(0.7, null, 500);

7. ChangeTexture (Alternanza Texture Rapida)

Alterna rapidamente la texture del GameObject ad intervalli regolari.

• Firme: ChangeTextureFx(texture, duration, speed) · ChangeTextureFx({ texture, duration, speed })
• Esempio: this.sprite.fx.ChangeTextureFx("nuova_texture", 600, 6);

8. FloatX / FloatY (Moto Armonico Sinusoidale)

Fa oscillare orizzontalmente o verticalmente l'oggetto in modo fluido tramite un'onda sinusoidale. Supporta loop infinito.

• Firme: FloatXFx(distance, duration, loop) · FloatYFx(distance, duration, loop)
• Esempi:

  this.sprite.fx.FloatXFx(50, 1000, true);
  this.sprite.fx.FloatYFx(30, 800, true);

9. Click (Simulazione Click Bottone UI)

Simula la pressione fisica di un bottone muovendolo verso il basso con un feedback visivo di oscuramento. Compatibile con Sprite/Image e con Shape/Rettangoli.

• Firma: ClickFx()
• Esempio: this.sprite.fx.ClickFx();

10. Slime (Deformazione Elastica Squash & Stretch)

Schiaccia e allunga l'oggetto con un oscillatore armonico smorzato, preservandone il volume (area).

• Firme: SlimeFx(duration, speed) · SlimeFx({ duration, speed })
• Esempio: this.sprite.fx.SlimeFx(1000, 1.2);

11. Immune (Lampeggio Invulnerabilità)

Modifica l'opacità dell'oggetto in modo intermittente per simulare uno stato di immunità temporanea.

• Firme: ImmuneFx(duration) · ImmuneFx({ duration })
• Esempio: this.sprite.fx.ImmuneFx(1000);

12. PopIn (Comparsa Elastica)

Mostra l'oggetto facendolo apparire da scala 0 con un rimbalzo elastico fluido.

• Firme: PopInFx(duration, finalScale) · PopInFx({ duration, finalScale })
• Esempio: this.sprite.fx.PopInFx(500, 1.5);

13. PopOut (Scomparsa Elastica)

Nasconde l'oggetto rimpicciolendolo elasticamente fino a 0.

• Firme: PopOutFx(duration, startScale) · PopOutFx({ duration, startScale })
• Esempio: this.sprite.fx.PopOutFx(500);

14. FadeIn (Dissolvenza in Entrata)

Porta l'opacità dell'oggetto da 0 al valore desiderato.

• Firme: FadeInFx(duration, finalAlpha) · FadeInFx({ duration, finalAlpha })
• Esempio: this.sprite.fx.FadeInFx(500, 1);

15. FadeOut (Dissolvenza in Uscita)

Riduce l'opacità dell'oggetto al valore desiderato.

• Firme: FadeOutFx(duration, finalAlpha) · FadeOutFx({ duration, finalAlpha })
• Esempio: this.sprite.fx.FadeOutFx(500, 0);

16. Blink (Lampeggio Alpha)

Fa lampeggiare l'opacità dell'oggetto alternandola tra il valore originario e un valore minimo.

• Firme: BlinkFx(duration, speed) · BlinkFx({ duration, speed })
• Esempio: this.sprite.fx.BlinkFx(1000, 5);

🎈 Metodi Complessi (.fx — Shader Post-FX)

Effetti avanzati che utilizzano la pipeline Barrel Post-FX di Phaser 3.60+ in modalità WebGL.

⚠️ Richiedono Phaser 3.60+ e il renderer WebGL. In modalità Canvas lo scaling viene comunque applicato ma senza la deformazione sferica dello shader.

17. BaloonFx (Gonfiamento a Palloncino 3D)

Gonfia progressivamente il target ingrandendolo in modo asimmetrico (più largo che alto) e applicando una deformazione sferica Barrel sulla texture. Lo shader rimane attivo al termine: ogni chiamata accumula il gonfiamento a partire dalla scala attuale.

• Firma: BaloonFx()
• Concatenamento: restituisce ChainFx con ritardo di 500ms
• Esempio:

  this.sprite.fx.BaloonFx();
  this.sprite.fx.BaloonFx().chain.ShakeFx(); // gonfia poi vibra

18. StopBaloonFx (Reset Completo Palloncino)

Interrompe l'effetto palloncino, rimuove lo shader Barrel dalla pipeline GPU e riporta l'oggetto alla scala originaria.

• Firma: StopBaloonFx()
• Esempio: this.sprite.fx.StopBaloonFx();

19. FireWorksFx (Esplosione Fuochi d'Artificio)

Scompone visivamente il target in una griglia 8x8 di frammenti che vengono proiettati radialmente verso l'esterno a 360 gradi a partire dal baricentro dell'immagine. Dispone di rallentamento progressivo per attrito (drag) e riduzione di scala delle particelle. Nota: l'oggetto target originale rimane permanentemente invisibile (alpha = 0) al completamento o arresto (simulando una distruzione definitiva).

• Firma: FireWorksFx(duration)
• Esempio: this.sprite.fx.FireWorksFx(1000);
• Compatibilità: Supporta l'ereditarietà automatica dello shader Barrel e del padding se applicato da BaloonFx prima dello scoppio.

20. DebrisFx (Scomposizione Dinamica in Frammenti)

Scompone l'oggetto in una griglia 8x8 di frammenti grafici statici (ereditando texture, coordinate, origin, profondità, rotazione, tinta, blend mode e shader/padding attivi sul target padre) e li restituisce sotto forma di array, pronti ad essere animati manualmente o gestiti esternamente.

• Firma: DebrisFx()
• Esempio: const frammenti = this.sprite.fx.DebrisFx();

21. ExplodeFx (Esplosione a Palloncino Sequenziale)

Un effetto combinato drammatico che innesca in sequenza temporizzata:

1. Il gonfiamento dell'oggetto a palloncino sferico 3D (BaloonFx per 500ms).
2. Una forte vibrazione contemporanea (ShakeFx per 500ms).
3. L'esplosione finale a fuochi d'artificio (FireWorksFx per altri 500ms), ereditando la deformazione sferica sui 64 frammenti che schizzano radialmente a 360 gradi e svaniscono rallentando. L'oggetto target rimane permanentemente invisibile (alpha = 0) al termine dell'effetto (simulando una completa distruzione).

• Firma: ExplodeFx()
• Esempio: this.sprite.fx.ExplodeFx();
• Concatenamento: restituisce ChainFx con durata totale di 1000ms.

⏹️ Arresto degli Effetti

La libreria permette di fermare gli effetti standard ripristinando posizione, scala, colore, opacità e texture originarie.

// Ferma un effetto specifico (case-insensitive):
this.sprite.fx.Stop('shake');
this.sprite.fx.Stop('FloatXFx');
this.sprite.fx.Stop('popin');
this.sprite.fx.Stop('fadeout');
this.sprite.fx.Stop('blink');

// Ferma tutti gli effetti standard:
this.sprite.fx.Stop();
// oppure:
this.sprite.fx.StopAllFx();

// Per fermare il Baloon usare il metodo dedicato:
this.sprite.fx.StopBaloonFx();

// Per fermare l'esplosione usare il metodo dedicato:
this.sprite.fx.StopExplodeFx();

Nota: BaloonFx ed ExplodeFx non vengono gestiti dallo stop globale poiché mantengono stati persistenti o sequenze temporizzate complesse. Usare sempre StopBaloonFx() e StopExplodeFx() per il rispettivo reset completo.

🌎 Effetti della Scena (fxSystem)

Il gestore fxSystem permette di orchestrare variazioni temporali sull'intera scena di gioco.

this.fxSystem = new fxSystem(this);

1. RallyFx (Slow Motion / Dilatazione Temporale)

Rallenta timer, tween e fisica per una durata definita, poi ripristina automaticamente la velocità normale.

• Firme: RallyFx(duration, rally) · RallyFx({ duration, rally })
• Esempio: this.fxSystem.RallyFx(3000, 0.2); (tempo al 20% per 3 secondi reali)

2. SetTimeSpeedFx (Velocità del Tempo Fissa)

Imposta la velocità del tempo globale a tempo indefinito.

• Firme: SetTimeSpeedFx(speed) · SetTimeSpeedFx({ speed })
• Esempio: this.fxSystem.SetTimeSpeedFx(0.5); (tempo dimezzato costantemente)

3. NormalTimeFx (Ripristino Forza Tempo)

Forza il ripristino istantaneo del timeScale a 1 (o al valore specificato).

• Firma: NormalTimeFx(speed?)
• Esempio: this.fxSystem.NormalTimeFx();

4. ScreenShotFx (Effetto Flash / Screenshot dello Schermo)

Esegue un effetto flash (colore bianco temporaneo) che copre l'intero viewport della telecamera principale, simulando uno scatto fotografico o un bagliore accecante.

• Firme: ScreenShotFx(duration) · ScreenShotFx({ duration })
• Esempio: this.fxSystem.ScreenShotFx(500); (flash da 500ms totali)

🛠️ Creazione di GameObject (Add)

La classe Add consente di istanziare rapidamente elementi grafici prefabbricati pronti all'uso e già configurati con interattività e stili coerenti.

import fx, { fxSystem, Add } from "phaserpluginfx";

// Nella scena di gioco:
this.addObjects = new Add(this);

1. Button (Pulsante UI Prefabbricato)

Crea un pulsante composto da uno sfondo rettangolare e da un testo centrale inseriti all'interno di un Phaser.GameObjects.Container interattivo (cliccabile).

• Firma: Button(x, y, width, height, text, color, textColor)
• Esempio:

  const btn = this.addObjects.Button(400, 300, 150, 60, "Gioca", 0x0000ff, "#ffffff");
  btn.on('pointerdown', () => {
      console.log("Pulsante cliccato!");
  });

💡 Caratteristiche Architetturali

• Modularità: ogni effetto standard risiede nel proprio file in methods/; gli effetti complessi con shader sono in complex/complexMethods/.
• Stop Preciso: se un effetto è già attivo viene arrestato prima di memorizzare i valori originari, evitando la registrazione di stati deformati.
• Garbage Collection Integrata: cloni, testi fluttuanti, timer e shader vengono distrutti automaticamente al completamento o allo stop.
• Riutilizzo Shader: BaloonFx rileva e riutilizza lo shader Barrel preesistente invece di istanziarne di nuovi ad ogni chiamata (evita stacking e sprechi GPU).

👥 Crediti

Tutto fatto da Angelo del Piano 🚀