# Pokemon Essentials - Advanced Topics

Peter O. (http://upokecenter.com/projects/pokestarter/)

This section contains advanced topics for Pokemon Essentials, that normally require a knowledge in Ruby and scripting.

This page cannot provide details on how to use the scripting language Ruby. For that, see the links provided in the Ruby language home page's Getting Started section. For reference material, consult the help file provided with RPG Maker XP.

## Contents

- Pokemon Essentials - Advanced Topics
  - Contents
  - Downloading from the Internet
  - Scripts
    - PBAbilities
    - PBMoves
    - PBItems
    - PBSpecies
    - PBMove
    - PokeBattle_AI
    - PokeBattle_ActiveSide
    - PokeBattle_DamageState
    - PokeBattle_Move
    - PokeBattle_Battle
    - PokeBattle_Confusion
    - PokeBattle_Effects
    - PokeBattle_MoveEffects
    - PokeBattle_Scene
    - PokemonItems
    - PokemonField
    - PokemonLoad
    - PokemonMenu
    - PokeBattle_Pokemon
    - PokeBattle_Trainer
    - PokemonStorage
    - PokemonTrainers
    - PokemonWeather
    - Compiler
    - PokemonUtilities
  - Advanced Configuration Files
    - PBS/metadata.txt
    - PBS/encounters.txt
    - PBS/connections.txt
    - PBS/trainernames.txt
    - PBS/trainers.txt
  - Internal Structure of Item Events
  - Scenes in Pokemon Essentials

## Downloading from the Internet

Pokemon Essentials contains methods that allow a game to retrieve data and files from the Internet, and for posting data to Internet pages. They are explained below.

- pbDownloadToString(url) - Retrieves the resource specified in _url_ and returns a string containing the downloaded data. For best results, the file should be saved in UTF-8. URLs whose resources are plain text files are the most ideal for this function
- pbDownloadToFile(url, filename) - Retrieves the resource specified in _url_ and saves the data downloaded to the file _filename_.
- pbDownloadData(url, filename) - Retrieves the resource specified in _url_. If filename is nil, returns a string containing the downloaded data. Otherwise, saves the data to the file _filename_. Raises an exception if the download failed. The exception's message may be something like this "HTTP error XXX", where XXX is the error code, like 404 (not found), or 403 (forbidden).
- pbPostToString(url, postdata) - Posts data to the resource specified in _url_ and returns a string containing the response. The postdata is a hashtable with keys and values specifying the data to send to the URL.
- pbPostToFile(url, postdata, filename) - Posts data to the resource specified in _url_ and saves the response to the file _filename_.
- pbPostData(url, postdata, filename) - Posts data to the resource specified in _url_. If filename is nil, returns a string containing the response. Otherwise, saves the response to the file _filename_. Raises an exception if the download failed. The exception's message may be something like this "HTTP error XXX", where XXX is the error code, like 404 (not found), or 403 (forbidden).

All these functions automatically handle redirects if necessary. However, they don't support HTTPS URLs, only HTTP URLs.

The example offered in the demo (on the far left of the first row of computers in the map "Test Map 2") shows how the function can be used to set a variable and display it as text. Of course, the function can also be used in the script editor, in advanced situations where the game must connect to the Internet.

## Scripts

Here are details on some of the scripts found in Pokemon Essentials. (Some of this documentation is currently out of date.)

### PBAbilities

Constants for each ability in the game. To get the name of an ability, call PBAbilities.getName(item). This script section is automatically generated.

### PokemonMessages

Contains functions for the Pokemon message system.

- `pbInterpreterRunning?()` - Determines whether the game is currently processing events and event commands. If false, the game is not currently processing any events. This is a good opportunity, for example, to respond to button events and display a custom menu system if the game has one.

### PBMoves

Constants for each move in the game. To get the name of a move, call PBMoves.getName(item). This script section is automatically generated.

### PBItems

Constants for each item in the game. To get the name of an item, call `PBItems.getName(item)`. This script section is automatically generated.

### PBSpecies

Constants for each Pokemon species in the game. To get the name of a species, call `PBSpecies.getName(item)`. This script section is automatically generated.

### PBMove

A lightweight class for storing information on a move. Call `PBMove.new` to create the object. After creating the object the following methods are available:

- ppup: Move's PP Up count.
- type: Move's type. Read only.
- id: Move's ID.
- pp: Move's current PP.
- totalpp: Move's total PP. Read only.

This class shouldn't be edited.

### PokeBattle_AI

Mechanism for intelligently choosing a Pokemon's moves. This is done by assigning a score to each move based on whether it can or should be used and depending on the situation.

### PokeBattle_ActiveSide

Structure for effects specific to only one side of a battle. Not meant to be edited.

### PokeBattle_DamageState

Structure for holding the results of damage calculation. Not meant to be edited.

### PokeBattle_Move

Structure for holding information about moves. This script also contains damage calculation and accuracy-checking routines.

### PokeBattle_Battle

Class for Pokemon battles. This is the heart of the battle system. Battles are implemented by dividing each round of a battle into a command phase, attack phase, and end-of-round phase. Also contains methods for using items and throwing Balls.

### PokeBattle_Confusion

Implements a pseudomove for confusion damage.

### PokeBattle_Effects

Contains methods for inflicting common in-battle effects such as stat reduction, confusion, and status problems. It is part of the PokeBattle_Battler class.

### PokeBattle_MoveEffects

Contains classes that derive from PokeBattle_Move. These classes implement effects specific to certain kinds of moves.

### PokeBattle_Scene

A simple implementation of a battle scene. It is mainly now used for debugging purposes.

### PokemonItems

Contains functions that implement the use of items out of battle.

- pbUseMachine(bag,item) - Uses a TM or HM (_item_). After the item is used, deletes the item from the bag (_bag_) if it's a TM.
- pbIsHiddenMachine?(item) - Returns true if the item is a Hidden Machine.
- pbUseItemFromBag(item) - Implements the use of items from the Bag screen.
- pbUseKeyItemInField(item) - Implements the use of Key Items on the field.
- pbUseItemOnPokemon(item,pokemon,scene) - Uses an item (_item_) on a Pokemon (_pokemon_). _scene_ is an instance of PokemonScreen and is used to display messages from that screen. Returns true if the item was used.
- pbUseItem(bag,item) - Uses an item and deletes it from the bag if necessary. Returns one of the following:
  - 0 - The item was not used.
  - 1 - The item was used.
  - 2 - The item was used and the bag screen should close.
- pbLearnMove(pokemon,move,ignoreifknown=false) - Adds a move to the Pokemon. _move_ is the move ID and _ignoreifknown_ is set to false if a message should be displayed when the Pokemon already has the move.

Utility functions:

- pbSpeciesCompatible?(species,machine) - Returns true if the species is compatible with a move. _machine_ is the ID of a move that can be learned with a TM or HM.
- pbRaiseEffortValues(pokemon,ev,evgain=10,evlimit=true) - Raises a Pokemon's Effort Values. _pokemon_ is the Pokemon, _ev_ is the type of EV to raise, _evgain_ is the number of EVs to raise it by, and _evlimit_ is whether an EV limit of 100 per stat should be respected. Returns the actual number of EVs gained.
- pbRestorePP(pokemon,move,pp) - Restores the PP of a move known by the Pokemon. _pokemon_ is the Pokemon, _move_ is the index (from 0 to 3) of the move, and _pp_ is the amount of PP to raise it by. Returns the actual amount of PP gained.
- pbItemRestoreHP(pokemon,restoreHP) - Restores a Pokemon's HP by _restoreHP_. Returns the actual amount of HP gained.

### PokemonField

Contains various functions called in the field.

Constants:

- BADGEFORCUT - Badge required (from 0 through 7) in order to use Cut outside of battle. The constants BADGEFORFLASH, BADGEFORROCKSMASH, BADGEFORSURF, etc. are defined in the same way. Each of these constants should have different values.
- STARTING_OVER_SWITCH - Number for the switch named "Starting Over".
- GRASS_ANIMATION_ID - Animation ID for the animation played when the player walks on grass.

Functions:

- pbWildBattle(species,level,variable=nil,canescape=true) - Starts a wild Pokemon battle with the defined _species_ and _level_. The optional _variable_ is the number of a variable to store the result, and _canescape_ is true if the player can escape.
- Kernel.pbOnStepTaken - Called whenever the player takes a step.
- Kernel.pbOnMapChange - Called whenever the map changes.
- Kernel.pbOnMapSceneCreated(scene,mapchanged) - Called after the scene is created after a map change. _scene_ is the scene, and _mapchanged_ is true if the map changed.
- Kernel.pbUpdateVehicle - Updates the character sprite based on transportation mode.
- Kernel.pbCancelVehicles - Cancels bike and surfing modes. Usually called when transferring the player to another map.
- Kernel.pbFishing - Implements fishing with the Rods.
- pbAllFainted - Returns true if all Pokemon other than Eggs have fainted.
- Kernel.pbSetPokemonCenter - Sets the location of the Pokemon Center to the player's current location.
- Kernel.pbStartOver - Transfers the player to a safe spot after the player's party was defeated.
- Kernel.pbItemBall(item) - Adds _item_ to the player's Bag. Returns true if the item was added.
- Kernel.pbCut - Implements messages for the hidden move Cut.
- Kernel.pbRockSmashRandomEncounter - May start a wild battle after smashing a rock.
- Kernel.pbRockSmash - Implements messages for the hidden move Rock Smash.
- Kernel.pbCanUseHiddenMove?(pkmn,move) - Returns true if the Pokemon (_pkmn_) can use the specified _move_ here.
- Kernel.pbUseHiddenMove(pkmn,move) - Makes the Pokemon (_pkmn_) use the specified _move_.
- Kernel.pbSweetScent - Implements the hidden move Sweet Scent.
- Kernel.pbUseKeyItem - Uses the Key Item currently registered for use with F5.
- Kernel.pbHiddenMoveEvent - Implements interaction with events relevant for hidden moves.

### PokemonLoad

This script loads games and starts new ones. There are two parts to this script: a class called PokemonLoad, which is the backend, and PokemonLoadScene, which is the frontend. This latter class implements the user interface of the load screen. PokemonLoadScene must implement these methods:

- pbChoose(commands) - Displays a list of commands (where _commands_ is the array of commands) and returns the index of the command that was chosen.
- pbSetAuxiliaryWindow(text) - Sets the text of an auxiliary window. The window should be from the class Window_ColoredTextPokemon.
- pbStartScene - Initializes the scene.
- pbEndScene - Closes the scene.

PokemonLoad, as the low-level backend, is generally not interesting to edit.

### PokemonMenu

This script displays the menu. The class PokemonMenu_Scene is the frontend, and the class PokemonMenu is the frontend. PokemonMenu_Scene must implement these methods:

- pbShowCommands(commands) - Displays a list of commands (where _commands_ is the array of commands) and returns the index of the command that was chosen.
- pbStartScene - Initializes the scene.
- pbEndScene - Closes the scene.
- pbShowMenu - Shows the menu.
- pbHideMenu - Hides the menu.

### PokeBattle_Pokemon

This class stores data on each Pokemon. Refer to `$Trainer.party` for an array of each Pokemon in the Trainer's current party. These methods are defined on the PokeBattle_Pokemon class.

- PokeBattle_Pokemon.new(species,level,trainer=nil) - Creates a Pokemon with the defined _species_ and _level_, and sets its Original Trainer to _trainer_.
- hp: Pokemon's current HP.
- totalhp, attack, defense, speed, spatk, spdef: Pokemon's stats. Read only.
- pokerus: Returns 0 if not infected; 1 if infected; 2 if cured.
- item: Pokemon's held item.
- species: Pokemon's species.
- name: Pokemon's nickname.
- happiness: Pokemon's happiness. Maximum of 255.
- iv: Individual values for HP, Attack, Defense, Speed, Special Attack, and Special Defense. Should not be modified unless the Pokemon is being created.
- ev: Effort values for HP, Attack, Defense, Speed, Special Attack, and Special Defense.
- eggsteps: Steps to hatch egg, 0 if Pokemon is not an egg.
- status: Status problem (0, or one of PBStatuses::SLEEP, PBStatuses::POISON, PBStatuses::PARALYSIS, PBStatuses::BURN, or PBStatuses::FROZEN)
- statusCount: Sleep count or Toxic flag.
- exp: Experience Points.
- level: Current level.
- ability: Returns the Pokemon's ability.
- nature: Returns the Pokemon's nature.
- ot: Original Trainer name.
- personalID: Personality ID. A 32-bit value.
- trainerID: TrainerID. A 32-bit value.
- isForeign?(trainer) - Returns true if the Pokemon's Original Trainer is not _trainer_.
- gender - Returns the Pokemon's gender: (0-male, 1-female, 2-genderless).
- egg? - Returns true if the Pokemon is an egg.
- makeShiny - Makes the Pokemon shiny.
- setGender(female) - Sets the Pokemon's gender (true: female; false: male). Returns whether the gender was set.
- isShiny? - Returns true if the Pokemon is shiny.
- type1 - Returns the Pokemon's first type.
- type2 - Returns the Pokemon's second type.
- heal - Heals the Pokemon completely.
- calcStats - Recalculates the Pokemon's stats.

### PokeBattle_Trainer

This class stores data on a Pokemon Trainer, such as the Trainer's party, money, badges, and Pokedex status. The global variable $Trainer stores the player's Trainer object.

- PokeBattle_Trainer.new(name,trainertype) - Creates a new Trainer object with the specified _name_ and _trainertype_. The Trainer initially has $2000.
- name - Gets the Trainer's name.
- id - Gets the Trainer's ID (32 bits; use publicID to get the portion of the ID to display in the game.)
- trainertype - Number identifying the type of Trainer.
- trainerTypeName - Name of this Trainer's type.
- moneyEarned - Money earned when defeating the Trainer.
- money - Current money. This value should not be less than 0 or greater than 999999.
- badges - Badges earned. This is an array of 8 true/false flags.
- seen - Array of true/false values indicating which species are seen. For example, if "$Trainer.seen[200]==true", the player has seen species 200.
- owned - Array of true/false values indicating which species are owned.
- party - Trainer's current party of Pokemon. There should be no more than six Pokemon in the Trainer's party.
- pokedex - Whether the Pokedex was obtained.
- pokemonCount - Number of Pokemon in the party that aren't eggs.
- ablePokemonCount - Number of Pokemon in the party that aren't eggs and whose HP is greater than 0.
- fullname - Combination of the trainer type name and the trainer name.
- numbadges - Number of badges earned.
- publicID - Portion of the ID to display in the game.
- pokedexSeen - Number of Pokemon seen.
- pokedexOwned - Number of Pokemon owned.
- getForeignID - A random ID other than this Trainer's ID.
- setForeignID(other) - Sets this Trainer's ID to a random one other than _other_'s ID.

### PokemonStorage

Implements the Pokemon Storage System.

### PokemonTrainers

Implements support for Trainer battles.

- pbLoadTrainer(trainerid,trainername) - Generates the Trainer with the defined trainer type and trainer name. Returns an array consisting of the Trainer's Trainer object; the Trainer's items, and the Trainer's party.
- pbTrainerBattle(trainerid,trainername,endspeech) - Starts a Trainer battle with the defined trainer type and trainer name. _endspeech_ is the text that the Trainer will say when the player wins the battle.

### PokemonWeather

Overrides the built-in RPG::Weather class. Here are the defined weather types:

- 0 - Rain
- 1 - Storm
- 2 - Snow
- 3 - Sandstorm
- 4 - Sunny

### AudioUtilities

This script contains various utility functions and classes for dealing with audio. This is a stand-alone script.

    Audio.square(durationInMs,freq,volume,timbre,async) - Generates a square wave.
    Audio.beep(durationInMs,freq,volume,timbre,async) - Alias for Audio.square
    Audio.sine(durationInMs,freq,volume,timbre,async) - Generates a sine wave.
    Audio.triangle(durationInMs,freq,volume,timbre,async) - Generates a triangle wave.
    Audio.saw(durationInMs,freq,volume,async) - Generates a saw wave.
    Audio.noise(durationInMs,volume,async) - Generates white noise.
    Audio.playTone(toneFile,async) - Plays a tone in the Apple iPod alarm tone format.
    Parameters:
     durationInMs - duration of the sound in milliseconds.
       The module Audio::NoteLength contains useful durations for tones.
       If 0 or nil, the frequency is determined using the maximum duration
       of the given sound envelopes.
     freq - the frequency of the sound in Hz. The higher the frequency,
      the higher the pitch. If 0, no sound will be generated.
      The module Audio::Note contains useful frequencies for tones.
      freq can also be a SoundEnvelope or an array of two element arrays,
      as follows:
       freq[0] - time in ms to apply the specified frequency
       freq[1] - frequency to apply. In between, values will be interpolated
     volume - volume of the sound, from 0 through 100
      volume can also be a SoundEnvelope.
     async - specifies whether the function will return immediately
      without waiting for the sound to finish (stands for asynchronous)
     timbre - specifies the timbre of the tone; from 0.0 through 1.0
      timbre can also be a SoundEnvelope or an array of two element arrays,
      as follows:
       volume[0] - time in ms to apply the specified timbre
       volume[1] - timbre to apply. In between, values will be interpolated

    WaveData - A class for holding audio data in memory. This class
    is easy to serialize into the save file.
     intensity() - Calculates the intensity, or loudness of the data
      Returns a value from 0 through 127.
     time() - Length of the data in seconds.
     play() - Plays the wave data

    getPlayTime(filename) - Gets the length of an audio file in seconds.
      Supports WAV, MP3, and OGG files.
    getWaveData(filename) - Creates wave data from the given WAV file path.
      Returns a WaveData object or an integer: 1=not found; 2=invalid format;
      3=format not supported; 4=no sound in the data (the last error is helpful
      for diagnosing whether anything was recorded, since a recording device
      can record even if no microphone is attached.)

    beginRecord() - Starts recording.  Returns 0 if successful.
    getRecorderSample() - Gets a single sample from the microphone.
     The beginRecord function must have been called beforehand.
    stopRecord() - Stops recording without saving the recording to a file.
    endRecord(file) - Stops recording and saves the recording to a file.

### Compiler

Converts setting files to an internal format used by the game. Should not be edited.

### PokemonUtilities

Contains various utility functions.

- pbGetRegionalNumber(region, nationalSpecies) - Gets the regional Pokedex number of the national species for the specified region. Returns 0 if the species is not part of the regional Pokedex. The parameter "region" is zero-based. For example, if two regions are defined, they would each be specified as 0 and 1. The parameter "region", for example, could be the return value of the "pbGetCurrentRegion" function.
- pbGetNationalNumber(region, regionalSpecies) - Gets the national Pokedex number of the specified species and region. The parameter "region" is zero-based. For example, if two regions are defined, they would each be specified as 0 and 1. The parameter "region", for example, could be the return value of the "pbGetCurrentRegion" function.
- pbAllRegionalSpecies(region) - Gets an array of all national species within a regional Pokedex, sorted by regional Pokedex number. The number of items in the array should be the number of species in the regional Pokedex plus 1, since index 0 is considered to be empty. The parameter "region" is zero-based. For example, if two regions are defined, they would each be specified as 0 and 1. The parameter "region", for example, could be the return value of the "pbGetCurrentRegion" function.
- pbCreatePokemon - Adds six Pokemon to the Trainer's party for demonstration purposes. It is not to be used in a real game.
- pbIsWeekday(variable[,day[,day[...]]]) - Returns true if today is one of the weekdays specified as an argument for this function. Stores the current weekday's name in the variable numbered _variable_. _day_ is 0 for Sunday, 1 for Monday, etc. For example, pbIsWeekday(1,0,2) returns true if today is Sunday or Tuesday, and stores today's weekday in variable 1.
- pbAddPokemon(species,level) - Adds a Pokemon of the defined _species_ and _level_. Returns true if the Pokemon was added.
- pbLoadPokemonIcon(pokemon,back=false) - Loads a Pokemon icon.
- pbWildBattleBGM(species) - RPG::AudioFile specifying background music to be played in the next wild Pokemon battle. _species_ is not used in the default implementation, but can be used to customize the music for certain wild Pokemon species, for example Rayquaza.
- pbWildVictoryBGM(species) - RPG::AudioFile specifying background music to be played when the player wins the next wild Pokemon battle.
- pbGetWildVictoryME(trainer) - RPG::AudioFile specifying background music to be played in the next Trainer battle. _trainer_ is either a PokeBattle_Trainer or an array of two PokeBattle_Trainer objects.
- pbGetTrainerBattleBGMFromType(trainer) - RPG::AudioFile specifying background music to be played in the next Trainer battle. _trainer_ is a trainer type from PBTrainers.
- pbGetTrainerVictoryME(trainer) - RPG::AudioFile specifying background music to be played when the player wins the next Trainer battle. _trainer_ is either a PokeBattle_Trainer or an array of two PokeBattle_Trainer objects.
- pbPlayCry(species) - Plays the cry for the specified Pokemon _species_. Can also be a PokeBattle_Pokemon object.
- getRandomName - Generates a random name for a person.
- pbChangePlayer(id) - Changes the player to the one with the specified _id_ (0 through 3).
- pbTrainerName - Opens the name entry screen to set the name of the Trainer, and creates the $Trainer global variable.
- pbHasSpecies?(species) - Returns true if a Pokemon of the specified _species_ is in the player's party.
- pbGenerateEgg(species,level) - Adds an egg of the specified _species_ and _level_ to the player's party. Raises an exception if the egg can't be added.
- pbGetCurrentRegion() - Gets the ID number for the current region based on the player's current position. Returns the value of _defaultRegion_ (optional, default is -1) if no region was defined in the game's metadata. The ID numbers returned by this function depend on the town map configuration.
- pbChoosePokemon(var1,var2) - Loads the Pokemon screen, where the player can choose a Pokemon in the party. The index of the chosen Pokemon is stored in the variable numbered _var1_, and its name in the variable _var2_.
- pbNumMoves(pokemon) - Returns the number of moves that a Pokemon has.
- pbTextEntry(helptext,minlength,maxlength,variable) - Opens the text entry screen with the help text _helptext_. Stores the entered text in the variable _variable_.
- pbChooseMove(pokemon,var1,var2) - Loads a screen where the player can choose a move that a Pokemon has. The index of the chosen move is stored in the variable numbered _var1_, and its name in the variable _var2_.
- pbLoadRpgxpScene(scene) - Loads an RPGXP-compatible scene object. This function fails if the current scene is not a Scene_Map object.
- pbCommonEvent(id) - Runs a common event with the given id and waits until the common event is finished.

## Advanced Configuration Files

These configuration files are to be edited only by advanced users. The Poemon Essentials editor contains features that make editing these files largely unnecessary. This section is only meant to give further detail on the format of these files.

### PBS/metadata.txt

The file is divided into sections, and each section's title is the ID of the map whose metadata the section describes (check the middle of the status bar to find a map's ID.) The section title is enclosed by two square brackets like this: [011]

Each section can have any number of entries. The entry's name and the entry's value are separated by an equal sign (=).

The map ID 000 is reserved for global metadata not specific to any map. For the section titled [000], possible entry types are:

- Home: The point that the player is placed in when all Pokemon have fainted and no Pokemon Center was entered. This setting consists of four numbers, separated by commas, that indicate the map ID, the X and Y coordinates, and the direction to make the player face (2=down; 4=left; 6=right; 8=up; 0=retain facing). The map identified by this setting musthave an event page with the "autorun" trigger and a conditional switch "Starting Over" (normally numbered 5, but can be changed by editing the STARTING_OVER_SWITCH constant in the script section PokemonField). The event page, when run, must heal all Pokemon in the player's party (For an example, see the event for the Pokemon Center's receptionist). This setting is required.
- StorageCreator: Creator of the Pokemon Storage System. Default is "BILL". To set whether this person was seen, use the script $PokemonGlobal.seenStorageCreator=true .
- PlayerA, PlayerB, PlayerC, PlayerD: Information on the player characters in the game. This setting consists of a number of comma-separated fields, described below:
  - Field 1: Trainer type. This is an internal name of the trainer type and has one of the values defined in trainernames.txt (or under "Internal name" in the debug menu's Trainer Types option). The file Graphics/Characters/trainerXXX.png, where XXX is the ID of that trainer type, should match the defined trainer type.
  - Field 2: Character sprite, as found in Graphics/Characters.
  - Field 3: Character sprite when mounted on a bicycle.
  - Field 4: This field is no longer used.
  - Field 5: Surfing character sprite.
  - Field 6: Running character sprite.
  - Field 7: Diving character sprite.

  Other graphics include the back of the Trainer, for use in battles. The size is 128x128 and the file must be located in Graphics/Pictures. It is not specific to a player but rather to a trainer type. The trainer back has a filename of trbackXXX.png where XXX is the trainer type's ID.

  To change the player in script, use pbChangePlayer(X) where X is one of 0, 1, 2, or 3 and refers to players A, B, C, or D. The PlayerA setting is required while the other three settings are optional.

- WildBattleBGM: Default music played in wild Pokemon battles. It should be placed in the Audio/BGM/ directory.
- TrainerBattleBGM: Default music played in Trainer battles. It should be placed in the Audio/BGM/ directory.
- WildVictoryME: Default victory music played in wild Pokemon battles. It should be placed in the Audio/ME/ directory.
- TrainerVictoryME: Default victory music played in Trainer battles. It should be placed in the Audio/ME/ directory.
- SurfBGM: Background music played while Surf is used.
- BicycleBGM: Background music played while on a bicycle.
- TextSkin: Default speech text frame.

Other map IDs are specific to a map. For sections with titles other than [000], the possible entry types are:

- Outdoor: If this is set to 1 or true, this map is an outdoor map. If this is set to 0 or false, this map is an indoor map. The default is false. Day/night tinting will be enabled only for outdoor maps.
- Bicycle: If this is set to 1 or true, the bicycle can be used on this map. The default is equal to the "Outdoor" setting. The bicycle will automatically dismount whenever the player loses a battle or enters an area where bicycles are not allowed.
- HealingSpot: If this setting is present, this map is a healing spot (such as a Pokemon Center), and this setting indicates this healing spot's entrance. This setting consists of three numbers, separated by commas, that indicate the map ID and the X and Y coordinates of the entrance. When this map is entered, the location that the player goes with Teleport will be set to the point identified by this setting. This setting is not to be confused with the point that the player goes after he or she loses a battle; that point is set using a Script event command consisting of the text "pbSetPokemonCenter" (which sets it to the player's current location; see also "Home"). This setting should not be used on a map of a city or town to indicate where its Pokemon Center is located; this setting should be used only if this map is a Pokemon Center.
- BicycleAlways: If this is set to 1 or true, the bicycle will be mounted automatically and can't be dismounted on this map.
- ShowArea: If this is set to 1 or true, a window with the map's location will be displayed when it is entered. The default is false. For outdoor maps, this setting is generally set to true.
- DarkMap: If this is set to 1 or true, this map is enshrouded in darkness and a circle of light will appear around the player.
- EscapePoint: The entrance of the location associated with this map, for instance, the entrance of a cave. This setting consists of three numbers, separated by commas, that indicate the map ID and the X and Y coordinates of the entrance. If this is not set, Dig and the Escape Rope cannot be used.
- MapPosition: The position on the regional map where this map is located. This setting consists of three numbers, separated by commas, that indicate the regional map ID and the position's X and Y coordinates. The cursor will be placed on this point when the regional map is opened. Multiple instances of this setting are not possible.
- Weather: The weather in effect on this map. This setting consists of two fields, the first field is one of Rain, Storm, Snow, or Sandstorm, and the second field is the chance in 100 that the weather will occur when the map is entered. The weather will affect battles within the map.
- DiveMap: The underwater layer of this map. This setting consists of a map ID, and is required if an area contains deep patches in the water (tiles with [[Terrain Tags|terrain tag]] 5). The map must have the same width and height as this map. Coordinates of this map are associated with the same coordinates of the underwater map. Because of this, the underwater walls should have the same shape as the deep patches on the water's surface. Multiple maps cannot refer to the same underwater layer.

### PBS/encounters.txt

This text file is for placing encounter data for each map.

For each section of the file:

- The section begins with a line consisting of the ID of the map (check the middle of the status bar)
- Then there is a line containing the densities for land, caves, and water. This line is optional. If it doesn't exist, then it is set to "25,10,10".
- Then there are one or more subsections. The first line of each subsection is one of the following:
  - Land - For grass, etc. For this encounter type, Pokemon will appear only on grass.
  - Cave - For caves, etc. For this encounter type, Pokemon will appear anywhere.
  - Water - For water.
  - RockSmash - Encounters after smashing a rock
  - OldRod - Fished with Old Rod
  - GoodRod - Fished with Good Rod
  - SuperRod - Fished with Super Rod
  - HeadbuttLow - Encounters after using Headbutt on trees where there is a low chance for Pokemon to appear (rarer species)
  - HeadbuttHigh - Encounters after using Headbutt on trees where there is a high chance for Pokemon to appear (commoner species)
  - LandMorning - For grass, etc. From 6 a.m. to 12 noon.
  - LandDay - For grass, etc. From 12 noon to 8 p.m.
  - LandNight - For grass, etc. From 8 p.m. to 6 a.m.

  The rest of the subsection is a number of lines that make up the encounter data. For Land and Cave encounter types, each entry in the subsection has a species and level, separated by commas. Rarer species should be placed lower in the list. For all other encounter types, each entry must have a species, minimum level, and optionally a maximum level, separated by commas. Each species entered must be capitalized with no spaces. Note in particular the following cases:

  NIDORANmA, NIDORANfE, FARFETCHD (sic), MR_MIME, PORYGON2

Depending on the encounter type, the number of entries required varies:

- Land/Cave: 12 entries (20, 20, 10, 10, 10, 10, 5, 5, 4,4,1,1)
- Water/RockSmash: 5 entries (60,30,5,4,1)
- OldRod: 2 entries (70, 30)
- GoodRod: 3 entries (60, 20, 20)
- SuperRod: 5 entries (40, 40, 15, 4, 1)
- HeadbuttHigh/HeadbuttLow: 8 entries (30,25,20,10,5,5,4,1)

### PBS/connections.txt

Pokemon Essentials supports maps that connect to each other seamlessly. This file defines connection points of maps with others in the game. This is done by associating a point on one map's edge with points on another map's edge. Due to the nature of connected maps, maps cannot overlap. Each line of this file contains six fields, separated by commas, as defined below:

- Field 1: The first map's ID number.
- Field 2: The edge of the map to connect with the other edge. One of N, S, E, or W (or North, South, East, or West).
- Field 3: The point on the edge to associate with the other edge's point (counting from 0). Must be a positive integer.
- Field 4: The second map's ID number.
- Field 5: The edge of the map to connect with the other edge. One of N, S, E, or W (or North, South, East, or West).
- Field 6: The point on the edge to associate with the other edge's point (counting from 0). Must be a positive integer.

The restriction here is that the east edge of a map can connect only to another map's west edge, and vice versa. The same applies to south and north edges.

More formally, each line defines a point on one map relative to another point on another map. Each line is in the format A,B,C,D,E,F where:

- A, D = Two different map IDs
- B and C = X and Y coordinates of a point on map A, in tile space
- E and F = This is where the point given in B and C is located relative to map D's top left corner. E represents the X offset (positive means east and negative means west), and F represents the Y offset (positive means south and negative means north).

In the example "4,0,0,5,-26,0", the first two zeros represent the point (0,0) within map 4, and the -26 means that the point is located 26 spaces west of map 5's top left corner.

### PBS/trainernames.txt

This file stores data on each trainer type. This file is divided into lines, and each line is divided by fields separated by commas. These fields are defined below.

- Field 1: ID of the trainer type.
- Field 2: Internal name of the trainer type. This name must be different from all other internal names in this file.
- Field 3: Name of the trainer type as displayed in the game.
- Field 4: Optional. Amount of money earned from Trainers of this type. This will be multiplied by the highest level among all the Trainer's Pokemon. The default value is 30.
- Field 5: Optional. BGM (background music) file played in battles against Trainers of this type.
- Field 6: Optional. Victory BGM (background music) played in battles against Trainers of this type.
- Field 7: Optional. ME (music effect) played before the battle begins.

### PBS/trainers.txt

This text file stores data on each Trainer in the game. This file consists of one or more trainer sections. Here is the format of each trainer section.

- The first line is the internal name of the Trainer type. This line must have one of the values defined in trainernames.txt (or under "Internal name" in the debug menu's Trainer Types option).
- The second line is the Trainer's name. If more than one Trainer with the same name and Trainer type is defined in this file, then there can follow a number (from 1 through 255) to distinguish them. In that case, the name and number are separated by a comma.
- The next line is a set of fields separated by commas, as defined below:
  - Field 1: Number of Pokemon in the Trainer's party. Required.
  - Field 2-5: Up to four items owned by the Trainer. The Trainer will use these items as appropriate during the battle. Each item is an internal name as defined in items.txt; basically, it's the item's name in uppercase, with no spaces. Optional.
- After that, there are a number of lines equal to the number of Pokemon. Each line is a set of fields separated by commas, as defined below:
  - Field 1: Internal name of the Pokemon's species (see [[PBS/pokemon.txt|pokemon.txt]] or PBSpecies for internal names). Required.
  - Field 2: Level of the Pokemon. Required.
  - Field 3: Individual Value of each stat of the Pokemon. Optional. If not given, this value is 10.
  - Field 4: Internal name of the item held by the Pokemon (see [[PBS/items.txt|items.txt]] or PBItems for internal names). Optional.
  - Field 5-8: Internal names of moves known by the Pokemon (see moves.txt or PBMoves for internal names). Optional. If no moves are given, then it has the same moves as a wild Pokemon of the given level.

## Internal Structure of Item Events

Items have two event pages. The first event page has an Action Button trigger and the following structure:

    @>Conditional Branch: Script: Kernel.pbItemBall(::PBItems::POTION)
      @>Control Self Switch: A =ON
      @>
     : Else
      @>
     : Branch End
    @>

The second event page has a condition of "Self Switch A is ON", has no graphic, and is blank.

Putting a Pokemon instead of an item in the event is easy. Just use something like: "Kernel.pbAddPokemon(PBSpecies::MEW,20)" in the conditional branch.

You can also make the item event hidden. In the first event page, select "Through" under Options, and set the Graphic to "(None)". However, it should be named HiddenItem so that detectors and other mechanisms can look for it.

## Scenes in Pokemon Essentials

The various screens used in the game system follow a different pattern than RPGXP's scripts. Each screen is separated into two different classes--one to handle the logic, and another to handle the appearance. The advantage of this separation is that the screen's appearance can change without impacting its logic, and vice versa. For instance, the basic tasks of switching and giving items to Pokemon will be same regardless of the scene's appearance.

The code below is a skeleton of a scene in Pokemon Essentials. You should read the comments carefully.

    #
    # Scene class for handling appearance of the screen
    #
    class MyScene
      #
      # Processes the scene
      #
      def pbScene
       loop do
        Graphics.update
        Input.update
        pbUpdate
        if Input.trigger?(Input::B)
         # Process the B button here
         break
        end
        if Input.trigger?(Input::C)
         # Process the B button here
         break
        end
       end
      end
      #
      # Update the scene here, this is called once each frame
      #
      def pbUpdate

      end
      #
      # End the scene here
      #
      def pbEndScene
       # Fade out all sprites
       pbFadeOutAndHide(@sprites) { pbUpdate }
       # Dispose all sprites
       pbDisposeSpriteHash(@sprites)
       # Dispose the viewport
       @viewport.dispose
      end
      def pbStartScene
        # Create sprite hash
        @sprites={}
        # Allocate viewport
        @viewport=Viewport.new(0,0,Graphics.width,Graphics.height)
        @viewport.z=99999
        # Create sprites, planes, and windows using the
        # pattern below.  Refer to sprites using
        # '@sprites["sprite1"]', etc.  Be sure to use
        # '@viewport' when creating the sprite
    =begin
        @sprites["sprite1"]=Sprite.new(@viewport)
        @sprites["sprite2"]=Plane.new(@viewport)
    =end
        # Fade in all sprites
        pbFadeInAndShow(@sprites) { pbUpdate }
      end
    end
    #
    # Screen class for handling game logic
    #
    class MyScreen
     def initialize(scene)
      @scene = scene
     end
     # If pbStartScreen includes parameters, it should
     # pass the parameters to pbStartScene.
     def pbStartScreen # (param1, param2)
      @scene.pbStartScene # (param1, param2)
      # Calls pbScene currently, but can instead be made
      # to call multiple functions instead, such as pbDisplay
      # for displaying a message, pbCommand for confirming
      # a choice, pbRefresh for updating the screen, etc.
      # The important thing is that this screen
      # should not be responsible for controlling the look of
      # the scene, that's the scene's responsibility.  Generic
      # methods such as display, command, and refresh are good
      # choices for methods.  To call a method on the scene,
      # like pbDisplay, use "@scene.pbDisplay", just as it's
      # done here.
      @scene.pbScene
      @scene.pbEndScene
     end
    end
    #
    #
    #  Here is how a script would initialize MyScene:
    #
    #  pbFadeOutIn(99999){           # Optional
    #    scene=MyScene.new           # Create the scene
    #    screen=MyScreen.new(scene)  # Create the screen
    #    screen.pbStartScreen        # Initialize the scene
    #  }                             # Optional
    #