Analytics Documentation

Comprehensive analytics and performance metrics for the Screeps AI bot.

Overview

The analytics system provides detailed insights into bot performance, resource utilization, and strategic effectiveness. The analytics data is visualized through interactive charts on the documentation site, updated automatically during each deployment.

Available Analytics

Performance Metrics

  • Bot Analytics Dashboard - 30-day performance charts and metrics visualization including:
    • CPU usage trends and bucket levels
    • Room progression and RCL growth
    • Controller upgrade progress
    • Creep population statistics
    • Infrastructure development (extensions, towers, containers)
    • Memory utilization

Schema Reference

  • PTR Stats Schema Reference - Complete schema documentation for PTR stats files, enabling strategic planning agents and automation systems to consume telemetry data for performance validation and analysis. Includes:
    • PTR stats JSON schema
    • Historical trends schema
    • Profiler data schema
    • Regression detection thresholds
    • Strategic planning agent integration examples

Data Collection

The analytics system collects daily snapshots of game state from the Public Test Realm (PTR) deployment. These snapshots are stored in reports/bot-snapshots/ and capture:

  • Room control levels (RCL) for each controlled room
  • Controller progress toward next level
  • CPU usage patterns (used, limit, bucket)
  • Creep counts by role
  • Structure counts (extensions, towers, containers, roads)
  • Memory usage in bytes and percentage
  • Energy available and capacity

Chart Types

The analytics dashboard displays several chart types:

Chart Type Description
CPU Usage Line Tracks CPU consumption over time
CPU Bucket Line Shows bucket level trends
Creep Count Bar Daily creep population
Room Statistics Dual-axis Line Room count and average RCL
Controller Progress Area Progress toward next RCL
Infrastructure Stacked Bar Structure counts by type
Memory Usage Dual-axis Line Memory in bytes and percentage

Data Pipeline

Analytics data is generated by the generate-analytics.ts script:

  1. Reads snapshot files from reports/bot-snapshots/
  2. Extracts and aggregates metrics from each snapshot
  3. Filters valid room data (excludes metadata entries)
  4. Outputs chart-ready JSON to packages/docs/source/docs/analytics/data.json

This script runs automatically during the documentation build process.