Navigation (BotHack JavaDoc)

Object
- Navigation

```
public final class Navigation
extends Object
```
Utility functions for navigation and dungeon exploration.
Note that navigation is one of the most computationally expensive functions the bot will likely use. You can limit the search by specifying a low maxSteps. When using the IPredicate function variants, efficient implementation of the predicate is crucial.
By default the functions will automatically make use of safe items like a pick-axe or rings of levitation. Furthermore:
- shorter paths will be dug through walls and rock when possible
- a pick-axe will be dropped when entering a shop (bots should not try to pick it back up – use isEnteringShop(IGame))
- the Pay command will be tried automatically when leaving a shop
- locked doors will be unlocked or kicked down when possible
- blocked doors may be kicked down
- traps will be escaped automatically, bot may wait for legs to heal
- levitation items will be used to cross water, ice, lava, trapdoors and holes, also on the planes of air and water
Most of these features can be disabled using some NavOption when using navigate(bothack.bot.IGame, bothack.bot.IPosition, bothack.actions.NavOption...). Exploration and seeking will however always use the listed behaviors.
When seeking/searching, the bot will generally:
- search dead ends and towards blanks on the map, eventually also corridors (where appropriate)
- push boulders around
- attempt to dig downwards or teleport when stuck
Seaching in sokoban levels is not recommended and may get the bot stuck. You should use ActionsComplex.doSokoban(IGame) in sokoban.
All level navigation functions automatically choose A* or Dijkstra's algorithm depending on the number of targets. The step cost function currently can't be influenced by the user.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static interface Navigation.IPath
Representation of a navigation result.

Nested Classes
Modifier and Type	Class and Description
`static interface`	`Navigation.IPath` Representation of a navigation result.

Method Summary

Methods
Modifier and Type	Method and Description
`static IAction`	`branchEntrance(IGame game, Branch branch)` Return Dlvl of `Branch.MAIN` containing the entrance to branch, if static or already visited
`static IAction`	`explore(IGame game, Branch branch)` Returns an action to explore the dungeon up to and including end of the given branch.
`static IAction`	`explore(IGame game, Branch branch, LevelTag tag)` Returns an action to explore the dungeon up to and including the specified level.
`static IAction`	`exploreCurrentLevel(IGame game)` Returns an action to explore the current level and items or null if it seems fully explored.
`static IAction`	`exploreLevel(IGame game, Branch branch, LevelTag tag)` Unless the specified level already seems fully explored, returns an action to go to that level or explore it.
`static IAction`	`exploreLevel(IGame game, Branch branch, String dlvl)` Unless the specified level already seems fully explored, returns an action to go to that level or explore it.
`static Boolean`	`isEnteringShop(IGame game)` Returns true if the player is just about to enter a shop and should not pick up pickaxes.
`static List<IPosition>`	`lastPath(IGame game)` Returns the intended path of the last performed action – if it was generated by some of the methods of this class.
`static Navigation.IPath`	`navigate(IGame game, IPosition target, long maxSteps, NavOption... opts)` Returns the shortest path to the given target and an action to perform to move along it.
`static Navigation.IPath`	`navigate(IGame game, IPosition target, NavOption... opts)` Returns the shortest path to the given target and an action to perform to move along it.
`static Navigation.IPath`	`navigate(IGame game, IPredicate<ITile> target, long maxSteps, NavOption... opts)` Returns the shortest path to a matching target and an action to perform to move along it.
`static Navigation.IPath`	`navigate(IGame game, IPredicate<ITile> target, NavOption... opts)` Returns the shortest path to a matching target and an action to perform to move along it.
`static IAction`	`searchCurrentLevel(IGame game)` Returns an action to explore or search the current level or null if the first round of searching is already done.
`static IAction`	`searchCurrentLevelRepeatedly(IGame game)` Returns an action to explore or search the current level repeatedly.
`static IAction`	`seek(IGame game, IPosition target)` Returns an action to look for the specified tile on the current level or null if already standing at a matching tile.
`static IAction`	`seek(IGame game, IPredicate<ITile> target)` Returns an action to look for the specified tile on the current level or null if already standing at a matching tile.
`static IAction`	`seekBranch(IGame game, Branch branch)` Returns an action to look for the specified branch or null if already there.
`static IAction`	`seekInterlevel(IGame game, IPredicate<ITile> target)` Interlevel navigation to the nearest matching tile.
`static IAction`	`seekInterlevel(IGame game, IPredicate<ITile> target, long maxDelta)` Intralevel navigation to the nearest matching tile.
`static IAction`	`seekInterlevelUpwards(IGame game, IPredicate<ITile> target)` Like `seekInterlevel(IGame, IPredicate)` but will only change levels upwards and avoid subbranches.
`static IAction`	`seekInterlevelUpwards(IGame game, IPredicate<ITile> target, long maxDelta)` Like `seekInterlevel(IGame, IPredicate)` but will only change levels upwards and avoid subbranches.
`static IAction`	`seekLevel(IGame game, Branch branch, LevelTag tag)` Returns an action to go to the specified level or null if already there.
`static IAction`	`seekLevel(IGame game, Branch branch, String dlvl)` Returns an action to go to the specified level or null if already there.
`static IAction`	`visitBranch(IGame game, Branch branch)` If the specified branch has never been visited, returns the action to navigate to it and possibly explore it until identified.
`static IAction`	`visitLevel(IGame game, Branch branch, LevelTag tag)` If the specified level has never been visited, returns the action to navigate to it.
`static IAction`	`visitLevel(IGame game, Branch branch, String dlvl)` If the specified level has never been visited, returns the action to navigate to it.

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - navigate
```
public static Navigation.IPath navigate(IGame game,
                        IPosition target,
                        NavOption... opts)
```
    Returns the shortest path to the given target and an action to perform to move along it. Returns null if the target is not reachable.
    
    Parameters:
    opts - Additional modifiers
  - navigate
```
public static Navigation.IPath navigate(IGame game,
                        IPosition target,
                        long maxSteps,
                        NavOption... opts)
```
    Returns the shortest path to the given target and an action to perform to move along it. Returns null if the target is not reachable.
    
    Parameters:
    maxSteps - Maximum number of steps
    opts - Additional modifiers
  - navigate
```
public static Navigation.IPath navigate(IGame game,
                        IPredicate<ITile> target,
                        NavOption... opts)
```
    Returns the shortest path to a matching target and an action to perform to move along it. Returns null if no target is reachable.
    
    Parameters:
    opts - Additional modifiers
  - navigate
```
public static Navigation.IPath navigate(IGame game,
                        IPredicate<ITile> target,
                        long maxSteps,
                        NavOption... opts)
```
    Returns the shortest path to a matching target and an action to perform to move along it. Returns null if no target is reachable.
    
    Parameters:
    maxSteps - Maximum number of steps
    opts - Additional modifiers
  - seek
```
public static IAction seek(IGame game,
           IPosition target)
```
    Returns an action to look for the specified tile on the current level or null if already standing at a matching tile. You should only use this to look for tiles that you know are present on the current level and reachable, otherwise if you loop this the bot will get stuck searching endlessly.
    
    See Also:
    navigate(IGame, IPosition, NavOption...)
  - seek
```
public static IAction seek(IGame game,
           IPredicate<ITile> target)
```
    Returns an action to look for the specified tile on the current level or null if already standing at a matching tile. You should only use this to look for tiles that you know are present on the current level and reachable, otherwise if you loop this the bot will get stuck searching endlessly.
    
    See Also:
    navigate(IGame, IPosition, NavOption...)
  - seekBranch
```
public static IAction seekBranch(IGame game,
                 Branch branch)
```
    Returns an action to look for the specified branch or null if already there.
  - seekLevel
```
public static IAction seekLevel(IGame game,
                Branch branch,
                String dlvl)
```
    Returns an action to go to the specified level or null if already there.
  - seekLevel
```
public static IAction seekLevel(IGame game,
                Branch branch,
                LevelTag tag)
```
    Returns an action to go to the specified level or null if already there.
  - exploreLevel
```
public static IAction exploreLevel(IGame game,
                   Branch branch,
                   String dlvl)
```
    Unless the specified level already seems fully explored, returns an action to go to that level or explore it.
  - exploreLevel
```
public static IAction exploreLevel(IGame game,
                   Branch branch,
                   LevelTag tag)
```
    Unless the specified level already seems fully explored, returns an action to go to that level or explore it.
  - exploreCurrentLevel
```
public static IAction exploreCurrentLevel(IGame game)
```
    Returns an action to explore the current level and items or null if it seems fully explored.
    
    See Also:
    searchCurrentLevel(IGame)
  - explore
```
public static IAction explore(IGame game,
              Branch branch,
              LevelTag tag)
```
    Returns an action to explore the dungeon up to and including the specified level.
  - explore
```
public static IAction explore(IGame game,
              Branch branch)
```
    Returns an action to explore the dungeon up to and including end of the given branch.
  - searchCurrentLevelRepeatedly
```
public static IAction searchCurrentLevelRepeatedly(IGame game)
```
    Returns an action to explore or search the current level repeatedly.
    - search dead ends and towards blanks on the map, eventually also corridors (where appropriate)
    - push boulders around
    - attempt to dig downwards or teleport when stuck
    If all tiles of the level become extremely thoroughly searched an IllegalStateException will be thrown as the bot is likely stuck.
  - searchCurrentLevel
```
public static IAction searchCurrentLevel(IGame game)
```
    Returns an action to explore or search the current level or null if the first round of searching is already done.
    - search dead ends and towards blanks on the map, eventually also corridors (where appropriate)
    - push boulders around
    - attempt to dig downwards or teleport when stuck
    See Also:
    searchCurrentLevelRepeatedly(IGame)
  - visitBranch
```
public static IAction visitBranch(IGame game,
                  Branch branch)
```
    If the specified branch has never been visited, returns the action to navigate to it and possibly explore it until identified.
  - visitLevel
```
public static IAction visitLevel(IGame game,
                 Branch branch,
                 String dlvl)
```
    If the specified level has never been visited, returns the action to navigate to it.
  - visitLevel
```
public static IAction visitLevel(IGame game,
                 Branch branch,
                 LevelTag tag)
```
    If the specified level has never been visited, returns the action to navigate to it.
  - branchEntrance
```
public static IAction branchEntrance(IGame game,
                     Branch branch)
```
    Return Dlvl of Branch.MAIN containing the entrance to branch, if static or already visited
  - seekInterlevel
```
public static IAction seekInterlevel(IGame game,
                     IPredicate<ITile> target,
                     long maxDelta)
```
    Intralevel navigation to the nearest matching tile. Will not traverse the castle or medusa's if the player is lacking safe levitation source, otherwise assumes all levels are passable and unit distance. Only runs tile-based navigation on the current level.
    
    Parameters:
    maxDelta - limits the number of traversed levels
  - seekInterlevel
```
public static IAction seekInterlevel(IGame game,
                     IPredicate<ITile> target)
```
    Interlevel navigation to the nearest matching tile. Will not attempt to traverse the castle or medusa's if the player is lacking a safe levitation source. Otherwise assumes all levels are passable and uniform distance (cost). Only runs tile-based navigation on the current level.
  - seekInterlevelUpwards
```
public static IAction seekInterlevelUpwards(IGame game,
                            IPredicate<ITile> target)
```
    Like seekInterlevel(IGame, IPredicate) but will only change levels upwards and avoid subbranches.
  - seekInterlevelUpwards
```
public static IAction seekInterlevelUpwards(IGame game,
                            IPredicate<ITile> target,
                            long maxDelta)
```
    Like seekInterlevel(IGame, IPredicate) but will only change levels upwards and avoid subbranches.
    
    Parameters:
    maxDelta - limits the number of traversed levels
  - lastPath
```
public static List<IPosition> lastPath(IGame game)
```
    Returns the intended path of the last performed action – if it was generated by some of the methods of this class.
  - isEnteringShop
```
public static Boolean isEnteringShop(IGame game)
```
    Returns true if the player is just about to enter a shop and should not pick up pickaxes.

Class Navigation

Nested Class Summary

Method Summary

Methods inherited from class Object

Method Detail

navigate

navigate

navigate

navigate

seek

seek

seekBranch

seekLevel

seekLevel

exploreLevel

exploreLevel

exploreCurrentLevel

explore

explore

searchCurrentLevelRepeatedly

searchCurrentLevel

visitBranch

visitLevel

visitLevel

branchEntrance

seekInterlevel

seekInterlevel

seekInterlevelUpwards

seekInterlevelUpwards

lastPath

isEnteringShop