# Mod Performance Profiling

This document covers `TODOS.phase-72.72.14.1.11`: per-mod CPU and memory usage
tracking, plus deterministic identification of poorly performing mods.

## Runtime Surface

- module: `V2Modding`
- budget: `FV2ModPerformanceBudget`
- sample: `FV2ModPerformanceSample`
- issue: `FV2ModPerformanceIssue`
- profile: `FV2ModPerformanceProfile`
- report: `FV2ModPerformanceReport`
- helper functions: `BuildDefaultModPerformanceBudget`,
  `BuildModPerformanceSample`, `EvaluateModPerformanceProfiles`, and
  `GetPoorPerformingModIds`
- subsystem forwarding: `UV2ModLoadingSubsystem::EvaluatePerformanceProfiles`
- automation: `V2/ue/Source/V2Tests/Private/Modding/ModLoadingSystem.spec.cpp`
- contract: `V2/ue/Content/V2/Modding/ModPerformanceProfiling_V2_Contract.json`

## Samples And Budgets

`FV2ModPerformanceSample` records the mod id, frame number, CPU time in
milliseconds, memory in MiB, script invocation count, asset streaming bytes, and
timestamp. The default budget requires at least three samples and caps average
CPU, peak CPU, average memory, peak memory, average script invocations, and peak
asset streaming bytes.

## Reports

`EvaluateModPerformanceProfiles` groups samples by mod id, computes average and
peak CPU/memory metrics, tracks script invocation pressure, records peak asset
streaming bytes, and emits per-mod issues for exceeded budgets.

`FV2ModPerformanceReport` exposes profile rows, all issues, `bWithinBudget`, and
`PoorPerformerModIds`. `GetPoorPerformingModIds` returns the flagged ids for
callers that need a compact list to disable, warn, or route mods through review.
Insufficient sample windows create issues without flagging a mod as a poor
performer.

## Verification

```bash
python3 V2/ue/Tools/check-v2-mod-performance-profiling.py
python3 V2/ue/Tools/check-v2-mod-loading-system.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 V2/tools/validate-v2-docs.py
python3 -m py_compile V2/ue/Tools/check-v2-mod-performance-profiling.py V2/ue/Tools/check-v2-mod-compatibility.py V2/ue/Tools/check-v2-ci-workflow.py
python3 -m json.tool V2/ue/Content/V2/Modding/ModPerformanceProfiling_V2_Contract.json
```