Release 0.155.21: Advanced Pathfinding with NesCafe62's Library

(Updated: )
Release Notes
, , ,

We’re excited to announce version 0.155.21, which brings a significant upgrade to the bot’s pathfinding capabilities by integrating the battle-tested screeps-pathfinding library by NesCafe62. This release marks a major step forward in movement efficiency, traffic management, and overall pathfinding performance.

Key Features

NesCafe Pathfinder Integration

  • Replaced the default pathfinding implementations with NesCafePathfinder as the primary provider
  • Added automatic fallback to native Screeps pathfinding when the library is unavailable
  • Integrated advanced traffic management with priority-based movement system
  • Implemented terrain and cost matrix caching for improved CPU efficiency

Traffic Management System

  • Added runMoves() function for coordinated, priority-based creep movement
  • Implemented reservePos() for position reservations to prevent collision conflicts
  • Added moveOffRoad() utility to move creeps off roads when finished working
  • Enhanced moveTo() with priority option for fine-grained traffic control
  • Added automatic move-off-exit behavior to prevent creeps from blocking room entrances

Technical Details

Why NesCafe Pathfinder?

The decision to integrate NesCafe62’s screeps-pathfinding library was driven by several factors:

  1. Proven Performance: The library has been battle-tested in the Screeps community and is known for its CPU efficiency and reliability.

  2. Advanced Features: Unlike our previous implementations (DefaultPathfinder and CartographerPathfinder), NesCafe Pathfinder provides sophisticated traffic management capabilities that were missing from our codebase.

  3. Caching Architecture: The library includes intelligent terrain and cost matrix caching, reducing redundant pathfinding calculations that were consuming valuable CPU cycles.

Implementation Architecture

The integration maintains our existing pathfinding abstraction layer defined in packages/bot/src/runtime/behavior/PathfindingProvider.ts. This means:

  • Clean Interface: The PathfindingProvider interface remains unchanged, ensuring compatibility with existing code
  • Graceful Degradation: If the NesCafe library is unavailable (e.g., during partial deployments), the system automatically falls back to native Screeps PathFinder
  • No Breaking Changes: All existing creep movement code continues to work without modification

The new NesCafePathfinder is implemented in packages/bot/src/runtime/behavior/NesCafePathfinder.ts and integrates seamlessly with our TaskManager and BehaviorController systems.

Traffic Management Design

One of the most significant additions is the priority-based traffic management system:

Priority Levels: The runMoves() function processes creep movements in priority order, ensuring critical roles (like haulers carrying energy to spawns) can move first while lower-priority creeps (like idle upgraders) yield appropriately.

Position Reservations: The reservePos() function allows creeps to claim positions before moving, preventing two creeps from attempting to occupy the same tile and causing movement conflicts.

Road Clearance: The moveOffRoad() utility intelligently moves creeps off roads when they’re finished working, keeping high-traffic infrastructure clear for active haulers and other moving creeps.

Exit Management: Automatic move-off-exit behavior prevents creeps from blocking room boundaries, which was a common source of traffic jams in multi-room operations.

Design Rationale

Why Remove DefaultPathfinder and CartographerPathfinder?

Following our repository’s zero-tolerance policy for obsolete code, we’ve completely removed the old pathfinding implementations rather than marking them as deprecated. This decision was made because:

  1. NesCafe Pathfinder is Superior: The new implementation provides all the functionality of the old systems plus significant additional features (traffic management, better caching, priority-based movement).

  2. Reduced Complexity: Maintaining multiple pathfinding providers adds unnecessary complexity and testing burden without providing real value.

  3. Single Source of Truth: Having one well-tested pathfinding system is better than having multiple competing implementations that could lead to inconsistent behavior.

  4. Performance Benefits: The NesCafe library’s caching and optimization strategies are more advanced than our previous implementations, resulting in measurable CPU savings.

The fallback to native Screeps pathfinding provides the necessary safety net without requiring us to maintain legacy code.

Bug Fixes

No bug fixes were included in this release—this is a pure feature enhancement focused on pathfinding improvements.

Breaking Changes

⚠️ Breaking Changes

  • Removed DefaultPathfinder: Code that explicitly references DefaultPathfinder will need to be updated to use NesCafePathfinder or the generic PathfindingProvider interface.
  • Removed CartographerPathfinder: Code that explicitly references CartographerPathfinder will need to be updated similarly.

However, if your code uses the PathfindingManager or TaskManager without directly referencing specific pathfinder implementations, no changes are required—the system will automatically use the new pathfinder.

Impact

Performance Improvements

The integration of NesCafe Pathfinder is expected to deliver several performance benefits:

  • CPU Efficiency: Reduced pathfinding overhead through intelligent caching of terrain and cost matrices
  • Fewer Recalculations: Path caching means creeps reuse paths more effectively, reducing redundant pathfinding calls
  • Traffic Optimization: Priority-based movement reduces congestion and prevents creeps from blocking each other

Development Workflow

  • Simplified Maintenance: One pathfinding implementation to maintain, test, and optimize
  • Better Testing: Focused testing efforts on a single, well-proven library rather than multiple competing implementations
  • Community Support: Leveraging a community-developed library means benefiting from ongoing improvements and bug fixes from the broader Screeps community

Bot Behavior

Creeps will now:

  • Navigate more efficiently through crowded areas
  • Automatically yield to higher-priority creeps when appropriate
  • Clear roads when idle to maintain traffic flow
  • Avoid blocking room exits during multi-room operations

What’s Next

With the pathfinding foundation significantly improved, future work will focus on:

  1. Tuning Traffic Priorities: Fine-tuning the priority system based on observed bot behavior in production environments
  2. Performance Monitoring: Collecting metrics on pathfinding CPU usage to validate the expected performance improvements
  3. Advanced Movement Patterns: Exploring convoy systems and coordinated multi-creep movement for complex logistics operations
  4. Multi-Room Optimization: Leveraging the new pathfinding capabilities for more efficient remote mining and inter-room logistics
  • packages/bot/src/runtime/behavior/NesCafePathfinder.ts - New pathfinder implementation
  • packages/bot/src/runtime/behavior/PathfindingProvider.ts - Pathfinding abstraction interface
  • packages/bot/src/runtime/behavior/PathfindingManager.ts - Pathfinding provider management
  • packages/bot/src/runtime/behavior/TaskManager.ts - Integration with task system
  • packages/bot/src/runtime/behavior/BehaviorController.ts - Integration with behavior system

Installation

This release is automatically deployed to the Screeps MMO environment. No manual installation is required—the bot will use the new pathfinding system immediately upon deployment.

Full Changelog: View on GitHub