Release 0.142.0: Intelligent Communication Filtering and State Machine Reliability

(Updated: )
Release Notes
, , , ,

We’re excited to announce Screeps GPT release 0.142.0, delivering intelligent creep communication filtering and critical state machine reliability improvements. This release focuses on reducing visual noise while maintaining operational visibility, alongside bug fixes that restore harvester energy delivery functionality.

Key Features

Severity-Based Creep Communication Filtering (#1306)

The new communication filtering system provides granular control over creep messages, reducing visual clutter as bot complexity scales while preserving critical error visibility. This feature introduces five severity levels that automatically classify and filter creep actions based on operational importance.

Communication Levels:

  • SILENT (0) - No messages displayed
  • ERROR (1) - Critical failures only (stuck creeps, pathfinding failures)
  • WARNING (2) - Errors + warnings (low TTL, resource depletion)
  • INFO (3) - Errors + warnings + important status updates
  • VERBOSE (4) - All messages (default behavior)

Design Rationale:

As the bot scales from 5 to 50+ creeps, constant action messages (⛏️ mining, 🔨 building, ⚡ upgrading) create visual noise that obscures actual problems. The filtering system solves this by automatically classifying actions by severity using the ACTION_SEVERITY mapping in CreepCommunicationManager. Routine operations (harvesting, delivering) map to VERBOSE level, while critical conditions (stuck, error) map to ERROR level.

Why This Approach:

Rather than requiring manual severity specification for every message, the system uses intelligent defaults based on action types. This maintains backward compatibility (existing code works unchanged) while enabling opt-in filtering for users who want cleaner visuals. The severity-aware API (error(), warn(), info(), verbose()) provides explicit control when default classification doesn’t match specific use cases.

Backward Compatibility:

Existing code continues to work without modification. The verbosity: "normal" mode maps to VERBOSE level (shows all messages), while verbosity: "minimal" maps to ERROR level. To enable the new filtered behavior, users explicitly configure level: CommunicationLevel.WARNING in the communication manager initialization.

Implementation Details:

The enhancement extends packages/bot/src/runtime/behavior/CreepCommunicationManager.ts with 147 new lines of code adding the CommunicationLevel enum, action severity mapping, and filtering logic. The system evaluates severity <= this.config.level before calling creep.say(), reducing unnecessary API invocations when messages are suppressed.

Files Changed:

  • packages/bot/src/runtime/behavior/CreepCommunicationManager.ts - Core filtering implementation
  • docs/runtime/communication.md - Comprehensive API documentation (482 lines)
  • tests/unit/creep-communication-severity.test.ts - 24 new unit tests

Performance Impact:

Filtering happens before creep.say() API calls, reducing invocations for suppressed messages. With WARNING level enabled, routine actions (harvest, deliver, upgrade) are filtered out, eliminating 70-80% of visual messages while preserving error visibility. The classification logic adds negligible CPU overhead (<0.001 per creep per tick).

Bug Fixes

State Machine Context Staleness (#1305)

Fixed critical bug where harvester state machines cached stale creep references, preventing state transitions. Harvesters remained stuck in “harvesting” state despite reaching full capacity, never delivering energy to spawns or controllers.

Root Cause:

HarvesterController and ScoutController cache StateMachine instances in a Map for performance. The context contained a creep reference set only during initialization. Guard conditions checking ctx.creep.store.getFreeCapacity() evaluated tick N-1 data on tick N, causing transition failures when creeps reached capacity.

Why This Happened:

State machine caching is a performance optimization that avoids recreating state machines every tick. However, the cached context wasn’t being updated with the current creep object, causing guards to evaluate against stale game state. A creep with 50/50 energy would still see getFreeCapacity() > 0 in the guard because the context referenced the previous tick’s creep object.

Solution:

The fix updates the creep reference in the state machine context every tick before executing state logic:

1
2
// HarvesterController.ts and ScoutController.ts
machine.getContext().creep = creep as Creep;

This surgical two-line change (one per controller) ensures guards evaluate current game state while preserving performance benefits of state machine caching.

Files Changed:

  • packages/bot/src/runtime/behavior/controllers/HarvesterController.ts
  • packages/bot/src/runtime/behavior/controllers/ScoutController.ts

Impact:

Harvesters now correctly transition from “harvesting” to “delivering” when reaching full capacity. Energy delivery to spawns and controllers is restored, resolving the resource starvation issue observed in production. Existing regression tests (harvester-container-transfer.test.ts) now pass, validating correct state transition behavior.

Dependency Updates

This release includes six GitHub Actions dependency updates to maintain security and compatibility:

  • @vitest/coverage-v8: 4.0.10 → 4.0.13 (test coverage reporting)
  • actions/upload-artifact: v4 → v5 (artifact management)
  • actions/github-script: v7 → v8 (workflow scripting)
  • actions/stale: v9 → v10 (issue management)
  • actions/setup-node: v4 → v6 (Node.js environment)
  • actions/checkout: v4 → v6 (repository checkout)

Why Update Actions:

GitHub Actions dependencies are updated proactively to benefit from security patches, performance improvements, and new features. These updates were applied through automated Dependabot pull requests, ensuring the CI/CD pipeline remains secure and efficient.

Technical Architecture

Communication System Design

The severity-based filtering system follows a layered architecture:

  1. Classification Layer: ACTION_SEVERITY mapping assigns default severity to each creep action type
  2. Configuration Layer: CommunicationConfig interface allows per-instance or global configuration
  3. Filtering Layer: Severity comparison (severity <= this.config.level) determines visibility
  4. API Layer: Convenience methods (error(), warn(), info(), verbose()) provide explicit control

This separation of concerns enables flexible configuration without coupling action types to display logic. The system supports both automatic classification (via action type) and explicit severity specification (via API methods).

State Machine Context Management

The state machine fix demonstrates the importance of context freshness in cached systems. The architecture now follows a pattern:

  1. Initialization: Create state machine and context once
  2. Caching: Store state machine in controller-level Map for performance
  3. Context Refresh: Update creep reference every tick before execution
  4. State Evaluation: Guards evaluate current game state

This pattern balances performance (avoiding state machine recreation) with correctness (evaluating current state).

Development Impact

Reduced Visual Noise

With filtering enabled, bot operators can focus on actionable information. Routine operations fade into the background, while warnings and errors remain visible. This is particularly valuable during multi-room operation when 50+ creeps would otherwise create information overload.

Debugging Support

The system maintains a VERBOSE mode for development and debugging. When investigating behavior issues, developers can temporarily increase the communication level to see all creep actions, then reduce it for production operation.

State Machine Reliability

The context staleness fix ensures state machines behave correctly with cached instances. This pattern applies to any cached game objects (creeps, structures, resources) where game state mutates between ticks but cached references remain constant.

What’s Next

The communication system provides a foundation for future enhancements:

  • Memory-Based Configuration: Runtime configuration via Memory.experimentalFeatures
  • Per-Role Filtering: Different severity levels for different creep roles
  • Dynamic Adjustment: Automatic severity adjustment based on error conditions
  • Performance Monitoring: Track communication overhead and filter effectiveness

The state machine reliability fix opens opportunities for broader state machine caching without correctness concerns.

Migration Guide

Enabling Filtered Communication

Existing code continues to work unchanged. To enable filtered communication:

1
2
3
4
5
6
7
// Before (shows all messages)
const comm = new CreepCommunicationManager();

// After (shows warnings and errors only)
const comm = new CreepCommunicationManager({
  level: CommunicationLevel.WARNING
});

Using Explicit Severity Methods

For fine-grained control:

1
2
3
4
5
6
7
8
// Automatic severity via action type
comm?.say(creep, "harvest");  // VERBOSE level

// Explicit severity via method
comm?.error(creep, "stuck", "path blocked");    // ERROR level
comm?.warn(creep, "empty", "low TTL");          // WARNING level
comm?.info(creep, "gather", "from storage");    // INFO level
comm?.verbose(creep, "deliver", "to spawn");    // VERBOSE level

State Machine Pattern

When caching state machines, always refresh the creep context:

1
2
3
4
5
6
7
8
9
10
11
12
let machine = this.stateMachines.get(creep.name);
if (!machine) {
  machine = createStateMachine(creep);
  this.stateMachines.set(creep.name, machine);
}

// CRITICAL: Update context with current creep
machine.getContext().creep = creep;

// Now execute state logic
const currentState = machine.getState();
// ... state execution logic

Acknowledgments

This release was developed collaboratively by GitHub Copilot autonomous agents and ralphschuler. The communication filtering system (#1306) and state machine fix (#1305) were implemented by Copilot agents following the repository’s zero-obsolete-code policy and surgical change principles.

  • Communication System: docs/runtime/communication.md - Complete API reference and usage patterns
  • State Machines: docs/runtime/behavior/ - Behavior controller architecture
  • Testing: 24 new unit tests in tests/unit/creep-communication-severity.test.ts
  • Changelog: Full version history at CHANGELOG.md

Release Statistics:

  • Version: 0.142.0
  • Release Date: November 24, 2025
  • Pull Requests: 8 (2 features, 6 dependency updates)
  • Files Changed: 6
  • Test Coverage: 24 new unit tests, all passing
  • Breaking Changes: None (fully backward compatible)

For complete details, see the full changelog and release tag.