FrameProfiler

Kind	class
Package	debug
Full name	debug.FrameProfiler
Source	source/debug/FrameProfiler.hx

Full-engine Haxe + C/C++ Frame Profiler for FNF-Phoenix-Engine.

Manages five independent lifecycle states:

1. Initialization (FrameProfiler.initialized): Set by FrameProfiler.init(). Repeated calls to init(targetFps) without forceReset = true update targetFps idempotently without clearing collected history or registering duplicate shutdown hooks.
2. Metric Recording (FrameProfiler.enabled, startRecording(), stopRecording()): Enabled by default on init() so background ring-buffer history is ready when the user opens the overlay (F3) or exports a report (F6). Calling stopRecording() (enabled = false) stops all sampling and resets inter-frame baselines; startRecording() (enabled = true) resumes recording while preserving previously recorded session totals.
3. Overlay Visibility (FrameProfiler.overlayVisible / ClientPrefs.frameProfiler): Hidden by default (false). Toggling the HUD overlay (F3, showOverlay(), hideOverlay(), toggleOverlay()) never stops recording, never resets recorded samples, and never re-initializes the profiler.
4. Automatic Exit Export (FrameProfiler.autoExportOnExit): Disabled by default (false), enabled via --profile / -profile / --frame-profiler CLI flags, -DPROFILE_FRAMES, or setting FrameProfiler.autoExportOnExit = true. Completely independent of overlayVisible.
5. Export In Progress (FrameProfiler.exportInProgress): True while a .log report is actively being written and finalized, preventing re-entrant export calls.

Public fields

Name	Type	Static	Default	Notes
LOG_DIR	String	yes	"debug/log"	—
initialized	Bool	yes	false	property (default, null) · Whether FrameProfiler.init() has been called.
enabled	Bool	yes	—	property (get, set) · Whether metric recording is currently active.
overlayVisible	Bool	yes	—	property (get, set) · Whether the live HUD profiler overlay is visible (ClientPrefs.frameProfiler).
exportInProgress	Bool	yes	—	property (get, never) · Whether a .log export is currently in progress.
rssSampleIntervalFrames	Int	yes	—	property (get, set) · Process RSS sampling interval in frames (0 = on-demand only, 1 = every frame, default 60 = once per ~1 second at 60 FPS).
collectMemoryMetrics	Bool	yes	—	property (get, set) · Whether managed heap and process RSS metrics are collected (true = full profiling, false = timing-only mode).
autoExportOnExit	Bool	yes	false	Whether a .log report should be exported automatically on application exit. Independent of overlayVisible (ClientPrefs.frameProfiler).
lastExportedLogPath	String	yes	""	property (default, null) · Path of the most recent .log file successfully written to debug/log/.

Public methods

init

static function init(targetFps:Float = 60.0, forceReset:Bool = false):Void

Initializes the frame profiler. If already initialized and forceReset is false, updates targetFps idempotently without wiping recorded frames or registering duplicate hooks.

Parameter	Type	Default
targetFps (optional)	Float	60.0
forceReset (optional)	Bool	false

View source

registerExitHook

static function registerExitHook():Void

Registers the application exit callback at most once across the process lifetime.

View source

ensureInitialized

static inline function ensureInitialized():Void

View source

reset

static function reset():Void

Clears all recorded frame samples and resets cumulative session statistics.

View source

startRecording

static function startRecording():Void

Explicitly enables frame/phase metric recording.

View source

stopRecording

static function stopRecording():Void

Explicitly disables frame/phase metric recording without clearing history.

View source

showOverlay

static function showOverlay():Void

Shows the live profiler HUD overlay without resetting or altering recording state.

View source

hideOverlay

static function hideOverlay():Void

Hides the live profiler HUD overlay without stopping recording or resetting history.

View source

toggleOverlay

static function toggleOverlay():Bool

Toggles the on-screen profiler overlay (F3) without resetting or corrupting recorded frame samples or re-initializing the profiler.

View source

setTargetFps

static function setTargetFps(targetFps:Float):Void

Parameter	Type	Default
targetFps	Float	—

View source

setStateName

static function setStateName(stateName:String):Void

Parameter	Type	Default
stateName	String	—

View source

queryHeapUsedBytes

static inline function queryHeapUsedBytes():Float

Queries current managed heap usage in bytes from the runtime GC, or -1.0 when memory collection is disabled or unavailable on the target runtime.

View source

queryHeapReservedBytes

static inline function queryHeapReservedBytes():Float

Queries reserved managed heap memory in bytes from the runtime GC, or -1.0 when memory collection is disabled or unavailable on the target runtime.

View source

beginFrame

static inline function beginFrame():Void

Marks the start of a new frame.

View source

endFrame

static inline function endFrame(drawCalls:Int = 0, frameTimeMs:Float = 0.0):Void

Marks the completion of the current frame.

Parameter	Type	Default
drawCalls (optional)	Int	0
frameTimeMs (optional)	Float	0.0

View source

beginUpdate

static inline function beginUpdate():Void

Marks the start of the gameplay/state update phase.

View source

endUpdate

static inline function endUpdate():Float

Marks the end of the gameplay/state update phase.

View source

beginRender

static inline function beginRender():Void

Marks the start of the rendering phase.

View source

endRender

static inline function endRender():Float

Marks the end of the rendering phase.

View source

beginAudio

static inline function beginAudio():Void

Marks the start of the audio processing/synchronization phase.

View source

endAudio

static inline function endAudio():Float

Marks the end of the audio processing/synchronization phase.

View source

beginGC

static inline function beginGC(major:Bool = true):Void

Marks the start of an explicit synchronous garbage collection cycle. No-op on targets that do not expose synchronous GC (!cpp && !hl && !neko).

Parameter	Type	Default
major (optional)	Bool	true

View source

endGC

static inline function endGC():Float

Marks the end of an explicit synchronous garbage collection cycle.

View source

recordPhaseMs

static inline function recordPhaseMs(phase:Int, durationMs:Float):Void

Manually records a subsystem phase duration in milliseconds.

Parameter	Type	Default
phase	Int	—
durationMs	Float	—

View source

recordAllocation

static inline function recordAllocation(bytes:Float, count:Int = 1):Void

Manually records an allocation event (bytes and count).

Parameter	Type	Default
bytes	Float	—
count (optional)	Int	1

View source

recordGCPause

static inline function recordGCPause(pauseMs:Float, reclaimedBytes:Float = 0.0, isExplicit:Bool = true):Void

Manually records a garbage collection pause (pauseMs, reclaimedBytes, isExplicit).

Parameter	Type	Default
pauseMs	Float	—
reclaimedBytes (optional)	Float	0.0
isExplicit (optional)	Bool	true

View source

getLastFrame

static function getLastFrame():Null<FrameSample>

Returns a snapshot of the most recently completed frame, or null if no frames have been recorded yet.

View source

getBufferedFrame

static function getBufferedFrame(chronologicalIndex:Int):Null<FrameSample>

Returns a snapshot of the buffered frame at chronologicalIndex (0 = oldest frame in ring buffer, getBufferedFrameCount() - 1 = newest).

Parameter	Type	Default
chronologicalIndex	Int	—

View source

getBufferedFrameCount

static function getBufferedFrameCount():Int

View source

getSummary

static function getSummary():FrameProfileSummary

Computes and returns the full statistical summary across the current session.

View source

getOverlayText

static function getOverlayText():String

Formats a compact HUD string suitable for FPSCounter without allocating full FrameSample / FrameProfileSummary structures.

View source

escapeCsvField

static function escapeCsvField(value:String):String

Escapes a string field according to RFC 4180 CSV rules (normalizing raw control chars to spaces and quoting fields containing ,, ", \r, \n, or leading/trailing spaces).

Parameter	Type	Default
value	String	—

View source

formatReport

static function formatReport(?engineVersion:String, ?platformName:String):String

Formats a complete .log report in Haxe matching the 6-section native C/C++ report layout ([1] through [6]), including top slowest frames and RFC 4180 CSV escaping.

Parameter	Type	Default
engineVersion (optional)	String	—
platformName (optional)	String	—

View source

exportLog

static function exportLog(?fileName:String):String

Exports the current frame profiler session to a .log file inside debug/log/. Returns the resolved path on success, or "" on failure. Never updates lastExportedLogPath when an export fails.

Parameter	Type	Default
fileName (optional)	String	—

View source

handleApplicationExit

static function handleApplicationExit():String

Handles automatic log export during application shutdown. Safe when initialization was incomplete or recording was never started, and idempotent across repeated shutdown callbacks.

View source

Internals

Private / internal members

Field	Type	Static
_recordingEnabled	Bool	yes
_collectMemory	Bool	yes
_exitHookRegistered	Bool	yes
_exitExportCompleted	Bool	yes
_currentStateName	String	yes
_lastStateInstance	Dynamic	yes

Method
static function get_enabled():Bool
static function set_enabled(value:Bool):Bool
static function get_overlayVisible():Bool
static function set_overlayVisible(value:Bool):Bool
static function get_exportInProgress():Bool
static function awardFirstUseAchievement():Void
static function get_rssSampleIntervalFrames():Int
static function set_rssSampleIntervalFrames(intervalFrames:Int):Int
static function get_collectMemoryMetrics():Bool
static function set_collectMemoryMetrics(value:Bool):Bool
static function readLoadedSample():FrameSample
static inline function roundDec(val:Float, decimals:Int = 2):Float
static function sanitizeSingleLine(value:String, fallback:String = "Unknown"):String
static function dominantSubsystem(sample:FrameSample):String
static function getEngineVersion():String
static function getPlatformLabel():String