BeeLadybug — Debug Visivo e Monitoraggio per BeeEngine

BeeLadybug — Debug Visivo e Monitoraggio di Motore

BeeLadybug è la classe di debug visivo ufficiale per BeeEngine. Offre un monitoraggio in tempo reale delle prestazioni (FPS, tempo di ciclo, entità attive) e disegna le hitbox AABB e i bounding box direttamente nello spazio mondo del Canvas.

📦 NPM: https://www.npmjs.com/package/beeengine

🐙 GitHub: antonioprosperi2-svg/BeeEngine-V2.5.0

---

📁 Caratteristiche Principali

• Scorciatoie di Tastiera Dedicate: Usa F2 per attivare/disattivare l'overlay, F3 per applicare lo slow-motion (0.25x) e F4 per congelare la simulazione (freeze frame). Non utilizza F12 né la tilde (~), garantendo piena compatibilità con i layout di tastiera italiani.
• Rendering a Due Spazi:
  1. drawWorld(ctx): Disegna le hitbox e i Bounding Box nello spazio mondo (prima di cancellare la trasformazione della camera).
  2. drawOverlay(ctx): Disegna l'HUD e i controlli in spazio schermo (dopo il ripristino della matrice di trasformazione).
• Rilevamento Collisioni integrato: Sfrutta BeeSpatialHash per calcolare ed evidenziare visivamente in rosso le entità in fase di collisione.
• Pulsanti Interattivi: Supporta l'interazione via mouse per attivare le modalità SLOW, STOP e LIVE.

---

🚀 Esempio di Integrazione

import { BeeEngine, BeeLadybug } from 'beeengine';

const gioco = new BeeEngine('gameCanvas', 800, 600);

// Attivazione rapida integrata nell'engine
gioco.enableLadybug();

// Oppure istanziazione manuale
const ladybug = new BeeLadybug(gioco);
ladybug.attach().show();

gioco.start((dt, input, time) => {
    // Intercetta i click sui pulsanti dell'overlay di debug (SLOW, STOP, LIVE)
    ladybug.poll();
});

---

🎹 Scorciatoie di Tastiera (Keybindings)

I seguenti tasti sono mappati nativamente per il controllo rapido del loop di gioco e del debug visivo senza interferire con i tool di sviluppo del browser:

Tasto	Azione	Descrizione
F2	Toggle Overlay	Mostra o nasconde l'interfaccia di debug in spazio schermo.
F3	Slow-Motion	Attiva la scala temporale a 0.25x (o ripristina 1x) per analizzare i frame al rallentatore.
F4	Freeze Frame	Congela la simulazione chiamando internamente time.togglePause().

---

⚙️ Configurazione di Default (BEE_LADYBUG_DEFAULTS)

La classe espone un oggetto immutabile con i valori predefiniti di configurazione estratti dal modulo:

export const BEE_LADYBUG_DEFAULTS = Object.freeze({
  toggleKey: 'F2',
  slowKey: 'F3',
  freezeKey: 'F4',
  slowScale: 0.25,
  colorActive: '#3dff6a',
  colorColliding: '#ff3b3b',
  colorInactive: '#8a8a8a',
  overlayX: 12,
  overlayY: 12
});

---

🛠️ API Reference

new BeeLadybug(engine, options)

Crea un'istanza del modulo di debug legata al motore corrente.

• engine (Object): L'istanza attiva di BeeEngine.
• options (Partial<typeof BEE_LADYBUG_DEFAULTS>, opzionale): Opzioni per sovrascrivere la configurazione di default (colori delle hitbox, coordinate dell'overlay, keybindings).

Metodi di Controllo Stato

.configure(options)

Aggiorna al volo le opzioni di configurazione dell'istanza unendo i valori passati con i default del motore. Ritorna this per il chaining.

.attach()

Aggancia il listener globale dell'evento keydown alla finestra per catturare i comandi rapidi di debug. Ritorna this.

.detach()

Rimuove i listener degli eventi di tastiera precedentemente agganciati con .attach(). Ritorna this.

.destroy()

Esegue il clean-up completo dell'istanza scollegando i listener di input, disabilitando l'overlay e svuotando la memoria delle entità tracciate e dei pulsanti.

.show() / .hide() / .toggle()

Metodi di utilità per manipolare lo stato di visibilità dell'interfaccia grafica (enabled). Ritornano tutti this.

.applySlowMo() / .toggleFreeze() / .restoreRealtime()

Metodi interni mappati sulle scorciatoie da tastiera e sui pulsanti interattivi per alterare la scala temporale o lo stato di pausa della simulazione di BeeEngine.time.

.poll()

Invocato all'interno del ciclo di aggiornamento dell'engine (prima di svuotare gli input del frame). Rileva la pressione del mouse e le coordinate del cursore per gestire l'interazione con i pulsanti HUD di runtime.

Metodi di Rendering

.drawWorld(ctx)

Rendering in spazio mondo. Deve essere invocato prima che la matrice di trasformazione della camera venga ripristinata. Rinfresca il sistema di collisione tramite BeeSpatialHash, calcola gli AABB aggiornati e disegna i rettangoli di selezione (Verde per le entità attive, Grigio per le inattive, Rosso semitrasparente per le entità in collisione).

.drawOverlay(ctx)

Rendering in spazio schermo. Deve essere invocato dopo l'azzeramento della matrice di trasformazione (coordinate HUD assolute). Disegna il pannello informativo semitrasparente nell'angolo dello schermo, i contatori in tempo reale di FPS, entità e cicli in millisecondi, e i tre pulsanti cliccabili (F3 SLOW, F4 STOP, 1x LIVE).