DEV Community: Antonio

BeeLadybug — Debug Visivo e Monitoraggio per BeeEngine

Antonio — Thu, 10 Sep 2026 20:21:22 +0000

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).

BeeTime — Documentazione Tecnica (BeeEngine)

Antonio — Thu, 10 Sep 2026 20:00:38 +0000

BeeTime — Gestione Avanzata del Tempo e del Core Loop

BeeTime è il motore temporale centralizzato di BeeEngine (situato in src/core/BeeTime.js). Gestisce un singolo ciclo di aggiornamento (tick) per ogni fotogramma applicando il concetto dei due assi temporali indipendenti. Questo approccio permette di congelare o rallentare il gameplay senza mai bloccare le interfacce utente (HUD), gli shader di transizione o i sistemi audio di sottofondo.

📦 NPM: https://npmjs.com

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

📁 Architettura dei Due Assi Temporali

A ogni frame, il ciclo principale invoca time.tick(timestamp) una sola volta. Da questo singolo impulso scaturiscono due metriche di delta time distinte:

Unscaled Time (Tempo Reale): Avanza costantemente basandosi sull'orologio di sistema. Viene utilizzato per l'HUD, i menu di pausa, gli effetti visivi dell'interfaccia e i mixer audio.
Scaled Time (Tempo di Simulazione): Risente dei modificatori di scala temporale (timeScale) e dello stato di pausa del gioco. Viene impiegato per la logica dei componenti, le animazioni dei personaggi, le intelligenze artificiali e la simulazione fisica.

import { BeeEngine } from 'beeengine';

const gioco = new BeeEngine('testCanvas', 800, 600);
gioco.start();

// Esempi di manipolazione temporale:
gioco.pause();              // Blocca l'asse di simulazione (scaled), l'HUD rimane interattivo
gioco.resume();             // Ripristina lo scorrimento normale del tempo di gioco
gioco.setTimeScale(0.25);   // Imposta l'effetto slow-motion (simulazione al 25% della velocità)
gioco.time.togglePause();   // Inverte lo stato di pausa (ideale per shortcut di sviluppo come F4)

⚠️ Nota Architetturale: BeeTime non è uno scheduler di eventi o una libreria di tweening. È un fornitore di dati puramente numerici. Sistemi complessi come BeeSceneManager o BeePhysicsWorld interrogano questi numeri per sincronizzare lo scorrimento del mondo di gioco.

⚙️ Configurazione di Default (`BEE_TIME_DEFAULTS`)

La configurazione iniziale dell'orologio è regolata da un oggetto congelato e immutabile:

export const BEE_TIME_DEFAULTS = Object.freeze({
  maxDelta: 0.05,          // Evita lo "spike del tempo" (es. lag improvvisi o cambi di tab)
  timeScale: 1,            // Scala temporale di base (1x = velocità normale)
  minTimeScale: 0,         // Limite minimo per il rallentatore
  maxTimeScale: 16,        // Limite massimo per l'accelerazione (fast-forward)
  fixedDelta: 1 / 60,      // Intervallo di tempo fisso per i calcoli della fisica (60Hz)
  maxFixedSteps: 5,        // Numero massimo di sotto-passi fisici per frame (previene la spirale della morte)
  fpsSampleWindow: 0.5     // Finestra di campionamento in secondi per il calcolo del framerate
});

🛠️ API Reference

Proprietà di Sola Lettura (Getters)

paused (boolean): Restituisce true se la simulazione di gioco è congelata.
timeScale (number): Il fattore di moltiplicazione corrente applicato all'asse di simulazione.
scaledDt / dt (number): Delta time modificato, espresso in secondi. Se il gioco è in pausa, il suo valore è 0.
realDt / unscaledDt (number): Delta time reale in secondi, limitato dal tetto massimo di maxDelta.
alpha (number): Valore percentuale residuo (da 0 a 1) dell'accumulatore fisico, utilizzato per interpolare graficamente le posizioni delle entità tra due step fisici.

Metodi di Controllo e Sincronizzazione

`.delta(unscaled = false)`

Restituisce il delta time appropriato per il sistema richiedente. Passando true, restituisce l'asse del tempo reale (unscaledDt).

`.setScale(value)`

Imposta una nuova velocità per il tempo di gioco, vincolando il valore numerico all'interno dei limiti minTimeScale e maxTimeScale.

`.pause()` / `.resume()` / `.togglePause()`

Metodi per congelare, riavviare o invertire al volo lo stato di avanzamento dell'asse di simulazione gameplay.

`.begin(timestamp)`

Allinea l'orologio interno al timestamp corrente senza azzerare i contatori di tempo totali accumulati. È essenziale per prevenire sbalzi distruttivi del delta time subito dopo il caricamento, il ripristino dalla pausa o il ritorno da una scheda del browser in background.

`.reset(timestamp)`

Ripristina interamente i contatori dell'istanza (inclusi i frame renderizzati, i tempi trascorsi e i campionamenti degli FPS) mantenendo inalterati i parametri di configurazione strutturali.

`.tick(timestamp)`

Aggiorna lo stato temporale dell'intero motore. Incrementa i tempi totali (elapsed e unscaledElapsed), calcola i fotogrammi al secondo (FPS) correnti e gestisce l'accumulo di tempo necessario per i cicli di fisica a intervallo fisso.

`.consumeFixedSteps(callback)`

Metodo fondamentale per i motori di fisica deterministici (come BeePhysicsWorld). Svuota l'accumulatore temporale eseguendo la callback passata tante volte quanti sono i passi fissi (fixedDelta) accumulati nell'ultimo frame, garantendo fluidità e precisione anche in caso di fluttuazioni del framerate del browser.

DEV Community: Antonio

BeeLadybug — Debug Visivo e Monitoraggio per BeeEngine

BeeLadybug — Debug Visivo e Monitoraggio di Motore

📁 Caratteristiche Principali

🚀 Esempio di Integrazione

🎹 Scorciatoie di Tastiera (Keybindings)

⚙️ Configurazione di Default (BEE_LADYBUG_DEFAULTS)

🛠️ API Reference

new BeeLadybug(engine, options)

Metodi di Controllo Stato

.configure(options)

.attach()

.detach()

.destroy()

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

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

.poll()

Metodi di Rendering

.drawWorld(ctx)

.drawOverlay(ctx)

BeeTime — Documentazione Tecnica (BeeEngine)

BeeTime — Gestione Avanzata del Tempo e del Core Loop

📁 Architettura dei Due Assi Temporali

⚙️ Configurazione di Default (BEE_TIME_DEFAULTS)

🛠️ API Reference

Proprietà di Sola Lettura (Getters)

Metodi di Controllo e Sincronizzazione

.delta(unscaled = false)

.setScale(value)

.pause() / .resume() / .togglePause()

.begin(timestamp)

.reset(timestamp)

.tick(timestamp)

.consumeFixedSteps(callback)

⚙️ Configurazione di Default (`BEE_LADYBUG_DEFAULTS`)

`new BeeLadybug(engine, options)`

`.configure(options)`

`.attach()`

`.detach()`

`.destroy()`

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

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

`.poll()`

`.drawWorld(ctx)`

`.drawOverlay(ctx)`

⚙️ Configurazione di Default (`BEE_TIME_DEFAULTS`)

`.delta(unscaled = false)`

`.setScale(value)`

`.pause()` / `.resume()` / `.togglePause()`

`.begin(timestamp)`

`.reset(timestamp)`

`.tick(timestamp)`

`.consumeFixedSteps(callback)`