Runtime Documentation

Comprehensive documentation for the Screeps AI bot runtime behavior, strategy, and implementation.

Overview

The runtime system is the core of the Screeps AI bot, executing every game tick to manage creeps, rooms, resources, and strategic decisions. This documentation covers the architecture, behavior patterns, and operational characteristics of the bot.

Documentation Sections

Architecture

Strategy & Decision Making

  • Creep Roles - Role definitions, decision trees, and performance characteristics
  • Task Prioritization - Task switching, efficiency optimization, and load balancing
  • Scaling Strategies - RCL progression, multi-room expansion, and CPU budgeting

Operations & Monitoring

Development & Testing

Key Concepts

Architecture

The runtime is organized into several key subsystems:

  • Bootstrap/Kernel - System initialization and module orchestration using decorator-based process registration
  • Behavior System - State machine-based creep role execution using RoleControllerManager and dedicated role controllers
  • Memory System - State persistence and consistency, including state machine serialization
  • Metrics System - Performance tracking and CPU accounting
  • Evaluation System - Health reports and improvement recommendations
  • Pathfinding System - Traffic management and priority-based movement using screeps-pathfinding library

State Machine Architecture: Each creep role is implemented as a dedicated state machine with explicit states (idle, harvesting, delivering, etc.) and valid transitions. See Behavior State Machines for details.

Traffic Management: The pathfinding system enables priority-based movement where higher priority creeps (harvesters, haulers) move first and can push lower priority creeps (upgraders) out of the way. See Pathfinding for details.

Execution Model

Each game tick follows this execution flow:

  1. Initialization Check - Verify phased initialization complete (post-restart/deploy)
  2. Bootstrap - Initialize kernel and load modules
  3. Memory Cleanup - Remove stale references and maintain consistency
  4. Role Execution - Execute behaviors for all creeps based on their roles
  5. Spawn Management - Queue and spawn new creeps as needed
  6. Metrics Collection - Track CPU usage and performance
  7. Evaluation - Generate health reports and recommendations

Performance Considerations

  • CPU Budgeting - Each room and role has CPU budget allocations
  • Caching - Expensive operations are cached within the tick
  • Early Termination - Non-critical tasks yield when CPU is constrained
  • Incremental Processing - Large operations are spread across multiple ticks