Using moves outside battle

*For creating obstacles that can be overcome by using moves on them, see Obstacles.*
This page describes how to **use moves outside of battle**.

## Using moves outside battle

The script section **Overworld\_FieldMoves** handles the use of moves outside battle.

The script section **Settings** contains the setting `FIELD_MOVES_COUNT_BADGES` which determines whether HMs require a given number of Gym Badges in order to be unlocked, or whether they need specific Badges. There are also settings for (most of) the moves that are usable outside of battle, which set the number of Badges/specific Badge needed to be able to use that move outside of battle. Badge 0 is the first Badge, 1 is the second Badge, and so on.

There are three main ways to use a move outside battle: interacting with an event or tile, selecting the move from the party screen, or selecting the move from the Ready menu. The first method uses different scripts from the other two. Below are descriptions of each variation of these methods - the effects themselves are not described, as they are fairly straightforward. Note that all moves use the second method, while some also use the first method as well.

## Interacting with an event

Interacting with an event is the easiest way to use a move outside battle. The event should, when interacted with, call a method that describes the effect (including checking for whether they are able to use the move for it, e.g. whether they have the Gym Badge(s) to allow it).

The moves that can be used in this way are:

* Cut - interact with a small tree.
* Headbutt - interact with a tree.
* Rock Smash - interact with a cracked rock.
* Strength - interact with a boulder.

See the page Obstacles for details of how to set up events for these objects.

For Strength, the boulder event simply moves the boulder if the player runs into it after using Strength. To use Strength in the first place, when the player presses the "Use" button, the game uses a procedure stored in `EventHandlers` to check whether the player is facing an event with "StrengthBoulder" in its name, and if so, to ask if they want to use the move Strength. This procedure is as follows:

```
EventHandlers.add(:on_player_interact, :strength_event,
  proc {
    facingEvent = $game_player.pbFacingEvent
    pbStrength if facingEvent && facingEvent.name[/strengthboulder/i]
  }
)

```

## Interacting with a tile

Interacting with a tile means checking the terrain tag of the tile immediately in front of the player. The three moves that can be used in this way are:

* Surf - interact with a water tile (terrain tags 5, 6, 7 or 9).
* Dive - interact while on a deep water tile (terrain tag 5).
* Waterfall - interact with a waterfall tile (terrain tag 8).

These interactions need some `:on_player_interact` code in `EventHandlers`, which checks the terrain tag of the tile in front of the player and calls another method that describes the actual effect of that move.

For example, the code for Surf is as follows:

```
EventHandlers.add(:on_player_interact, :start_surfing,
  proc {
    next if $PokemonGlobal.surfing
    next if $game_map.metadata&.always_bicycle
    next if !$game_player.pbFacingTerrainTag.can_surf_freely
    next if !$game_map.passable?($game_player.x, $game_player.y, $game_player.direction, $game_player)
    pbSurf
  }
)

```

Note that these procedures do not check for followers or the appropriate Gym Badge(s) or so forth - those checks are done in `def pbSurf` (or whichever method is called for other moves). This procedure simply checks whether the player is in the right place to be able to use the move, not whether they are actually allowed to use it.

Note that the method called here should first ask the player whether they want to use the move, rather than automatically use it straight away.

## Using the move from the party screen

All moves that can be used outside battle should appear in the party screen menu when selecting a Pokémon. This includes all of the above moves, plus:

* Chatter
* Dig
* Flash
* Fly
* Milk Drink
* Soft-Boiled
* Sweet Scent
* Teleport

The way the game decides whether a move should appear in the menu is to see whether there exists a `HiddenMoveHandlers::CanUseMove` handler for each of the Pokémon's moves. If there is, then that move will be added to the menu options (even if it can't be used). However, this does not apply to Milk Drink or Soft-Boiled, which are dealt with separately (see below).

There are two types of handler associated with using moves from the party screen: `CanUseMove` and `UseMove`. The former does all the checks to decide whether the move can be used, and the latter carries out the move.

For example, the two handlers for Surf are as follows:

```
  next false if !pbCheckHiddenMoveBadge(Settings::BADGE_FOR_SURF, showmsg)
  if $PokemonGlobal.surfing
    pbMessage(_INTL("You're already surfing.")) if showmsg
    next false
  end
  if !$game_player.can_ride_vehicle_with_follower?
    pbMessage(_INTL("It can't be used when you have someone with you.")) if showmsg
    next false
  end
  if $game_map.metadata&.always_bicycle
    pbMessage(_INTL("Let's enjoy cycling!")) if showmsg
    next false
  end
     !$game_map.passable?($game_player.x, $game_player.y, $game_player.direction, $game_player)
    pbMessage(_INTL("No surfing here!")) if showmsg
    next false
  end
  next true
})

```

This handler performs all the checks for whether the player is allowed to surf. It returns TRUE if they can.

```
  $game_temp.in_menu = false
  pbCancelVehicles
  if !pbHiddenMoveAnimation(pokemon)
    pbMessage(_INTL("{1} used {2}!", pokemon.name, GameData::Move.get(move).name))
  end
  surfbgm = GameData::Metadata.get.surf_BGM
  pbCueBGM(surfbgm, 0.5) if surfbgm
  pbStartSurfing
  next true
})

```

If the player can surf, this handler performs the effect. It displays an animation (see below) and then calls a method that starts the player surfing. This method (`def pbStartSurfing`) is different to the one called above (`def pbSurf`) because it assumes the player has already confirmed they want to use the move, so the game shouldn't ask the player again whether they want to use it.

Note that, in the end, both the `UseMove` handler above and `def pbSurf` call the same method (`def pbStartSurfing`). This final method actually handles the start of surfing.

### Fly

Fly is a little more involved, as the move is not used straight away, but instead the player has to choose a destination to fly to. That is, the specific effect of Fly is not the same every time it is used - the destination can vary.

Before the hidden move handler for Fly is called, the game opens the region map screen so that the player can choose a destination. This is done in the script section **UI\_Party** in `def pbPokemonScreen`. The chosen Fly destination is stored in a temporary variable, and then Fly's hidden move handler is called as normal.

Fly can also be used from the Town Map if the setting `CAN_FLY_FROM_TOWN_MAP` is TRUE.

### Milk Drink and Soft-Boiled

These two moves can be used outside battle, but they do not affect anything in the field like other moves do. Instead, they simply affect Pokémon in the player's party, and thus don't need the party screen to close in order to occur.

When deciding which commands should appear in the party screen menu (in the script section **UI\_Party** in `def pbPokemonScreen`), in addition to looking for hidden move handlers as mentioned above, the game also specifically checks whether the Pokémon knows Milk Drink or Soft-Boiled, and adds these options to the list if so.

The effects of these two moves also appear in that same method, a little further down. There are no separate scripts in the script section **Overworld\_FieldMoves** for these two moves.

## Using move animation

When the player uses a move outside battle (except Milk Drink or Soft-Boiled), an animation will be shown of the Pokémon sweeping across the screen. This animation is defined in the script section **Overworld\_FieldMoves** in `def pbHiddenMoveAnimation`.