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.

For reference material on the scripts, see the script documentation page.

Notes for Pokémon Essentials

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.

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, 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

If you haven't changed any of the scripts, you can easily upgrade by copying the files Scripts.rxdata and EditorScripts.rxdata in the Data folder to your project's Data folder, then running Editor.exe or running the game from RPG Maker™ XP.

Problem when opening project

If you are using RPG Tsukuuru XP in Japanese and you can't 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.

Common Questions

How do I create a Poké Mart?

To create a Poké 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é 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 give that rival a name?

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 the player didn't visit a Pokémon Center yet, he or she goes to the "home point". To set the "home point", open editor.exe, then choose "Set Metadata", then "Global", then "Home".

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.

See the section "Allowing a Player to Lose a Trainer Battle" if you want the player to stay at the same place after losing a Trainer battle.

How do I create an animated title screen?

There are many ways to create a title screen, and the Scene_Intro script in Pokemon Essentials is just one example. Please see the section Title Screen, which shows the basic form of a title screen. You should 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 is intentional. It happens only when you run the game from RPG Maker™ XP. It won't happen when you run the game normally. Please see Playtesting Functions for more information.

How can I change the color of in-game text?

To change the color of the text displayed in battle, open the Script Editor, and go to the script section PokeBattle_ActualScene. Then, look for lines like these.

MESSAGEBASECOLOR=Color.new(248,248,248)
MESSAGESHADOWCOLOR=Color.new(104,88,112)
MENUBASECOLOR=Color.new(72,72,72)
MENUSHADOWCOLOR=Color.new(208,208,208)
BOXTEXTBASECOLOR=Color.new(64,64,64)
BOXTEXTSHADOWCOLOR=Color.new(216,208,176)

These colors define the "base" color and "shadow" color for message boxes, command menus, and status boxes, respectively. The numbers in parentheses give the red, green, and blue color components of each color. You can edit these numbers in any way you want.

To change the color of text messages, menus, and so on, open the Script Editor, and go to the script section SpriteWindow. Then, look for the following lines:

LIGHTTEXTBASE=Color.new(31*8,31*8,31*8)
LIGHTTEXTSHADOW=Color.new(23*8,23*8,23*8)
DARKTEXTBASE=Color.new(12*8,12*8,12*8)
DARKTEXTSHADOW=Color.new(26*8,26*8,25*8)

Edit the colors in the same way as mentioned above. LIGHTBASECOLOR and LIGHTSHADOWCOLOR are used when text is displayed on a dark background. DARKBASECOLOR and DARKSHADOWCOLOR are used when text is displayed on a light background.

Map Making

Map making in Pokemon Essentials is generally the same as it is for other RPG Maker™ XP games. This section has everything you should know about map making in Pokemon Essentials.

A Note on Scripting

This page can't say everything about how to use the scripting language Ruby. To learn how, see the links in the Ruby language Web site's Getting Started section. For reference material, read the help file included in RPG Maker™ XP. For general information on RPG Maker™ XP and RGSS, please read 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's 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.

Terrain Tags

The following terrain tags are defined:

1: Ledges (Tiles with this tag should have only one valid direction. The player will jump over the ledge in this direction.)
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. To access it, open the Pokémon Essentials Editor (editor.exe), then choose "Edit Terrain Tags."

Ledges

Ledges can be jumped on by the player. They have terrain tag 1, and they can be jumped on only from a certain direction. To set that direction, go to the Tilesets tab of the Database and click Passage (4 dir).

For each tile, sides with arrows on them are passable, and sides with a dot on them are not passable. For example, a tile with an arrow only on the north side and dots on all other sides can be entered only from the north side.

To make a ledge that the player can jump over from west to east, set its Terrain tag to 1, then, in Passage (4 dir), set the tile so that it shows an arrow on the west side and dots on the other three sides. Making a south-to-north ledge, an east-to-west ledge, and so on, follows a similar process.

Couches

Tiles that represent couches should be passable only on the sides and the front of the couch and should not be passable on the back.

See "Ledges" to learn how to make a tile passable only from certain directions.

Expanding the Text Fields

Pokemon Essentials includes a utility (expandtext.exe) for expanding the Show Text, Script, Comment, and Batch Text Entry dialog boxes of RPG Maker™ XP. Start RPG Maker™ XP if it isn't running, then start expandtext.exe. Then, all dialog boxes with those names will be enlarged to give you more room to enter text, scripts, and comments. In particular, the Show Text box will be expanded to four lines instead of just three.

The Pokemon Essentials editor will also run expandtext.exe automatically.

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, walls, and so on.

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. However, the RPGXP map system ignores tiles without terrain tags when it finds out what terrain tag an area has. In this case, bridge tiles have no terrain tag, but since a water tile is underneath it, the game treats the bridge as terrain tag 7, making the player surf over the bridge. To work around this, define a terrain tag for bridges (the neutral terrain tag 13 is designed for this purpose). To change the terrain tag, open "editor.exe" (the Pokemon Essentials Editor), then choose "Edit Terrain Tags."

Game freezes during movement

You may have this problem when an event has a move route followed by a "Wait for Move's Completion" command, but the event can't move. To solve this problem, do the following.

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. Then test whether it works.
Are any events blocking the way? If so, move them using the Set Event Location event command. Then test whether it works.
Add "Through ON" to the beginning of the event's move route, and add "Through OFF" to the end of the move route. Then test whether it works.
Enable the setting "Ignore If Can't Move" for the event's move route.

Starting Position

You can't change the player's starting position to any map other than the introduction, unless you've used a script to set up the player (see "Intro Screen" for more information). Otherwise, the game system won't work.

Dungeons

Pokemon Essentials includes support for so-called dungeons. The layout of a dungeon changes each time the player enters it. To make a map a dungeon, open the Pokemon Essentials editor (editor.exe), choose Set Metadata, select the map, and finally set the "Dungeon" setting.

A dungeon uses three different autotiles:

Autotile 1 - Ceiling of the wall (should not be passable). An example of a suitable ceiling is the image Graphics/Pictures/wall.bmp.
Autotile 2 - Floor (should be passable). An example of a suitable floor is the image Graphics/Pictures/AutoTile n8p.png.
Autotile 3 - Wall (should not be passable). An example of a suitable wall is the image Graphics/Pictures/wall2.bmp.

You can place events anywhere on the dungeon map. The game will place them randomly on the dungeon floor when it generates the dungeon. However, you should include an event that moves the player to a new map. Otherwise, the player can't leave the dungeon. Also, the player's starting position should not be placed on a dungeon map.

The minimum recommended size for a dungeon is 40x40 pixels.

Other than these rules, dungeon maps are the same as any other maps. You can set encounters, background music, and other metadata of a dungeon map as normal.

Configuration Files

Many aspects of the game are defined in several text 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
types.txt - Data on types
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 game system will compile the configuration text files into an internal format when you run the game from RPG Maker™ XP or set the $DEBUG global variable within a script. This compilation usually happens only if the text files have changed after the last run of the game. However, you can force it 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 Pokémon 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/types.txt

This text file describes each Pokémon type. The file is divided into sections, and each section's title is the type's ID enclosed by two square brackets like this: [5]

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 - Required. Name of the type.
InternalName - Required. Internal name of the type.
IsPseudoType - Optional. Specifies whether the type is a pseudotype for special situations, such as "???". Either true or false.
IsSpecialType - Optional. Specifies whether the type is a special Pokémon type, rather than a physical Pokémon type. Either true or false. If not given, the type is physical. Normally, though, physical and special moves are not classified according to type.
Weaknesses - Optional. A comma-separated list of the internal names of Pokémon types that are "super effective" against Pokémon of this type.
Resistances - Optional. A comma-separated list of the internal names of Pokémon types that are "not very effective" against Pokémon of this type.
Immunities - Optional. A comma-separated list of the internal names of Pokémon types that are ineffective against Pokémon of this type.

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 Pokémon.
InternalName - Internal name of the Pokémon.
Kind - The kind of Pokémon.
RegionalNumbers - Optional. 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. 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. 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.
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 you leave out this setting, this Pokémon has a single type.
Height - Height in meters, rounded to the nearest tenth of a meter. (Use a period for the decimal point, and don't use commas for thousands.)
Weight - Weight in kilograms, rounded to the nearest tenth of a kilogram. (Use a period for the decimal point, and don't use commas for thousands.)
GenderRate - Gender rate of the Pokémon. One of FemaleOneEighth, Female25Percent, Female50Percent, Female75Percent, AlwaysMale, AlwaysFemale, or Genderless. This value should be FemaleOneEighth for the first Pokemon that the player receives in a game (such as Bulbasaur, Cyndaquil, or Mudkip).
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. In general, the rarer or heavier the species is, the lower this value. This value should equal 3 if the Pokemon is "legendary."
BaseEXP - Base experience. A higher number means the Pokémon gains more experience upon defeating a Pokémon of this species. 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. Use the Parabolic growth rate for the first Pokemon that the player receives in a game (such as Bulbasaur, Cyndaquil, or Mudkip). Use the Slow growth rate if the species is "unique".
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 can't breed. In general, these numbers should be the same for each species in the same line of evolution. However, for baby Pokemon that previously weren't the lowest evolutionary form (e.g. Azurill, Pichu, Wynaut) these two numbers should each equal 15.
- Meaning of each number: 1="Monster"; 2="Water1" (sea creatures); 3="Bug"; 4="Flying", 5="Ground", 6="Fairy", 7="Plant", 8="Humanshape", 9="Water3" (shellfish), 10="Mineral", 11="Indeterminate" (ghosts, having no defined shape), 12="Water2" (fish), 13="Ditto", 14="Dragon"
EffortPoints - Effort values for HP, Attack, Defense, Speed, Special Attack, and Special Defense, earned when a Pokémon of this species is defeated. A comma-separated list of six numbers, each ranging from 0 through 3. In general, these values should correspond to the base stats for this species. The total of all six values should be 1, 2, or 3 (1 for Pokemon at evolution stage 1; 2 for Pokemon at stage 2; and 3 for Pokemon at stage 3).
Abilities - One or two abilities possible for this species. For the first Pokemon a player receives in a game, this value traditionally equals OVERGROW for Grass types, BLAZE for fire types, and TORRENT for Water types.
Moves - 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 groups of three entries each, 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	Notes
Happiness	---	Evolves if happiness is 200 or greater.
HappinessDay	---
HappinessNight	---
Level	Level	Most Pokemon evolve in this way.
Trade	---
TradeItem	Item's internal name	Evolves if holding the specified item after it is traded.
Item	Item's internal name	Evolves if the player uses the specified item on it.
AttackGreater	Level	Evolves if its Attack is greater than its Defense after it levels up.
AtkDefEqual	Level	Evolves if its Attack and Defense are equal after it levels up.
DefenseGreater	Level	Evolves if its Defense is greater than its Attack after it levels up.
Silcoon	Level	Special evolution type for species that can evolve in one of two forms that is predetermined upon creation of the Pokemon.
Cascoon	Level	Special evolution type for species that can evolve in one of two forms that is predetermined upon creation of the Pokemon.
Ninjask	Level	Special evolution type for species that create a duplicate of a Pokemon in another species. This is the evolved form.
Shedinja	Level	Special evolution type for species that create a duplicate of a Pokemon in another species. This is the species of the duplicate Pokemon.
Beauty	Minimum Beauty	Not implemented in Pokemon Essentials, since the game system has no concept of Beauty, Toughness or other Pokemon Contest aspects.
ItemMale	Item's internal name	Evolves if the player uses the specified item on it and it's male.
ItemFemale	Item's internal name	Evolves if the player uses the specified item on it and it's female.
DayHoldItem	Item's internal name	Evolves if it's holding the specified item and it's day.
NightHoldItem	Item's internal name	Evolves if it's holding the specified item and it's night.
HasMove	Move's internal name
HasInParty	Species's internal name
LevelMale	Level	Evolves only if male.
LevelFemale	Level	Evolves only if female.
Special1	-	Reserved.
Special2	-	Reserved.
Special3	-	Reserved.
Custom1	Number from 0 through 65535	See below for more on custom evolution types.
Custom2	Number from 0 through 65535	See below for more on custom evolution types.
Custom3	Number from 0 through 65535	See below for more on custom evolution types.
Custom4	Number from 0 through 65535	See below for more on custom evolution types.
Custom5	Number from 0 through 65535	See below for more on custom evolution types.
Custom6	Number from 0 through 65535	See below for more on custom evolution types.
Custom7	Number from 0 through 65535	See below for more on custom evolution types.

Example:

OMASTAR,Level,40
VILEPLUME,Item,LEAFSTONE,BELLOSSOM,Item,SUNSTONE
ESPEON,HappinessDay,,UMBREON,HappinessNight,
SHELLDER,HasInParty,

Pokemon Essentials intentionally doesn't include evolution entries for Glaceon, Leafeon, or Probopass because these three species are obtained only if the player is in a certain place (that is, map), which can't reliably be verified in Pokemon Essentials without more.

For the custom evolution types, the number given serves 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. An example of code for an example evolution type, where a Pokémon species evolves if it is raining, follows:

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 - 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 not used anymore because Technical and Hidden Machines are now supported differently, see PBS/tm.txt and Technical Machine.
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. This number can be negative.
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. This number can be negative.
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. For scripting experts: To add a function code not defined in that page, open the script section PokeBattle_MoveEffects and add a so-called move effect class for that function code.
Field 5: Base damage.
Field 6: Type.
Field 7: Move category, either Physical, Special, or Status. As of the January 19, 2008 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. (Physical attacks represent brute force, while special attacks represent magic.)
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
- 02 - Opposing Pokémon selected at random
- 04 - All opposing Pokémon
- 08 - All Pokémon other than the user
- 10 - User
- 20 - Both sides
- 40 - User's side
- 80 - Opposing Pokémon's side
- 100 - User's partner
- 200 - User or user's partner
- 400 - Single Pokémon on opponent'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. Any combination of the following letters:
- 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. Direct attacks (flag a) that use the attacker's body (such as punches, kicks, and tail swings), and nondirect attacks that represent pure elemental attacks like fire and water, don't have this flag.
Field 14: Contest type, either Cool, Beauty, Cute, Smart, or Tough.
Field 15: Description of the move. 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.

PBS/items.txt

This file stores data on each item in the game. You can also use the "Edit Items" option in the Pokemon Essentials Editor (editor.exe) to edit items. For examples, see "Adding New Items".

Implementing New Items

The following describes an advanced scripting feature.

New items are implemented by registering item handlers with the game system. Item handlers are scripts that control how a particular item works.

Fields 7 and 8 of items.txt give the moments where a player can use a certain item. These fields determine which handlers an item should implement. There are six different item handlers that are called whenever the player tries to use an item:

ItemHandlers::UseFromBag.add(item,proc) - Registers the item handler _proc_ for an item that the player can use directly from the Bag, such as a bicycle, Repel, or the Town Map. The game calls this item handler after the player selects the item from the Bag screen. Parameters:
- _item_ - item to use
Returns one of the following: 0 = Item not used; 1 = Item used, don't end screen; 2 = Item used, end screen; 3 = Item used, consume item; 4 = Item used, end screen and consume item.
ItemHandlers::UseInField.add(item,proc) - Registers the item handler _proc_ for an item that the player can use on the field by pressing F5. The game calls this item handler after the player presses the F5 key or after an "addUseFromBag" item handler returns 2 or 4 (item used, end screen). Parameters:
- _item_ - item to use
ItemHandlers::UseOnPokemon.add(item,proc) - Registers the item handler _proc_ for an item that the player can use on a Pokemon. The game calls this item handler after the player chooses a Pokemon. Parameters:
- _item_ - item to use
- _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 like this: scene.pbDisplay(_INTL("Message."))
The item handler returns true if the item was used successfully, and false otherwise.
ItemHandlers::BattleUseOnPokemon.add(item,proc) - Registers the item handler _proc_ for an item that the player can use on a party Pokémon while in battle. Examples include Potion, Revive, and Full Heal. The game calls this item handler after the player chooses a Pokemon. Parameters:
- _item_ - item to use
- _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 successfully, and false otherwise.
ItemHandlers::BattleUseOnBattler.add(item,proc) - Registers the item handler _proc_ for an item that the player can use on an active Pokémon. Examples include X Attack and Guard Spec. The game calls this item handler after the player selects the item from the Bag screen. Parameters:
- _item_ - item to use
- _battler_ - Battler the item will be used on (type: PokeBattle_Battler)
- _scene_ - Bag screen (type: PokemonBagScreen).
The item handler returns one of the following: false - item not used; true - item was used
ItemHandlers::UseInBattle.add(item,proc) - Registers the item handler _proc_ for an item that the player uses in battle. Examples include the Poké Ball, Poké Doll, and Poké Flute. The game calls this item handler after the player selects the item from the Bag screen, the Bag is closed, and the game returns to the battle screen. Parameters:
- _item_ - item to use
- _battler_ - Battler the item is used on (type: PokeBattle_Battler)
- _battle_ - Battle object (type: PokeBattle_Battle).
The item handler doesn't return a value.

The script section PokemonDefaultItems includes item handlers for all items included by default in Pokemon Essentials. To implement an item handler, go to the Script editor, insert a new script section just before the last one, and write the code for the item handler.

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"Cake", which restores 30 HP. For completeness, it implements all five item handlers.

# Handlers implemented
ItemHandlers::UseFromBag.add(
 :CAKE,
 proc{|item,pokemon,scene|
  pbHPItem(pokemon,30,scene)
 }
)
ItemHandlers::BattleUseOnBattler.add(
 :CAKE,
 proc{|item,pokemon,battler,scene|
  pbBattleHPItem(pokemon,battler,30,scene)
 }
)
# Handlers not implemented
ItemHandlers::UseFromBag.add(
 :CAKE,
 proc{|item| 0; }
)
ItemHandlers::UseInField.add(
 :CAKE,
 proc{|item| 
  Kernel.pbMessage(_INTL("Can't use that here."))
 }
)
ItemHandlers::BattleUseOnPokemon.add(
 :CAKE,
 proc{|item,battler,scene| false; }
)

PBS/trainernames.txt

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

PBS/trainers.txt

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

PBS/tm.txt

Very simple file. This file is a list of moves and the Pokemon 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. However, the map should be drawn in terms of 16x16 tiles. The example map included is the map of Hoenn. You can get a good idea on how the Town Map Editor works when you fill in the map.

Start by clicking any point on the map; for instance a city. Then fill in details about the point:

Name: Name of this point.
Point of Interest: Name of a point of interest this point describes.
Healing Spot: This field specifies the map ID of a town where a Pokémon Center or similar healing spot is located, followed by and the X and Y coordinates of that healing spot's entrance. These three values are separated by commas. This is where the player will travel to when the player uses Fly, but only if he or she has already visited it.
Switch: If you enter a number here, the point won't be shown until the switch with this number is on. This number is one of the switches in RPG Maker™ XP. You would set this, for example, if this is a location outside of the main storyline, where special Pokémon can be found.

After completing the fields, click Save. You can now see the point in the text below the Save button. Copy and paste this text to townmap.txt after you are done with the editor. You can put the text in a new or existing section of that 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 in brackets) onto the big text box and click Load to start editing again.

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 the point describes. 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 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. If you click on the canvas, the object will appear 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:Shadow - When a shadow Pokémon enters battle.
- Common:StatUp - When something raises a Pokémon's stat.
- Common:StatDown - When something lowers a Pokémon's stat.
- 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.
- Common:Poison - When a Pokémon is poisoned.

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's 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 basic 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
@>

On the other hand, the event could look like this:

@>Comment: Initializes the player character.
@>Script: pbTrainerName("ASH")
@>Comment: Stops autorun event
@>Control Self Switch: A =ON
@>Comment: Transfers player to start position
@>Transfer Player:[011: Test Map], (009, 009), Down
@>

Use the script pbTrainerName("name"), where name is any name, to initialize the player Trainer with a particular name rather than a player-defined name.

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

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.

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.

All image resources in this section can be animated images and can have a file extension other than ".png".

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 at least 128x128 pixels.
Graphics/Battlers/XXXs.png - Shiny (different-colored) front of the Pokémon. Measures at least 128x128 pixels.
Graphics/Battlers/XXXb.png - Back of the Pokémon. Measures at least 128x128 pixels.
Graphics/Battlers/XXXsb.png - Shiny (different-colored) back of the Pokémon. Measures at least 128x128 pixels.
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.

Putting the letter 'f' after the number represents the female version of the sprite. Example: Graphics/Battlers/235fs.png. Putting the symbol '_' followed by a number represents an alternate form of the same species. Example: Graphics/Battlers/201b_4.png

Placement of Sprites

To ensure optimal placement of Pokémon sprites in battle, you should open the Pokémon Essentials editor (editor.exe) and select "Reposition Sprites" from the menu.

Alternate Forms

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

Many other well-known species have alternate forms as well. Such forms are implemented in the script section PokemonMultipleForms. The numbers for these forms are shown below:

UNOWN: 0-25 = A through Z; 26 = !; 27 = ?.
SHELLOS, GASTRODON: Can be 0 through 1. If the Pokemon was created in a map given in the array of map IDs in the script section PokemonMultipleForms, the Pokemon's form is 1; otherwise 0.
DEOXYS: 0 = Normal Forme; 1 = Attack Forme; 2 = Defense Forme; 3 = Speed Forme.
BURMY, WORMADAM: 0 = Plant Cloak; 1 = Sandy Cloak, 2 = Trash Cloak.
ROTOM: 0 = Normal; 1 = Heat Rotom; 2 = Wash Rotom; 3 = Frost Rotom; 4 = Fan Rotom; 5 = Mow Rotom.
GIRATINA: 0 = Altered Forme; 1 = Origin Forme.
SHAYMIN: 0 = Land Forme; 1 = Sky Forme.
ARCEUS: 0 = Normal Forme; 1 = Fighting; 2 = Flying, 3 = Poison, 4 = Ground, 5 = Rock, 6 = Bug, 7 = Ghost, 8 = Steel, 10 = Fire, 11 = Water, 12 = Grass, 13 = Electric, 14 = Psychic, 15 = Ice, 16 = Dragon, 17 = Dark.

For some species, the form changes automatically. For others, the form changes only in response to an event. To change a Pokemon's form manually, use a script like the following:

pokemon.form = form_number

where form_number is the number for the alternate form. Of the species shown above, only Deoxys, Shaymin, and Rotom must have their form changed manually.

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 has 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.

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

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

$PokemonGlobal.nextBattleBack="XXX"

where XXX is an arbitrary identifier. Here's 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"

The script code above should be placed only immediately before an event command that would run the wild Pokemon battle or Trainer battle; using an autorun or parallel process event is not recommended for this purpose, as the effect will linger even if the player leaves the map. To set the battle background for an entire map, open the Pokemon Essentials editor (editor.exe) and set the "BattleBack" setting in the map's metadata (using the Set Metadata option).

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 they can be animated image files, including animated GIF files (even with an extension of 'gif').

Pokémon Types Image

Images for all Pokémon types is found in Graphics/Pictures/types.png. The types are arranged by ID number, as defined in the file PBS/types.txt.

Titles

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

Windowskins

Pokémon Essentials supports windowskins in RPG Maker™ XP (RGSS) and RPG Maker™ VX (RGSS2) format.

Pokémon Essentials also 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.

RGSS2 Windowskin Format

Windowskins in RPG Maker™ VX are similar to those in RPG Maker™ XP. However, these windowskins have a different format, which is explained below. For an example, look at the file Window.png in the Graphics/Windowskins/ folder.

A windowskin file is 128x128 pixels in size.
The top left part of the skin (64x64) is the background, drawn on the window.
The bottom left part of the skin (64x64) is a pattern which is drawn tiled on top of the window background.
The top right part of the skin (64x64) consists of the window's borders and scroll arrows. In Pokemon Essentials, however, scroll arrows are not shown.
The bottom right part of the skin (64x64) is itself divided into three parts. The top left (32x32) consists of the cursor, a rectangle which is placed over the currently selected command. The top right (32x32) is the pause arrow, an animation of four 16x16 frames. Pokemon Essentials doesn't show the cursor or pause arrows. The bottom (64x32) consists of the colors used when drawing text on the window.

Events

Pokémon Essentials comes with many predefined events for your use. Pokémon Essentials also contains many new ways to define special kinds of events that otherwise would take longer to achieve. 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. This means that anything that makes the player leave should move the player at the door and not next to it.

The door character image file should be arranged like this: 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

With Pokémon Essentials, the player can skip or cancel certain events designated as "cut scenes" by pressing F5. In this way, the player can 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. For example, the event could move the player directly to the next destination.

Triggers

Normally, pressing the Action button (the C key) next to an event with a Player Touch trigger will trigger the event. This isn't the case in Pokemon Essentials; the behavior is disabled in order to allow such events, such as boulders, to work more intuitively.

Switches and Variables

Debugging Switches and Variables

In debug mode, you can set switches and variables during a running game by selecting Debug from the main menu and selecting Switches or Variables.

Script-Based Switches

The event system in Pokémon Essentials supports script-based switches, where an arbitrary script is evaluated. If the condition on the switch's name holds true, the switch is on. Script-based switches are distinguished from regular switches using the prefix "s:". Due to the size limit on a switch's name, however, you may have 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 event command like the following:

setTempSwitchOn("A")

or:


setTempSwitchOff("A")

Temporary self switches are currently used in doors. They also have other uses where stand-alone stateful events are desired.

Reserved Variables

Variables 1 through 25 are reserved for internal use by the game system. The values they hold generally never live longer than the event that uses them.

Event-Specific Variables

Each event in the game comes with its own Ruby variable. To retrieve a variable within an event, call the script function "getVariable". 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 Variables

The following functions allow you to implement situations that are valid only for a limited time after they are announced. These situations can include special discounts or an unusual frequency of a rare Pokemon in a certain area. They work by setting an RPG Maker™ XP variable to the current time, then later comparing it against the current time to determine whether it has expired.

pbTimeEvent(variableNumber, ageInSeconds=86400) - Sets the variable numbered variableNumber to the current time. ageInSeconds represents the number of seconds until the variable expires. Default age is 86400 seconds (24 hours).
pbTimeEventDays(variableNumber, ageInDays=1) - Sets the variable numbered variableNumber to the current time. ageInDays represents the number of days until the variable expires. The event will expire at midnight.
pbIsTimeValid(variableNumber) - Compares the variable numbered variableNumber to the current time. Returns true if the time event hasn't expired yet. If the time event has expired, clears the variable's value.

Suppose you're making a character that calls the player at some point. This character asks that player to meet him or her by a certain time, say, in two hours. The character's event could look like this:

Text: \PN! Meet me at ROUTE 158 in two hours.
Text: OK, see you.
Comment: Expires in 2 hours (7200 seconds)
Script: pbTimeEvent(55,7200)

Note the script uses variable 55 to store the current time. You could then place the character in a certain spot and set a script-based switch. That switch would check whether it's still two hours since the event occurred. The event could look like this:

Condition "Switch 's:pbIsTimeValid(55)' is ON", Action Button trigger

Text: Hey, \PN. You're just in time.
Text: Have I got a surprise for you.

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 (or once within a specific time period). Here's 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 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

The game uses this event page while the event is "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. By default, the event will expire in 24 hours. However, you can make it expire earlier or later by renaming the switch. For example, to make the event expire in one hour (3600 seconds, use a switch with the following name:

s:expired?(3600)&&tsOff?("A")

And this example makes the event expire in 2 days, where a "day" begins at midnight:

s:expiredDays?(2)&&tsOff?("A")

Counter Events

A counter event triggers when the player is a number of spaces away from it, even if they can't meet.

A counter event is named Counter(X), where X is the maximum distance for the event to trigger. A counter event also has the Event Touch trigger.

Side Stairs

Side stairs, or 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
  @>

Road Blocks

Road block events are designed to block the player's way. For example, they may keep the player from going to a road that's under construction, or leaving a town without a Pokémon. Road block events have two event pages.

Event Page 1

Trigger: Player Touch
Graphic: None

@>Text: \PN: Wait! I can't leave without a Pokémon!
@>Set Move Route: Player (Ignore If Can't Move)
                       : $>Turn 180
                       : $>1 Step Forward
@>Wait for Move's Completion

The move route command is important. It turns the player back from the road.

Event Page 2

The game uses this event page if a switch is on that disables the roadblock, allowing the event to act like a normal tile. The switch can also be a script-based switch.

Condition: Switch 'Any switch name' is ON
Trigger: Any trigger
Graphic: None

No event commands

Displays

Displays, such as works of art, the directory of a shopping center, or a famous sculpture, are viewable only from the front. To enforce this behavior, use a conditional branch that checks which direction the player is facing. If the display is directed forward, as is usually the case, the branch should check whether the player is facing up, as in this example:

@>Conditional Branch: Player is facing Up
  @>Text:  This is a famous sculpture.
  @>
 : Branch End

Introductions

If an event introduces itself, you should wrap the event commands that introduce the event in a conditional branch. The condition checks whether the event's temporary self switch is off. If so, the game shows the introduction, then, the event sets its temporary self switch to on again. The code below shows this technique.

@>Conditional Branch: Script: isTempSwitchOff?("A")
  @>Text:  Hello, I'm the move tutor.
  @>Text:  Welcome to my place.
  @>Comment: Stop showing the intro again
  @>Script: setTempSwitchOn("A")
  @>
 : Branch End

If the introduction should happen only once in the entire game, then you should use regular self switches instead. This is more appropriate if the character is surprised for having met the player for the first time in a long time:

@>Conditional Branch: Self Switch A == ON
  @>Text:  Hello, I'm the move tutor.
  @>Text:  Welcome to my place.
  @>Comment: Stop showing the intro again
  @>Control Self Switch:  A =ON
  @>
 : Branch End

Random Processing

Randomness allows for events that say a different thing every time the player talks to it. The technique 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

PC

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


Script:  pbPokeCenterPC

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

Script:  pbTrainerPC

To set whether the player has seen the Pokemon Storage System's creator, use the following Script event command.

Script: $PokemonGlobal.seenStorageCreator=true

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).

The game will convert both types of item events 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

Kernel.pbReceiveItem is not a replacement for Kernel.pbItemBall.

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

 $PokemonBag.pbDeleteItem(
    PBItems::POTION
   )

This script command does not display a message.

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
)

These script commands does not display a message.

Adding New Items

You can add new items to your game 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,8,0,"This is a custom Key Item.",0,0

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

Technical Machine

298,TM10,TM10,4,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,4,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. (Note that the price of a Hidden Machine should be 0.)

Regular Item

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

For regular items. The number 2 stands for the Medicine pocket, for items that restore HP, PP, or status problems, or for items that raise stats. Replace 2 with 7 for the Battle Items pocket (items used only in battle), or with 6 for the Mail pocket. For details on the last two numbers, see fields 7 and 8 in the items.txt section in the advanced notes.

Evolution Stone

95,FIRESTONE,FIRE STONE,1,2100,"A peculiar stone that makes certain species of POKeMON evolve. It is colored orange.",1,0

For evolution stones, placed in the Items pocket. When adding a new stone for evolving Pokemon, add the following line to a new or existing script section in the script editor:

ItemHandlers::UseOnPokemon.copy(:SUNSTONE,:ITEMNAME)

Replace ITEMNAME above with the internal name of the new item.

Selling Items

Poké Mart

To set up the Poké 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])
@>

Note that the script includes a list of items in the Poké Mart, separated by commas. Note also that each item begins with PBItems::.

SellItem command

For a convenient way to have an event sell items (for example, selling exotic items or selling common items for less), you can use the SellItem pseudo-command. To use it, put a Comment event command consisting of the text SellItem(ITEM, PRICE) where ITEM is the internal name of the item, and PRICE is the selling price. The game will convert this command to appropriate event commands when you run the game from RPG Maker™ XP. An example follows:

Comment: SellItem(POTION,150)

Trainers

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

A Trainer event usually has 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 you run the game 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 have the chance to define the Pokémon that the Trainer has. The meanings of each supported comment are defined below.

Battle: What 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 gives the introduction text for rematch battles. If there is more than one Battle comment, then the player can register the Trainer in the phone.
EndSpeech: What the Trainer says when the player wins a battle. There can be more than one of these comments.
RegSpeech: What the Trainer says before registering the Trainer's phone number.
EndBattle: What 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 RPG Maker™ XP 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.
DoubleBattle: Enter the word true or yes to make this battle a double battle.
VanishIfSwitch: If the RPG Maker™ XP switch with this number is ON, the game won't show the event.
Backdrop: Sets the battle background for this Trainer battle (see Battle Backgrounds). For example, if this value is "Water", the backgrounds would have filenames of Graphics/Pictures/battlebgWater.png, playerbaseWater.png, and enemybaseWater.png.

Behind the Scenes

Please note that for simple Trainer battles, you can just follow the instructions given above. 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 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's a list of the parameters:

Parameter 1: Trainer type (for example, PBTrainers::CAMPER).
Parameter 2: Trainer's name.
Parameter 3: What the Trainer says when the player wins.
Parameter 4: Optional. Whether the battle is a double battle. The default is false. Before the double battle begins, you must check if the player has only one Pokémon, like this:
```
@>Conditional Branch: Script: $Trainer.ablePokemonCount<=1
 @>Text: But you just have one Pokemon.
 @>Exit Event Processing
 @>
 : Branch End
```
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. You should check the option "Set handling when conditions do not apply" and place commands to run when the player loses 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 just talking to it will start a battle. This is often 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), you should turn on the other event's self switch after the player wins. You can use the script pbSetSelfSwitch(event, switch,value) for this. ( "event" is the event's ID number, "switch" is the switch's name, for example "A", and "value" is true, ON, or false, OFF.)

Double Trainer Battles

To start 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 run when the player wins
  @>
 : Else
  @> -- Event commands to run when the player loses
  @> Exit Event Processing
  @>

 : Branch End

The function's parameters are as follows:

Parameter 1: Trainer 1's Trainer type (for example, PBTrainers::CAMPER).
Parameter 2: Trainer 1's name.
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: What Trainer 1 says when the player wins.
Parameter 5: Trainer 2's Trainer type (for example, PBTrainers::CAMPER).
Parameter 6: Trainer 2's name.
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: What Trainer 2 says when the player wins.
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 how to make Trainers that battle only at night. However, this technique also applies to Trainers that are active only 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 has a partner with him or her. 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. However, you can try making sure two opposing Trainers face each other.

You can combine this feature 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 Back). Trainer backs for partner Trainers and other Trainers are defined in the same way.

Editing Trainers and Battles

To edit Trainers and trainer types, open the Pokémon Essentials editor (editor.exe) and select "Edit Trainers" or "Trainer Types." (To delete a Trainer type or battle, select it and press Z.)

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. 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("EEVEE",25)
  @>Text: Pokémon was received...
  @>
 : Else

  @>Text: Sorry, you have no room...
  @>
 : Branch End
@>

In the example above, "EEVEE" represents the internal name of the Pokemon species, and 25 represents the level of the Pokemon. The Pokemon's species can be given either by its internal name or by its number.

pbAddPokemon will add the Pokémon to either the party or the PC boxes. If the Pokemon was added, it displays a message and allows the player to give the Pokemon a nickname. A similar method, pbAddToParty, will add a Pokémon just to the party.

If you don't want to display messages as the Pokemon is added, you can use the methods pbAddPokemonSilent and pbAddToPartySilent instead.

All four methods mentioned above return true if the game has added the Pokemon, and false if there's no room to add the Pokemon.

Modifying a Pokémon Before Adding It

The following example shows how to create a Pokémon and add it to the Trainer's party. It also shows how the Pokemon's data can be modified before the Pokémon is added, for example by making it shiny (different-colored) or by changing its gender. The example uses pbAddToParty to add the Pokémon. Alternatively, the method pbAddToPartySilent could be used.

@>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
   :      : pbAddToParty(p)
  @>

 : Branch End
@>

Modifying a Pokemon in this way is optional. Another example: Replace "p.makeShiny" above with the following to ensure that the Pokémon always has the move Tackle:

pbAutoLearnMove(p,PBMoves::TACKLE)

If the Pokémon can be stored in the PC boxes in case the party is full, you can use the method pbAddPokemon or pbAddPokemonSilent instead to add the Pokemon, as shown in the example below.

@>Conditional Branch: Script: pbBoxesFull?
  @>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
   :      : pbAddPokemon(p)
  @>
 : Branch End

@>

Adding a Pokémon Owned by Another Person

Use the function "pbAddForeignPokemon" to add a Pokémon owned by another person, like this:

@>Conditional Branch: Script: pbAddForeignPokemon("SHUCKLE",20,_I("MARK"),_I("SHUCKIE"))
  @> --- Pokémon was added ---

  @>
 : 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 player, since the player doesn't own that Pokémon. This method will display a message if the Pokémon was added.

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

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: pbGenerateEgg("TOGEPI",5)
  @>Text: You have no room to store the Egg...
  @>
 : Else
  @>Text: Received a Pokémon Egg.
  @>
 : Branch End
@>

In the example above, "TOGEPI" represents the internal name of the egg's Pokemon species, and 5 represents the starting level of the Pokemon. The Pokemon's species can be given either by its internal name or by its number.

pbGenerateEgg displays no messages and 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) }

A safer way to remove a Pokemon is the pbRemovePokemonAt(X) function, which removes the Pokemon only if the player would still have an unfainted Pokemon left. It returns true if the function is successful, and false otherwise. pbRemovePokemonAt should be used within a conditional branch rather than a Script event command.

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.pokemonParty[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

Note the use of $Trainer.pokemonParty, which ignores eggs, instead of $Trainer.party.

Choosing a Pokémon

In some situations it may be useful to allow the player to choose a Pokémon from the party in order to handle that Pokémon in some way. You can use the pbChoosePokemon function for this purpose:

pbChoosePokemon(var1,var2) - Loads the Pokémon screen, where the player can choose a Pokémon in the party. The index of the chosen Pokémon is stored in the variable numbered _var1_, and its name in the variable _var2_. Stores -1 in the _var1_ variable if the player canceled choosing a Pokemon.

There are three outcomes to this method: the player canceled choosing a Pokémon, the player chose an egg, and the player chose a Pokémon. Each of these three situations should be checked. Here's an example of using pbChoosePokemon. It also shows how the chosen Pokémon can be retrieved and information queried from it.


Script: pbChoosePokemon(1,3)
Conditional Branch: Variable [0001] < 0
  Text: You canceled the choice.
  Jump To Label: Done
Branch End
Comment: Gets the Pokemon stored in variable 1
Conditional Branch: pbGetPokemon(1).egg?
  Text: You chose an egg.
  Jump To Label: Done
Branch End
Comment: Variable 3 has the Pokemon's name
Text: You chose a \v[3].
Comment: Set variable 2 to the chosen Pokemon's level
Script: pbSet(2,pbGetPokemon(1).level)
Text: It's at level \v[2].
Label: Done

A related function is called pbChooseAblePokemon. It takes the same parameters as pbChoosePokemon, but here, the player can't choose eggs or fainted Pokémon. The player can still cancel, though.

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.
Y is the Pokémon's level.
V is optional and 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).
C is optional and is true if the player can escape from the battle (the default is true).

The following code example starts a battle against a Kecleon at level 20, and stores the result of the battle in variable number 10.

pbWildBattle(PBSpecies::KECLEON,20,10)

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.

Teaching Moves

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. (That move can also be a TM or HM 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)

Teaching Moves in Script

There are two other ways to teach a move: using the functions pbLearnMove(pokemon,move) and pbAutoLearnMove(pokemon,move) within a script. These two methods take a Pokemon object (see the Choosing a Pokemon section for more on Pokemon objects) and the ID of the move (like PBMoves::TACKLE) as parameters. Moves can be taught to a Pokemon using these functions even if the Pokemon isn't intended to learn them. pbLearnMove will display messages and won't replace HM (Hidden Machine) moves.pbAutoLearnMove won't display anything and can replace HM moves.

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 serve 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 the script section Transitions 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, and so on. 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's 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 sprite, 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). In all other cases, an IconSprite acts exactly like a Sprite and can be used wherever sprites can be used.

Example

The example below loads a sprite and makes it display the bitmap named "Graphics/Pictures/picture"

# Create viewport
viewport=Viewport.new(0,0,640,480)
# Place sprite at X=100 and Y=50
sprite=Sprite.new(100,50,viewport)
sprite.setBitmap("Graphics/Pictures/picture")

Message System

These are the message system's commands:

\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, the second is 1, and so on), _b_ is the choice used when the player cancels (or 0 if the player can't cancel; the first choice is 1, the second is 2, and so on), and _choices_ is a comma-separated list of choices. This command is designed to support more than four choices, but you can still use the existing choice system. See below for examples.
\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, the message system won't display a windowskin.
\sign[X] - Displays the message in the form of a sign and in the windowskin X. If this field is blank, the message system won't display a windowskin.
... - Formats the text in bold.
<o=X> ... </o> - Changes the opacity of the text. X can be 0 (fully transparent) to 255 (fully opaque).
... - Formats the text in italics.
... - 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.
- 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/).
' - Converted to "'".
< - Converted to "<".
> - Converted to ">".
& - Converted to "&".
" - 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.

Choice Display Examples

Here are examples of the \ch message command.

The following example displays four choices, stores the chosen variable in variable number 5, and specifies that choice number 1 will be chosen if the player cancels.

\ch[5,1,Choice 1,Choice 2,Choice 3,Choice 4]

Variable 5 will store the number 0 if Choice 1 is chosen, the number 1 if Choice 2 is chosen, and so on.

The following example displays five choices, stores the chosen variable in variable number 5, and specifies that the player must make a choice.

\ch[5,0,Choice 1,Choice 2,Choice 3,Choice 4,Choice 5]

Here's a complete example that shows how an event can do different things depending on the choice the player chose. Note the conditional branches that check the value of the stored variable.

@>Comment: Store choice in variable 1 and 
    :    store the value -1 if the player cancels.
@>Text: Please choose one.\ch[1,-1,Choice 1,Choice 2]
@>Conditional Branch: Variable [0001] == -1
  @>Text: The choice was canceled.
  @>
 : Branch End
@>Conditional Branch: Variable [0001] == 0
  @>Text: Choice 1 was chosen.
  @>
 : Branch End
@>Conditional Branch: Variable [0001] == 1
  @>Text: Choice 2 was chosen.
  @>
 : Branch End

In the following example, the player must make a choice.

@>Comment: Store choice in variable 1.
@>Text: Please choose one.\ch[1,0,Choice 1,Choice 2]
@>Conditional Branch: Variable [0001] == 0
  @>Text: Choice 1 was chosen.
  @>
 : Branch End
@>Conditional Branch: Variable [0001] == 1
  @>Text: Choice 2 was chosen.
  @>
 : Branch End

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.

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

To set the background music for a certain kind of Trainer: Open the Pokémon Essentials Editor (editor.exe), then choose "Trainer Types", then choose the Trainer type, then choose Battle BGM, Battle End ME, or Battle Intro ME.

You may, for example, want to use one kind of music for Elite Four members and Gym Leaders.

Default Background Music

To change the default battle music for a certain map, open the Pokémon Essentials Editor (editor.exe), then choose "Set Metadata", then choose a map, then choose TrainerBattleBGM, WildBattleBGM, TrainerVictoryME, or WildVictoryME. The names mostly speak for themselves. The BGM (background music) files are found in the Audio/BGM/ directory, and the ME (music effects) files are found in the Audio/ME/ folder.

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. Only the next Pokémon battle will use these settings. (Note that these event commands should be placed very close to the event command that starts 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 field.

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.

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 the player to flee or decide the outcome of the battle.
The player can use hidden moves any time, even if he or she 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. You can access it by pressing F9 during a playtest or by choosing Debug from the game's main menu.

Test Wild Battle - Starts a battle with a wild Pokémon of any species and of any level.
Test Trainer - Starts a battle with a Pokémon Trainer.
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.

Shadow Pokemon and Purify Chamber

Since the February 8, 2010 release, Pokemon Essentials includes support for shadow Pokemon and the Purify Chamber. However, some required data is intentionally not included. Follow these steps to add this data.

First, open the file 'PBS/types.txt' and add the following lines.

[18]
Name=SHADOW
IsSpecialType=true
InternalName=SHADOW
Resistances=SHADOW

Also, add SHADOW as a weakness to each other type in the file.

Then, open the file 'PBS/moves.txt' and add the following lines.

471,SHADOWBLITZ,SHADOW BLITZ,121,40,SHADOW,Physical,100,60,0,00,0,bef,Cool,"Shadow Blitz"
472,SHADOWWAVE,SHADOW WAVE,121,50,SHADOW,Special,100,60,0,08,0,b,Cool,"Shadow Wave"
473,SHADOWRAVE,SHADOW RAVE,121,70,SHADOW,Special,100,60,0,08,0,be,Cool,"Shadow Rave"
474,SHADOWBREAK,SHADOW BREAK,121,75,SHADOW,Physical,100,60,0,00,0,abef,Cool,"Shadow Break"
475,SHADOWBLAST,SHADOW BLAST,12E,80,SHADOW,Special,100,60,0,00,0,bef,Cool,"Shadow Blast"
476,SHADOWRUSH,SHADOW RUSH,121,80,SHADOW,Physical,100,60,0,00,0,abef,Cool,"Shadow Rush"
477,SHADOWMIST,SHADOW MIST,122,0,SHADOW,Status,100,60,0,08,0,be,Cool,"Shadow Mist"
478,SHADOWSHED,SHADOW SHED,123,0,SHADOW,Status,100,60,0,10,0,b,Cool,"Shadow Shed"
479,SHADOWHOLD,SHADOW HOLD,124,0,SHADOW,Status,80,60,0,08,0,be,Cool,"Shadow Hold"
480,SHADOWDOWN,SHADOW DOWN,125,0,SHADOW,Status,100,60,0,08,0,be,Cool,"Shadow Down"
481,SHADOWFIRE,SHADOW FIRE,126,75,SHADOW,Special,100,60,10,00,0,bef,Cool,"Shadow Fire"
482,SHADOWCHILL,SHADOW CHILL,127,75,SHADOW,Special,100,60,10,00,0,bef,Cool,"Shadow Chill"
483,SHADOWBOLT,SHADOW BOLT,128,75,SHADOW,Special,100,60,10,00,0,bef,Cool,"Shadow Bolt"
484,SHADOWPANIC,SHADOW PANIC,129,0,SHADOW,Status,100,60,0,08,0,be,Cool,"Shadow Panic"
485,SHADOWSTORM,SHADOW STORM,12A,95,SHADOW,Special,100,60,0,00,0,b,Cool,"Shadow Storm"
486,SHADOWEND,SHADOW END,12B,120,SHADOW,Physical,60,60,0,00,0,abef,Cool,"Shadow End"
487,SHADOWHALF,SHADOW HALF,12C,0,SHADOW,Status,100,60,0,10,0,b,Cool,"Shadow Half"
488,SHADOWSKY,SHADOW SKY,12D,0,SHADOW,Status,100,60,0,10,0,b,Cool,"Shadow Sky"

As an optional step, open the file 'PBS/items.txt' and add the following lines.

501,JOYSCENT,JOY SCENT,1,300,This scent massage opens the hearts of Pokemon a little.,1,0,0
502,EXCITESCENT,EXCITE SCENT,1,500,This scent massage opens the hearts of Pokemon.,1,0,0
503,VIVIDSCENT,VIVID SCENT,1,800,This scent massage opens the hearts of Pokemon a lot.,1,0,0
504,TIMEFLUTE,TIME FLUTE,1,3000,This item fully opens the hearts of a Pokemon.,1,0,0

That's it. There are a few things you can do with the new support:

To make a Trainer have a shadow Pokemon, open the Pokemon Essentials editor, select "Edit Trainers", select the Trainer, then the Pokemon, and make sure "Shadow" is set to true.
To open the "Relic Stone" event, type the following text in a Script event command: pbRelicStone()
To open the "Purify Chamber" event, type the following text in a Script event command: pbPurifyChamber()

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 PokemonHiddenMoves 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.

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:  pbSet(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 doesn't equal -1), run a script containing the following code. Note that the species received is Haunter.

pbStartTrade(
pbGet(1),
PBSpecies::HAUNTER,
"HAHA", # Nickname
"ANDY" # OT
)

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) or use the script $PokemonGlobal.bicycle in a conditional branch 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.

Day/Night support

Pokemon Essentials will adjust the outdoor screen's colors according to the time of day. This behavior is based not just on the clock time, but on the user's location in the world. To improve the accuracy of the day/night adjustment, you should set the correct time and time zone in your system.

In the Custom and Perspective map views, the day/night adjustment will be disabled for any event named "RegularTone". Such events will normally represent lighted windows.

You can use the following functions in scripts and conditional branches:

PBDayNight.isNight?() - Returns true if it's night (from sunset to sunrise)
PBDayNight.isDay?() - Returns true if it's day (from sunrise to sunset)
PBDayNight.isMorning?() - Returns true if it's morning (from sunrise to high noon)
PBDayNight.isAfternoon?() - Returns true if it's the afternoon (from high noon to sunset)
PBDayNight.getShade() - Returns a value from 0 through 255, where 0 is full night and 255 is full day.

Miscellaneous

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

Use pbShowMap to show the Town Map. In Debug Mode, you can edit the name of any point on the map by selecting it.

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

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

Suggestions for Customizing Scripts

For further scripting ideas, see the advanced topics.

This page can't provide details on how to use the scripting language Ruby. For that, see the links in the Ruby language home page's Getting Started section. For reference material, read 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.

pbSet(X,100)

where X is the variable's number, such as 50. The code above sets that variable to 100. Later, you can display that variable's value 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, for example, \v[50].

And this example sets variable 60 to the number of Pokemon that the player has seen:

 
pbSet(60,$Trainer.seen)

To get the value of a variable in a script, use pbGet(X) where X is the variable's ID.

Displaying a Player-Supplied Name for a Person

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

pbSet(25,pbEnterText("Rival's name?",1,7,"Gary"))

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

With this approach, you can display the person's new name within a Text event command using the command "\v[25]".

(Here's optional, but necessary if the person is also a Pokémon Trainer.) Then modify the script section PokemonTrainers by adding the lines in bold, assuming that the Trainer's trainer type is RIVAL and the Trainer's name is "???". Here's from lines 14 to 16, and the lines not in bold show only 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 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 won't affect any other Pokemon, including Pokémon added to the Trainer's party.

Allowing a Player to Lose a Trainer Battle

Here's 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).

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 player has the Pokédex
$Trainer.party -- Array that specifies the player's current party of Pokémon

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.

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, within 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. If you change the screen size, you should delete the option "Screen Size" in the script section "PokemonOption" (see "Option Screen", above).

Playing a Sound When Stepping on Tiles

The following example plays a sound (in this case, sand.wav in the Audio/SE folder) whenever the player walks on sand. To use the example, put the code below in a new script section in the script editor.

Events.onStepTakenFieldMovement+=proc{|sender,e|
  event=e[0] # Get the event that just stepped on the tile
  if event==$game_player # Check whether the player just stepped on the tile
   if pbGetTerrainTag(event)==PBTerrain::Sand # If this is a sand tile
     pbSEPlay("sand.wav") # Play a sand sound file
   end
  end
}

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's 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 doesn't 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 doesn't wait for the move route to complete. This function's return value is the generated move route (RPG::MoveRoute).

Configuring the Server

Here's 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".

Download "Hamachi®" and install it. You should choose the "Basic" configuration during the installation process.
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.
If necessary, you should disable any firewalls you have.

And here is a more difficult way to publish the server.

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.
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 you don't see your router on the list, please contact your Internet Service Provider.
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".

Wii® Remote

Pokemon Essentials includes a script that accesses the accelerometer of the Wii® Remote. Three new methods are added to the Input module for accessing the X, Y, and Z acceleration parameters. An accelerometer is a sensor that detects changes to the device's orientation. The three new functions for accessing accelerometer data are:

Input.xaccel() - Returns a value from -1 through 1 that specifies the degree of movement, or acceleration, for the X axis.
Input.yaccel() - Returns a value from -1 through 1 that specifies the degree of movement, or acceleration, for the Y axis.
Input.zaccel() - Returns a value from -1 through 1 that specifies the degree of movement, or acceleration, for the Z axis.

Since this script was not tested with an actual Wii® Remote and Bluetooth® dongle, this script might currently not work as expected or the definitions of the above functions may be wrong.

This functionality is made possible with a library called WiiYourself!. As specified in the license terms, it must be said that this product:

contains WiiYourself! wiimote code by gl.tter
    http://gl.tter.org

History

July 21, 2008

Maintenance only; font names were changed

February 3, 2008

Modified scripts for RPGVX compatibility

Added the SellItem pseudocommand

Added the Backdrop command for Trainer battles

Full script is shown if an error occurs during a Script event command

Improved dependent events implementation

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 serve 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, and so on). 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. 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.
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, it is hoped)
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, for example, 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 and the like.)
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é 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

Notice

Pokémon Essentials is a noncommercial project not associated with Nintendo or the makers of the Pokémon video game. Pokémon and Wii are registered trademarks of Nintendo. The names of each Pokémon character are trademarks of Nintendo. Microsoft and Access are registered trademarks of Microsoft Corporation. RPG Maker™ is a trademark of Enterbrain, Inc. Bluetooth is a registered certification mark of Bluetooth SIG, Inc. Hamachi is a registered trademark of LogMeIn, Inc. Other marks are the property of their respective owners.

Notes for Pokémon Essentials

Contents

Controls

Upgrading from previous versions

Problem when opening project

Common Questions

How do I create a Poké Mart?

How can I create a rival and give that rival a name?

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 Pokemon able to do so!

How can I change the color of in-game text?

Map Making

A Note on Scripting

Finding Information About Tiles and Maps

Terrain Tags

Ledges

Couches

Expanding the Text Fields

Considerations

Avoiding Black Regions Near Map Edge

Can still surf on water even with a bridge over it

Game freezes during movement

Starting Position

Dungeons

Configuration Files

Data Compilation

PBS/connections.txt

PBS/encounters.txt

PBS/metadata.txt

PBS/types.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

Windowskins

RGSS2 Windowskin Format

Events

Predefined Events

Trees

Boulders

Headbutt Trees

Cracked Rocks

Doors

Event Page 1

Event Page 2

Cut Scenes

Triggers

Switches and Variables