# AppStats

Class · category: Framework

Source: https://github.com/playcanvas/engine/blob/f059dc005842f76e052cdf44d8370c8c7ec475ac/src/framework/app-stats.js#L47

Performance statistics for an application, accessed through [AppBase#stats](https://api.playcanvas.com/engine/classes/AppBase.md#stats). Engine
measurements are read-only; [user](https://api.playcanvas.com/engine/classes/AppStats.md#user) holds writable application-defined counters.
Includes frame cadence, CPU phase timings, overall GPU frame timing, and estimated GPU resource
memory usage. CPU timings, GPU timings and memory statistics are available in all builds, subject
to graphics capabilities. Primitive counting requires a debug or profiler build; see each getter
for its availability.

Durations are in milliseconds and memory sizes are in bytes. Values are the latest available
measurements, not averages, except for [fps](https://api.playcanvas.com/engine/classes/AppStats.md#fps), which refreshes approximately once per second.
Frame counters are published at the start of the next application tick; CPU timings are updated
when their respective phases finish. CPU phases overlap and must not all be added together.
CPU timings and counters are initially zero. GPU results arrive asynchronously and can describe
an older frame than the CPU measurements.

GPU profiling is disabled by default. Enable it with
`app.graphicsDevice.gpuProfiler.enabled = true` when a profiler exists (see the example below).
WebGL requires the disjoint timer query extension; WebGPU requires the timestamp-query feature.
Enabling profiling on an unsupported device produces no timings. [gpuFrameTime](https://api.playcanvas.com/engine/classes/AppStats.md#gpuframetime) returns
undefined when profiling is disabled, unsupported, or no valid result has arrived. Reading stats
does not enable profiling. MiniStats also enables GPU profiling when it creates its GPU timer.

Memory statistics estimate resources tracked by the application's graphics device, which may be
shared by applications. They do not represent total physical GPU memory usage or capacity, and
exclude untracked driver overhead and JavaScript memory.

**Example**

```ts
const profiler = app.graphicsDevice.gpuProfiler;
if (profiler) {
    profiler.enabled = true;
}

app.on('frameend', () => {
    const stats = app.stats;
    console.log(stats.cpuUpdateTime, stats.cpuRenderTime, stats.gpuFrameTime);
});
```

**See** AppBase#stats

## Accessors

### cpuAnimationTime

```ts
get cpuAnimationTime(): number
```

CPU duration of the latest dedicated animation-update phase in milliseconds, used by
[AnimComponentSystem](https://api.playcanvas.com/engine/classes/AnimComponentSystem.md). Excludes the legacy [AnimationComponentSystem](https://api.playcanvas.com/engine/classes/AnimationComponentSystem.md), which
runs in the system update phase. Part of [cpuUpdateTime](https://api.playcanvas.com/engine/classes/AppStats.md#cpuupdatetime). Available in all builds.

### cpuPhysicsTime

```ts
get cpuPhysicsTime(): number
```

CPU duration of the most recent physics step in milliseconds, including synchronization and
contact handling. Normally part of [cpuSystemUpdateTime](https://api.playcanvas.com/engine/classes/AppStats.md#cpusystemupdatetime). Multiple manual steps are not
accumulated. Zero before any step or when physics is paused through its timeScale property.
Available in all builds.

### cpuRenderTime

```ts
get cpuRenderTime(): number
```

CPU duration of the latest scene render in milliseconds, including prerender and postrender
event listeners, hierarchy synchronization, batching and render command submission. Excludes
graphics device frameStart/frameEnd work and does not measure GPU execution. Retains the
latest measurement when rendering is skipped. Available in all builds.

### cpuSystemPostUpdateTime

```ts
get cpuSystemPostUpdateTime(): number
```

CPU duration of the latest component systems post-update phase in milliseconds, including
script postUpdate callbacks. Part of [cpuUpdateTime](https://api.playcanvas.com/engine/classes/AppStats.md#cpuupdatetime). Available in all builds.

### cpuSystemUpdateTime

```ts
get cpuSystemUpdateTime(): number
```

CPU duration of the latest component systems update phase in milliseconds. Includes script
updates, physics and other systems subscribed to the update event. Part of
[cpuUpdateTime](https://api.playcanvas.com/engine/classes/AppStats.md#cpuupdatetime). Available in all builds.

### cpuUpdateTime

```ts
get cpuUpdateTime(): number
```

CPU duration of the latest application update in milliseconds, including component systems,
application update event listeners and input updates. Excludes graphics device updates.
Includes the other CPU update phase timings. Available in all builds.

### drawCallCount

```ts
get drawCallCount(): number
```

Total draw calls submitted during the previous frame, published at the start of the next
application tick. Available in all builds.

### fps

```ts
get fps(): number
```

Frame count over the latest approximately one-second reporting interval. Initially zero
until an interval completes. Available in all builds.

### frameTime

```ts
get frameTime(): number
```

Interval between application ticks in milliseconds, including time outside the engine.
Unaffected by time scaling or delta-time clamping. Available in all builds.

### gpuFrameTime

```ts
get gpuFrameTime(): number | undefined
```

Overall duration of the most recently resolved GPU frame in milliseconds. Available in all
builds when GPU profiling is supported and enabled. Returns undefined until a valid timing
arrives, when profiling is disabled, or after timing invalidation such as context loss.
Results arrive asynchronously and may be several frames old.

WebGL measures a whole-frame timer query. WebGPU measures the span from the first profiled
pass beginning to the last pass ending, including gaps between passes. This is elapsed GPU
time, not GPU utilization, and is not the sum of potentially overlapping pass durations.

### primitiveCount

```ts
get primitiveCount(): number | undefined
```

Total primitives submitted during the previous frame, published at the start of the next
application tick. Counts triangles, lines and points across all passes, including instances
and CPU-authored multi-draw commands. Counts are calculated before GPU clipping and culling.

Available only in debug and profiler builds. Returns undefined in release and minified builds.
This is an estimate from draw parameters: GPU-generated indirect draws are excluded, and
primitive-restart indices in indexed strips are not inspected. No GPU readback is performed.

### user

```ts
get user(): Map<string, number>
```

Application-defined numeric counters. Returns the same map on every access. Entries can be
added, updated, deleted or cleared by the application; the engine never resets them.
Available in all builds. Values and their units are defined by the application.

To display a counter in [MiniStats](https://api.playcanvas.com/engine/classes/MiniStats.md), configure a graph with a path such as `user.ai`.
Counter names used in MiniStats must not contain dots, which separate path segments.
Initialize counters before accumulating values and reset per-frame totals on `frameupdate`.

**Example**

```ts
app.stats.user.set('ai', 0);
app.on('frameupdate', () => app.stats.user.set('ai', 0));

// Accumulate time spent in application code during this frame.
const start = performance.now();
// ... run AI logic ...
app.stats.user.set('ai', app.stats.user.get('ai') + performance.now() - start);
```

### vramIndexBufferBytes

```ts
get vramIndexBufferBytes(): number
```

Estimated GPU index buffer memory in bytes. Available in all builds.

### vramStorageBufferBytes

```ts
get vramStorageBufferBytes(): number
```

Estimated GPU storage buffer memory in bytes. Available in all builds. Zero on backends
without storage buffers or when none have been allocated.

### vramTextureBytes

```ts
get vramTextureBytes(): number
```

Estimated GPU texture memory in bytes. Available in all builds.

### vramTotalBytes

```ts
get vramTotalBytes(): number
```

Total estimated GPU resource memory in bytes: textures, vertex buffers, index buffers,
uniform buffers and storage buffers. Available in all builds.

### vramUniformBufferBytes

```ts
get vramUniformBufferBytes(): number
```

Estimated GPU uniform buffer memory in bytes. Available in all builds. Zero when no tracked
uniform buffers have been allocated.

### vramVertexBufferBytes

```ts
get vramVertexBufferBytes(): number
```

Estimated GPU vertex buffer memory in bytes. Available in all builds.