Essentials Docs Wiki
Essentials Docs Wiki
For how trainer types are defined, see Defining a trainer.

This page describes how to set up the player character. It also details the rest of the game's global metadata.

Setting up a player character

Main article: Metadata

The PBS file "metadata.txt" contains much of the information about the player characters, including listing the graphics used to depict them in the game.

You will also need to ensure that all relevant graphics are in the appropriate places. These include charsets depicting various kinds of movement (walking, running, cycling, surfing, diving and fishing), and front and back sprites as used in battle and on the Trainer card. The front and back sprites are part of defining a trainer type.

Manipulating the player

To set the player (and thus set all their sprites), use the following script:


"X" is a number between 0 and 7, corresponding to player characters A through H. This script is called in the game intro, and is one of the two vital things that MUST happen there (along with setting the player's name).

You can also use this command at any point during the game, but note that all it will do is change whichever information is written for that player character in the global metadata (i.e. the trainer type and the charsets) - it will NOT change their party/money/name/etc. In this sense, changing the player is purely cosmetic, as all that changes is the player's appearance.

Naming the player

To name the player, use the following script:


This opens the naming screen, where the player can choose a name for themselves. If they close the naming screen while the name section is still blank, the player's username on their computer will be used (or a randomly generated name if that can't be found). The randomly generated name is nearly always terrible, as it is generated letter by letter according to a set of rules, rather than choosing one name from a list of names. You may wish to change this to use a specific name (or a random choice from a list of names); if so, find this script in the script section PSystem_Utilities and edit as appropriate. Remember to differentiate between genders.

To set the player's name automatically without letting the player choose it for themselves, use the following command in the game intro event instead of the above (you can change the highlighted part to whatever you want):


If this script is called, but pbChangePlayer hasn't been, then the player's character will be set to the default character A.


The player can be given a selection of outfits to choose from. These effectively behave like multiple forms do for Pokémon, in that the outfit ("form") is a single number which determines the graphics to use for the player. This number is stored in the variable $Trainer.outfit, and is 0 by default.

The charsets which the player will use are named by taking the defined charset names in the PBS file "metadata.txt" for the player's character, and then adding an underscore followed by the outfit number to the end of it. Therefore, each outfit will require its own collection of charsets. If the appropriate charset does not exist, the game will instead use the base charset name (without any outfit number on the end). As with Pokémon multiple forms, it is recommended that outfit 0's graphics actually have no numbers on the ends of their filenames, so that outfit 0 can also act as the default/backup outfit if necessary.

This file naming convention also applies to the trainer sprites (both front and back sprites), as well as the player's head icon which is shown on the region map, and to the Vs. battle intro animation.

By default, there is no in-game way to change the player's outfit in Essentials (except for a Debug mode option). Implementing a "wardrobe" feature, and deciding how to number each outfit and which outfits are available, is left to the user to do.

Trainer-related information

A number of pieces of information are stored in the variable $Trainer, as follows:

Information Description
$ The player's name (e.g. "Dave").
$Trainer.trainerTypeName The name of the trainer type that the player has (e.g. "PkMn Trainer").
$Trainer.fullname The full name of the trainer (e.g. "PkMn Trainer Dave").
$Trainer.trainertype The player's trainer type (typically 000 if male, 001 if female).
$ An 8 digit hexadecimal number (between 00000000 and FFFFFFFF).
$Trainer.publicID The last 4 hexadecimal digits of the player's ID (a number between 0 and 65535). This is the player's ID number as shown on the Trainer card, as well as the displayed OT ID for a Pokémon originally owned by the player.
$Trainer.secretID The first 4 hexadecimal digits of the player's ID (a number between 0 and 65535).
$Trainer.gender The gender of the trainer type that the player has (0=male, 1=female, 2=unknown).
$Trainer.outfit The outfit the player is wearing (0 by default, or any positive number).
$Trainer.language A number corresponding to the language used by the player's computer. All Pokémon caught by the player have the same language.
  • 0=Unknown, 1=Japanese, 2=English, 3=French, 4=Italian, 5=German, 7=Spanish, 8=Korean

If the language is known but none of the above, it is set to English.

$ The amount of money the player currently has.
$Trainer.badges An array of values, each of which is TRUE if the corresponding badge is owned and FALSE if it is not. The first value, $Trainer.badge[0], is the first badge, and so on.
$Trainer.numbadges The total number of badges that the player has. It counts every region's badges.
$Trainer.pokegear Is TRUE if the player has the Pokégear (i.e. it shows up in the Pause menu).
$Trainer.pokedex Is TRUE if the player has the Pokédex (i.e. it shows up in the Pause menu).
$Trainer.pokedexSeen(dex) The total number of Pokémon species the player has seen in the specified Regional Dex. Leave the parameter blank or -1 to count the National Dex (i.e. all Pokémon that exist in the game) instead.
$Trainer.pokedexOwned(dex) The total number of Pokémon species the player has owned in the specified Regional Dex. Leave the parameter blank or -1 to count the National Dex (i.e. all Pokémon that exist in the game) instead.
$Trainer.numFormsSeen(species) Returns the total number of alternate forms that the player has seen of the given species. This only counts "true" alternate forms, i.e. gender differences are ignored.
$Trainer.clearPokedex Completely erases everything in the Pokédex.
$ An array that contains up to 6 entries, each entry being a Pokémon (or egg). This is the player's party.