Essentials Docs Wiki
Advertisement
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 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:

pbChangePlayer(X)

"X" is the character ID, which corresponds to a player characters defined in the PBS file "metadata.txt". A character ID can be 1 or higher. 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 which set of information is used from "metadata.txt", which is typically just the player's appearance and trainer type - 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:

pbTrainerName

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 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 name you want):

pbTrainerName("Dave")

If this script is called, but pbChangePlayer hasn't been, then the player's character ID will be set to the default value (1).

Outfits

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 $player.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 multiple forms of Pokémon, 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 (front sprites are named "<trainer type>_<outfit number>" and back sprites are named "<trainer type>_<outfit number>_back"), 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 developer to do.

Trainer-related information

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

Information Description
$player.name The player's name (e.g. "Dave").
$player.trainer_type_name The name of the trainer type that the player has (e.g. "Pokémon Trainer").
$player.full_name The full name of the trainer (e.g. "Pokémon Trainer Dave").
$player.trainer_type The player's trainer type (e.g. :POKEMONTRAINER_Red).
$player.id An 32-bit hexadecimal number (between 00000000 and FFFFFFFF).
$player.public_ID 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.
$player.secret_ID The first 4 hexadecimal digits of the player's ID (a number between 0 and 65535).
$player.gender The gender of the trainer type that the player has (0=male, 1=female, 2=unknown).
$player.outfit The outfit the player is wearing (0 by default, or any positive number).
$player.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.

$player.money The amount of money the player currently has.
$player.coins The amount of Game Corner coins the player currently has.
$player.battle_points The amount of Battle Points (BP) the player currently has.
$player.soot The amount of soot the player currently has.
$player.badges An array of values, each of which is TRUE if the corresponding Gym badge is owned and FALSE if it is not. The first value, $player.badges[0], is the first badge, and so on.
$player.badge_count The total number of Gym badges that the player has. It counts every region's badges.
$player.has_running_shoes Is TRUE if the player has running shoes and can run in the overworld, and FALSE if not.
$player.has_exp_all Is TRUE if the effect of the Exp. All applies to all battles (even if the player does not have that item in their Bag or has not activated it), and FALSE if not.
$player.has_box_link Is TRUE if the player can access their Pokémon storage from the Party screen, and FALSE if not.
$player.seen_storage_creator Is TRUE if the player has met the Pokémon storage system creator and knows their name, and FALSE if not.
$player.has_pokegear Is TRUE if the player has the Pokégear (i.e. it shows up in the Pause menu).
$player.has_pokedex Is TRUE if the player has the Pokédex (i.e. it shows up in the Pause menu).
$player.pokedex.seen_count(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.
$player.pokedex.owned_count(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.
$player.pokedex.seen_forms_count(:UNOWN) 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.
$player.pokedex.clear Completely erases everything in the Pokédex.
$player.party An array that contains up to 6 entries, each entry being a Pokémon (or egg). This is the player's party.
Advertisement