Messages

*For how to change some text options in-game, see Options screen.*
This page describes various **message** options, including modifying the appearance of text and the message box, and displaying choices.

## Messages

A message is any text which appears in a box, either by an event's "Show Text" command or by the method `pbMessage` or any of a number of similar methods.

There are two kinds of messages: speech and system. Speech is for any text that appears as dialogue, while system is typically for choice menus and informative text.

When typing a message into an event, you do not need to add in any line breaks or restrict how much text you enter. The message system will automatically wrap text as appropriate, and scroll the text if it won't all fit in the text box at once.

## Windowskins

A windowskin is the background image of the message box. All windowskins are stored in the folder "Graphics/Windowskins".

Each windowskin is a single graphic of specific dimensions. The graphic's dimensions determine which margins it should use to split itself up when displaying as a proper message box. The image on the right shows how windowskins of different sizes are divided up.

A windowskin has two kinds of margins:

* "Tiling" - This is how the graphic itself is drawn to fill the area of the screen it should occupy. The four middle side segments and the central segment are tiled as often as necessary.
* "Text position" - The central segment defined by these margins is where the text is displayed.

Only one of the four styles of windowskin has different margins for tiling and text position.

Pokémon Essentials also supports windowskins in the forms used by RPG Maker XP (192x128) and RPG Maker VX (128x128). Information about those formats can be found online.

The player is able to change the windowskins of the speech and system messages in the Options screen.

### Special windowskins

There is one notable windowskins. It is:

* goldskin.png - Used for the boxes which show the player's money and Coins.

## Modifying text

These are a number of ways to modify the text in Pokémon Essentials. You can do so by using the following commands:

* Display text
* Format text
* Text colours
* Text positioning
* Alter message box
* Alter text displaying
* Play sound
* Display extra things

 `
...
 `<fn=X>...</fn>` | Makes the text between these commands display in a specified font (or a default font if the specified font doesn't exist in the "Fonts" folder).
 `<o=X>...</o>` | Changes the opacity of the text between these commands. "X" is a number between 0 (fully transparent) and 255 (fully opaque).

 `<ar>...</ar>` | Makes the text between these commands right-aligned. Causes line breaks before and after this text.

 `\1` | Pauses the message. When the player presses a button, the message will carry on being shown.
If you're showing several messages in a row via code (e.g. with `pbMessage`), these ordinarily won't show the pause arrow at the end of the first message, even though there's a second message immediately afterwards. However, you can put `\1` at the end of the first message to display the pause arrow, and continuing from it will immediately start on the second message.
 `\.` | Pauses the message for 1/4 of a second, then automatically continues to show the rest of the text
 `\|` | Pauses the message for 1 second, then automatically continues to show the rest of the text
 `\wt[X]` | Pauses the message for `X`/20 of a second, then automatically continues to show the rest of the text.
 `\wtnp[X]` | Pauses the message for `X`/20 of a second, then automatically continues to show the rest of the text. The message closes immediately when it is done.

 `\me[X]` | Plays the music effect (ME) named "`X`".

It can be shown alongside the money window, but if so, this command must appear *after* the money window's command (e.g. `\G\CN`).
The number is optional, is 0 by default, and indicates which part of the picture to show. The picture is considered to be a 4x4 grid of squares, starting with square 0 being the top left one and counting across and then down (e.g. square 7 is the far right square of the second row).
This command works with animated gifs.

When using a message command, you should not put any spaces around it as you would a word. For example, you should write "`\bText`" rather than "`\b Text`".

## Choices

RPG Maker XP has an event command called "Show Choices", which allows for up to four options on its own. If you want more options at once, you can put two or more "Show Choices" commands next to each other (with no other command between them) and they will combine into one longer list of choices.

The player may be able to cancel choosing an option by pressing the Back key. These are the three possibilities:

* An option is chosen by default - The "Show Choices" event command containing that option should name it as its "When Cancel" setting, and all other "Show Choices" event commands should be set to "Disallow" cancelling.
* A branch option is chosen - One of the "Show Choices" event commands should be set with "Branch" cancelling, and all other "Show Choices" event commands should be set to "Disallow" cancelling. It does not matter which "Show Choices" event command has the branch, but for neatness, use the last one. If there are multiple "Show Choices" event commands that "Branch", only the first one will happen.
* Cancelling is not allowed - Every "Show Choices" event command should be set to "Disallow" cancelling.

You can rename any of the options shown to the player. Before the "Show Choices" event command, use a "Script" event command to run the following:

```
rename\_choice(1, \_I("New choice name"))

```

The number is which choice to rename. Note that this starts at 1, and counts how many choices have been defined in each "Show Choices" event command (it does not assume every command has exactly 4 choices). For example, if the first "Show Choices" event command lists 2 options and the second lists 3 options, then there are 5 options in total and renaming choice 4 will rename the second option in the second list (because it is the fourth listed in order).

You can also remove any option from the list. Before the "Show Choices" event command, use a "Script" event command to run the following:

```
hide\_choice(2, !$bag.has?(:AURORATICKET))

```

The number is which choice to remove (using the same logic as above). The second parameter is code that returns either TRUE or FALSE, and which determines whether the option should be shown - the option is shown if this is FALSE, and hidden if this is TRUE. In this example, option 2 will be hidden if the player does not have an Aurora Ticket.

An equivalent way of writing this is:

```
if !$bag.has?(:AURORATICKET)
 hide\_choice(2)
end

```

The second parameter is TRUE by default (i.e. the choice will be hidden).

## Entering text

The player can provide text for the game to use. There are two different kinds of text entry. This section only describes how to get text from the player; it does not describe what you can do with it.

### Entering a word/name

This method lets the player enter a short name. It is used for naming the player character (and rivals), giving a Pokémon a nickname, and naming a Pokémon storage box. This is done via the *naming screen*.

There are two versions of the naming screen - cursor entry and keyboard entry. Which one is used by a game depends on an option in the Options screen. The cursor entry version is identical to text entry in the official games, where you are provided with a grid of letters, numbers and symbols to select and insert into the name. The keyboard entry version takes advantage of Essentials games being PC games, and allows direct text entry by typing it in via the keyboard (albeit without access to most of the special symbols).

Entering a word is done by using the following code:

```
name = pbEnterText(\_INTL("Your name?"), 0, 7, \_INTL("Red"))

```

The first parameter is the "helper text", a phrase which appears in the naming screen and lets the player know what they're supposed to be entering a name for.

The second parameter is the minimum length that the name can be. If this is 0, the naming can be cancelled (and `name`will be set to `""`). The third parameter is the maximum length that the name can be, and is traditionally 7 characters for player names and 10 characters for Pokémon nicknames.

The fourth parameter is optional, and is the default name which the player can edit/replace.

#### Variants

There are three variants of `pbEnterText`, which are used to give names to specific things. The difference is that they display an icon of the thing being named.

None of these variants need to be manually used by you. The scripts automatically use these variants where appropriate, and it is highly unlikely you would ever want to use them manually. They are mentioned here for the sake of completeness.

```
pbEnterPlayerName(\_INTL("Your name?"), 0, Settings::MAX\_PLAYER\_NAME\_SIZE, \_INTL("Red"))

```

This specifically is for naming the player. It shows the player's south-facing overworld image, animated and walking on the spot. Its parameters are the same as for `pbEnterText`.

```
pbEnterPokemonName(\_INTL("Nickname?"), 0, Pokemon::MAX\_NAME\_SIZE, "", pkmn)

```

This specifically is for naming a Pokémon. It shows the Pokémon's animated icon, along with its gender symbol if it has a gender. Its parameters are the same as for `pbEnterText`, except for the addition of one at the end, which is a Pokémon object.

```
pbEnterBoxName(\_INTL("Box name?"), 0, 12, "Box 1")

```

This specifically is for naming a Pokémon storage box. It shows an animated icon that represents a storage box. Its parameters are the same as for `pbEnterText`.

### Entering a message

This method lets the player enter a longer message. It is used for writing a message in a mail item when giving it to a Pokémon.

Unlike naming something, entering a message does not involve a separate screen. Instead, a message box appears on-screen which the player can type into using the keyboard.

Message entry is done by using the following code:

```
message = pbMessageFreeText(\_INTL("Please enter a message."),
 \_INTL("Default message."),
 false, 256, Graphics.width)

```

The first parameter is the "helper text", a phrase which appears to let the player know what they're supposed to be doing.

The second parameter is the default message. If you don't want a default message, simply put `""` here instead.

The third parameter is whether the message is a password. If this is true, then the message is shown as asterisks instead of actual letters. If this is false, then the message is shown as normal.

The fourth parameter is the maximum length that the message can be, in characters.

The fifth parameter is optional, and is the width of the message entry box. If this is blank, the width will be 240 pixels (just under half the width of the screen). `Graphics.width` is the entire width of the screen.

Note that message entry can be cancelled. In that case, `message` will be set to `""`.