Script sections

This page gives an overview of the **scripts** and the **script sections** they are stored in.

## Scripts

"Scripts" is the word for the Ruby code that makes Pokémon Essentials work, including making the player move around, displaying menus and messages, defining items and Pokémon, and performing battles.

You can view the scripts in RPG Maker XP by clicking the "Script Editor" button, or going to "Tools > Script Editor", or by pressing F11. The list on the left of the Script Editor lists all the script sections, and the main display shows the code in the selected script section. Each script section generally contains code about one specific feature or function.

Since there are hundreds of script sections, they have been put into groups and visually separated from each other by empty script sections with names of "`==================`" (or blank names). Each script group is named and the name is another empty script section with a name in double square brackets, e.g. "`[[ Game processing ]]`".

### GitHub scripts

If using the version of Essentials on GitHub, you will notice that the scripts do not appear in RPG Maker XP's Script Editor. Instead they are all in separate ".rb" files in the "Data/Scripts" folder, which contains subfolders corresponding to the group names. This makes them easier to work with for some people, as they can use their own choice of IDE to edit the scripts, and it also makes it easier to track changes to the scripts with version control software such as Git.

The GitHub version includes scripts called "scripts\_extract.rb" and "scripts\_combine.rb", which will move the scripts between the single Scripts.rxdata data file (which the Script Editor displays the contents of) and individual files. For these, the formatting of the names of group separators and group names is important as they tell these scripts how and when to make folders when extracting them.

## List of script groups

### Settings

*Main article: Settings*
This first script group does not actually have a name. The group contains script sections that contain the settings, a collection of constants and methods used throughout the scripts to make them work in particular ways. Settings are the more common values and features that the developer may want to change, so they are all collected here for convenience. Each setting has an accompanying description of what it does.

Many settings depend on the value of the setting `MECHANICS_GENERATION`, but you are free to change them however you want.

It is worth reading through the settings script sections to see what they contain, even if you don't want to touch any of the other scripts.

### Technical

These script sections are best left alone. They contain code that helps the game to function properly, such as helpful methods, text translation, the plugin manager, debug tools and code relating to the use of files.

This script group is split into three sub-groups for extra organisation.

### Save data

These script sections define what gets put into a save file and how it works. It also contains code that allows save data to be modified, such as to support save files created with an older version of Essentials/the game which may have saved their information in a different way.

### Game processing

These script sections represent starting a new game (or loading a save file), the very basic game loop (i.e. the code that makes the game run at all), and the mechanics of how event commands work.

It also contains event handlers, where in this case "event" means "a thing that happens in the game" rather than "event objects you place in maps". Handlers let you store code to be run later on, and are used for a variety of things, such as numerous triggers (such as taking a step or when setting up an NPC trainer to battle against), the contents of some menus, ability and item effects, and code relating to Pokémon forms.

### Game classes

These script sections contain code for various overworld elements, including maps themselves, events, the player and followers. There are also script sections for pictures displayed on-screen by an event command, the game screen itself, game statistics, common events, Game Switches and Variables, and a set of system variables that help the game to run.

### Sprites

These script sections deal with the displaying on-screen of the things in the script group above ("Game classes"), as well as code for other visual features such as a particle engine and code that helps to display graphics elsewhere (such as in battle).

### Map renderer

These script sections display maps and work with tilesets and autotiles.

### Scenes

The script sections in here don't really belong elsewhere, and are grouped together for the sake of it. They are visual in nature, hence the name of this script group.

One of the script sections contains code for all the transition animations. The majority of these animations are used when starting a battle (wild and trainer ones) to fade the screen to black.

Another script section contains code to display a basic UI screen. This is only used by two pieces of UI (the splash/title screens and the controls help screen).

### Data

There are two main sub-groups of scripts in here: one for hardcoded game data, and one for game data compiled from PBS files.

### Battle

*Main article: Battles*
There are a lot of script sections in here, arranged in a number of sub-groups. Between them, they make battles work.

A battler is a Pokémon that is in battle. A move here is specifically one known by a battler. Pokémon and moves have battle-specific versions here because a lot of things can happen to them in a battle but which won't affect them outside of battle. They can also do more things in battle than they can outside of battle (moves have effects when used to attack, for example), so it is convenient to have in-battle versions of these things.

The "Scene" sub-group is for the visual aspects of a battle.

The battle AI also has script sections in here.

### Items

These script sections contain various pieces of code that help items to do things, as well as the effects they have when used in or out of battle. Some items, including the Poké Radar and phone (which isn't technically an item but is close enough), have their own script sections to describe their effects.

There is also a script section for item sprites (sometimes called item icons), and one that describe how the Bag and item storage work.

### Pokemon

These script sections define individual Pokémon, what information they contain and various behaviours.

There is a sub-group of scripts for things relating to Pokémon but which are not directly part of Pokémon objects. These include code for alternate forms, Shadow Pokémon mechanics, Pokémon sprites and the Pokémon storage.

### Trainers and player

These script sections define individual trainers, as well as the player (who is also a trainer, just one with a Pokédex/money/running shoes/etc.). There is also a script section for creating an animated overworld sprite of a trainer, which is used in some places (trainer graphics used elsewhere are coded elsewhere).

### Minigames

*Main article: Mini-games*
The various mini-games in Essentials are coded here.

### Alternate battle modes

*Main article: Safari Zone*
*Main article: Bug Catching Contest*
*Main article: Battle Frontier*
These script sections contain code that make the Safari Zone and Bug Catching Contest work (battle-related code for these is in the "Battles" script group).

There are also many script sections for the Battle Frontier facilities, including their rulesets and generating random trainers/Pokémon for them.

### Utilities

These script sections contain various useful scripts that don't fit elsewhere. One script section contains various scripts for giving Pokémon to the player and analysing Pokémon/the player's party. Another script section contains scripts that load [[Backgrounds and music|music] for battles.

### Debug

*Main article: Debug mode*
These script sections contains the three main Debug menus (overworld, in battle, and per Pokemon) and their functionalities. A large number of these are information editors (changing data stored in PBS files) and the Animation Editor.

### Compiler

*Main article: Compiler*
These scripts are responsible for compiling information from PBS files into forms usable by the game, and for modifying map/event data. There are also methods for generating PBS files from compiled information.

### Main

This is the last script group, and contains just one script section which is responsible for starting the game when running it. This script section must always be last in the list, as script sections that are below this one will not work.