query · developer.performance

Current performance

Returns a continuously updated rolling frame, CPU, and process-memory snapshot.

developer.performance.current(filters?, cursor?, page_size?) -> query-page

Stable ID: developer.performance.current
Owner: app.runtime-performance-monitor
Authority: read_only
Timing: immediate
Availability: active-session
Side effects: none
Determinism: stable owner order at the current committed tick
Introduced: 1.0.0

Usage

Call through world.query to read the latest rolling FPS, frame time, process CPU, process resident-memory, and logging-state snapshot. Treat values as nondeterministic presentation diagnostics, not simulation facts.

Parameters

cursor: must remain zero for the single current record.
page_size: positive record limit capped by the host; one record is returned.
filters: no filters are accepted.

Returns

One detached current record after at least one frame has been presented, or error.capability-unavailable before then.

Cost

Aggregates at most 120 retained frame samples and consumes one query, one result record, and one owner visit per included sample.

Fields

ID	Type	Units	Required	Description
`average_cpu_ms`	`number`	milliseconds	yes	Rolling process CPU time per frame.
`average_frame_ms`	`number`	milliseconds	yes	Rolling average frame duration.
`cpu_percent`	`number`	percent-of-one-core	yes	Rolling process CPU time relative to wall time.
`frames_per_second`	`number`	frames-per-second	yes	Rolling average frame rate.
`latest_frame`	`unsigned-integer`	none	yes	Latest recorded frame index.
`latest_frame_ms`	`number`	milliseconds	yes	Latest frame duration.
`logging_active`	`boolean`	none	yes	Whether a bounded logging session is active.
`logging_session_id`	`unsigned-integer`	none	yes	Current or most recent logging session identity.
`memory_available`	`boolean`	none	yes	Whether current resident memory is available.
`resident_memory_bytes`	`unsigned-integer`	bytes	yes	Current process resident memory when available.
`sample_count`	`unsigned-integer`	none	yes	Samples in the rolling window.

Errors

Examples

local result = world.query("developer.performance.current", {page_size = 1})
if result.status == "completed" then
    local current = result.records[1]
    ui.row("FPS", string.format("%.1f", current.frames_per_second))
    ui.row("Memory", tostring(current.resident_memory_bytes))
end

API history

1.0.0: Current frame, CPU, and process-memory telemetry added during Phase 15 closure.