Package io.github.jspinak.brobot.navigation.path

package io.github.jspinak.brobot.navigation.path
Path discovery and traversal for state-based navigation.

This package implements the pathfinding and path execution components of Brobot's navigation system. It provides algorithms for discovering routes through the state graph and mechanisms for executing those routes by triggering state transitions. This is the core implementation of the Path Traversal Model (§) from the formal framework.

Core Components

  • Path - Represents a route through states as tuple ρ = (S_ρ, T_ρ)
  • Paths - Collection of paths with scoring and selection capabilities
  • PathFinder - Implements f_pathfind to discover all routes to target states
  • PathTraverser - Executes paths by performing transitions in sequence
  • PathManager - Manages path collections, cleanup, and adaptation

Path Model

A path consists of:

  • State Sequence: S_ρ = [s₀, s₁, ..., sₙ] from start to target
  • Transition Sequence: T_ρ = [t₀, t₁, ..., tₙ₋₁] connecting states
  • Score: Calculated based on state weights and transition costs
  • Validity: Paths must connect adjacent states via transitions

Pathfinding Algorithm

The PathFinder uses recursive graph traversal:

  1. Start from target state (backward search)
  2. Find all states with transitions TO current state
  3. Recursively explore each predecessor
  4. Terminate when reaching any start state
  5. Prevent cycles by tracking visited states

Path Execution

PathTraverser executes discovered paths:

  1. Iterate through consecutive state pairs
  2. Execute transition between each pair
  3. Monitor success/failure of each transition
  4. Record failure points for recovery
  5. Return success only if target reached

Usage Examples

Basic Pathfinding


 PathFinder finder = context.getBean(PathFinder.class);

 // Find all paths from current states to target
 Set<State> currentStates = stateMemory.getActiveStates();
 Paths allPaths = finder.getPathsToState(currentStates, targetState);

 // Paths are automatically scored and sorted
 Path bestPath = allPaths.getBestPath();
 System.out.println("Best path score: " + bestPath.getScore());

Path Traversal


 PathTraverser traverser = context.getBean(PathTraverser.class);

 // Execute the best path
 boolean success = traverser.traverse(bestPath);

 if (!success) {
     // Get failure information
     Long failedFromState = traverser.getFailedFromState();
     System.out.println("Failed at state: " + failedFromState);
 }

Path Management


 PathManager manager = new PathManager(paths);

 // Remove paths that use a failed transition
 manager.cleanFailedTransition(failedFromState, failedToState);

 // Adjust paths after partial progress
 manager.adjustForProgress(reachedState);

 // Get remaining viable paths
 Paths remainingPaths = manager.getPaths();

Path Scoring

Paths are scored using:

  • State Weights: Lower weight = more desirable to traverse
  • Path Length: Shorter paths generally preferred
  • Transition Reliability: Historical success rates
  • Custom Heuristics: Application-specific scoring 

 // Path cost calculation
 score = Σ(stateWeight[i]) for all states in path

 // Lower scores are better
 paths.sort(); // Sorts by ascending score

Failure Handling

The package provides robust failure recovery:

  • Failure Detection: Identifies exact transition that failed
  • Path Filtering: Removes paths using failed transitions
  • Progress Preservation: Adjusts paths based on partial success
  • Alternative Routes: Automatically tries next best path

Advanced Features

Multi-Start Pathfinding


 // Find paths from multiple possible starting points
 Set<State> possibleStarts = Set.of(stateA, stateB, stateC);
 Paths paths = finder.getPathsToState(possibleStarts, targetState);

 // PathFinder finds optimal paths from any start

Path Analysis


 // Analyze path characteristics
 Path path = paths.getBestPath();

 List<Long> stateSequence = path.getStates();
 int pathLength = path.size();
 boolean visitState = path.contains(specificStateId);

 // Get human-readable representation
 String pathDescription = path.getStatesAsString();

Design Principles

  1. Completeness - Finds ALL valid paths, not just one
  2. Efficiency - Cycle detection prevents infinite recursion
  3. Flexibility - Supports multiple start and end states
  4. Robustness - Graceful handling of failures
  5. Transparency - Clear tracking of execution state

Integration

Path components integrate with:

  • StateTransitions for discovering connections
  • TransitionExecutor for performing state changes
  • StateNavigator for high-level orchestration
  • StateMemory for current state information
Since:
1.0
See Also:
  • Classes
    Class
    Description
    Path
    Represents a navigation path between states in the Brobot model-based GUI automation framework.
    PathFinder
    Implements graph traversal algorithms to find navigation paths between States.
    PathManager
    Manages path scoring and recovery after failed state traversals.
    Paths
    Collection of navigation paths in the Brobot model-based GUI automation framework.
    PathTraverser
    Executes navigation paths by performing state transitions in sequence.