MicroProfiler

Il MicroProfiler è uno strumento di ottimizzazione delle prestazioni e risoluzione dei problemi in Roblox Studio e nel client Roblox. Fornisce informazioni dettagliate e visive sui tempi di esecuzione per tutti i compiti del motore che vengono eseguiti durante un frame, come l'animazione dei personaggi, l'aggiornamento della fisica, l'esecuzione degli script e il rendering della geometria. Puoi identificare quali compiti sono stati eseguiti durante quale frame, quanto tempo hanno impiegato a essere eseguiti e se qualcuno di essi ti ha fatto perdere i tuoi obiettivi di tempo per frame.

Tempi di frame

Per utilizzare il MicroProfiler, devi comprendere la relazione tra tempo di frame e frequenza dei frame.

• Il tempo di frame è quanto tempo ha impiegato un frame a essere visualizzato sullo schermo, generalmente misurato in millisecondi.
• La frequenza dei frame è il numero di frame visualizzati sullo schermo, generalmente misurato in frame al secondo (FPS).

Tempi di frame più bassi significano una frequenza di frame più alta. Dividi 1.000 millisecondi (1 secondo) per il tempo di frame per ottenere la frequenza di frame.

Tuttavia, per un gameplay fluido, non è sufficiente avere una frequenza di frame alta. Hai bisogno di tempi di frame coerenti. Ad esempio, se 59 frame arrivano in 10 millisecondi e un frame in 410 millisecondi, i giocatori percepiscono un enorme e brusco scossone, anche se il gioco sta girando a 60 FPS. Se tutti i frame impiegano all'incirca lo stesso tempo per essere renderizzati, il tuo gioco sembrerà percepibilmente più fluido grazie a quella coerenza, specialmente a frequenze di frame più basse.

Il MicroProfiler si concentra interamente sul tempo di frame. Il suo scopo è aiutarti a identificare i picchi di tempo di frame e cosa li ha causati.

Aprire il MicroProfiler

L'apertura del MicroProfiler varia a seconda della piattaforma:

• Sul client mobile, apri il menu Impostazioni e attiva il MicroProfiler su On. Poi, da un computer di sviluppo sulla stessa rete, usa il tuo browser web per navigare all'indirizzo IP e alla porta forniti.

  

  Questo screenshot mostra un indirizzo IP di 172.18.56.105 e una porta di 1338, quindi naviga a 172.18.56.105:1338. A seconda della configurazione di rete del tuo dispositivo, potresti vedere più indirizzi IP. Se uno non funziona, prova il successivo.

  Per impostazione predefinita, l'interfaccia web del MicroProfiler mostra i 30 frame più recenti dal tuo dispositivo mobile. Per un set più ampio di frame, aggiungi una barra e un numero all'URL, come 172.18.56.105:1338/90. Per ottenere un nuovo set di frame, usa il pulsante Ri-cattura.

• Sul client desktop, premi CtrlF6 (⌘F6).

• In Studio, premi CtrlF6 (⌘F6).

In generale, il client mobile è il miglior posto per profilare il tuo gioco. La maggior parte dei giocatori su Roblox utilizza telefoni e tablet, e questi dispositivi hanno severe limitazioni termiche e di potenza che ne limitano le prestazioni. Se il tuo gioco funziona bene su un tablet Android di fascia media, è quasi certo che funzioni molto, molto meglio su un desktop da gioco.

Nozioni di base sul MicroProfiler

Il MicroProfiler ha due componenti chiave: il grafico a barre del tempo di frame e la linea temporale dei compiti dettagliati.

• Il grafico del tempo di frame si estende lungo la parte superiore dell'interfaccia e mostra quanto tempo ha impiegato ogni frame a essere renderizzato. Barre più alte significano tempi di frame più lunghi.
• La linea temporale mostra tutti i singoli compiti che sono stati eseguiti durante il frame. Barre più larghe rappresentano compiti che hanno impiegato più tempo a essere eseguiti.

Un flusso di lavoro tipico nel MicroProfiler è utilizzare il grafico del tempo di frame per identificare un picco (una barra più alta) e poi utilizzare la linea temporale per identificare quali compiti hanno causato il picco. Poi puoi controllare il Riferimento ai tag per informazioni sul compito e su come migliorare le sue prestazioni.

Grafico del tempo di frame

L'altezza di ogni barra indica il numero di millisecondi che ci sono voluti per completare il frame. I frame più recenti si trovano a destra. Passa il mouse su un frame per alcune informazioni di base sull'uso della CPU e della GPU.

• Le barre arancioni sono frame in cui il Tempo di Lavoro dei Compiti supera il Tempo di Lavoro di Rendering. In questi frame, almeno uno dei thread di lavoro, che eseguono operazioni come eseguire script, calcolare la fisica e riprodurre animazioni, ha impiegato più tempo a essere eseguito rispetto al thread di rendering principale.

  Se il gioco non raggiunge i tuoi obiettivi di tempo di frame e ha un gran numero di frame arancioni, le cause comuni sono script, fisica e animazioni. Vedi Migliora le prestazioni.

• Le barre blu sono frame in cui il Tempo di Lavoro di Rendering supera il Tempo di Lavoro dei Compiti. In questi frame, il thread di rendering principale ha impiegato più tempo di qualsiasi dei thread di lavoro.

  Se il gioco non raggiunge i tuoi obiettivi di tempo di frame e ha un gran numero di frame blu, ciò indica un collo di bottiglia nel rendering. Le cause comuni sono una densità eccessiva di oggetti, movimento degli oggetti e illuminazione. Vedi Migliora le prestazioni.

• Le barre rosse sono frame in cui sono vere due condizioni:

  • Tempo di Lavoro di Rendering supera Tempo di Lavoro dei Compiti
  • Tempo di Attesa della GPU è maggiore di 2,5 millisecondi

  Le barre rosse sono meno comuni delle arancioni e blu e spesso il risultato di una complessità eccessiva degli oggetti, dimensioni delle texture e effetti visivi. L'ottimizzazione è simile a quella delle barre blu. Vedi Migliora le prestazioni.

Compiti piccoli alla fine di un frame possono talvolta alterare il Tempo di Lavoro dei Compiti e il Tempo di Lavoro di Rendering, il che è un buon motivo per concentrarsi di più sul tempo di frame piuttosto che sul colore del frame. Non esiste un "colore buono" da perseguire. Una miscela di arancione, blu e rosso non è problematica finché raggiungi i tuoi obiettivi di tempo di frame. Se non stai raggiungendo i tuoi obiettivi di tempo di frame, i colori possono indicare dove ottimizzare.

Linea temporale

• Fai clic con il pulsante sinistro e trascina per spostare la linea temporale. Su una macchina con molti core CPU, potresti dover spostarti su e giù per trovare il thread che esegue un compito particolare.

  

• Scorrere ingrandisce e riduce la linea temporale. Combinato con le etichette in millisecondi nella parte superiore della linea temporale, puoi avere un'idea di quanto tempo ha impiegato un compito in senso assoluto, ma anche quanto tempo ha impiegato rispetto ad altri compiti.

  

• La sovrapposizione verde sul grafico a barre indica il numero di frame attualmente visibili sulla linea temporale—il tuo livello di zoom. Fai clic con il pulsante sinistro su una barra di frame per saltare a quella posizione sulla linea temporale.

  Potresti dover regolare il tuo livello di zoom, ma passando il mouse su una barra si evidenzia il frame sulla linea temporale. Linee grigie chiare delimitano i frame.

  

• Le etichette che appaiono direttamente sotto un'altra etichetta indicano compiti che vengono eseguiti come parte del compito di livello superiore.

  Piuttosto che il compito genitore, di solito vuoi risolvere i compiti figlio con le prestazioni peggiori; un compito genitore non può essere più breve della somma dei suoi compiti figlio.

• Fai clic con il pulsante destro su un'etichetta per ingrandire la linea temporale esattamente alla durata di quel compito.

• Se la quantità di informazioni è opprimente, usa il menu Gruppi o Thread per filtrare la linea temporale. Ad esempio, potresti voler vedere solo i compiti Render nel thread principale.

  

• Usa CtrlF (⌘F) per saltare all'occorrenza di un compito che occupa più tempo nel dump. Ad esempio, computeLightingPerform viene eseguito in ogni frame client. Se lo cerchi in un dump con 128 frame, puoi saltare al frame in cui ha impiegato più tempo a completarsi.

Thread

Come molti programmi, Roblox utilizza più thread per eseguire sequenze di compiti contemporaneamente. Il MicroProfiler visualizza il nome del thread sul lato sinistro della linea temporale.

Ci sono tre tipi di thread importanti:

• Principale ("RBX Main"): Gestisce i compiti di rendering basati su CPU. Elabora input, Humanoids, animazioni/tweening, proprietà fisiche, suono e attesa delle riprese degli script. Aggiorna anche le interfacce di Studio e coordina gli altri thread.

• Lavoratore ("RBX Worker"): Aiuta il thread principale con networking, fisica e pathfinding. A causa del numero di core nei moderni CPU, probabilmente hai molti thread di lavoro, la maggior parte dei quali è in uno stato di sonno in qualsiasi momento.

• Render ("GPU"): Segue una logica di "preparare, eseguire, presentare". Comunica con l'unità di elaborazione grafica (GPU) del dispositivo.

  • Preparare: Le informazioni dal thread principale vengono utilizzate per aggiornare i modelli di rendering.
  • Eseguire: Emissione di comandi di rendering, inclusi interfacce 2D.
  • Presentare: Sincronizza con la GPU.

Profili di script personalizzati

Se i tuoi script stanno eseguendo compiti complicati, puoi profilare porzioni critiche del codice per assicurarti che non stiano impiegando troppo tempo. Avvolgi il codice con debug.profilebegin() e debug.profileend() per misurare tutto ciò che viene eseguito tra quelle chiamate di funzione e creare un'etichetta sulla linea temporale del MicroProfiler.

local RunService = game:GetService("RunService")

local function onPreSimulation()
  debug.profilebegin("Hard Work")
  -- Esempio di lavoro duro: scambia due variabili 200.000 volte
  local a, b = 0, 1
  for _ = 1, 200000 do
    a, b = b, a
  end
  debug.profileend()
end
RunService.PreSimulation:Connect(onPreSimulation)

Dalla sua durata sulla linea temporale, puoi dire che la funzione sta utilizzando molto tempo di elaborazione rispetto ad altri compiti.

Analizza le catture con Assistant

In Studio, puoi chiedere ad Assistant di analizzare automaticamente una cattura del MicroProfiler in pausa, identificare i colli di bottiglia delle prestazioni e proporre correzioni.

1. In Studio, apri il MicroProfiler con CtrlF6 (⌘F6).
2. Quando noti un picco di tempo di frame, metti in pausa la cattura premendo Pausa nel menu in alto o usando CtrlP (⌘P).
3. Apri Assistant e chiedi di analizzare la cattura. Esempi di richieste includono:

   • "Ho catturato un picco di tempo di frame nel MicroProfiler—analizzalo."
   • "Cosa ha causato il picco?"
   • "È legato alla fisica o agli script?"
   • "Quale categoria ha il tempo esclusivo più alto?"
   • "Quando sono nell'hangar, gli FPS calano. Riproduci il problema, usa il MicroProfiler per trovare la causa, risolvila e ritesta."

Assistant legge la cattura in pausa tramite l'API del MicroProfiler e restituisce un rapporto sui probabili colli di bottiglia, insieme a proposte di modifiche agli script o alla scena che puoi applicare.

Questa funzionalità funziona anche tramite il server Studio MCP, quindi puoi integrare le analisi del MicroProfiler nel tuo agente AI o ciclo agentico per ottenere feedback automatico su come le nuove modifiche influenzano le prestazioni del tuo gioco.

Salva i dati dei frame

Se desideri salvare un insieme di dati sui frame per una revisione successiva (o per condividerli con qualcun altro), usa il pulsante Salva su file. Il MicroProfiler salva i dati dei frame in un file HTML autonomo chiamato microprofile-<data>-<ora>.html.

Sul client desktop o in Studio, usa il menu Dump. In entrambi i casi, il MicroProfiler salva automaticamente il file nella directory dei log di Roblox:

• Su Windows, controlla %LOCALAPPDATA%\Roblox\logs.

  Se utilizzi l'app Universal Windows Platform (UWP), controlla \Users\<username>\AppData\Local\Packages\ROBLOXCORPORATION.ROBLOX_<hash>\LocalState\logs\.

• Su macOS, controlla ~/Library/Logs/Roblox.

Profilare il server

Oltre a profilare il client, puoi catturare brevi dump dell'attività del server:

1. Sul client desktop, unisciti a un gioco per il quale hai permessi di modifica.

2. Apri la Console Sviluppatore con CtrlF9 (⌘F9).

3. Nel menu a discesa, seleziona MicroProfiler.

4. Nella scheda Server, specifica il numero di frame da catturare (massimo 60) e il numero di secondi di ritardo prima di iniziare la cattura (massimo 4).

5. Fai clic su Inizia registrazione server.

   

   Dopo alcuni secondi, la Console Sviluppatore fornisce il percorso del file, che è lo stesso percorso di un dump standard.

Funzionalità solo web

Il MicroProfiler ha due interfacce utente: l'interfaccia web (mobile e dump) e l'interfaccia desktop (client e Studio). Ti consigliamo di utilizzare l'interfaccia web ogni volta che è possibile. In generale, le due funzionano in modo simile, ma l'interfaccia web ha alcune funzionalità extra:

• Usa il menu X-Ray per abilitare o disabilitare la codifica a colori per l'allocazione della memoria.

  

  • Frame più chiari all'interno del grafico a barre principale indicano un'allocazione di memoria più alta.
  • Porzioni più chiare della barra di anteprima e etichette più chiare sulla linea temporale indicano porzioni del frame con un'allocazione di memoria più alta.
  • In modalità X-ray, premi C per mostrare la dimensione totale delle allocazioni di memoria piuttosto che il numero di allocazioni.

• Usa il menu Esporta per esportare un grafico a fiamma della CPU o della memoria, una visualizzazione specializzata che aggrega tutti gli stack di chiamate inclusi nel dump, mantiene la gerarchia genitore-figlio e li dimensiona in base alla durata. I grafici a fiamma sono particolarmente utili per identificare compiti che non ti fanno perdere i tuoi obiettivi di tempo di frame (e quindi sono difficili da notare), ma vengono eseguiti così spesso che il loro tempo di elaborazione diventa significativo.

  

  Puoi anche creare grafici a fiamma in Studio, sebbene solo per script (tempo di esecuzione e allocazioni di memoria). Rispetto ai grafici a fiamma basati sul web, quelli in Studio sono dall'alto verso il basso piuttosto che dal basso verso l'alto e supportano tempi di cattura notevolmente più lunghi.

  

• Trascina e rilascia un secondo file di dump nell'interfaccia web per generare un grafico a fiamma differenziale, che può aiutarti a identificare miglioramenti o regressioni nelle prestazioni del tuo gioco nel tempo. Fai clic su Combina e Confronta per esportare un nuovo file HTML.

  

  Puoi combinare diversi file di dump—ad esempio, quattro su ciascun lato, prima e dopo un aggiornamento importante—per ottenere un confronto più aggregato. Confrontare i dati tra luoghi diversi può essere utile, ma non combinare dati provenienti da luoghi diversi!

  Il grafico a fiamma differenziale evidenzia il dump (sinistro o destro) che consuma più CPU o memoria, con colori più brillanti che indicano una maggiore differenza.

  

Funzionalità solo desktop

Sulla linea temporale desktop, fai clic con il pulsante sinistro su un'etichetta per aggiungerla a un grafico a linee in basso a destra. Il grafico mostra il tempo che il compito impiega in ogni frame. Utilizzando questo grafico, puoi testare le prestazioni solo di alcuni compiti nel tuo gioco. Quando hai finito, fai clic con il pulsante destro del mouse sul grafico per nasconderlo.

Questo grafico è sincronizzato con le barre del profiler principale. L'intervallo di frame attualmente selezionato è evidenziato in verde sul grafico. Puoi anche fare clic ovunque su questo grafico per ri-centrare la vista principale del profiler su quel frame specifico, il che è utile per trovare picchi nella vista dettagliata.

Cerca nella vista dettagliata

Sul client desktop, puoi cercare compiti per nome nella vista Dettagliata:

1. Apri il MicroProfiler con CtrlF6 (⌘F6) e passa alla modalità Dettagliata.

2. Premi CtrlF (⌘F) per aprire la casella di ricerca.

3. Digita parte di un nome di compito o etichetta. Il matching non fa distinzione tra maiuscole e minuscole e trova il testo ovunque nel nome. Le etichette corrispondenti mantengono il loro colore e tutte le altre etichette sono attenuate. I frame che contengono una corrispondenza sono evidenziati nel grafico del tempo di frame.

4. Spostati tra le corrispondenze:

   Azione	Scorciatoia
   Prossima corrispondenza	F3 o Invio
   Corrispondenza precedente	ShiftF3 o ShiftInvio

   Puoi anche fare clic sui pulsanti < e > accanto alla casella di ricerca. La corrispondenza attuale è delineata e contrassegnata con un triangolo sopra di essa, e un contatore come 12 / 340 mostra la sua posizione tra tutte le corrispondenze. Se la corrispondenza è fuori schermo, la linea temporale scorre verso di essa. Se hai spostato la linea temporale, la navigazione continua dalle corrispondenze attualmente visibili.

5. Premi Esc, o premi di nuovo CtrlF (⌘F), per chiudere la ricerca. Chiudere la ricerca non chiude il MicroProfiler.