Apri SGG/Perfmeter/Setup e seleziona la scheda FTUE. I controlli obbligatori coprono compatibilita, integrazione di rendering, Frame Timing Stats, il percorso del package e un JSON delle impostazioni caricato. Le righe opzionali possono essere installate o ignorate; una riga installata mostra l'azione successiva invece di dichiarare silenziosamente completato il workflow.
Dopo l'installazione di com.unity.memoryprofiler, la riga Memory Profiler offre Open Window/Analysis/Memory Profiler, Copy RequestMemorySnapshot Snippet, Copy Memory Trigger Snippet, Open Runtime e Reveal Snapshots quando esiste la cartella gestita. Gli snippet copiati sono codice runtime che il progetto deve invocare; FTUE non richiede uno snapshot e non configura autonomamente i trigger. I file .snap one-shot vengono preparati sotto Temp/PerfMeter/MemorySnapshots; apri o copia il risultato prima che una richiesta successiva o la pulizia runtime rimuova la sorgente gestita.
Lo snippet one-shot e:
PerfMeterMemorySnapshotRequestResult result = PerformanceMeter.RequestMemorySnapshot(
new PerfMeterMemorySnapshotOptions("ftue-memory-snapshot"));Lo snippet opt-in per i trigger e:
bool configured = PerformanceMeter.ConfigureMemorySnapshotTriggers(
new PerfMeterMemorySnapshotTriggerOptions(
enabled: true,
systemMemoryThresholdBytes: 2L * 1024L * 1024L * 1024L,
leakGrowthThresholdBytes: 256L * 1024L * 1024L));Usa Open Runtime per ispezionare lo snapshot di capability/status. La cattura manuale e il comportamento predefinito; le soglie dei trigger restano disabilitate finche non vengono configurate esplicitamente.
La riga installata Profile Analyzer offre Open Profile Analyzer e Open Runtime. Inizia prima la registrazione in Unity Profiler, poi avvia e arresta una sessione PerfMeter all'interno di quella registrazione. L'apertura usa PerfMeterProfileAnalyzerIntegration.TryOpenProfileAnalyzerForCurrentSession() per aprire Profile Analyzer e copiare l'ID della sessione; carica i dati Profiler registrati e cerca quell'ID. Non installa Profile Analyzer, non carica i dati Profiler e non applica automaticamente un filtro.
La riga installata Adaptive Performance offre Open Runtime per ispezionare lo stato corrente del provider di telemetria opzionale. L'azione FTUE non avvia sessioni e non esegue catture.
RenderDoc e uno strumento esterno e non e incluso in PerfMeter. Segui il flusso di integrazione ufficiale di Unity:
-
Installa RenderDoc dalla pagina ufficiale dei download: https://renderdoc.org/builds.
-
Salva le modifiche del progetto, poi usa Load RenderDoc dal menu della scheda Game View o Scene View. In alternativa, avvia Unity Editor o un Development Build tramite RenderDoc; riavvia Unity se dopo l'installazione Unity non espone l'attachment. La guida ufficiale Unity e https://docs.unity3d.com/6000.0/Documentation/Manual/RenderDocIntegration.html.
-
Fai clic su Check Attachment in FTUE. Questo aggiorna solo il segnale condiviso di Unity per l'external profiler; FTUE non puo rilevare l'installazione di RenderDoc e Unity non puo distinguere RenderDoc da PIX tramite quel segnale.
-
Fai clic su Copy Capture Snippet, entra in Play Mode e invoca il codice copiato dal codice runtime del progetto:
PerfMeterCaptureRequestResult result = PerformanceMeter.RequestCapture( new PerfMeterCaptureOptions("ftue-renderdoc-capture", PerfMeterCaptureTool.RenderDoc, 1));
-
Nell'Editor Windows x64 puoi prima usare Download Verified Bridge o Install Local Bridge; viene installato solo il bridge separato esattamente fissato come plugin Editor-only, mai RenderDoc. Riavvia l'Editor. La richiesta nativa copiata usa
NativeRequired+Copy; MetadataOnly eDoNotSharee Copy/Embed sonoReviewBeforeShare.
La riga opzionale inclusa GraphicsStateCollection non richiede l'installazione di package. Offre Open Runtime, Copy Trace Snippet, Copy Prewarm Snippet e Reveal Artifacts. FTUE non richiede automaticamente trace o prewarm. Usa questa sequenza:
-
In Play Mode, avvia e mantieni attiva una sessione PerfMeter con
PerformanceMeter.StartSession(...). -
Invoca il codice trace copiato dal codice runtime del progetto:
PerfMeterGraphicsStateCollectionRequestResult result = PerformanceMeter.RequestGraphicsStateTrace( new PerfMeterGraphicsStateTraceOptions("ftue-graphics-state-trace", 60));
-
Esegui il polling di
PerformanceMeter.GetGraphicsStateCollectionStatus()fino aState == PerfMeterGraphicsStateCollectionState.Completed. Usa il suoArtifactRelativePath, che punta sottoTemp/PerfMeter/GraphicsStateCollections, come input per il prewarm. Arrestare la sessione durante il tracing annulla il trace. -
Sostituisci
<trace-artifact-file>nello snippet di prewarm copiato con il path restituito:PerfMeterGraphicsStateCollectionRequestResult result = PerformanceMeter.PrewarmGraphicsStateCollection( new PerfMeterGraphicsStatePrewarmOptions("Temp/PerfMeter/GraphicsStateCollections/<trace-artifact-file>"));
-
Fai clic su Reveal Artifacts dopo un trace per rivelare la cartella degli artefatti locale al progetto. Il prewarm e sincrono, conserva l'artefatto e puo segnalare un progressive warmup incompleto. La lunghezza del trace e limitata a 600 frame e gli artefatti gestiti a 64 MiB; il backend Unity non fornisce prove di cache miss.
In Setup > Initialization Code, fai clic su Refresh from Project Settings, quindi su Copy Init Code. Il PerfMeterBootstrap generato include lo snapshot completo e normalizzato delle impostazioni del progetto e chiama PerformanceMeter.TryApplySettingsJson(SettingsJson, out string warning) dopo il caricamento della scena. Trasporta le impostazioni di overlay, logging, alert, session-default e overdraw, rispetta enabled e collectionMode: Stopped e non esegue StartSession né richieste di cattura.
Usa questo bootstrap esplicito invece del percorso Resources di impostazioni zero-code quando e preferibile un avvio gestito dal codice. Se sono presenti entrambi, una chiamata esplicita analizzata correttamente sopprime il callback Resources auto-start per il dominio corrente; se Resources e gia partito prima, lo snapshot esplicito viene applicato dopo e diventa authoritative. Un JSON esplicito non valido lascia invariato il runtime corrente e non sopprime un Resources auto-start successivo. Le operazioni di sessione e overdraw predefinito usano lo snapshot runtime esplicito attivo.
Usa l'overlay quando ti serve visibilita immediata dentro il gioco.
PerformanceMeter.EnsureRunning();
PerformanceMeter.SetOverlayVisible(true);
PerformanceMeter.SetOverlayCorner(PerfMeterOverlayCorner.TopRight);
PerformanceMeter.SetOverlayLayout(PerfMeterOverlayLayout.MetricBars);
PerformanceMeter.SetTargetFps(PerfMeterTargetFps.Fps60);L'overlay usa UI Toolkit e non intercetta l'input di gameplay. Supporta FPS-only, testo compatto, grafici, diagnostica completa, barre metriche, temi visivi, filtri modulo, grafici CPU/GPU, widget dei core CPU e righe limitate di metriche personalizzate.
PerfMeter crea e possiede un host UI Toolkit versionato per l'overlay: Unity 6000.4 usa UIDocument, mentre Unity 6000.5+ usa PanelRenderer. L'host di proprieta e separato dalla UI estranea e ne conserva panel settings e children; i rebuild rimuovono solo il container di proprieta di PerfMeter.
Usa la modalita background per test, esecuzioni su dispositivo o workflow agent in cui non serve UI visibile.
PerformanceMeter.SetCollectionMode(PerfMeterCollectionMode.Background);Usa le sessioni per finestre di profiling ripetibili.
PerformanceMeter.StartSession(new PerfMeterSessionOptions(30, 0.25f, 600));
// Run the measured scenario.
PerformanceMeter.StopSession();
PerfMeterSessionSummarySnapshot summary = PerformanceMeter.GetSessionSummary();
PerformanceMeter.ExportSessionJson("Logs/perfmeter-session.json");
PerformanceMeter.ExportSessionCsv("Logs/perfmeter-session.csv");Le esportazioni sessione includono timing, FPS lows, spikes, conteggi dei colli di bottiglia, contatori render, contatori memoria, stato overdraw, disponibilita di warning/counter, riepiloghi scena, frame peggiori, metadati dispositivo, metadati camera, metadati impostazioni e custom metrics.
Le regole possono segnalare violazioni del budget, FPS bassi, GPU timing non disponibile e soglie overdraw.
PerformanceMeter.AlertFired += alert => UnityEngine.Debug.Log(alert.Message);
PerfMeterAlertSnapshot[] latestAlerts = PerformanceMeter.GetLatestAlerts();Gli avvisi Editor sono limitati da cooldown e possono essere disabilitati tramite impostazioni JSON o controlli runtime. I log degli alert strutturati e gli avvisi Editor sono indipendenti: PerformanceMeter.SetStructuredLogsEnabled(false) sopprime solo l'output Debug.Log degli alert strutturati, mentre PerformanceMeter.SetEditorWarningLogsEnabled(false) controlla separatamente i log di avviso Editor. Callback, alerts/history, avvisi dell'overlay e sessioni restano attivi.
Usa il capture coordinator per una richiesta limitata di RenderDoc o PIX quando lo strumento e gia collegato:
PerfMeterCaptureRequestResult result = PerformanceMeter.RequestCapture(
new PerfMeterCaptureOptions("gpu-spike", PerfMeterCaptureTool.RenderDoc, 1, 30, 30));
PerfMeterCaptureStatusSnapshot status = PerformanceMeter.GetCaptureStatus();GenericUnity conserva la matrice precedente di ExternalGPUProfiler e non puo autenticare tool/artifact. NativePreferred puo fare fallback solo prima del begin; NativeRequired mai. Native RenderDoc e supportato solo nell'Editor Unity Windows x64 con D3D11, D3D12 o Vulkan.
Generic Completed resta solo wrapper lifecycle. Lo status nativo espone backend kind e generation-bound phase e puo autenticare un .rdc finalizzato. Gli artefatti generic/caller restano observed. MCP accetta backend_mode, ma lo storage mode si seleziona nell'API C#.
Il numerical overdraw e opt-in e limitato nel tempo.
PerformanceMeter.RequestOverdrawMeasurement(frameCount: 60);
PerformanceMeter.SetOverdrawHeatmapVisible(true);Numerical overdraw e heatmap usano il diagnostic path URP Render Graph. La misurazione overdraw richiede PerfMeterRenderGraphFeature, supporto replacement shader, supporto fragment UAV/storage-buffer, supporto compute shader, una graphics API supportata e async GPU readback. HDRP riporta overdraw/heatmap come unsupported, mentre core overlay, session, API e MCP diagnostics restano disponibili. I target non supportati restituiscono OverdrawState.Unsupported invece di eseguire il pass.
Usa gli snapshot per conservare l'ambiente che ha prodotto una cattura prestazionale.
PerfMeterDeviceSnapshot device = PerformanceMeter.GetDeviceInfo();
PerfMeterCameraSnapshot camera = PerformanceMeter.GetCameraSnapshot();Le esportazioni sessione includono metadati di device e camera, cosi una cattura puo essere compresa o riprodotta in seguito.
Registra provider specifici del progetto senza fare fork di PerfMeter.
PerformanceMeter.RegisterCustomMetricProvider(provider);
PerfMeterCustomMetricSnapshot[] customMetrics = PerformanceMeter.GetCustomMetrics();Le custom metrics sono esposte tramite letture API, esportazione sessione JSON, MCP latest metrics e fino a otto righe overlay quando il modulo CustomMetrics e abilitato.
La strumentazione e interna ed e visibile solo profilando l'Editor, un Development Build o un altro build con Profiler abilitato. Nei Release player senza Profiler, questi marker/counter sono no-op e non producono dati di strumentazione; gli schemi di public API, status, MCP ed export restano invariati.
- I marker coprono collect/frame timing (
SGG.PerfMeter.Collect,SGG.PerfMeter.Collect.FrameTiming), provider (SGG.PerfMeter.Provider.CustomMetrics,SGG.PerfMeter.Provider.CpuCore,SGG.PerfMeter.Provider.DeviceSnapshot,SGG.PerfMeter.Provider.CameraSnapshot), bottleneck/capture (SGG.PerfMeter.Bottleneck.Classify,SGG.PerfMeter.Capture.Session,SGG.PerfMeter.Capture.AlertScope,SGG.PerfMeter.Capture.Coordinator) ed export JSON/CSV (SGG.PerfMeter.Export.Json,SGG.PerfMeter.Export.Csv).SGG.PerfMeter.Thermal.Samplee un hook interno riservato per i provider. - I counter coprono i tempi frame CPU/GPU (
SGG.PerfMeter.CPU.FrameTime,SGG.PerfMeter.CPU.MainThreadTime,SGG.PerfMeter.CPU.RenderThreadTime,SGG.PerfMeter.CPU.PresentWaitTime,SGG.PerfMeter.GPU.FrameTime) come gauge di fine frame in nanosecondi.SGG.PerfMeter.CPU.FrameTimingAvailable,SGG.PerfMeter.GPU.FrameTimingAvailable,SGG.PerfMeter.Capture.AlertScopeActiveeSGG.PerfMeter.Thermal.Availablecodificano availability/active come0/1;SGG.PerfMeter.Bottleneck.Kind,SGG.PerfMeter.Capture.SessionState,SGG.PerfMeter.Capture.OverdrawStateeSGG.PerfMeter.Capture.Stateusano enum codes;SGG.PerfMeter.Provider.CustomMetricCounte un count. Tutti i counter usano la categoriaScriptseFlushOnEndOfFrame. - Non viene emesso alcun sample termico sintetico;
SGG.PerfMeter.Thermal.Availableresta a0/non disponibile finche un provider di piattaforma reale non fornisce dati.
Usa PerformanceMeter.GetSelfOverhead() o PerformanceMeter.GetStatus().SelfOverhead per diagnosticare costo dei callback CPU e allocazioni di collector, custom providers, CPU-core provider, overlay e integrazione URP/HDRP. La misurazione usa finestre fisse di 120 frame, medie per invocazione e budget CPU/allocazione specifici per componente.
Usa PerformanceMeter.GetSelfOverheadWindow(kind, identity) per un receipt legato esattamente a una session/capture. Il risultato include epoch e containment dei frame, identita quality/pipeline/renderer, evidence feature installed/enabled/enqueued, limiti callback/invocation e un motivo di inattivita tipizzato. JSON capture/session e stato MCP conservano la stessa identita di window e falliscono in modo chiuso con CaptureWindowMismatch o UnknownInactiveReason invece di allegare dati live stale.
Il valore URP copre solo la registrazione CPU-side di RecordRenderGraph() posseduta dal package e l'allocazione del current thread. Piu camere possono produrre piu invocazioni dei callback frame. L'attribuzione GPU e esplicitamente Unavailable; CPU/GPU/hitch/GC whole-frame resta contesto separato. L'accounting e solo diagnostico: PerfMeter non sottrae overhead e non modifica le metriche CPU/GPU esistenti.
Una tipica esecuzione guidata da MCP:
perfmeter.profiler.capabilities {}
perfmeter.runtime.mode.set {"mode":"Background"}
perfmeter.session.start {"warmup_seconds":1,"sample_interval_seconds":0.25,"max_samples":240}
perfmeter.runtime.mode.set {"mode":"Overlay"}
perfmeter.overlay.set {"preset":"Timing","mode":"Graphs","visible":true}
perfmeter.session.summary {}
perfmeter.session.export {"format":"json","path":"Temp/PerfMeter/session.json"}
perfmeter.alerts.latest {}
perfmeter.profiler.capabilities {} e una lettura dalla cache; non avvia il runtime e non esegue la discovery.
- Usa Unity
6000.4+e installacom.unity.memoryprofiler1.1.0+tramite Package Manager. L'assembly opzionaleSGG.PerfMeter.MemoryProfilerregistra quindi automaticamente il backend; senza questo pacchetto l'integrazione core resta unavailable. - In Play Mode, leggi
PerformanceMeter.GetMemorySnapshotCapabilities()operfmeter.memory.snapshot.capabilitiese verifica la disponibilità del backend e dei flag richiesti. - Richiedi uno snapshot manuale con
RequestMemorySnapshot(new PerfMeterMemorySnapshotOptions("memory-spike-01")), oppure configuraConfigureMemorySnapshotTriggers(...)per abilitare esplicitamente una soglia della memoria di sistema o una finestra limitata di crescita delle perdite. - Leggi
GetMemorySnapshotStatus()operfmeter.memory.snapshot.statusfinché lo snapshot e il bundle correlato raggiungono uno stato terminale. Esporta l'evidence pronta conPerformanceMeter.ExportCaptureBundle(captureId)operfmeter.capture.export.
L'evidence solo memoria passa attraverso l'API esistente dei capture bundle sotto Temp/PerfMeter/CaptureBundles. Il bundle registra MemoryProfiler come strumento richiesto, include la provenienza della memoria e uno SHA-256 in streaming per il .snap, senza includere un artefatto GPU esterno. La sorgente posseduta si trova sotto Temp/PerfMeter/MemorySnapshots; un export riuscito la consuma una sola volta.
- Chiama
PerformanceMeter.GetGraphicsDiagnostics()operfmeter.graphics.diagnosticsper leggere gli ultimi valori dei marker e il contesto della graphics API. - Controlla per ogni capability
SampleState,Resolution,ResolvedRecorderNames,Unit,DataType, i component counts risolti/campionati e la revisione del catalogo. La discovery e dinamica: avviene all'avvio del runtime e durante un refresh/reconfigure esplicito del catalogo del profiler. - Tratta i valori come raw recorder values nelle loro units scoperte. Un marker puo essere unavailable, disponibile senza sample o sampled; lo zero numerico non e un segnale universale di unavailable e il valore non e garantito come count di shader o PSO.
Lo shader marker risolve prima esattamente Shader.CreateGPUProgram, quindi gli alias Shader.CreateGPUPrograms, Shader.CompileGPUProgram e Shader.DynamicLoadGPUProgram. Il pipeline marker risolve esattamente CreatePSO.Job. Gli stessi valori e la provenance sono disponibili tramite perfmeter.metrics.latest e session JSON/CSV.
Durante il profiling, ogni sessione emette i sample istantanei SGG.PerfMeter.Session.<sessionId>.Begin e .End. SGG/Perfmeter/Open Profile Analyzer For Session apre la finestra opzionale di Profile Analyzer e copia negli appunti l'ID della sessione corrente. Il comando non installa Profile Analyzer, non carica i dati del Profiler e non applica automaticamente un filtro; dopo aver caricato la cattura pertinente, cercare l'ID copiato.
Apri SGG/Perfmeter/Session Analysis per una vista Editor di sola lettura della sessione corrente in memoria. Le tab virtualizzate mostrano la timeline dei sample conservati, il worst frame autorevole con i dettagli del sample disponibili, le violazioni derivate dei budget CPU-main/CPU-render/GPU e gli scope autorevoli whole-run/current-scene. CPU-main esclude present wait; valori e violazioni GPU richiedono disponibilita esplicita del timing GPU.
La finestra legge solo GetSessionSummary() e GetSessionSamples() e non avvia mai il runtime. Il timing non disponibile viene mostrato come Unavailable, non come zero numerico. Una sessione arrestata resta visibile finche esiste la sua istanza runtime; PerformanceMeter.Stop(), un domain reload o l'uscita dal Play Mode possono eliminare la sessione in memoria.
- Su Unity
6000.4+, verifica che sia disponibile l'assembly opzionaleSGG.PerfMeter.GraphicsStateCollection. Usa il namespaceUnityEngine.Experimental.Rendering.GraphicsStateCollectionsu Unity6000.4eUnityEngine.Rendering.GraphicsStateCollectionsu Unity6000.5+. - Avvia una sessione PerfMeter prima del trace. Esegui
StartSession(...), poiRequestGraphicsStateTrace(new PerfMeterGraphicsStateTraceOptions("shader-stutter-01", 60))o la richiesta MCP corrispondente. Senza una sessione attiva la richiesta viene rifiutata; la sessione deve restare in registrazione fino alla fine del trace ePerformanceMeter.StopSession()annulla un trace attivo. - Lascia in esecuzione lo scenario mentre procede il trace limitato. In Play Mode normale ogni trace frame viene tickato dopo
WaitForEndOfFrame; in batch mode il coordinator usa un fallback al frame successivo. I sample di sessione ammessi in questo intervallo riportanoGraphicsStateTraceId/graphics_state_trace_id; le impostazioni della sessione determinano quanti sample correlati vengono conservati. - Interroga
GetGraphicsStateCollectionStatus()operfmeter.graphics.state_collection.statusfino aCompleted, poi arresta la sessione se necessario. Arrestarla durante il trace attivo lo annulla e puo lasciareIsBusy/is_busytrue mentre viene ritentato il cleanup owned. L'artefatto.graphicsstateowned e relativo al progetto, si trova sottoTemp/PerfMeter/GraphicsStateCollectionsed e limitato a 64 MiB. - Passa il path relativo owned indicato a
PrewarmGraphicsStateCollection(new PerfMeterGraphicsStatePrewarmOptions(path, maxStateCount))o al comando MCP di prewarm. Il prewarm e sincrono, conserva l'artefatto e riporta i warmup completati eIsWarmedUp; un progressive warmup puo terminare con un warning esplicito di incompletezza.
Il coordinator graphics-state ammette un solo flight e rifiuta anche l'overlap con external GPU capture, memory snapshot o alert-capture attivi. Lo stesso trace ID attivo restituisce AlreadyActive; un altro ID restituisce RejectedOverlap. CancelGraphicsStateTrace annulla solo un trace attivo/in preparazione corrispondente e pulisce l'artefatto in attesa. Se un artefatto owned non puo essere cancellato, HasPendingCleanup/has_pending_cleanup resta true, un sidecar adiacente .delete-pending viene mantenuto e ripristinato/ritentato dopo un domain reload; IsBusy/is_busy e il warning restano visibili fino al successo. Il backend Unity non supporta il cache-miss tracing, quindi non e disponibile alcuna evidence di cache-miss.
Usa lo snapshot neutrale quando serve una vista indipendente dalla pipeline dell'ultima render integration tipizzata:
PerfMeterRenderIntegrationSnapshot context = PerformanceMeter.GetRenderIntegrationSnapshot();Gli stessi dati sono leggibili tramite MCP:
perfmeter.render.snapshot {}
Queste letture non avviano la raccolta del runtime. Controlla insieme State, ObservationAgeFrames, LastObservedFrame e ObservationMatchesCurrentPipeline. Dopo un cambio di pipeline o di asset configuration, l'observation precedente è stale; conserva warning e non-match e non interpretare i suoi valori di pass, mode, GRD o VRS come correnti. La API legacy PerformanceMeter.GetRenderGraphSnapshot() e il comando perfmeter.rendergraph.snapshot restano disponibili.
Per diagnosticare GRD, controlla DegradedReason, supporto SRP, configurazione del progetto, supporto compute, compatibilità del modo URP e ActivityAvailability. IsObservedActive è lo stato enabled globale di Unity. Usa Effectiveness solo come contesto BRG aggregato: AvailableNoSample/Unavailable non significano workload zero e counter BRG positivi non provano l'uso GRD di un renderer specifico.
Nel capture bundle, lo schema sgg.perfmeter.capture-context versione 1 conserva render e aggiunge render_integration. Per un external GPU capture, il context viene congelato al primo sample della fase Capturing; un bundle Memory Profiler lo registra quando la richiesta di memoria termina. Gli schema JSON/CSV di sessione non cambiano. La API pubblica non offre un viewer stabile RenderGraph/CustomPass né pass target, quindi questo workflow non promette navigazione nell'Editor.