# Profiling Reports

This directory contains performance profiling reports generated by the FlexLöve profiling system.

## Directory Structure

Reports are organized by profile name:
```
reports/
├── animation_stress/
│   ├── latest.md          # Most recent report (Markdown)
│   ├── latest.json        # Most recent report (JSON)
│   ├── 2025-11-20_10-30-00.md
│   └── 2025-11-20_10-30-00.json
├── event_stress/
│   ├── latest.md
│   └── latest.json
└── ...
```

## Report Format

Each test run generates two files:
- `<timestamp>.md` - Human-readable Markdown report with formatted tables
- `<timestamp>.json` - Machine-readable JSON data for programmatic analysis
- `latest.md` - Always contains the most recent report for quick access
- `latest.json` - Most recent JSON data

## Report Contents

### FPS Statistics
- **Average FPS**: Mean frames per second across the entire test
- **Median FPS**: Middle value of all FPS measurements
- **1% Worst FPS**: The FPS at which 1% of frames performed at or below this level (useful for identifying stutters)
- **0.1% Worst FPS**: The FPS at which 0.1% of frames performed at or below this level (worst case performance)

### Frame Time Statistics
- **Average**: Mean frame time in milliseconds
- **Median**: Middle value of all frame time measurements
- **95th/99th/99.9th Percentile**: Frame times that 95%/99%/99.9% of frames completed under

### Memory Usage
- **Average**: Mean memory usage across the test
- **Peak**: Maximum memory used during the test
- **95th/99th/99.9th Percentile**: Memory usage levels that 95%/99%/99.9% of samples were under

## How to Generate Reports

### Automatic (on exit)
Reports are automatically saved when you:
- Press ESC to return to the menu
- Quit the profiling application

### Manual
While a profile is running, press **S** to manually save a report without stopping the test.

## Interpreting Results

### Good Performance Indicators
- Average FPS close to target (60 FPS for most applications)
- Small difference between average and 1% worst FPS
- Low 99.9th percentile frame times (< 20ms for 60 FPS)
- Stable memory usage without continuous growth

### Performance Issues to Watch For
- Large gap between average and 1%/0.1% worst FPS (indicates frame drops/stutters)
- High 99.9th percentile frame times (indicates occasional severe lag spikes)
- Continuously growing memory usage (indicates memory leak)
- High memory peak compared to average (indicates GC pressure)