BeeTime — Documentazione Tecnica (BeeEngine)

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:

1. 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.
2. 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.