# Notes for Pokémon Essentials

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

For the latest version of this document, see: http://upokecenter.com/projects/pokestarter/notes.html

For advanced topics, see the Advanced Topics page.

## Contents

- Notes for Pokémon Essentials
  - Contents
  - Controls
  - Common Questions
    - How do I create a Pokémon Mart?
    - How can I heal the party without a Pokémon Center?
    - How can I set where the player goes after losing a battle?
    - How do I create an animated title screen?
    - I can use a hidden move even without a Pokémon able to do so!
  - Basics
    - A Note on Scripting
    - Finding Information About Tiles and Maps
  - Upgrading from previous versions
  - Problem when opening project
  - Configuration Files
    - Data Compilation
    - PBS/connections.txt
    - PBS/encounters.txt
    - PBS/metadata.txt
    - PBS/pokemon.txt
    - PBS/moves.txt
    - PBS/items.txt
      - Implementing New Items
    - PBS/trainernames.txt
    - PBS/trainers.txt
    - PBS/tm.txt
  - Town Map Generator (townmapgen.html)
    - Points of Interest
  - Animations
    - Animation Editor
      - Quick Start
      - Editor Features
    - Battle Animations
  - Game Screens
    - Title Screen
    - Intro Screen
  - Resource Specifications
    - Pokémon Graphics and Icons
      - Placement of Sprites
      - Alternate Forms
    - Item Icons
    - Mail Preview
    - Pokémon Cries
    - Battle Backgrounds
    - Trainer Graphics
    - Trainer Back
    - Fishing Animation
    - Badge Image
    - Trainer Card
    - Border
    - Backgrounds
    - Pokémon Types Image
    - Titles
  - New Window Skin Format
  - Events
    - Predefined Events
      - Trees
      - Boulders
      - Headbutt Trees
      - Cracked Rocks
      - Doors
        - Event Page 1
        - Event Page 2
    - Cut Scenes
    - Switches and Variables
      - Script-Based Switches
      - Temporary Self-Switches
      - Variables
      - Event-Specific Variables
    - Time-Sensitive Events
      - Event Page 1
      - Event Page 2
      - Event Page 3
    - Counter Events
    - Side Stairs
      - One-Tile-Deep Side Stairs
      - Side Stairs More than Two Tiles Deep
    - Random Processing
    - Event Commands
    - Saving the Game
  - Items
    - Item Events
    - Item Management
      - Checking for Items
      - Adding/Removing Items
    - Adding New Items
      - Key Items
      - Technical Machines
      - Hidden Machine
      - Regular Item
  - Pokémon Mart
  - Checking for Pokémon
  - PC
  - Wild Pokémon Battles
  - Trainers
    - Behind the Scenes
    - Double Trainer Battles
    - Nightly Trainers
      - Event Page 1
      - Event Page 2
    - Partner Trainers
    - Editing Trainers and Battles
  - Terrain Tags
  - Trainer Object
  - Adding a Pokémon
    - Adding a Pokémon Owned by Another Person
    - Modifying a Pokémon After Adding It
    - Adding an Egg
  - Removing a Pokémon
  - Graphical Effects
    - Water Reflection
    - Light Sources
    - Shadows
    - Particle Engine
    - Transitions
    - Animated Images
    - GIF Support
  - Message System
    - Using the Message System in Other Projects
  - Background Music
    - Default Background Music
    - Changing the Battle Music
    - Nightly Music
  - Localization and Translation
  - Map Making Considerations
    - Avoiding Black Regions Near Map Edge
    - Can still surf on water even with a bridge over it
    - Game freezes during movement
  - Common Mistakes
  - Debugging
    - Playtesting Functions
    - Debug Menu
  - Pokedex
  - Town Map
  - Pokegear
  - Running Shoes
  - Badges
  - Phone
  - Name Rater and Move Deleter
  - Coin Case and Game Coins
  - Dependent Events
  - Move Tutors
  - Bicycle
  - Miscellaneous
  - Suggestions for Customizing Scripts
    - Displaying a Player-Supplied Name for a Trainer
    - Shiny Wild Pokémon
    - Allowing a Player to Lose a Trainer Battle
    - No Shiny Pokémon
    - Pokémon Types
  - Controlling Events with Scripts
    - pbWait(x)
    - pbShake(power,speed,x)
    - pbFlash(color,x)
    - pbToneChangeAll(tone,duration)
    - pbMoveRoute(event,commands)
  - Configuring the Server
    - Publishing the Server
  - History
    - October 4, 2008
    - September 22, 2008
    - September 14, 2008
    - September 1, 2008
    - August 8, 2008
    - July 10, 2008
    - July 1, 2008
    - June 24, 2008
    - June 1, 2008
    - May 25, 2008
    - May 21, 2008
    - May 15, 2008
    - May 2, 2008
    - April 26, 2008
    - March 1, 2008
    - February 19, 2008
    - February 11, 2008
    - February 3, 2008
    - January 24, 2008
    - January 19, 2008
    - January 14, 2008
    - January 6, 2008
    - January 1, 2008
    - December 28, 2007
    - December 24, 2007
    - December 19, 2007
    - December 14, 2007
    - December 9, 2007
    - December 3, 2007
    - November 23, 2007
    - November 13, 2007
    - November 6, 2007
    - October 30, 2007
    - October 26, 2007
    - October 23, 2007
    - October 20, 2007
    - October 14, 2007
    - October 6, 2007
    - October 2, 2007
    - September 28, 2007
    - September 15, 2007
    - September 7, 2007

## Controls

- `Z`/`Shift` key - Dash
- Arrow keys - Move the characters
- `X`/`Esc` key - Opens the menu, cancels choices
- `C`/`Enter`/`Space` key - Confirms choices, used to talk to people
- `F5` - Uses a registered item
- `F8` - Takes a screenshot of the game. Screenshots are stored on the game folder and have names like capture000.bmp.
- `F9` - Opens the debug menu (playtests only)

Press `Ctrl+X+Down` during the title screen to delete save data.

## Common Questions

### How do I create a Pokémon Mart?

To create a Pokémon Mart, give the event a Script event command with "pbPokemonMart([X])", where X is a list of the items available for purchase there. See Pokémon Mart for details.

Check the girl event next to the PC on Test Map 2 to see an example.

### How can I create a rival and name him?

See the section "Displaying a Player-Supplied Name for a Person."

### How can I heal the party without a Pokémon Center?

The event command "Recover All: Entire Party" was redefined in Pokemon Essentials for just this purpose. It works essentially the same as in other RPG Maker XP games.

### How can I set where the player goes after losing a battle?

The point where the player goes after losing a battle depends on the last Pokémon Center visited. If no such Pokémon Center was visited, the player goes to the point defined in the metadata setting called "Home" (set it in the editor, under "Set Metadata", then "Global").

Though this approach is rarely necessary, you can also change the position within an event, by putting a Script event command consisting of the text "Kernel.pbSetPokemonCenter" within that event, which sets it to the player's current position. If you use this approach, there must be another event page on that event with an Autorun trigger and the condition "Switch '0005: Starting Over' is ON". That event page must heal all Pokémon (use the event command "Recover All: Entire Party") and set the switch '0005: Starting Over' to OFF. For an example, see the event for any Pokémon Center receptionist.

### How do I create an animated title screen?

There are a multitude of ways to create such a title screen, and the Scene_Intro class provided with Pokemon Essentials is just one example of a title screen. Please see the section Title Screen, which includes a skeleton that all custom title screens should follow. For best results, name the class "Scene_Intro". Please note that this is an advanced scripting feature.

### I can use a hidden move even without a Pokemon able to do so!

This likely happened while you were playtesting a game. This behavior is intentional. It applies only when the game is run from debug mode, that is, when the game is playtested from RPG Maker XP. It will not be the case when the game is run normally. Please see Playtesting Functions for more information.

## Basics

### A Note on 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. For general information on RPG Maker XP and RGSS, please see the Wikipedia article on it.

For advanced topics, see the Advanced Topics page.

### Finding Information About Tiles and Maps

The status bar on the bottom of RPG Maker XP contains information about the map. Here is an example of a status bar:

    011: Test Map (30 x 28)

The middle of the status bar shows the map ID (011), the name of the map (Test Map), and the width and height of the map (30 x 28)

Now move your mouse over the map. Notice how another area on the status bar changes. This shows the X and Y coordinates of the point where the mouse currently is. Example: 013, 014 means that the mouse is pointing to the tile at X coordinate 13 and Y coordinate 14.

## Upgrading from previous versions

Since September 2007, there have been many releases of Pokémon Essentials (see the history), so it may be helpful to learn how to upgrade to a new version. If you modified the scripts in Pokémon Essentials, then you should keep them separate as you replace them with the newer versions. Also, keep this in mind (posted by Flameguru):

> Simple...well, maybe not. Here I go!

> First, make a copy of your entire projects folder. Then go into your games Data Folder. Copy over all of the Map Files, MapInfos, and the Tilesets data files.

> If you used any custom Tilesets or charsets or even pictures copy them over too, same for audio.

> Then go into the merged project and make an event and make it control switches. Then copy all of your switches from your game to the merged project.

> It's kind of confusing but it only takes 20 minutes max and it's what i have been doing this whole time

## Problem when opening project

If you are using RPG Tsukuuru XP in Japanese and you cannot open the project, then open Game.rxproj in Notepad and change "RPGXP 1.02" to "RPGXP 1.01" or, if necessary "RPGXP 1.00", then save the file.

If you have problems opening the game, you may need to get the file "RGSS102E.dll", which is probably included with Pokémon Essentials. Once you have that file, put it within the game's folder. That file should be included in finished game projects if you are not sure whether users will possess that file.

## Configuration Files

Many aspects of the game can be customized by editing the .txt files contained in the PBS folder:

- items.txt - Data on items
- metadata.txt - Various settings, both global and map-specific.
- trainernames.txt - Names of the kinds of Trainers in the game.
- connections.txt - Map connection data
- encounters.txt - Data on encounters with wild Pokemon.
- trainers.txt - Data on Trainers
- townmap.txt - Data on the region map
- pokemon.txt - Data on Pokémon

For all configuration files, comment lines begin with a "#". Each file must be saved in UTF-8 encoding.

The file townmapgen.html in this distribution is designed for editing region maps.

### Data Compilation

The configuration text files will be compiled into an internal format when the game is run from RPG Maker XP or when the $DEBUG global variable is set. Normally this is done only if the text files have changed after the last run of the game. However, you can force compilation by holding CTRL as the game loads.

### PBS/connections.txt

Pokémon Essentials supports maps that connect to each other seamlessly. This file defines connection points of maps with others in the game. However, an easier way to edit map connections is to use the "Visual Editor" option on the Pokemon Essentials editor (editor.exe).

### PBS/encounters.txt

This text file is for placing encounter data for each map. However, an easier way to edit Pokémon encounters is to use the "Set Encounters" option on the Pokémon Essentials editor (editor.exe). That method is also preferred.

### PBS/metadata.txt

This text file describes metadata on each map in the game. However, an easier way to edit metadata is to use the "Set Metadata" option on the Pokémon Essentials editor (editor.exe). That method is also preferred.

### PBS/pokemon.txt

This text file describes each Pokémon in the game. The file is divided into sections, and each section's title is the Pokémon's number (in the National Pokedex order) enclosed by two square brackets like this: [120]

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

Here are the possible entry types:

- Name - Name of the Pokemon.
- InternalName - Internal name of the Pokemon.
- Kind - The kind of Pokemon.
- RegionalNumbers - The order of this Pokémon in one or more regional Pokedexes; for example, Treecko is number 1 in the Hoenn Pokedex. This is a comma-separated list of numbers. If at least one of the numbers is 0, then a species doesn't exist in at least one regional Pokedex. This setting is optional. To manipulate regional and national Pokedex numbers, use the functions pbAllRegionalSpecies, pbGetNationalNumber, and pbGetRegionalNumber in the script section PokemonUtilities. See the comments within those functions for more information.
- Pokedex - Description of the Pokémon as shown in the Pokedex.
- Color - Body color of the Pokémon. One of Red, Blue, Yellow, Green, Black, Brown, Purple, Gray, White, Pink.
- Type1 - Type 1 of the Pokémon. Required.
- Type2 - Type 2 of the Pokémon. Optional. If this is omitted, this Pokémon has a single type.
- Height - Height in meters, rounded to the nearest tenth of a meter.
- Weight - Weight in kilograms, rounded to the nearest tenth of a kilogram.
- GenderRate - Gender rate of the Pokémon. One of FemaleOneEighth, Female25Percent, Female50Percent, Female75Percent, AlwaysMale, AlwaysFemale, or Genderless.
- BaseStats - Base stats of the Pokémon for HP, Attack, Defense, Speed, Special Attack, and Special Defense. A comma-separated list of six numbers, each ranging from 0 through 255.
- Rareness - Catch rate. A higher number means the species is easier to catch. From 0 through 255.
- BaseEXP - Base experience. A higher number means more experience is gained when the species is defeated. From 0 through 255.
- Happiness - Starting happiness when caught. From 0 through 255. Normally equal to 70.
- GrowthRate - Growth rate. One of Fast, Medium, Slow, Parabolic, Erratic, or Fluctuating.
- StepsToHatch - Number of steps required before egg hatches. Should be a multiple of 256. Normally 5120.
- WildItemCommon - Item commonly found in this species in the wild. Optional.
- WildItemRare - Item rarely found in this species in the wild. Optional.
- Compatibility - Compatibility with other species for breeding purposes. A comma-separated list of two numbers. If either number is 15, this species cannot breed.
  - Meaning of each number: 1="Monster"; 2="Water1"; 3="Bug"; 4="Flying", 5="Ground", 6="Fairy", 7="Plant", 8="Humanshape", 9="Water3", 10="Mineral", 11="Indeterminate", 12="Water2", 13="Ditto", 14="Dragon"
- EffortPoints - Effort values for HP, Attack, Defense, Speed, Special Attack, and Special Defense, earned when the species is defeated. A comma-separated list of six numbers, each ranging from 0 through 3.
- Abilities - One or two abilities possible for this species.
- Moves - Third-generation moves learned by this species by gaining levels. This is a comma-separated list consisting of pairs of move-level entries.
  - Example: 1,TACKLE,4,GROWL,7,LEECHSEED,10,VINEWHIP,15,POISONPOWDER,15,SLEEPPOWDER,20,RAZORLEAF,25,SWEETSCENT,32,GROWTH,39,SYNTHESIS,46,SOLARBEAM
- Evolutions - Evolved forms of this species. This is a comma-separated list consisting of triples of entries, where the first is the evolved form, the second is the evolution type, and the third is data that depends on the evolution type. Evolution types are:

  Field 2's value | Field 3's value
  --- | ---
  Happiness | ---
  HappinessDay | ---
  HappinessNight | ---
  Level | Level
  Trade | ---
  TradeItem | Item's internal name
  Item | Item's internal name
  AttackGreater | Level
  AtkDefEqual | Level
  DefenseGreater | Level
  Silcoon | Level
  Cascoon | Level
  Ninjask | Level
  Shedinja | Level
  Beauty | Minimum Beauty factor
  ItemMale | Item's internal name
  ItemFemale | Item's internal name
  DayHoldItem | Item's internal name
  NightHoldItem | Item's internal name
  HasMove | Move's internal name
  HasInParty | Species's internal name
  LevelMale | Level
  LevelFemale | Level
  Special1 | -
  Special2 | -
  Special3 | -
  Custom1 | Number from 0 through 65535
  Custom2 | Number from 0 through 65535
  Custom3 | Number from 0 through 65535
  Custom4 | Number from 0 through 65535
  Custom5 | Number from 0 through 65535
  Custom6 | Number from 0 through 65535
  Custom7 | Number from 0 through 65535

  For the custom evolution types, the number given is used as one of the parameters to the evolution-checking function within the script section PokemonEvolution. In the function pbMiniCheckEvolution, there are areas of code such as "Add code for custom evolution type X" where you can add a custom evolution check. The function has four parameters: "pokemon", which is the Pokémon to be checked; "evonib", which is the evolution type; "level", which is the level or other parameter; and "poke", which is the species to evolve to. Here is code for an example evolution type where a Pokémon species evolves if it is raining:

      return poke if $game_screen && $game_screen.weather==1 || $game_screen.weather==2

  And here is a more complex evolution check where a Pokémon evolves only if it is well trained (that is, if its total effort values meet or exceed a certain amount):

      evtotal=0
      for i in 0...6
       evtotal+=pokemon.ev[i]
      end
      return poke if evtotal>=level

  The parameter here, marked as "level", can be 300, for example.

- EggMoves - Third-generation moves that the species can learn only as an egg. This data is valid only if the species is in its lowest evolutionary form.
  - Example: LIGHTSCREEN,SKULLBASH,SAFEGUARD,CHARM,PETALDANCE
- Machines - This setting is no longer used because Technical and Hidden Machines are now supported differently, see PBS/tm.txt and Technical Machines.
- BattlerPlayerY - Specifies the relative position of the back of the sprite (Graphics/Battlers/XXXb.png) on the battle screen. A higher number means the back sprite is placed lower on the screen.
- BattlerEnemyY - Specifies the relative position of the front side sprite (Graphics/Battlers/XXX.png) on the battle screen. A higher number means the front side sprite is placed lower on the screen.
- BattlerAltitude - Specifies how far from the ground the front sprite is placed, that is, this value will be higher than 0 if the sprite has the appearance of being suspended in the air. A higher number means the front sprite is placed further from the ground.

For information on Pokémon graphics, see Pokémon Graphics and Icons.

### PBS/moves.txt

This file stores data on each move in the game. It will be converted to a runtime format when you run a playtest of the game from RPG Maker XP. Each line contains data on one move and is divided into fields separated by commas:

- Field 1: ID of the move.
- Field 2: Name used internally, as in scripts, to refer to the move.
- Field 3: Name of the move as displayed in the game.
- Field 4: Function code of the move. A hexadecimal value. See the list of moves for the meaning of each function code. In that page, the function code for that move is located before the description of each move's effect.
- Field 5: Base damage.
- Field 6: Type.
- Field 7: Move category, either Physical, Special, or Status. As of the January 19 release, the game will use this category instead of type to determine whether an attack is physical or special. Set to Status if the base damage is 0.
- Field 8: Accuracy of the move, up to 100. Set to 0 if the move has no opponent as a target.
- Field 9: Total PP.
- Field 10: Additional effect chance, up to 100. The meaning of the additional effect depends on the move's function code (field 4).
- Field 11: Target. A hexadecimal value.
  - 00 - Single Pokémon other than the user
  - 01 - No target
  - 04 - Opposing Pokémon selected at random
  - 08 - All opposing Pokémon
  - 10 - User
  - 20 - All Pokémon other than the user
  - 40 - Opposing Pokémon's side
- Field 12: Priority. Normally, this value is 0, but set to a positive number to make it strike earlier than normal attacks, or to a negative number to make it strike later. For moves like Quick Attack, this should equal 1.
- Field 13: Flags:
  - a: This is a direct attack, where the attacker makes direct contact with the opponent.
  - b: The opponent can use Protect or Detect to protect itself from this move.
  - c: The opponent can use Magic Coat to redirect the effect of this move. Use this flag if the move deals no damage but causes a negative effect on an opponent.
  - d: The opponent can use Snatch to steal the effect of this move. Use this flag for most moves that target the user. (Flags c and d are mutually exclusive.)
  - e: The game does an accuracy check for this move, the accuracy field should not be 0.
  - f: If the user holds a King's Rock, the opponent may flinch after the attacker uses this attack.
- Field 14: Contest type, either Cool, Beauty, Cute, Smart, or Tough.
- Field 15: Description of the move.

### PBS/items.txt

This file stores data on each item in the game. It will be converted to a runtime format when you run a playtest of the game from RPG Maker XP. For examples, see Adding New Items. Each line contains data on one item and is divided into fields separated by commas:

- Field 1: ID of the item. To define an item, assign it a unique ID number. The ID 0 is reserved for internal use. Also, item IDs cannot be negative. (Although it's customary to make the item ID three digits long, in reality the number of possible items is unlimited.)
- Field 2: Name used internally, as in scripts, to refer to the item.
- Field 3: Name of the item as displayed in the game.
- Field 4: Pocket of the Bag where this item is placed:
  - 1: Items
  - 2: PokeBalls
  - 3: TMs and HMs
  - 4: Berries
  - 5: Key Items
- Field 5: Purchase price of the item. Items can be sold for half their purchase price. Items with a purchase price of 0 cannot be sold and should not appear in shops. This should be true of all Key Items.
- Field 6: Description of the item. If the description contains commas or quotation marks it must be contained within quotation marks and the quotation marks within the description must be preceded by the "\" symbol. For consistency, though, putting all descriptions in quotation marks is preferred.
- Field 7: Usability of the item outside of battle. This setting can have one of these values:
  - 0: This item can't be used outside of battle.
  - 1: This item can be used on a Pokémon. When this item is chosen, a screen appears allowing the player to choose a Pokémon. This setting does not apply to TMs and HMs.
  - 2: Other items that can be used outside of battle.
  - 3: This item is a technical machine.
  - 4: This item is a hidden machine.
- Field 8: Usability of the item within a battle. This setting can have one of these values:
  - 0: This item can't be used in battle.
  - 1: This item can be used on a Pokémon. When this item is chosen, a screen appears allowing the player to choose a Pokemon.
  - 2: This item is a Ball for catching Pokémon or can be used directly from the Bag screen.
  - 3: Same as 1, but the item is reusable.
- Field 9: For special kinds of items.
  - 0: This item has no special type.
  - 1: This item is a Mail.
  - 2: This item is a Mail, where an image of the holder will appear on the mail.
  - 3: This item is a Snag Ball.
  - 4: This item causes a wild Pokemon battle to end when used.

Also, an icon of the item must be placed in the Graphics/Icons folder with a filename of itemXXX.png, where XXX is the ID number of the item, left-padded with zeros. The icon's dimensions must be 48x48.

Comment lines begin with "#". This file, however, doesn't allow comments at the end of the line.

#### Implementing New Items

The following describes an advanced scripting feature.

New items are implemented by registering item handlers with the game system. Fields 7 and 8 of items.txt give the moments where an item can be used. These fields determine which handlers an item should implement. There are five different item handlers for an item, corresponding to the moments where items are used:

- ItemHandlers.addUseFromBag(item,proc) - Registers the item handler _proc_ for an item that can be used directly from the Bag, such as a bicycle, Repel, or the Town Map. Parameters:
  - _item_ - item to be used
- ItemHandlers.addUseInField(item,proc) - Registers the item handler _proc_ for an item that can be used on the field by pressing F5. Parameters:
  - _item_ - item to be used
- ItemHandlers.addUseOnPokemon(item,proc) - Registers the item handler _proc_ for an item that can be used on a Pokemon. Parameters:
  - _item_ - item to be used
  - _pokemon_ - Pokémon the item will be used on (type: PokeBattle_Pokemon)
  - _scene_ - Pokémon selection screen (type: PokemonScreen). Often only used to display a message, and is often used like this: `scene.pbDisplay(_INTL("Message."))`
  The item handler returns true if the item was used, and false otherwise.
- ItemHandlers.addUseOnPokemon(item,proc) - Registers the item handler _proc_ for an item that can be used on a Pokemon while in battle. Examples include Potion, Revive, and Full Heal. Parameters:
  - _item_ - item to be used
  - _pokemon_ - Pokémon the item will be used on (type: PokeBattle_Pokemon)
  - _battler_ - Battler object, if _pokemon_ is one of the active Pokémon (type: PokeBattle_Battler); nil otherwise
  - _scene_ - Pokémon selection screen (type: PokemonScreen).
  The item handler returns true if the item was used, and false otherwise.
- ItemHandlers.addUseOnBattler(item,proc) - Registers the item handler _proc_ for an item that can be used on a battler while in battle. Examples include X Attack and Guard Spec. Parameters:
  - _item_ - item to be used
  - _battler_ - Battler the item will be used on (type: PokeBattle_Battler)
  - _scene_ - Bag screen (type: PokemonBagScreen).
  The item handler returns true if the item was used, and false otherwise.

The following gives some guidance on the item handlers that an item should implement depending on its usability.

Field 7 (usability outside of battle)

- If Field 7 is 1, the function ItemHandlers.addUseOnPokemon should be called for that item.
- If Field 7 is 2, the function ItemHandlers.addUseFromBag should be called for that item. If the item is a key item, it should also implement ItemHandlers.addUseInField.

Field 8 (usability in battle)

- If Field 8 is 1 or 3, the function ItemHandlers.addBattleUseOnPokemon should be called for that item.
- If Field 8 is 2, the function ItemHandlers.addBattleUseOnBattler should be called for that item.

The following shows some examples of item handlers for a hypothetical item called "Cake", which restores 30 HP to a Pokémon. For completeness, it implements all five item handlers.

    # Handlers implemented
    ItemHandlers.addUseFromBag(
     PBItems::CAKE,
     proc{|item,pokemon,scene|
      pbHPItem(pokemon,30,scene)
     }
    )
    ItemHandlers.addBattleUseOnBattler(
     PBItems::CAKE,
     proc{|item,pokemon,battler,scene|
      pbBattleHPItem(pokemon,battler,30,scene)
     }
    )
    # Handlers not implemented
    ItemHandlers.addUseFromBag(
     PBItems::CAKE,
     proc{|item| 0; }
    )
    ItemHandlers.addUseInField(
     PBItems::CAKE,
     proc{|item|
      Kernel.pbMessage(_INTL("Can't use that here."))
     }
    )
    ItemHandlers.addBattleUseOnPokemon(
     PBItems::CAKE,
     proc{|item,battler,scene| false; }
    )

### PBS/trainernames.txt

This file stores data on each trainer type. However, an easier way to edit trainer types is to use the "Trainer Types" option on the Pokémon Essentials editor (editor.exe). That method is also preferred.

### PBS/trainers.txt

This text file stores data on each Trainer in the game. However, an easier way to edit trainers and trainer battles is to use the "Edit Trainers" option on the Pokémon Essentials editor (editor.exe). That method is also preferred.

### PBS/tm.txt

Very simple file. It consists of a list of moves and the species that can learn each move. Used in TMs/HMs.

## Town Map Generator (townmapgen.html)

The Town Map editor is designed to make editing the region map easier.

When the editor is started, it loads the file at Graphics/Pictures/Map.png. You can replace that file with the map of your game's region, keeping in mind that the map should be drawn in terms of 16x16 tiles. The example map in the distribution is the map of Hoenn; and filling the map will give you a good idea on how the Town Map Editor works.

Start by clicking any point on the map; for instance a city. Once you have done so, fill in details about the point:

- Name: Name described by this point.
- Point of Interest: Name of a point of interest described by this point.
- Healing Spot: This field specifies the map ID and the X and Y coordinates of the entrance of a healing spot, such as a Pokémon Center, separated by commas. This location is where the player will travel to when Fly is used and if the map indicated by the map ID was visited before. Generally set only if the location is a city or town.
- Switch: Number of a switch (in RPG Maker XP). If this is set, the point will not be shown until the switch is on. This field is generally set for locations outside of the main storyline, where special Pokémon can be found.

After completing the fields, click Save. You will notice that the point is added to the text below the Save button. This text is meant to be pasted to townmap.txt after you are done with the editor. You can put the text in a new or existing section of the file. (Sections begin with a number within brackets, for example: [1])

The next time you use the map editor, you can paste a section from townmap.txt (without the section heading) onto the big text box and click Load to resume editing.

### Points of Interest

The "Point of Interest" setting is meant to describe an entrance to a cave, the location of an important zone (preferably one with RPGXP maps of its own), or anything interesting within the main location described by the point. Examples:

    0,0,"FUCHSIA CITY","SAFARI ZONE",,
    2,2,"ROUTE 111","DESERT",,
    4,3,"ROUTE 220","LOST TOWER",,
    6,6,"LAVENDER CITY","POKeMON TOWER",,
    8,8,"EVER GRANDE CITY","VICTORY ROAD",,

However, that setting should not be used to name a building within a city or town, as in these cases:

    0,0,"SAFFRON CITY","SILPH CO.",,
    5,0,"RUSTBORO CITY","DEVON CORPORATION",,
    3,3,"VEILSTONE CITY","GAME CORNER",,

In most cases, however, the Point of Interest setting is left blank, since the number of points of interest is generally small within a game.

## Animations

The battle system allows the animations to be customized. Currently, almost all of the animations are of the move Tackle. There are two ways to add move animations-- using RPG Maker XP or using the in-game Animation Editor.

### Animation Editor

The Animation Editor is designed for creating Pokémon battle animations. A separate editor is necessary because the animations for many moves require the attacker and the target to be manipulated.

The Animation Editor is located on the game's Debug menu.

#### Quick Start

The controls at the bottom left of the window are important ones when working with the editor. The "Frame:" control changes the number of frames; "Set Animation Bitmap" changes the bitmap used for animations; "Frames:X" lets you set the number of frames; and you can rename or add more animations by clicking List of Animations.

The animation palette is located just above the name window. Click the left and right arrows to scroll the palette, and click on an object in the palette to select it. Clicking on the canvas will then place the object on it as a cell. To select an existing cell, click on it. You can then move it, press L to lock it, preventing movement, or press P to open its properties.

Animations will be saved in the file Data/PkmnAnimations.rxdata.

#### Editor Features

Here are descriptions of the editor's controls:

- Frame: Changes the current frame.
- Set Animation Bitmap: Sets the bitmap file that contains the objects used in the animation.
- Frames: Shows the number of frames. Click to change the number of frames.
- Name: Shows the animation's name.
- List of Animations: Shows the list of animations. Here you can select an animation. Press F5 to rename an animation, or change the number of animations by modifying the number under "Animations" and clicking "Resize Animation List". Press ESC to close.
- Paste Last: Copies the last frame to this frame.
- Copy Frames: Copies a sequence of frames elsewhere.
  - First Frame: First frame in the sequence of frames to copy. The first frame is numbered 0.
  - Last Frame: Last frame in the sequence of frames to copy.
  - Copy to: Makes this frame equal to (First Frame), makes the next frame equal to (First Frame + 1), and so on.
- Clear Frames: Deletes all cells in each frame except locked cells.
  - First Frame: First frame in the sequence of frames to clear.
  - Last Frame: Last frame in the sequence of frames to clear.
- Tweening: Interpolates the cells between one frame and another frame for a smoother animation.
  - Starting Frame: Frame containing the starting positions of cells to interpolate.
  - Ending Frame: Frame containing the ending positions of cells to interpolate.
  - First Cel: First cell in the sequence of cells to interpolate.
  - Last Cel: Last cell in the sequence of cells to interpolate.
  - Pattern: If checked, the pattern of each cell will be interpolated.
  - Position/Zoom/Angle: If checked, the position of each cell will be interpolated.
  - Opacity/Blending: If checked, the transparency of each cell will be interpolated.
- Cell Batch: Modifies multiple cells at once.
  - First Frame: First frame in the sequence of frames to modify.
  - Last Frame: Last frame in the sequence of frames to modify.
  - First Cel: First cell in the sequence of cells to modify within the specified frames.
  - Last Cel: Last cell in the sequence of cells to modify within the specified frames.
  - Click the checkboxes on the right side to specify which parameters to modify on the selected cells.
- Entire Slide: Shifts the position of all cells in one or more frames.
  - First Frame: First frame in the sequence of frames to shift.
  - Last Frame: Last frame in the sequence of frames to shift.
  - X-Axis Movement: A negative value means shift left, a positive value means shift right.
  - Y-Axis Movement: A negative value means shift up, a positive value means shift down.
- Sounds: Set the sounds to play for this animation. In this screen, choose a sound to modify its filename, volume, and pitch, or choose "Add New Sound" to add a new one. To change the sound's frame, select a frame and click "Set Frame". Finally, to delete a sound, select it and choose "Delete Sound Effect".
- Play: Plays this animation.
- Help: View help.

The animation palette is located just above the name window. Click the left and right arrows to scroll the palette, and click on an object in the palette to select it. Clicking on the canvas will then place the object on it as a cell.

To select a cell, simply click on it. Holding Alt will enable finer selection of cels on the screen. If a frame is selected, the following actions are available:

- L: Lock or unlock a cell. Locking a cell prevents it from being moved or deleted.
- Delete: Delete
- E: Rotate left.
- R: Rotate right.
- P: Open properties screen.
- Right click: Open menu.
- Arrow keys: Move cell 8 pixels (hold Alt for 2 pixels).
- + (numeric pad): Zoom in
- - (numeric pad): Zoom out

### Battle Animations

There are several rules to keep in mind when making battle animations in RPG Maker XP.

- Battle animations for moves must be named Move:XXX, where XXX is the internal name of the move as defined in PBS/moves.txt. For instance, the animation for Fire Punch will be named Move:FIREPUNCH.
- When creating animations that involve an attacker and an opponent, the point at (-160,80) is considered to be the attacker, and the point at (160,-80) is considered to be the opponent. The animation must have a "position" of "Screen." As a guide, you can use the file battlers.png (under "[ED] Battler..."). (Moves that the user uses on itself, as well as common animations [see below], should not use this technique.)
- The next time you run the game from RPG Maker XP, the game will convert any animations here to a different format so that they will display properly in the battle system.
- Certain animations are commonly used and have special names for them:
  - Common:Shiny - When a shiny (different-colored) Pokémon enters battle.
  - Common:StatUp - When a Pokémon's stat was raised.
  - Common:StatDown - When a Pokémon's stat was lowered.
  - Common:Frozen - When a Pokémon is frozen.
  - Common:Burn - When a Pokémon is burned.
  - Common:Sleep - When a Pokémon is asleep.
  - Common:Paralysis - When a Pokémon is paralyzed.
  - Common:Confusion - When a Pokémon is confused.

## Game Screens

### Title Screen

The game's title screen can be changed by replacing the files Pic_1.png , Pic_2.png , and Start.png . Each of these files is found in the directory Graphics/Titles. The files can be animated GIF files (with the same filename and extension).

Essentially, though, the title screen just calls the game-loading screen. Here is an example of a very simple title scene:

     class Scene_Xxxx
       def main
         # Prepare scene
         Graphics.transition
         while $scene != self
            Graphics.update
            Input.update
            update
         end
         Graphics.freeze
         # Dispose sprites
       end
       def update
         if Input.trigger?(Input::C)
           # Close scene here
           sscene=PokemonLoadScene.new
           sscreen=PokemonLoad.new(sscene)
           sscreen.pbStartLoadScreen # Will change scene if appropriate
         end
       end
     end

The title's music can be changed with the "Title BGM" setting in the System tab of the database.

### Intro Screen

The introduction screen when the game starts is found in the map titled Intro. This map should be where the starting position is placed. It also contains an event with an autorun trigger. The event may appear long, but that's only because it's a representative appearance of the intro screen only. The most fundamental introduction event looks like the following:

    @>Comment: Initializes the player character.
    @>Script: pbChangePlayer(0)
    @>Comment: opens the name entry screen and initializes the
     :         : Trainer object
    @>Script: pbTrainerName
    @>Comment: Displays the player's name
    @>Text: Hello, \PN.
    @>Comment: Stops autorun event
    @>Control Self Switch: A =ON
    @>Comment: Transfers player to start position
    @>Transfer Player:[011: Test Map], (009, 009), Down
    @>

Of course, it can be expanded to include multiple player characters and to show the character on screen:

    @>Text: Are you a boy or a girl?
    @>Show Choices: BOY, GIRL
     : When [BOY]
      @>Comment: initializes player 0 (PlayerA)
      @>Script: pbChangePlayer(0)
      @>
     : When [GIRL]
      @>Comment: initializes player 1 (PlayerB)
      @>Script: pbChangePlayer(1)
      @>
     : Branch End
    @>Comment: Shows the character's picture
    @>Script: pbShowPicture(2,pbGetPlayerGraphic,
     :      : 1,230,160)
    @>Text: Choose a name.
    @>Comment: opens the name entry screen and initializes the
     :         : Trainer object
    @>Script: pbTrainerName
    @>Comment: Displays the player's name
    @>Text: Hello, \PN.
    @>Comment: erases the character's picture
    @>Erase Picture: 2
    @>Comment: Stops autorun event
    @>Control Self Switch: A =ON
    @>Comment: Transfers player to start position
    @>Transfer Player:[011: Test Map], (009, 009), Down
    @>

In the Pokémon Essentials editor, under "GLOBAL" within "Set Metadata", you can enter data for each player character in the settings PlayerA, PlayerB, etc.

## Resource Specifications

A good program for graphics editing is Paint.NET. A good program for audio recording is Audacity. Both programs are open-source and available free of charge.

### Pokémon Graphics and Icons

There should be five different image files for each Pokémon (XXX is the Pokémon's number):

- Graphics/Battlers/XXX.png - Front of the Pokémon. Measures 128x128 pixels, perhaps also larger.
- Graphics/Battlers/XXXs.png - Shiny (different-colored) front of the Pokémon. Measures 128x128 pixels, perhaps also larger.
- Graphics/Battlers/XXXb.png - Back of the Pokémon. Measures 128x128 pixels, perhaps also larger.
- Graphics/Battlers/XXXsb.png - Shiny (different-colored) back of the Pokémon. Measures 128x128 pixels, perhaps also larger.
- Graphics/Icons/iconXXX.png - Icon of the Pokémon. This is a two-frame animation measuring 128x64 pixels. Each of its frames has a size of 64x64 pixels.

#### Placement of Sprites

To ensure optimal placement of Pokémon sprites in battle, you should edit the PBS/pokemon.txt file for these three parameters for each Pokémon species:

- BattlerPlayerY - Specifies the relative position of the back of the sprite (Graphics/Battlers/XXXb.png) on the battle screen. A higher number means the back sprite is placed lower on the screen.
- BattlerEnemyY - Specifies the relative position of the front side sprite (Graphics/Battlers/XXX.png) on the battle screen. A higher number means the front side sprite is placed lower on the screen.
- BattlerAltitude - Specifies how far from the ground the front sprite is placed, that is, this value will be higher than 0 if the sprite has the appearance of being suspended in the air. A higher number means the front sprite is placed further from the ground.

#### Alternate Forms

For Pokémon named SPINDA, extra spots are added to the graphic depending on the Pokemon.

For the Pokémon named UNOWN, there should be one set of files for each letter (from A to Z and continuing with "?" and "!". For example the letter A would have filenames of Graphics/Battlers/201_00.png, Graphics/Battlers/201s_00.png, and so on; and the letter B would have filenames of Graphics/Battlers/201_01.png, Graphics/Battlers/201s_01.png, and so on. This is not necessary for the Pokémon's icon (Graphics/Icons/icon201.png). Change the number 201 according to the actual national number for the Pokémon named UNOWN in this case.

Many other well-known species have alternate forms that are not implemented in Pokémon Essentials. To give special forms to these and other species, edit the methods "pbLoadPokemonBitmapSpecies" and "pbPokemonIconFile" in the script section PokemonUtilities. It may also be necessary to add methods to the script section PokeBattle_Pokemon that calculate which form to display depending on the Pokémon's internal data (see PokeBattle_Pokemon in the advanced notes). This, however, is an advanced scripting feature.

### Item Icons

Each item's icon has a filename of Graphics/Icons/itemXXX.png where XXX is the item's ID. Measures 48x48 pixels.

### Mail Preview

Each mail has a filename of Graphics/Pictures/itemXXX.png where XXX is the item's ID. Measures 320x240 pixels.

### Pokémon Cries

The cry of each Pokémon has a filename of Audio/SE/XXXCry.wav where XXX is the Pokémon's ID.

### Battle Backgrounds

Each battle background consists of three parts: the background, a base for the player's Pokemon, and a base for the enemy Pokémon. These files are given below (XXX stands for an arbitrary identifier):

- Graphics/Pictures/battlebgXXX.png - Any size.
- Graphics/Pictures/playerbaseXXX.png - Measures 256x32 pixels and has the appearance of a semi-ellipse.
- Graphics/Pictures/enemybaseXXX.png - Measures 256x64 pixels and has the appearance of an ellipse.

To change the battle background for the next battle, use the script:

    $PokemonGlobal.nextBattleBack="XXX"

where XXX is an arbitrary identifier. Here is an example. Suppose you have created the following three files as a custom battle background:

- Graphics/Pictures/battlebgDarkness.png
- Graphics/Pictures/playerbaseDarkness.png
- Graphics/Pictures/enemybaseDarkness.png

Note that all three files end in the word "Darkness". To access this background in a script, you would use the following Script event command:

    $PokemonGlobal.nextBattleBack="Darkness"

All three parts of the battle background can be animated image files, including animated GIF files (with a PNG extension).

### Trainer Graphics

Each trainer type's graphic has a filename of Graphics/Characters/trainerXXX.png, where XXX is the ID of that trainer type. Measures 128x128 pixels, perhaps also larger. Trainers that appear in the Battle Tower should also have a RPGXP character image file named Graphics/Characters/trcharXXX.png, where XXX is the ID of that trainer type.

### Trainer Back

To define the back of a Trainer, for use in battles, create a graphic file with a size of 128x128 and the file must be located in Graphics/Pictures. This graphic file 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. Alternatively, the file can have a size of 512x128, where each 128x128 block is a single frame of a 4-frame animation. See the example at Graphics/Pictures/trback000.png.

### Fishing Animation

The fishing animation is a five-frame animation. It resembles the 16-frame character sprites, but only the first five frames are used. Its filename must be Graphics/Characters/fishingXXX.png, where XXX is a trainer type's ID. Example: fishing000.png. See below for the layout of the frames.

    Frame1   Frame2   Frame3   Frame4

    Frame5   ------   ------   ------

    ------   ------   ------   ------

    ------   ------   ------   ------

### Badge Image

The image for all Badges is located at Graphics/Pictures/badges.png. This image is 256 pixels in width and contains X rows of eight badges, where X is the number of regions in the game. Each badge is 32x32 pixels in size. For example, if the game has two regions, the image's height would be 64 pixels (2 * 32); the first row would have badges for the first region (region 0) and the second row would have badges for the second region (region 1). See Badges for more information.

### Trainer Card

The Trainer Card's image is found in Graphics/Pictures/trcard.png, and the background is found in Graphics/Pictures/trcardbg.png. Measures 320x240 pixels.

### Border

The border used in some screen size modes is found in Graphics/Pictures/border.png. Measures 640x480 pixels.

### Backgrounds

The various screens use the following backgrounds (measuring 320x240 pixels or smaller):

- Pokémon screen - Graphics/Pictures/pokeselbg.png
- Pokedex screen - Graphics/Pictures/pokedexbg.png
- Phone screen - Graphics/Pictures/phonebg.png
- Name entry screen - Graphics/Pictures/entrybg.png
- Evolution screen - Graphics/Pictures/evobg.png
- Trading progress screen - Graphics/Pictures/tradebg.png
- Game loading screen - Graphics/Pictures/loadbg.png
- Log In screen - Graphics/Pictures/loginbg.png
- Register screen - Graphics/Pictures/registerbg.png

The backgrounds can have any size, and animated image files, including animated GIF files, can be used (even if they have an extension of 'gif').

### Pokémon Types Image

Images for all Pokémon types is found in Graphics/Pictures/types.png. They should appear in the same order as in the script section PBTypes (see Pokémon Types.)

### Titles

The game's title screen can be changed by replacing the files Pic_1.png , Pic_2.png , and Start.png . Each of these files is found in the directory Graphics/Titles.

## New Window Skin Format

Pokémon Essentials supports a new window skin format that allows different-sized window borders and different placement of text than usual. It involves a PNG file and a text file. The PNG file shows the look of a window at its minimum possible size. The corners and sides of the image will be adjusted to match the size of the window. An optional TXT file with the same name describes the sizes of the sides, corners, and borders. If the file is not given, it is assumed that the center 16x16 square is the center of the window and the window's sides and corners make up the rest of the image.

## Events

Pokémon Essentials comes with many predefined events for your use, and also contains many new ways to define special kinds of events that otherwise wouldn't be possible with RPG Maker XP alone. This section will discuss the game's predefined events, the switches and variables used in the game, and details on implementing Time-Sensitive Events. The rest of the section discusses Event Commands and a way to save the game via an event.

### Predefined Events

The following are definitions of events used in Pokémon games. These events include trees, boulders, Headbutt trees, cracked rocks, and doors. Other common kinds of events are items and Trainers.

#### Trees

Events that can be cut using the hidden move Cut are named Tree, have an Action Button trigger, and have the following structure:

    Conditional Branch:  Script:  Kernel.pbCut
     Script: pbEraseThisEvent
    Branch End

An animation for the tree being cut is possible by modifying the event just before "Script: pbEraseThisEvent".

#### Boulders

Events that can be pushed using Strength are named Boulder, have a Player Touch Trigger, and consist of the single event command "Script: pbPushThisBoulder".

#### Headbutt Trees

Trees that a Pokémon can use Headbutt on are named HeadbuttTree, have an Action Button Trigger, and consist of the single event command "Script: pbHeadbutt".

#### Cracked Rocks

Rocks that can be smashed are named Rock, have an Action Button trigger, and have the following structure.

    Conditional Branch:  Script:  Kernel.pbRockSmash
     Script: pbEraseThisEvent
     Script: pbRockSmashRandomEncounter
    Branch End

#### Doors

Doors have two event pages, with the following structure:

##### Event Page 1

No conditions, Player Touch trigger

The graphic should be of a closed door.

    @>Set Move Route: This event (Ignore If Can't Move)
     :              : $>SE: 'Entering Door', 80, 100
     :              : $>Wait: 2 frame(s)
     :              : $>Turn Right
     :              : $>Wait: 2 frame(s)
     :              : $>Turn Up
     :              : $>Wait: 2 frame(s)
     :              : $>Turn Left
     :              : $>Wait: 2 frame(s)
    @>Wait for Move's Completion
    @>Set Move Route: Player (Ignore If Can't Move)
     :              : $>Through ON
     :              : $>Move Up
     :              : $>Through OFF
    @>Wait for Move's Completion
    			@>Change Screen Color Tone: (-255,-255,-255,0), @6
    @>Wait: 6 frame(s)
    @>Transfer Player:[001: Pokémon Center], (004, 007), Up, No Fade
    @>Change Screen Color Tone: (0,0,0,0), @6
    @>

The emphasized event commands are also useful for normal player transfers that don't involve doors.

##### Event Page 2

Condition 'Switch s:tsOff?("A") is ON', Autorun trigger

The graphic should be of a closed door.

    Conditional Branch:  Script:  get_character(0).onEvent?
      Set Move Route: This event (Ignore If Can't Move)
      :             : $>Turn Left
      Set Move Route: Player (Ignore If Can't Move)
      :             : $>Move Down
      Wait for Move's Completion
      Set Move Route: This event (Ignore If Can't Move)
      :             : $>Wait: 2 frame(s)
      :             : $>Turn Up
      :             : $>Wait: 2 frame(s)
      :             : $>Turn Right
      :             : $>Wait: 2 frame(s)
      :             : $>Turn Down
      :             : $>Wait: 2 frame(s)
      Wait for Move's Completion
    Branch End
    Script: setTempSwitchOn("A")

This event page checks whether a player is on the door, and if so, moves the player one space down and closes the door. Therefore, event commands that cause the player to exit a building should have their destination placed on the door and not next to it.

The door character image file should be arranged so that the first row shows a closed door, the second row an open door, the third row a partially closed door, and the fourth row a partially open door.

### Cut Scenes

Pokémon Essentials contains a way to skip or cancel certain events designated as "cut scenes" by pressing F5. This feature can be useful if a player wants to skip the dialogue and advance the story.

To make an event a cut scene, add to the event a Comment event command consisting of the text "Cut Scene". When the player presses F5, the event's self switch A will be set to ON. Therefore, the event should have another event page with the Autorun trigger and the condition "Self Switch A is ON". The event page should have the effect of canceling the effect of the cut scene, perhaps by moving the player directly to the next destination or doing any other necessary cleanup.

### Switches and Variables

#### Script-Based Switches

The event system in Pokémon Essentials supports script-based switches, where an arbitrary script is evaluated. The switch is true as long as the condition on the switch's name remains true. Script-based switches are distinguished from regular switches using the prefix "s:". Be aware that due to the size limit on a switch's name, it may be necessary to use this kind of switch to call other methods that return a true or false value. Methods on script-based switches are called within the context of the Game_Event class.

#### Temporary Self-Switches

Each event in the game comes with a set of temporary self switches. This set is cleared whenever a map is entered. To check whether a temporary self switch is on, use a switch named "s:tsOn?(X)" where X is one of "A", "B", "C", or "D". To check whether it's off, use a switch named s:tsOff?(X). To turn a temporary self switch on or off, use a script like:

    get_character(0).setTempSwitchOn("A")

or:

    get_character(0).setTempSwitchOff("A")

Temporary self switches are currently used in doors, but they have other uses where stand-alone stateful events are desired.

#### Variables

Variables 1 through 25 are reserved for internal use by the game system. They are defined as follows:

- 1: Temp Pokémon Choice
- 2: Temp Move Choice
- 3: Temp Pokémon Name
- 4: Temp Move Name
- 5: Temp Text Entry

#### Event-Specific Variables

Each event in the game comes with its own variable, which can be used for any purpose. To retrieve a variable, call the script function "getVariable", and to set the value of the current event's variable, call the script function "setVariable(X)", where X is the value to set to the variable. To check the variable's value in an event page's condition, use the event function "variable" to help you. For example, to check whether the event's variable is equal to 1, you would use a switch named: "s:variable==1".

### Time-Sensitive Events

Thanks to temporary self-switches and event-specific variables, it is possible to implement events that are active only once each day. For an example, see the event on the northeast side of the Pokémon Center. Here is the basic structure of such events:

#### Event Page 1

No conditions, any trigger

    -- Do something here
    Script:  pbSetEventTime

The script pbSetEventTime sets the event's self switch A to ON and sets the event's variable to the current time, so that later the game can check whether the event "expires" and returns to normal. pbSetEventTime can also be used to set other events' variables to the current time. For example, pbSetEventTime(2) sets this event and the event numbered 2 on this map.

#### Event Page 2

Condition "Self Switch A is ON", any trigger

    -- Do something here

This event page is used in cases when the event is currently "inactive"; for example, in the case of a tree that grows berries every day, there could be a message here that the tree is empty.

#### Event Page 3

Condition "Self Switch A is ON", Condition 'Switch s:expired?&&tsOff?("A") is ON', Autorun trigger

    Control Self Switch: A =OFF
    Script:  setTempSwitchOn("A")

This event page checks whether the event has expired and becomes active again.

### Counter Events

A counter event is one that is triggered when the player is a number of spaces away from the event's visibility range, even if there is no counter tile separating them.

To make one, name it Counter(X), where X is the maximum distance for the event to trigger, and use the Event Touch trigger.

### Side Stairs

Side stairs (stairs on the side of a cliff) were introduced in Pokémon Diamond and Pearl. To make such an event, consider the following diagram.

    ......||------
    ......||------
    ......|A------
    ......BA------
    ......B|------
    ......||------

In this diagram,"." represents flat ground; "-" represents rocky ground; and "|" represents cliffs. The letters A and B represent side stair events. Use the following event for the A events.

- Trigger: Player Touch
- Condition: None

    @>Set Move Route: Player
     :              : $>Move Lower Left
     :              : $>Move Left

And use the following event for the B events.

- Trigger: Player Touch
- Condition: None

    @>Set Move Route: Player
     :              : $>Move Upper Right
     :              : $>Move Right

#### One-Tile-Deep Side Stairs

Example:

    ......|------
    ......|------
    ......A------
    ......A------
    ......|------
    ......|------

Use the following event for the tiles labeled A.

    @>Conditional Branch: Player is facing Left
      @> Set Move Route: Player
        :              : $>Move Lower Left
      @>
     : Else
      @> Set Move Route: Player
        :              : $>Move Upper Right
      @>

#### Side Stairs More than Two Tiles Deep

Example:

    ......||A----
    ......||A----
    ......A|A----
    ......A||----
    ......A||----
    ......|||----

Use the following event for the tiles labeled A.

    @>Conditional Branch: Player is facing Left
      @> Set Move Route: Player
        :              : $>Through ON
        :              : $>Move Lower Left
        :              : $>Move Lower Left  -- Repeat this command depending on depth of side stairs
        :              : $>Move Left
        :              : $>Through OFF
      @>
     : Else
      @> Set Move Route: Player
        :              : $>Through ON
        :              : $>Move Upper Right
        :              : $>Move Upper Right  -- Repeat this command depending on depth of side stairs
        :              : $>Move Right
        :              : $>Through OFF
      @>

### Random Processing

This technique is useful, e.g., for creating events that say a different thing every time the player talks to it. It uses the Control Variables event command to generate a random number, and calls one of several conditional branches depending on the number generated.

    @>Control Variables: [0001] = Random No. (0...3)
    @>Conditional Branch: Variable [0001] == 0
      @>Text: Hello, this is text number 1.
      @>
     : Branch End
    @>Conditional Branch: Variable [0001] == 1
      @>Text: Hello, this is text number 2.
      @>
     : Branch End
    @>Conditional Branch: Variable [0001] == 2
      @>Text: Hello, this is text number 3.
      @>
     : Branch End
    @>Conditional Branch: Variable [0001] == 3
      @>Text: Hello, this is text number 4.
      @>
     : Branch End

### Event Commands

The following event commands have no effect in Pokémon Essentials:

- Change Items
- Change Weapons
- Change Armor
- Change Party Member
- Battle Processing
- Shop Processing
- Name Processing
- Change HP
- Change SP
- Change State
- Change EXP
- Change Level
- Change Parameters
- Change Skills
- Change Equipment
- Change Actor Name
- Change Actor Class
- Change Actor Graphic
- Change Enemy HP
- Change Enemy SP
- Change Enemy State
- Enemy Recover All
- Enemy Appearance
- Enemy Transform
- Show Battle Animation
- Deal Damage
- Force Action
- Abort Battle

The following event commands have been redefined in Pokémon Essentials:

- Recover All (only "Entire Party" is supported)
- Show Text (uses a different message system)
- Show Choices (uses a different message system)
- Input Number (uses a different message system)
- Change Battle BGM (for the next battle only)
- Change Battle End ME (for the next battle only)
- Call Save Screen
- Change Gold
- Game Over
- Button Input Processing

### Saving the Game

To save the game, use pbSaveScreen:

    Conditional Branch:  Script:  Kernel.pbSaveScreen
      -- The game was saved
    Else
      -- The game was not saved
    End

## Items

### Item Events

To create an item event, give it the following name: Item:XXX, where XXX is the internal name of the item (generally, the name of the item in all uppercase letters, with no spaces). For example, Item:POTION creates a Potion item, and Item:FULLHEAL creates a Full Heal item.

To create a hidden item event, give it the following name: HiddenItem:XXX, where XXX is the internal name of the item (generally, the name of the item in all uppercase letters, with no spaces).

Both types of item events will be converted to real events when you run the game from RPG Maker XP.

### Item Management

#### Checking for Items

The PokemonBag class has a function, pbQuantity, that you can use to check for the existence or amount of an item in the Bag. Here's how to use it:

Conditional branch for checking for the existence of an item:

    $PokemonBag.pbQuantity(PBItems::POTION)>0

Script example: Printing the number of items

    itemname=PBItems.getName(PBItems::POTION)
    itemqty=$PokemonBag.pbQuantity(PBItems::POTION)
    print("#{itemqty}x #{itemname}")

#### Adding/Removing Items

To add an item:

    Conditional Branch:  Script:  $PokemonBag.pbStoreItem(::PBItems::POTION)
      -- The item was added
    Else
      -- The item couldn't be added
    Branch End

This is the most generic of all functions that add items.

To add an item received from a person, use event commands like the following.

    Conditional Branch:  Script:  Kernel.pbReceiveItem(::PBItems::POTION)
      -- The item was added
    Else
      -- The item couldn't be added
    Branch End

It is not to be used as a replacement for Kernel.pbItemBall.

To delete an item, use this as a Script event command:

     $PokemonBag.pbDeleteItem(
        PBItems::POTION
       )

To add more than one item at once, use this as a Script event command:

    5.times do
      $PokemonBag.pbStoreItem(
         PBItems::POKeBALL
      )
    end

or this newer syntax:

    $PokemonBag.pbStoreItem(
         PBItems::POKeBALL, 5
    )

### Adding New Items

New items are added by editing items.txt in the PBS folder (See also Implementing New Items). Here are examples of entries in that file.

#### Key Items

    500,LABKEY,LAB KEY,5,0,"This is a custom Key Item.",0,0

The first number, 500, is the item's ID, and the number 5 stands for the Key Items pocket.

#### Technical Machines

    298,TM10,TM10,3,3000,"An attack that varies in type and intensity depending on the user.",3,0,,HIDDENPOWER

The number 3000 specifies the price. The last field here, HIDDENPOWER, identifies this item's move. When creating a new TM, also edit tm.txt in the PBS folder to add the list of species who can learn the move. Here's an example for the move Softboiled.

    [SOFTBOILED]
    CHANSEY,BLISSEY,HAPPINY,TOGEPI,TOGETIC,TOGEKISS

#### Hidden Machine

    340,HM02,HM02,3,0,"A 2-turn move that hits on the 2nd turn. Use it to fly to any known town.",4,0,,FLY

Practically the same as above, except with a 4 after the description.

#### Regular Item

    16,ICEHEAL,ICE HEAL,1,250,"A spray-type medicine. It defrosts a frozen POKeMON.",1,1

For items stored in the items pocket. For details on the last two numbers, see fields 7 and 8 in the items.txt section.

## Pokémon Mart

To set up the Pokémon Mart, use the following Script event command (you don't type the word "Script:"):

    @>Script: pbPokemonMart([
     :      : PBItems::POKeBALL,
     :      : PBItems::POTION,
     :      : PBItems::ANTIDOTE,
     :      : PBItems::TM20,
     :      : PBItems::TM21,
     :      : PBItems::TM22,
     :      : PBItems::ICEHEAL,
     :      : PBItems::REPEL,
     :      : PBItems::ESCAPEROPE])
    @>

Within the brackets is a list of items to be found in the Pokémon Mart, separated by commas. Note that each item begins with PBItems::.

## PC

To open the PC, use the following Script event command.

    Script:  pbPokeCenterPC

It is to be used on any event with a PC.

For the player's PC, use the following Script event command instead.

    Script:  pbTrainerPC

## Wild Pokémon Battles

To generate a wild Pokémon battle, call pbWildBattle(X,Y,V,C) where X is the species number of the Pokémon, and Y is its level. See PBSpecies for species IDs. The optional parameter V represents the number of a variable to store the result of the battle (for example, if V is 2, then the result of the battle -- 1=won; 2=lost; 3=escaped; 4=caught -- will be stored in variable number 2), and the optional parameter C is true if the player can escape from the battle (the default is true).

To change the kinds of wild Pokémon found in an area, you can use the "Set Encounters" option in the Pokémon Essentials Editor (editor.exe). After doing so, it is enough to put grass tiles (or other tiles with terrain tag 2) on the map for wild Pokémon to appear there -- no events are necessary. Pokemon Essentials supports two different encounter types: Land and Cave. For Land encounter types, wild Pokémon will appear only on the grass. For Cave encounter types, wild Pokémon will appear anywhere. Several other encounter types are also supported.

## Trainers

Trainer events have a name of "Trainer(X)", where X is the maximum range of vision of the Trainer, that is, the number of spaces that the Trainer can "see". For example, if the event is named "Trainer(4)", the event will trigger if the player is up to 4 spaces away from it.

A Trainer event usually consists of these Comment event commands:

    Comment: Battle: Battle me now!
    Comment: Type: CAMPER
    Comment: Name: Cindy
    Comment: EndSpeech: A very good battle, indeed.
    Comment: EndBattle: Thanks for the battle.\mI enjoyed it.

The game will convert these comments to appropriate event commands automatically when the game is run from RPG Maker XP. Also, the game will automatically detect whether a Trainer is added when a battle with that Trainer would begin. If not, you will be given the chance to define the Pokémon that the Trainer has. The meanings of each supported comment are defined below.

- Battle: The text that the Trainer says before a battle begins. Use "\m" to split the text into individual messages. There can be more than one of these comments, and each one specifies the introductory text for rematch battles. If there is more than one Battle comment, then the Trainer can be registered in the phone.
- EndSpeech: The text that the Trainer says when the player wins a battle. There can be more than one of these comments.
- RegSpeech: The Trainer's speech when registering the Trainer's phone number.
- EndBattle: The text that the Trainer says when a battle is over. Use "\m" to split the text into individual messages. There can be more than one of these comments.
- Type: Trainer type. This is an internal name (like LEADER_Roxanne) that is defined under "Internal name" in the debug menu's Trainer Types option.
- Name: Name of the Trainer.
- BattleID: A number to distinguish Trainers with the same Trainer type and Trainer name.
- EndIfSwitch: If the switch with this number is ON, the battle is treated as already over. This is usually only set for Trainers within a Pokémon Gym.
- Backdrop: Sets the battle background for this Trainer battle (see Battle Backgrounds).

### Behind the Scenes

Please note that the instructions above are sufficient for simple Trainer battles. Using the method shown below is appropriate only for more complex battles, such as Gym Leader battles.

If you inspect the generated event commands, you will see that Trainer events normally consist of two event pages. The first has an Event Touch trigger and has the following structure:

    Text:  I challenge you!
    Conditional Branch: Script: pbTrainerBattle(PBTrainers::LEADER_Roxanne,"Roxanne",_I("Excellent.  You have earned the Stone Badge."))
      -- here you can add event commands to be run when the player wins, but this is not necessary
      Script: $Trainer.badges[0]=true
      Text:  \PN received the Stone Badge!
      Text:  The Stone Badge proves you can succeed in the Pokémon League.
      Control Self Switch:  A =ON
    Branch End

Notice the parameters to pbTrainerBattle. Here is a list of the parameters:

- Parameter 1: Trainer type.
- Parameter 2: Trainer's name. The Trainer type and Trainer name must be found in the Trainer data file.
- Parameter 3: Dialogue that the Trainer says when the player wins. This parameter should be wrapped in _I() (with a capital i), to support localization of the text.
- Parameter 4: Optional. Whether the battle is a double battle. The default is false. If the battle is a double battle, an exception will be raised if the player has only one Pokémon, so this case must be checked before the battle begins. For an example, see the two people to the left of the Pokémon Center's PC.
- Parameter 5: Optional. A number to distinguish Trainers with the same Trainer type and Trainer name. Specify 0 if there is only one such Trainer.
- Parameter 6: Optional. If `true`, the game will continue where the battle began even if the player loses the battle. If the player loses, the option "Set handling when conditions do not apply" should be active for the conditional branch and commands to run when the player loses should be placed in the Else part of that branch.

You can play music when a Trainer wants to battle by adding a "Play ME" event command as the first on the list of commands. Also, the Trainer event need not be named "Trainer(X)" if it only needs to be talked to in order to start a battle, as is the case for Gym Leaders and other special Trainers.

The second event page has a condition of "Self Switch A is ON", and usually contains text that the Trainer says after the battle is over. The trigger must be other than Event Touch.

The game system will automatically handle the case when two Trainers come into contact with the player at the same time; in that case, a multi battle will begin if the player has at least two Pokemon.

For Trainer battles that span two events (as is the case with many double battles), the other event's self switch should be turned on when the player wins. You can use the pbSetSelfSwitch function for this.

### Double Trainer Battles

To invoke a battle against two different Trainers, use the pbDoubleTrainerBattle function.

    @> Conditional Branch: Script: pbDoubleTrainerBattle(PBTrainers::CAMPER,"Andrew",0,_I("ABC"),PBTrainers::CAMPER,"Andrew",0,_I("DEF"))
      @> -- Event commands to be run when the player wins
      @>
     : Else
      @> -- Event commands to be run when the player loses.  For example:
      @> Exit Event Processing
      @>
     : Branch End

The function's parameters are as follows:

- Parameter 1: Trainer 1's Trainer type.
- Parameter 2: Trainer 1's name. The Trainer type and Trainer name must be found in the Trainer data file.
- Parameter 3: For Trainer 1, a number to distinguish Trainers with the same Trainer type and Trainer name. Specify 0 if there is only one such Trainer.
- Parameter 4: Dialogue that Trainer 1 says when the player wins. This parameter should be wrapped in _I() (with a capital i), to support localization of the text.
- Parameter 5: Trainer 2's Trainer type.
- Parameter 6: Trainer 2's name. The Trainer type and Trainer name must be found in the Trainer data file.
- Parameter 7: For Trainer 2, a number to distinguish Trainers with the same Trainer type and Trainer name. Specify 0 if there is only one such Trainer.
- Parameter 8: Dialogue that Trainer 2 says when the player wins. This parameter should be wrapped in _I() (with a capital i), to support localization of the text.
- Parameter 9: Optional. If `true`, the game will continue where the battle began even if the player loses the battle.

The important thing to note here is that each Trainer mentioned must have three or fewer Pokemon.

### Nightly Trainers

The following example event shows not only how to make Trainers that fight only at night, but also how to make Trainers that are active only at certain moments or under certain conditions (using the first conditional branch at the top of both event pages.)

#### Event Page 1

- Trigger: Action Button
- Condition: (none)

    @>Conditional Branch: Script: Time.now.hour<6||Time.now.hour>=20
      @>Text: Halt!  Who goes there?
      @>Conditional Branch: Script: pbTrainerBattle(PBTrainers::POKeMANIAC,"Andrew",_I("Whoops..."),false,0)
        @>Control Self Switch: A =ON
        @>
       : Branch End
      @>
     : Else
      @>Text: I'm on guard for suspicious activity.
      @>
     : Branch End
    @>

#### Event Page 2

- Trigger: Action Button
- Condition: Self Switch A is ON

    @>Conditional Branch: Script: Time.now.hour<6||Time.now.hour>=20
      @>Text: Oh, sorry.  You may proceed.
      @>
     : Else
      @>Text: I'm on guard for suspicious activity.
      @>
     : Branch End
    @>

### Partner Trainers

In Pokémon Essentials, a partner trainer can be registered so that he or she will appear as the player's partner in Pokémon battles. To register a partner, use a Script event command:

    pbRegisterPartner(PBTrainers::PkMnTRAINER_Cheryl,"Cheryl",0)

The first parameter is the internal name of the partner's trainer type, and the second parameter is the partner's name. The parameter shown here as 0 is optional, it indicates which party to use for the partner trainer. To define the partner, choose "Edit Trainers" from the Pokémon Essentials Editor (editor.exe).

The partner will be registered as long as the player remains on the same map. To deregister the partner, use a Script event command:

    pbDeregisterPartner

Special rules apply when the player is accompanied by a partner. First, the entire party will be healed at the end of the battle; and second, all opposing trainers must have at least two Pokemon with them. It is interesting, though, to make sure two opposing trainers face each other on the map.

This feature can be used in combination with Dependent Events.

The back of the trainer is to be placed in Graphics/Pictures/ and has a filename of trbackXXX.png, where XXX is the trainer type's ID number (see [[Trainer Backs]]). Trainer backs for partner trainers and other trainers are defined in the same way.

### Editing Trainers and Battles

The easiest way to edit trainers and trainer types is to use the options "Edit Trainers" and "Trainer Types" options on the debug menu (press F9 during a game) or the Pokémon Essentials editor (editor.exe). Both options offer an intuitive way of editing Trainer battles and Trainer types. (To delete a Trainer type or battle, select it and press Z.)

## Terrain Tags

The following terrain tags are defined:

- 1: Ledges
- 2: Grass
- 3: Sand
- 4: Rocky ground
- 5: Deep water
- 6: Still water (events will be reflected by these tiles)
- 7: Normal water
- 8: Waterfall
- 9: Crest of waterfall
- 10: Tall grass
- 11: Underwater grass
- 12: Ice (The player may slide on these tiles)
- 13: Neutral (For use on tiles that the player could walk on but have special tiles underneath them.)

More may be defined in the future. However, RPGXP's tileset editor only supports seven terrain tags. That's why Pokémon Essentials contains a built-in terrain tag editor. It can be accessed by choosing "Edit Terrain Tags" from the "Debug" option in the game menu, or from the Pokémon Essentials Editor (editor.exe).

## Trainer Object

PokeBattle_Trainer.new has two parameters: the first is the trainer name, and the second identifies the trainer type (such as PBTrainers::YOUNGSTER). The $Trainer object identifies the player. Here are some properties of the $Trainer object:

- $Trainer.pokedexSeen -- Number of Pokémon seen
- $Trainer.pokedexOwned -- Number of Pokémon owned
- $Trainer.numbadges -- Number of badges
- $Trainer.pokedex -- Whether the Pokedex was obtained
- $Trainer.party -- Array that specifies the player's current party of Pokémon

## Pokémon Management

### Adding a Pokémon

For an easy way to add a Pokémon, call pbAddPokemon(X,Y) where X is the species number of the Pokemon, and Y is its level. You can modify that function, which is located in PokemonUtilities, to remove the messages. Adding a Pokémon may fail, so this statement should appear in a "Conditional Branch" event command. An example is below.

To learn how to create a new Pokémon species, edit the file pokemon.txt in the PBS folder.

    @>Conditional Branch: Script: pbAddPokemon(PBSpecies::EEVEE,25)
      @>Text: Pokémon was received...
      @>
     : Else
      @>Text: Sorry, you have no room...
      @>
     : Branch End
    @>

pbAddPokemon will add the Pokémon to either the party or the PC boxes. A similar method, pbAddPokemonToParty, will adding a Pokémon just to the party.

#### Adding a Pokémon Owned by Another Person

Use the function "pbAddForeignPokemon" to add a Pokémon owned by another person. An example follows:

    @>Conditional Branch: Script: pbAddForeignPokemon(PBSpecies::SHUCKLE,20,_I("MARK"),_I("SHUCKIE"))
      @>Text: Received a Pokémon from Mark.
      @>
     : Else
      @>Text: You have no room to store the Pokemon...
      @>
     : Branch End
    @>

Note the four parameters: species, level, owner's name, and nickname. (Specifying a nickname is optional.) The Pokémon added will also have a different ID number from that of the Trainer, to underscore the fact that the player does not own it.

pbAddForeignPokemon will add the Pokémon only to the Trainer's party.

#### Modifying a Pokémon After Adding It

A Pokémon added to the party is always placed last on the Trainer's party. However, using pbAddPokemon may add the Pokémon to the player's PC instead if the Trainer's party is full. That's why there should be a check for a full party before adding the Pokémon. Then, it becomes easy to modify the Pokémon as desired, for example to make it shiny (different-colored) or to change its gender. Here's an example which demonstrates this technique.

    @>Conditional Branch: Script: $Trainer.party.length>=6
      @>Text: You have no room to store the Pokemon...
      @>
     : Else
      @>Script: Kernel.pbAddPokemon(
       :      :   PBSpecies::MAGIKARP,10
       :      : )
      @>Script: # Get the Pokémon just added
       :      : p=$Trainer.party[
       :      : $Trainer.party.length-1]
       :      : # Make it shiny
       :      : p.makeShiny
      @>
     : Branch End
    @>

Another example: Replace "p.makeShiny" above with the following to ensure that the Pokémon always has the move Tackle:

    pbAutoLearnMove(p,PBMoves::TACKLE)

#### Adding a Pokémon Silently

The following example shows how to create a Pokemon and add it to the Trainer's party. It also shows how the Pokemon's data can be modified before the Pokemon is added (see also "Modifying a Pokemon After Adding It, above).

    @>Conditional Branch: Script: $Trainer.party.length>=6
      @>Text: You have no room to store the Pokemon...
      @>
     : Else
      @>Script: p=PokeBattle_Pokemon.new(
       :      :   PBSpecies::MAGIKARP,10,$Trainer
       :      : )
       :      : # Make it shiny (optional)
       :      : p.makeShiny
       :      : # Add the Pokemon
       :      : $Trainer.party.push(p)
      @>
     : Branch End
    @>

#### Adding an Egg

You can use the function pbGenerateEgg to add an egg to the Trainer's party. Here's an example.

    @>Conditional Branch: Script: $Trainer.party.length>=6
      @>Text: You have no room to store the Egg...
      @>
     : Else
      @>Script: Kernel.pbGenerateEgg(
       :      :   PBSpecies::TOGEPI,5
       :      : )
      @>Text: Received a Pokémon Egg.
      @>
     : Branch End
    @>

pbGenerateEgg will add the egg only to the Trainer's party.

### Removing a Pokémon

To remove a Pokémon from the party, use the script `$Trainer.party.delete_at(X)` where X is the Pokémon's position (starting at 0). For example, to remove the first Pokemon in the party, use 0 for X; or, to remove the second Pokemon in the party, use 1 for X.

To remove more than one Pokémon at a time, use a loop like the following, which removes the first three Pokémon from the party.

    3.times { $Trainer.party.delete_at(0) }

### Checking for Pokémon

The script function pbHasSpecies? checks for a Pokémon in the player's party. Example:

    Conditional Branch:  Script:  pbHasSpecies?(::PBSpecies::CELEBI)
      -- The Pokémon Celebi is in the party
    Else
      -- The Pokémon Celebi is not in the party
    Branch End

To determine whether just the first Pokemon in the player's party is a certain species, use the following instead:

    Conditional Branch:  Script:  $Trainer.party[0].species==::PBSpecies::CELEBI
      -- The Pokémon Celebi is the first in the party
    Else
      -- The Pokémon Celebi is not the first in the party
    Branch End

## Graphical Effects

### Water Reflection

Any tile with terrain tag 6 will display a reflection of any events on it.

### Light Sources

Any event can serve as a light source. To make an event a light source, name the event either "Light" or "OutdoorLight". The difference between them is that an event named "OutdoorLight" will change its intensity according to the time of day.

### Shadows

Any event can draw a shadow on the player. To make an event a shadow source, add a Comment event command consisting of the text "begin Shadow Source". You can add up to four additional Comment event commands for extra parameters of the shadow, like this:

    Comment:  begin Shadow Source
    Comment:  anglemin 180
    Comment:  anglemax 360
    Comment:  distancemax 350
    Comment:  opacity 100

To allow a shadow to appear on an event, add a Comment event command consisting of the text "begin Shadow".

### Particle Engine

Pokémon Essentials includes a particle engine for enabling special graphical effects with particles. To add a particle effect to an event, add to the event a Comment event command consisting of the text "Particle Engine Type" and add another Comment event command consisting of one of the following: fire, smoke, teleport, spirit, aura, soot, sootsmoke, rocket, fixteleport, smokescreen, flare, splash, or starteleport.

### Transitions

In addition to normal transitions, Pokémon Essentials also supports special transitions that are not possible with transition bitmaps alone. Most of them require the file rubyscreen.dll, included with the distribution, since a screen capture of the game is required for them. These transitions activate when a special pseudofile is entered into the Graphics.transition function. For example, for the Breaking Glass transition, which breaks the screen into pieces, the file would be "Graphics/Transitions/BreakingGlass". That file need not exist, but it can be used as a map and/or battle transition if that file does exist. Even if the file exists, it can even be zero-length and it will still work.

The following transitions are available:

RotatingPieces, BreakingGlass, Mosaic, Splash, ScrollDown, ScrollUp, ScrollLeft, ScrollRight, RandomStripeV, RandomStripeH, ScrollDownRight, ScrollDownLeft, ScrollUpLeft, ScrollUpRight

Each special transition is contained in an object similar to that of Sprite -- it contains initialize, update, dispose, and disposed?. Here are the four methods of a transition object.

- initialize(numframes) - sets up the transition so that it lasts _numframes_ frames. The setup can involve taking a screenshot of the game with a call to "pbScreenshot", which returns a bitmap. If the transition fails to initialize, it should set its disposed flag to true. It should also do so if _numframes_ is 0 or less.
- dispose - disposes all resources used by the transition and sets the disposed flag to true. This function should let itself be called multiple times.
- disposed? - returns true if the transition was disposed, that is, if the disposed flag is true.
- update - updates the transition. This method is called once per frame. Once the transition is over, it must call _dispose_ to clean up the transition's resources.

New transitions are added to the `judge_special_transition` method, located in the script section Transitions, within the list of "elsif" lines within that method. For example, a transition named "mytransition" would be added like this:

        elsif dc=="mytransition"
          @@transition=MyTransition.new(duration)

You can look at the different transition objects in SpriteWindow to get an idea of how to create your own.

### Animated Images

Pokémon Essentials supports two kinds of animated images: GIF files and specially designed multi-frame images. Animated panoramas and fogs, for example, allow special effects such as twinkling stars in the night sky, or moving sand, etc. Animated GIF files should have an extension of 'png'. To allow other kinds of images to be animated, add "[X]", where X is the number of frames in the animation, to the beginning of the image's file name, and make a horizontally arranged image of each frame in the animation. For example, a four-frame panorama might have the name [4]MyPanorama.png, and the panorama's image would show the four frames of the animation, arranged horizontally.

Animated images (and especially GIF files) can be used anywhere other kinds of images can be used -- as character sprites, as tilesets, as pictures -- practically everywhere. In fact, even projects containing only GIF files and no PNG files are possible.

The Show Picture event command takes advantage of animated image support, and can even animate image files automatically. You may have to give the file an extension of "png", though, in order to make it appear on the list of pictures in RPG Maker XP.

### GIF Support/GIF Sprites

There is a special class defined, called IconSprite, which can load animated image files, including animated GIF files, and display them one frame at a time. An IconSprite can be created within a script using `IconSprite.new(x,y,viewport)` where x and y are the X and Y coordinates of the script, and specifying the viewport is optional. The IconSprite's "update" method must be called in order to animate the sprite. Its "setBitmap" method sets the file path of an animated image that the sprite refers to (file extensions can be omitted). Otherwise, an IconSprite acts exactly like a Sprite and can be used wherever sprites can be used.

## Message System

This is the syntax used by the message system:

- \PN - Displays the player's name. (Please see Displaying a Player-Supplied Name for a Trainer for information on how to display other Trainers' names using message commands.)
- \G - Displays a window showing the player's current money.
- \PM - Displays the player's current money within the message. (example: $1000)
- \v[n] - Displays the value of variable number n.
- \f[X] - Displays the face picture X near the message. The image specified must be in the Graphics/Pictures/ folder.
- \c[n] - Displays the text that follows in color number n. 0=Black; 1=Blue; 2=Red; 3=Green; 4=Cyan; 5=Magenta; 6=Yellow; 7=Gray; 8=White.
- \[XXXXYYYY] - Displays the text in the base color XXXX and shadow color YYYY. Each color is a hexadecimal 15-bit RGB color. Examples:
  - \[043c3aff] - Red
  - \[06644bd2] - Green
  - \[65467b14] - Blue
  - \[318c675a] - Gray
- \ch[a,b,choices] - Displays a list of choices. _a_ is the number of a variable to store the chosen choice (the first choice is 0, etc.), _b_ is the default choice in case the player cancels (or 0 if the player can't cancel; the first choice is 1, etc.), and _choices_ is a comma-separated list of choices. This command is designed to support more than four choices, but the existing choice system can still be used if desired.
- \1 - Pauses the message. This is usually not necessary unless pauses are desired within a message.
- \n - Causes a line break.
- \b - Male dialogue colors.
- \r - Female dialogue colors.
- \wt[X] - Waits X frames, where a frame is equal to 1/20 of a second.
- \wtnp[X] - Wait and no pause. Waits X frames, and makes the message close without pausing.
- \se[X] - Plays the sound effect (SE) named X.
- \me[X] - Plays the music effect (ME) named X.
- \\ - Displays the backslash character "\".
- \w[X] - Displays the message in the windowskin X. If this field is blank, no windowskin will be used in the message display.
- \sign[X] - Displays the message in the form of a sign and in the windowskin X. If this field is blank, no windowskin will be used in the message display.
- <b> ... </b> - Formats the text in bold.
- <o=X> ... </o> - Changes the opacity of the text. X can be 0 (fully transparent) to 255 (fully opaque).
- <i> ... </i> - Formats the text in italics.
- <u> ... </u> - Underlines the text.
- <c=RRGGBBAA> ... </c> - Displays the text that follows in the specified RGB color (similar to how colors are given in HTML, except without the "#" sign). The "AA" is optional and specifies the hexadecimal opacity of the color and can range from 00 (fully transparent) to FF (fully opaque).
- <c3=RRGGBBAA,RRGGBBAA> ... </c3> - Displays the text that follows in the specified RGB colors (similar to how colors are given in HTML, except without the "#" sign). The "AA" is optional and specifies the hexadecimal opacity of the color and can range from 00 (fully transparent) to FF (fully opaque). The first color is the base color and the second color is the shadow color.
- <s> ... </s> - Draws a strikeout line over the text.
- <outln> ... </outln> - Displays the text in outline format.
- <r> - Right-aligns the text until the next line break.
- <br> - Causes a line break.
- <fn=X> ... </fn> - Formats the text in the specified font, or Arial if the font doesn't exist.
- <fs=X> ... </fs> - Changes the font size to X.
- <ac> ... </ac> - Centers the text. Causes line breaks before and after the text.
- <al> ... </al> - Left-aligns the text. Causes line breaks before and after the text.
- <ar> ... </ar> - Right-aligns the text. Causes line breaks before and after the text.
- <icon=X> - Displays the icon X (in Graphics/Icons/).
- &apos; - Converted to "'".
- &lt; - Converted to "<".
- &gt; - Converted to ">".
- &amp; - Converted to "&".
- &quot; - Converted to double quotation mark.
- \l[n] - Changes the number of lines in the text box to n lines.
- \wu - Shows the textbox at the top of the screen.
- \wm - Shows the textbox at the middle of the screen.
- \wd - Shows the textbox at the bottom of the screen.
- \op - Moves the window toward the screen as it opens.
- \cl[X] - Moves the window away from the screen as it closes. The "[X]" is optional, where X is the sound file to play as the window closes.

It is not necessary or recommended to put spaces after a message command; such spaces will be reflected in the message when it is rendered. For example, "\bText" is preferred over "\b Text".

It is also not necessary to add manual line breaks to text and limit Text event commands to two lines. The message system will automatically break the text as appropriate and scroll the text as needed if all of it doesn't fit on a single text box.

### Using the Message System in Other Projects

To use the message system in other RPGXP projects, copy the script sections BitmapCache, DrawText, SpriteWindow, and PokemonMessages and put them just before the last script in the script editor. In addition, create a new script section that consists of the following code:

    def _INTL(*args);
     string=args[0].clone
     for i in 1...args.length
      string.gsub!(/\{#{i}\}/,"#{args[i]}")
     end
     return string
    end
    def _ISPRINTF(*args);
     string=args[0].clone
     for i in 1...args.length
      string.gsub!(/\{#{i}\:([^\}]+?)\}/){|m|
       next sprintf("%"+$1,args[i])
      }
     end
     return string
    end
    def _MAPINTL(*args);
     string=args[1].clone
     for i in 2...args.length
      string.gsub!(/\{#{i}\}/,"#{args[i+1]}")
     end
     return string
    end
    module Graphics
      if !self.respond_to?("width")
        def self.width; return 640; end
      end
      if !self.respond_to?("height")
       def self.height; return 480; end
      end
    end

Also, copy the following files to your project:

- Graphics/Pictures/uparrow.png
- Graphics/Pictures/downarrow.png
- Graphics/Pictures/leftarrow.png
- Graphics/Pictures/rightarrow.png
- Graphics/Pictures/pause.png
- Graphics/Pictures/selarrow.png
- Graphics/Windowskins/skin1.png
- Graphics/Windowskins/frlgtextskin.png
- Graphics/Windowskins/frlgtextskin.txt

After doing so, the new message system will be ready to use.

## Background Music

The background music for specific types of Trainers can be set from the debug menu's "Trainer Types" option, under Battle BGM, Battle End ME, and Battle Intro ME. You may, for example, want to use one kind of music for Elite Four members and Gym Leaders.

### Default Background Music

The default battle music can be changed by going to the "Set Metadata" option within the debug menu or Pokémon Essentials Editor, and choosing "GLOBAL". There are four possible settings for background music: TrainerBattleBGM, WildBattleBGM, TrainerVictoryME, and WildVictoryME. The names are pretty self-explanatory. The BGM (background music) files mentioned here are to be placed in the Audio/BGM/ directory, and the ME (music effects) files to the Audio/ME/ directory.

### Changing the Battle Music

You can change the background music to be played during a battle by using the "Change Battle BGM" and "Change Battle End ME" event commands. These settings apply only to the next Pokémon battle. (Note that within an event, these event commands should be placed very close to the event command that initiates the Pokemon battle. Their effect doesn't end if the event is run to completion.)

### Nightly Music

To specify a different BGM file to play at night, add an "n" to the filename before the file extension. For example, the nightly version of "song.mid" would be "songn.mid". This will apply only to BGM files played on the map.

## Localization and Translation

All the text in Pokémon Essentials can be translated to a different language using the "Extract Text/Compile Text" feature.

To use this feature, open the Pokémon Essentials editor (editor.exe) and select "Extract text". This function will save a file called "intl.txt" within the game folder. Open the file, then translate every second line of the file. For example, if one part of the file reads:

    Good day.
    Good day.

you could translate it by changing it to:

    Good day.
    Guten Tag.

After you are done translating, select "Compile Text" from the Debug menu. This function will convert the text to another file called "intl.dat" within the game folder. Rename that file and put it into the Data folder of the project, then close and restart the game.

The languages that the game uses can be found in the LANGUAGES array of the PokemonSystem script section. That script defines an array called LANGUAGES that contains two sample languages and message files, which are commented out. Each entry in the array includes the name of the language followed by the message data file's filename (like intl.dat), located in the Data folder. Please note that the mentioned files don't really exist.

## Map Making Considerations

### Avoiding Black Regions Near Map Edge

In general, the border of a map needs to be wide enough so that the player can remain centered without any black spots on the edges. That means 7 tiles on the left and right edges of the map and six tiles on the top and bottom edges. You can easily add more room to a map using the following steps:

- Right-click on the map's name and select "Map Properties". You can set the width and height of the map to allow more room for edges.
- Right-click on the map's name and select "Shift". You can use this feature to move the map to the right and down as needed to allow more room for edges. You can then draw the edges with trees, etc.

On the other hand, this behavior of a black area outside the map is desired for indoor maps.

### Can still surf on water even with a bridge over it

Water tiles have terrain tag 7, but due to the way the RPGXP map system works, tiles without terrain tags are ignored in determining what terrain tag an area has. In this case, bridge tiles have no terrain tag, but since a water tile is underneath it, the bridge is inappropriately considered to have terrain tag 7 and could thus be surfed on. To work around this, define a terrain tag for bridges (the neutral terrain tag 13 is designed for this purpose). To do so, open the game from RPG Maker XP, then open the in-game menu and select "Debug", then "Edit Terrain Tags." (Setting terrain tags higher than 7 is not possible in RPG Maker XP.)

### Game freezes during movement

This usually happens when a move route is defined on an event and a "Wait for Move's Completion" event command follows it, but the event to be moved is prevented from moving. This problem is not limited to Pokémon Essentials, though. To solve this problem, check the following in order, testing after each step.

- Is the event to be moved placed on an impassable tile? If so, make the tile in question passable (using the Tilesets tab of the database), or move the event to a passable tile.
- Are any events blocking the way? If so, move them using the Set Event Location event command.
- Add "Through ON" to the beginning of the event's move route, and add "Through OFF" to the end of the move route.
- Enable the setting "Ignore If Can't Move" for the event's move route.

## Common Mistakes

- It is incorrect to change the player's starting position to any map other than the introduction, unless the player was configured properly beforehand (see "Intro Screen" for more information). The game system will not work properly otherwise.

## Debugging

### Playtesting Functions

In playtests (when the $DEBUG global variable is set), the following functions are available:

- In a Pokémon's option menu, the option SHOW VALUES displays the Pokémon's Individual Values, Effort Values, personal ID, and happiness.
- In a Pokémon's option menu, the option CHEAT CODES saves a file containing cheat codes for the Pokémon. The generated codes are compatible with Visual Boy Advance.
- Holding CTRL will disable random encounters and skip Trainer battles. It will also make every tile passable.
- Holding CTRL while selecting the RUN command during a battle will allow you to flee or decide the outcome of the battle.
- Hidden moves can be used any time, even if the player doesn't have the right Badge or the right Pokemon.
- The DEBUG option appears on the main menu.

### Debug Menu

The debug menu contains features useful for debugging or configuring a Pokémon game. It can be accessed by pressing `F9` during a playtest or by choosing `Debug` from the game's main menu.

- RGSS Object Count - Gives the count of all graphical resources.
- Switches - Opens a window containing all defined switches. To turn a switch on or off, simply select it.
- Variables - Opens a window containing all defined variables. To change a variable, select it then press the left or right arrow keys.
- Set Terrain Tags - Opens a screen allowing you to set the terrain tags of each tile. This feature is necessary because of the terrain tag limit set by RPG Maker XP.
- Warp to Map - Transfers the player to a random space on another map.
- Animation Editor - Opens the Animation Editor.
- Fill Boxes - Fills all Pokémon Boxes with one Pokémon of each species. These Pokémon will have a level of 50.
- Heal Party - Heals all Pokémon in the player's party.
- Fill Bag - Adds a defined number of each item to the player's Bag.
- Extract Text - Extracts all text in the game for localization (see Localization and Translation).
- Compile Text - Compiles a text file into a localized format.
- Load Boxes
- Bitmap Cache - Saves information about the bitmap cache to bitmapcache.txt, in the game's folder.
- Reset Trainers - Resets all Trainers on the current map.
- Visual Editor
- Debug Console - Opens the debug console. This is useful when debugging the game's scripts. To send text to the console, call echo(X) within a script, where X is the text to send.
- Compile Data - Compiles all data from the text files in the PBS folder.
- Set Encounters - Allows the Pokémon encounters for each map to be modified.

## Pokedex

Use `$Trainer.pokedex=true` to add the Pokedex.

## Town Map

Use `pbShowMap` to show the Town Map.

## Pokegear

Use `$Trainer.pokegear=true` to add the Pokegear.

## Running Shoes

Use `$PokemonGlobal.runningShoes=true` to give Running Shoes to the player.

## Badges

To add a Gym Badge, use `$Trainer.badges[X]=true` where X is a number from 0 through 7 (though it is safe to assume that more Badges are possible). It is normally set after the player defeats a Gym Leader.

The constants found in the PokemonField script section (like BADGEFORCUT) determine which Badge enables which hidden move.

The image for all Badges is located at Graphics/Pictures/badges.png. This image is 256 pixels in width and contains X rows of eight badges, where X is the number of regions in the game. Each badge is 32x32 pixels in size. For example, if the game has two regions, the image's height would be 64 pixels (2 * 32); the first row would have badges for the first region (region 0) and the second row would have badges for the second region (region 1).

## Phone

The Pokegear phone supports the storage of Trainers' phone numbers and enabling rematches. A Trainer's phone number can be added if there are multiple battles for the same Trainer event.

The possible dialogue from a phone can be edited in PBS/phone.txt. It contains four sections:

- Greetings - Phrases that begin a phone call.
- Bodies - Phrases that follow a greeting and complete a phone call.
- Generics - Phrases that consist of a complete phone call.
- BattleRequests - Phrases that offer to battle.

## Name Rater and Move Deleter

Looking at the events for the Move Deleter and Name Rater can be very instructive when learning to call such tasks as choosing a Pokémon or choosing a move.

## Coin Case and Game Coins

`$PokemonGlobal.coins` in a script retrieves the current number of coins. Example:

    Text:  Here are some coins.
    Script:  $PokemonGlobal.coins+=10
    Text:  Obtained 10 game coins!

(It may be useful here to add code to enforce a maximum number of coins:)

    Script:  $PokemonGlobal.coins+=10
    :     :  if $PokemonGlobal.coins>9999
    :     :     $PokemonGlobal.coins=9999
    :     :  end

However, a player can't obtain Coins without a Coin Case, so that case should be checked first.

    Conditional Branch:  Script:  $PokemonBag.pbQuantity(PBItems::COINCASE)==0
      Text:  Oops!  Forgot the Coin Case!
      Exit Event Processing
    Branch End

Another example:

    Script:  $game_variables[1]=
    :     :    $PokemonGlobal.coins
    Text:  You have \v[1] game coin(s).

## Dependent Events

The game system supports dependent events. Dependent events are those that follow the player character whenever the player moves. To add a dependent event, use this script:

    Kernel.pbAddDependency2(ID, "XXX", COMMONEVENT)

where ID is the event's ID number (use @event_id to refer to the current event; to find out an event's ID number, double-click on the event, and the ID will appear on the dialog box shown), "XXX" is an arbitrary name used to identify the event, and COMMONEVENT is the common event number to call when the player talks to the dependent event.

To remove a dependent event, use this script:

    Kernel.pbRemoveDependency2("XXX")

where XXX is the name used in the call to "pbAddDependency2".

Dependent events will remain even if a player leaves one map and enters another one. The implementation of dependent events was changed considerably since the September 22, 2008 release.

## In-Game Trades

To make an in-game trade event, copy the example found in the man at the demo's Pokémon Center.

Essentially, there are two steps to making a trade event. First, add a Script event command containing the command to choose a Pokémon from a certain species, in this case Rattata:

    pbChoosePokemon(1,2,
    proc {|poke|
     !poke.egg? and
      poke.species==PBSpecies::RATTATA
    })

Then, if the player chose a Pokémon (use a Conditional Branch checking whether the variable 1 does not equal -1, run a script containing the following code. Note that the species received is Haunter.

    pbStartTrade(
    $game_variables[1],
    PBSpecies::HAUNTER,
    "HAHA", # Nickname
    "ANDY" # OT
    )

## Move Tutors

The game system allows the creation of "move tutor" events, like in Pokémon FireRed and LeafGreen. To use it, call the script function pbMoveTutorChoose(PBMoves::X, Y) where X is the name of a move, and Y is a list of species that can use that move. An example of its use follows. The move tutor here teaches the move Softboiled.

    @>Conditional Branch: Script: pbMoveTutorChoose(PBMoves::SOFTBOILED,::SOFTBOILEDLIST)
      @>Text: Move learned.
      @>
     : Else
      @>Text: Move not learned.
      @>
     : Branch End

The script code in the conditional branch refers to the array called "::SOFTBOILEDLIST", which is a list of species that can learn Softboiled. It can appear in a new script section like this:

    ::SOFTBOILEDLIST=[
    PBSpecies::CHANSEY,
    PBSpecies::HAPPINY,
    PBSpecies::BLISSEY,
    PBSpecies::TOGEPI,
    PBSpecies::TOGETIC,
    PBSpecies::TOGEKISS
    ]

Alternatively, you can specify the list of Pokemon who can learn Softboiled in the PBS/tm.txt file, like this:

    [SOFTBOILED]
    CHANSEY,HAPPINY,BLISSEY,TOGEPI,TOGETIC,TOGEKISS

In that case, the conditional branch script shown above will be reduced to the following:

    pbMoveTutorChoose(PBMoves::SOFTBOILED)

## Bicycle

Use the script "pbMountBike" and "pbDismountBike" to mount and dismount the bicycle.

If the setting BicycleAlways is set on a map, the player will appear with a bicycle whether or not the player has a bicycle present in the inventory. This behavior is intentional and is present for convenience purposes, so that the game need not check whether the player actually has a bicycle. For that reason, events within a game should check for the presence of a Bicycle (see "Checking for Items" in this document) before the player is allowed to enter a map where the player mounts a bicycle automatically.

## Multiple Regions

Pokemon Essentials supports multiple regions in a single game. A region, here, is defined as a single collection of related maps. These maps can be indoor or outdoor, but all belong to the same general "area" of a game instead of any other area. Here are things to consider when creating a multiple-region game.

- The file townmap.txt in the PBS folder holds information on each region in the game and the locations of each major area on the map. The sections begin with lines like "[0]" (the first region), "[1]" (the second region), and so on. To create a new region, assign it a new section title at the end of the file (like "[2]").
- The HTML page townmapgen.html is a town map generator editor which makes it easier to edit the information in the townmap.txt file. It is fairly intuitive to use.
- In the metadata, you should specify the location in the town map of every RPG Maker XP map in your game, even for houses, Pokemon Centers, and other indoor maps. To do this, open the editor (editor.exe), and select Set Metadata, then edit the MapPosition setting of every map in your game.
- Edit the file badges.png in Graphics/Pictures/ according to the badges used in each region of the game, if more than one region has its own Pokémon League.

## Miscellaneous

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.

In the Custom and Perspective map views, the day/night tinting will be disabled for any event named "RegularTone".

## Suggestions for Customizing Scripts

For further scripting ideas, see the advanced topics.

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.

### Setting a Variable from Script

In addition to using event commands, you can set game variables from scripts as well. This is useful if the function is implemented in script, such as a function described in the advanced topics. This is how a variable can be set in a script.

     $game_variables[X]=100

where X is the variable's number, such as 50. The code above sets that variable to 50. Later, you can display that variable's name in a Text event command like this:

    Text: The magic number is \v[X]!

Replace X in the example above with the same value you defined in the previous example (e.g. \v[50]).

This is another example that sets variable 60 to the number of Pokemon that the player has seen:

    $game_variables[60]=$Trainer.seen

### Displaying a Player-Supplied Name for a Person

To make the player supply a name for a person, you can use this Script event command within an event (assuming that 25 is the variable you want to use):

    $game_variables[25]=
    pbEnterText("Rival's name?",1,7,"Gary")

"Gary", here, is the trainer's default name. "Rival's name?" is the text to display as the title of the name entry screen.

The advantage of this approach is that the person's new name can be displayed in any Text event command using the command "\v[25]".

(The following is optional, but necessary if the person is also a Pokémon Trainer.) Then modify the script section PokemonTrainers by adding the lines in bold (the following is from lines 14 to 16), assuming that the Trainer's trainer type is RIVAL and the Trainer's name is "???" (the lines not in bold serve only to identify where to place the code):

       name=pbGetMessageFromHash(MessageTypes::TrainerNames,name)
       if trainerid==PBTrainers::RIVAL && trainername=="???"
         name=$game_variables[25] # Replace 25 with the variable number for the name
       end
       opponent=PokeBattle_Trainer.new(name,thistrainerid)

The code above replaces the name "???" with the name the player gave.

### Shiny Wild Pokémon

To allow battles with shiny (different-colored) wild Pokémon, you first need to define a switch for shiny Pokémon, say, 50. Now, insert a new script section just before the last script section in the script editor. In that script, enter the following:

    Events.onWildPokemonCreate+=proc {|sender,e|
      pokemon=e[0]
      if $game_switches[50]
        pokemon.makeShiny
      end
    }

(The code can also be used to modify the Pokémon in a different way, such as editing its Individual Values or changing the moves it knows.)

Then, enable the switch (in this case, 50) before a wild battle with a shiny Pokémon, and disable the switch when the battle is over. Example:

    Control Switches: [0050: Shiny] = ON
    Script: pbWildBattle(
              ::PBSpecies::GYARADOS,30,1)
    Control Switches: [0050: Shiny] = OFF

The steps mentioned above affect only wild Pokémon battles, and will not affect any other Pokemon, including Pokémon added to the Trainer's party.

### Allowing a Player to Lose a Trainer Battle

Here is an example of a battle where the player stays at the same position whether he or she loses or wins a Trainer battle.

    Conditional Branch: Script: pbTrainerBattle(PBTrainers::LEADER_Roxanne,"Roxanne",_I("Excellent."),false,0,true)
      -- here you can add event commands to be run when the player wins the battle
    Else
      -- here you can add event commands to be run when the player loses the battle
    Branch End

### No Shiny Pokémon

If you don't want shiny (different-colored) Pokémon in your game, you can use the following script section in the script editor:

    class PokeBattle_Pokemon
     def isShiny?
      return false # No Pokémon are shiny
     end
    end

Then it should be safe to remove all shiny Pokémon sprites (in Graphics/Battlers, with names like poke001s.png and poke001sb.png).

### Changing the Maximum Possible Level

To change the maximum level from 100 to any other number (such as 200), go to the script section PBExperience, look for the line starting with "MAXLEVEL=", and change the value of MAXLEVEL to any other number.

### Pokémon Types

The script section PBTypes contains instructions for adding new Pokémon types. To incorporate an icon of the new type, edit the file Graphics/Pictures/types.png.

### Option Screen

The script section PokemonOption displays the game's option screen. There are several predefined options such as Text Speed and Battle Style. Options are placed in a class named PokemonSystem, which is also found in the PokemonOption script section. Find the array named "@PokemonOptions". To add an option, define a setter and a getter for that option. (The setter and getter are "proc" statements that define an inline function used by each option.) To delete an option, comment it out or delete it. The game's options may be placed in any order.

### Screen Size

Change the screen size (resolution) by changing the "@@width" and "@@height" variables in the script section SpriteResizer. For best results, however, you should delete the option "Screen Size" in the script section "PokemonOption" (see "Option Screen", above).

## Controlling Events with Scripts

The script section PokemonMessages contains several functions for controlling events with scripts. This includes applying move routes, waiting, and so on. For an example of their use, see the script section PokemonDuel.

### pbWait(x)

Waits x frames, where a frame is 1/40 of a second. While waiting, processes the rest of the scene.

### pbShake(power,speed,x)

Shakes the screen x frames, where a frame is 1/20 of a second. The shake has power "power" and speed "speed". Returns immediately.

### pbFlash(color,x)

Flashes the screen x frames, where a frame is 1/20 of a second. in the specified color (Color).

### pbToneChangeAll(tone,duration)

Sets the screen color tone ("tone", Tone) on the screen and all pictures. Fades the tone in for duration frames, where a frame is 1/20 of a second.

### pbMoveRoute(event,commands)

Runs a move route on an event (Game_Character). To get the player, use "$game_player". To get an event, use "$game_map.events[X]" where X is the event ID. "event" can be nil. "commands" is an array of move route commands, with each command followed by a set of parameters for that command. Here is an example of a move route defined for a player:

        pbMoveRoute($game_player,[
          PBMoveRoute::ChangeSpeed,2,
          PBMoveRoute::Backward
        ])

Notice that the ChangeSpeed command is followed by a number specifying the speed. The Backward command has no parameters, however. Here is a list of possible commands. Most are self-explanatory.

- Taking no parameters: Down, Left, Right, Up, LowerLeft, LowerRight, UpperLeft, UpperRight, Random, TowardPlayer, AwayFromPlayer, Forward, Backward, TurnDown, TownLeft, TurnRight, TurnUp, TurnRight90, TurnLeft90, Turn180, TurnRightOrLeft90, TurnRandom, TurnTowardPlayer, TurnAwayFromPlayer, WalkAnimeOn, WalkAnimeOff, StepAnimeOn, StepAnimeOff, DirectionFixOn, DirectionFixOff, ThroughOn, ThroughOff, AlwaysOnTopOn, AlwaysOnTopOff
- Jump - 2 parameters: X offset, Y offset
- Wait - 1 parameter: Number of frames to wait (1/20 second)
- SwitchOn - 1 parameter: Switch number
- SwitchOff - 1 parameter: Switch number
- ChangeSpeed - 1 parameter: Desired movement speed (1-6)
- ChangeFreq - 1 parameter: Desired frequency (1-6)
- Graphic - 4 parameters: Filename, hue (0-359), direction (2=up, 4=left, 6=right, 8=up), pattern (0-3)
- Opacity - 1 parameter: New opacity (0-255)
- Blending - 1 parameter: New blend type (0=normal, 1=add, 2=subtract)
- PlaySE - 1 parameter: Name of the Sound Effect (SE) file to play
- Script - 1 parameter: Script to run
- ScriptAsync - 1 parameter: Script to run, except that the move route does not wait for its completion

The function adds a ThroughOn command at the beginning and a ThroughOff command at the end of the move route. This function returns immediately and does not wait for the move route to complete. This function's return value is the generated move route (RPG::MoveRoute).

## Configuring the Server

The following is a guide for using the new server in Pokémon Essentials (as of September 1, 2008), as used in the online trade system. For those interested, the protocol document details the protocol used.

The very small server, 32 KB, was written in C# using the .NET Framework 2.0. It uses the Microsoft Access database driver that is included in the .NET Framework. To begin, copy the files in Server.zip to an empty folder and open netserver.xml (in Notepad) to configure the details of the server used to listen for connections:

- The hostname (IP) can either be a subdomain, an IP address, or the special value "localhost", which stands for the local computer. Using a subdomain allows you to hide the IP address of your server, since the subdomain is less likely than the IP address to change.
- The port (port) can be any number from 1 through 65535; the number 4000 appears to be a fine choice.

Enter the hostname and port and save the file. Then run netserver.exe and you're all finished. (It should say that the server is using the specified IP address and port.) The source code to the server is included in Source.zip.

### Publishing the Server

There are two ways to make the server available for others for use. The easier way is to use a program called "Hamachi".

1. Download "Hamachi" and install it. You should choose the "Basic" configuration during the installation process.
2. After installing Hamachi, run it and follow the instructions until you create a Hamachi network. Then, use the IP address found at the top of the Hamachi window in the netserver.xml file.
3. If necessary, you should disable any firewalls you have.

There is also a more difficult way to publish the server, which is detailed here.

1. Create an account on DynDNS.com. After doing so, log in, choose a hostname (subdomain), choose "Use auto detected IP address" in the IP address section, and finally choose "Create Host". Use the hostname generated in this step in the netserver.xml file.
2. Choose a port from 1 through 65535, such as 4000. Use this page to find your router, and follow the instructions to forward the selected port to allow its use by outsiders. (You can also forward other ports in the same way, such as the HTTP port 80.) If you don't have a router, skip this step. If your router is not listed, please contact your Internet Service Provider.
3. If necessary, you should disable any firewalls you have.

Finally, add an entry to "servers.txt" containing the hostname and port determined in the preceding steps. An example of such a line is: "xxx.xxx.net:4000" or "111.222.33.44:4000".

## History

### January 9, 2008

Accent marks added where appropriate

Changes and fixes to better support different window sizes

Better support for animated GIF files and animated images

Option screen is now more extensible

Added the hidden move Chatter

Maps copied to the Data folder are automatically imported

Day/night cycle changes depending on the season

Improved recording support

Backgrounds and title screen now supports animated images/GIFs

### December 14, 2008

Honors 'Change Save Access', 'Change Menu Access' and 'Change Encounter' event commands, as well as Button Input Processing

Bug fixes

Added support for 'Game Over' event command

Pause arrow

### October 4, 2008

More improvements to dependent event system, removed map limitation for partner trainers

Allowed changes to maximum level

### September 22, 2008

Fixed bugs that hindered playing from encrypted archives

Reimplemented dependent events feature

Changed text display algorithm

Added feature to delete save files

Disallowed running within caves and indoor maps

### September 14, 2008

Added support for animated panoramas and fogs

Allowed GIF files to be used as pictures in event commands

Added documentation regarding publishing the server

Fixed bug in tilemap for certain maps

Added mechanism for changing the battle background for a single battle (see documentation for details

### September 1, 2008

Stabilized and updated online trade system and replaced Ruby server with a new C# server

Moved advanced topics to a separate "Advanced Topics" file, made editing metadata.txt deprecated

### August 8, 2008

Added more speech frames

Improved localization (translation) support

Added section on scenes to the notes

Made editing trainers.txt, encounters.txt, and trainernames.txt deprecated

### July 10, 2008

More message system improvements

Toned down the nighttime color

Performance improvement with thread priorities

### July 1, 2008

### June 24, 2008

Added a very simple Pokémon lab example

Prevented throwing an error if the player has no Pokémon

Added support for common battle animations: "Common:StatUp", "Common:StatDown", "Common:Burn", "Common:Frozen", "Common:Poison", "Common:Sleep", "Common:Paralysis", and "Common:Confusion"

Made Audio.dll optional

Improved sandstorm animation a little

### June 1, 2008

Added a very simple Gym example

Added support for Recover All event command

Miscellaneous fixes and improvements

### May 25, 2008

- Fixed bug where reflection can extend off the water for larger sprites.
- More improvements to message system
- Fixed bug where Pokémon can earn more effort values than the maximum, thus preventing wild stat changes

### May 21, 2008

Improved on the message system and added instructions for incorporating the message system into other projects.

### May 15, 2008

New name entry system, implemented "Area" feature of the Pokedex.

### May 2, 2008

- Restructured game system for more extensibility
- Implemented roaming Pokémon mechanism (Latios, Raikou, etc.). See PokemonRoaming to learn how to set it up. This component is optional.
- Improved Poke Radar. The Poke Radar component is now optional.
- Fixed animation bug where animation didn't reverse
- Added two functions to game editor
- Implemented in-game trade events

### April 26, 2008

Implemented Poke Radar; rewrote Bitmap Caches to avoid memory problems; made Trainer Pokémon stronger than wild Pokemon. Implemented Spinda's Spots; improved battle AI in Pokemon-switching decisions.

### March 1, 2008

Another maintenance release. Included an editor for easy access to the game settings without opening RPG Maker XP.

### February 19, 2008

Just a maintenance release, no features were added. Code was changed and scripts added to make Pokémon Essentials compatible with RGSS 2, and moved trainer, item, and species constants to a separate data file, to prevent problems that can occur when a project is saved. Also, the Audio DLL was modified to help fix a bug in playback.

### February 11, 2008

- Fixed EXP gain animation problem
- Changed first map in demo to give more information in-game
- Added more formatting codes to message system
- Added debug option for teaching moves
- General memory fixes and improvements

### February 3, 2008

- More battle transitions added
- Hidden move animation and fishing animation
- Support for double wild battles and partner trainers
- Fixed potential problem where a wild encounter can run even if an event triggers on grass
- Fixed bugs in storage system
- Fixed bug where defining custom moves for a trainer causes an error

### January 24, 2008

- Increased number of storage boxes to 40
- Improved custom Tilemap's performance in large maps
- Changed font installation code
- Message system now supports "Change Text Options" event command
- Fixed bug in 640x480 mode where battle transitions were improperly displayed
- Fixed Revival Herb bug where it restored half HP and not full HP.
- New GifSprite class supports loading GIF images and animations
- Fixed bug that causes error after losing a Trainer battle

### January 19, 2008

- Fixed default map view to synchronize water animation, etc. in connected maps
- Added mechanism to define custom moves
- Changed code to make Pokémon pictures larger than 128x128 display properly.
- Reorganized script section PBTypes and added comments
- New feature checks the battery on laptop computers and gives a warning

### January 14, 2008

- Audio module was replaced with a custom one
- More changes to adapt to "Graphics.width/ Graphics.height" convention
- Various bug fixes in data compiler
- Fixed bugs in animation generation routine
- Added option "Use PC" to debug menu
- Input module was replaced

### January 6, 2008

- Fixed bug where trainer battle intro music lingers in battle
- Move tutor support added
- Improvements in visual editor:
  - Full-color miniature maps
  - Canvas can be dragged
  - Global metadata is available by double-clicking
- More detailed error reporting in data compiler
- Events are stabler while walking in 240x160 mode
- Adopted "Graphics.width/Graphics.height" convention in script code, based on RGSS2
- Added "Quick Hatch" and "Trainer types" to debug menu
- Added more features to Pokémon debug menus
- Mechanism for defining custom TMs and HMs

### January 1, 2008

- Fixed bug in data compiler for generated trainer type data
- Fixed bugs in item storage system
- Added the Town Map as an item
- Incorporated Wichu's changes to PokemonWeather and PokemonRegionMap
- Solved problem where changed weather was not applied when game is reloaded
- Added item handlers as a way of implementing new items
- Female and male signs were added to Pokémon fonts; Nidoran species were renamed accordingly
- Nightly music, thanks to Wichu

### December 28, 2007

- Small changes to trade system
- Small change to variable section in debug menu
- Implemented mail and the mailbox
- Added more features to message system
- Changed money loss method to make it less grave; money won was set for each trainer type
- Added a special script-based transition system
- Changed first screen and project title to "Pokemon Essentials"
- Small bug fix in rubyscreen.dll
- Pressing `F8` will take a screenshot of the game
- Implemented item storage
- Implemented the player's PC

### December 24, 2007

- Changes in trainer event system for supporting move routes, etc.
- Fixed performance bug in evolution animation
- Many edits to server and trade system, released protocol and included server
- Fixed bug when game causes error after storing Pokémon in daycare

### December 19, 2007

- Restructured the documentation and created an HTML Help version.
- Defined "counter events"
- Implemented the Safari Zone
- Implemented the Bug Catching Contest
- Added debug menu option for setting the player's money
- Begun to add comments to scripts within event commands, explaining what they do.

### December 14, 2007

- Implemented online trade system with Netplay 2.0
- Support for recording and playing back battles
- More bug fixes in battle system
- Added shift/summary menu to in-battle Pokémon list
- Fixed bug where day/night land encounters failed to work properly (for real this time, I hope)
- Fixed bug where starting a new game can fail during the running of an event

### December 9, 2007

- Made evolution and load screens "skinnable".
- Forced map to update to reflect changes in terrain tag editor
- Added character sprites for some Trainers
- Implemented Battle Tower/Battle Palace
- Various bug fixes in battle system (such as Choice Band)
- Added a game option to change the speech frame

### December 3, 2007

- Implemented the phone function
- Included a simplified way to add Trainer events
- Made sliding on ice a little more realistic
- Made walking in grass a little more realistic
- Combined Interpreter scripts into one section
- Fixed bug in data compiler where day/night land encounters failed to work
- Fixed subtle bug in jumping function
- Implemented AI in double battles
- Changed name entry screen and made that and other screens "skinnable"
- Can now convert RPGXP animations to battle animations; implemented a mechanism for custom move animations

### November 23, 2007

- Moved background music code to PokemonUtilities and made music event commands work with that code.
- Added more battle sounds
- Made tileset editor more reliable with RPGXP.
- Added Pokeball graphics and catch animations
- Replaced encounter editor with a much more versatile visual editor
- New look for Pokegear thanks to OblivionMew
- Fixed bug where wrong base EXP values were used
- Improved path functions in animation editor

### November 13, 2007

- Day/night land encounters
- Moved all custom data files to Data instead of PBS
- Integrated animation editor in the debug menu
- Modified Shadow script to work properly in connected maps
- Added more screen size options
- Changed main procedure to handle hanging programs
- Added face support to the message system.

### November 6, 2007

- Added all Pokémon new to the fourth generation
- Outdoor and indoor light sources
- Game data is compiled only when necessary upon test runs, included compile function and map warping in debug menu
- Added a duel minigame similar to Alael's on RMXP.ORG (may be used, e.g., after defeating a Gym Leader but before conferring a Badge)
- Added a way to cancel events designated as cut scenes using F5
- Modified Pokémon screen to support choosing multiple Pokémon
- Removed all unused scripts in the distribution
- Modified intro screen

### October 30, 2007

- Added encounter editor in Debug menu
- Fixed bug where surfing ends unexpectedly between connected maps
- Fixed bug in custom tilemap where a black line can appear between connected maps
- Added Ice terrain tag (12)
- Added more box graphics and included ability to jump to and rename boxes
- Added more evolution types and included support for custom evolution types
- Fixed bug where save file can fail to load in connected maps
- Corrected placement of Pokémon sprites in battle
- RegionalNumbers setting in pokedex.txt

### October 26, 2007

- Implemented use of items by enemy Trainers
- Fixed bug where encounters were assigned to the wrong maps when they were connected
- Added predefined colors and multiple choice support to the message system
- Added a Map View option, which includes a new Perspective Tilemap
- Added Switch/Variable settings to Debug menu and made Debug menu accessible with F9
- Added more terrain tags and included location-appropriate battle backgrounds

### October 23, 2007

- Removed dependency on RGSS-RTP
- Added Trainer battle victory music settings in metadata.txt and trainernames.txt
- Implemented hidden items and Itemfinder
- Implemented Synchronize
- Added support for temporary self switches in events, as well as event-specific variables
- Added usage of items in and out of battle to items.txt
- Implemented robust, stand-alone door events
- Implemented events that are active only once a day (for fruit-bearing trees, etc.)
- Changed day/night tinting code to allow "Change Screen Color Tone" to work properly
- Redefined "Change Gold" to act on Trainer's money
- More performance changes in map connections feature

### October 20, 2007

- Implemented abilities that trigger on direct attacks
- Added custom music function to Pokegear radio
- Fixed bug where item GUARDSPEC wasn't defined
- Fixed bug where Repel step count wasn't decreasing
- Fixed bug where Flash darkness sprite disappeared after Pokegear was closed
- Fixed bug where trainer music failed to be set
- Added support for a new format for windowskins
- Improved performance of custom Tilemap class even more
- Some performance changes in map connections feature
- Using predefined Tilemap instead of custom Tilemap in 480x320 screen size

### October 14, 2007

- Added rudimentary support for battle animations
- All documentation for Pokémon Essentials is in one place, the notes.html file
- Added Running Shoes flag; now running is allowed only when the player has Running Shoes; use the script $PokemonGlobal.runningShoes=true
- Added the Battle Scene option to the option screen.
- Added cries for each Pokemon.
- Implemented the Pokerus virus.
- Made statuses display in battle and in the summary screen.

### October 6, 2007

- Stabler Tilemap class -- Tile displacement problem was eliminated
- Trainer battles can be skipped in playtests by holding CTRL
- Internationalization support -- Texts can be extracted and compiled for localization
- Battle start transition included
- Finer day/night tinting
- WildBattleBGM and TrainerBattleBGM metadata classes
- Move speed problem fixed
- Title background music is set to that in the System tab of the database
- The Bag is no longer filled automatically in playtesting; instead use the "Fill Bag" option in the Debug menu.

### October 2, 2007

- Implemented the hidden moves Waterfall, Dive, and Flash
- Improved performance of redefined Tilemap class
- Removed 386-species limit; now any number of species is possible
- For demonstration, the Pokémon Spiritomb is included
- Included metadata setting for running, surfing, and diving sprites

### September 28, 2007

- Support for the hidden moves Fly and Headbutt
- Flameguru's Pokegear script included
- Customizable region maps
- Script support for double battles and multi battles
- Debug menu option with integrated terrain tag editor
- Problems fixed with Rare Candy
- Problem fixed on player placement after jumping
- StorageCreator metadata setting added
- MapPosition metadata setting added
- Combined PokeBattle_Move_XX scripts into PokeBattle_MoveEffects

### September 15, 2007

A Pokedex screen, a Pokémon Mart screen, evolution support, a finished summary screen, as well as the Name Rater and Move Deleter. Also a method to add custom items to the game.

### September 7, 2007

First release