Essentials Docs Wiki
Advertisement
For the main page about items, see Items.
For a description of how item effects work, see Item effects.
For adding, removing, counting and choosing items in the Bag, see Manipulating items.

This page describes how to define an item.

Defining an item

An item begins with its definition. This means that is is listed in the PBS file "items.txt", so that it can be recognised by the game as an item. This alone does not give the item an effect, but you must start by defining it before you can use it.

This page only describes how to define an item. See the page Item effects to find out how to add effects to defined items.

PBS file "items.txt"

The PBS file "items.txt" lists all the defined items in the game. Each section in this file is one separate item, where a section begins with a line containing an ID in square brackets and ends when the next section begins. Each line in a section is one separate piece of information about that item.

Aside from the ID line, every line in a section follows the format:

XXX = YYY

where XXX is a property and YYY is the value or values associated with it (the spaces are optional). For example:

[POTION]
Name = Potion
NamePlural = Potions
Pocket = 2
Price = 200
FieldUse = OnPokemon
BattleUse = OnPokemon
Flags = Fling_30
Description = A spray-type medicine for treating wounds. It can be used to restore 20 HP to a single Pokémon.
#-------------------------------
[TM42]
Name = TM42
NamePlural = TM42s
Pocket = 4
Price = 3000
FieldUse = TR
Flags = Fling_70
Move = FACADE
Description = This attack move doubles its power if the user is poisoned, burned, or paralyzed.
#-------------------------------
[TOWNMAP]
Name = Town Map
NamePlural = Town Maps
Pocket = 8
Price = 0
FieldUse = Direct
Flags = KeyItem
Description = A very convenient map that can be viewed anytime. It even shows your present location.

All pieces of information are optional, but will have default values if they are not defined. The order of the lines does not matter, except for the ID line in square brackets which must be first.

Data Description Default value
[ID] This is how the scripts refer to the item. Each item must have a different ID. Typically this is the same as the item name, but written in all capital letters and with no spaces or special characters. In the scripts, the ID is used as a symbol (i.e. with a colon in front of it, e.g. :POTION). The ID is never seen by the player.

This line must come first in a section, because, as mentioned above, this line defines when a new section begins.

In Bag pockets that auto-sort themselves, items will be sorted in the same order that they are defined in the PBS file "items.txt".

n/a
Name The name of the item, as seen by the player. "Unnamed"
NamePlural The plural form of the name of the item, as seen by the player. For example, "Potions". "Unnamed"
Pocket The Bag pocket number the item is stored in. By default, this is one of:
  • 1 - Items
  • 2 - Medicine
  • 3 - Poké Balls
  • 4 - TMs & HMs
  • 5 - Berries
  • 6 - Mail
  • 7 - Battle Items
  • 8 - Key Items

The list of Bag pockets is in the script section Settings, in def self.bag_pocket_names.

1
Price The cost of the item when the player buys it from a Poké Mart. Note that when the player sells the item to a Poké Mart, it is sold for half this price (by default; see SellPrice). If an item has a price of 0, the player cannot sell it. 0
SellPrice The amount of money gained when selling the item to a Poké Mart. Half of Price
FieldUse How the item can be used outside of battle. Is one of the following:
  • OnPokemon - The item can be used on a Pokémon (e.g. Potions, Elixirs). The party screen will appear when using this item, allowing you to choose the Pokémon to use it on. Not for TMs, TRs and HMs, though.
  • Direct - The item can be used out of battle, but it isn't used on a Pokémon (e.g. Repel, Escape Rope, usable Key Items).
  • TR - The item is a TR. It teaches a move to a Pokémon, and disappears after use.
  • TM - The item is a TM. It teaches a move to a Pokémon, but does not disappear after use.
  • HM - The item is a HM. It teaches a move to a Pokémon, but does not disappear after use. Moves taught by a HM cannot be forgotten.
None
BattleUse How the item can be used in battle. Is one of the following:
  • OnPokemon - The item can be used on one of your party Pokémon (e.g. Potions, Elixirs, Blue Flute). The party screen will appear when using this item, allowing you to choose the Pokémon to use it on.
  • OnMove - The item can be used on one of the moves known by one of your party Pokémon (e.g. Ether). The party screen will appear when using this item, followed by a list of moves to choose from.
  • OnBattler - The item is used on the Pokémon in battle that you are choosing a command for (e.g. X Accuracy, Red/Yellow Flutes).
  • OnFoe - The item is used on an opposing Pokémon in battle (Poké Balls). If there is more than one opposing Pokémon, you will be able to choose which of them to use it on.
  • Direct - The item is used with no target (e.g. Poké Doll, Guard Spec., Poké Flute).
None
Consumable Whether the item will be consumed after being used from the Bag. Is true or false. Usually only used to make a non-Key Item infinite use (e.g. Black/White Flutes). False if a Key Item, TM or HM, and true otherwise
Flags Comma-separated labels applied to the item which can be used to make it behave differently. The existing flags are:
  • Mail - The item is a Mail item.
  • IconMail - The item is a Mail item, and the images of the holder and two other party Pokémon appear on the Mail.
  • PokeBall - The item is a Poké Ball item.
  • SnagBall - The item is a Snag Ball (i.e. it can capture enemy trainers' Shadow Pokémon).
  • Berry - The item is a berry that can be planted.
  • KeyItem - The item is a Key Item.
  • EvolutionStone - The item is an evolution stone.
  • Fossil - The item is a fossil that can be revived. Not to be used for the incomplete fossils from Gen 8 which are pieced together to revive a Pokémon.
  • Apricorn - The item is an Apricorn that can be converted into a Poké Ball.
  • TypeGem - The item is an elemental power-raising Gem.
  • Mulch - The item is mulch that can be spread on berry patches.
  • MegaStone - The item is a Mega Stone. This does NOT include the Red/Blue Orbs.
  • MegaRing - The item is a Mega Ring, which allows Mega Evolution.
  • Repel - The item is a Repel, and can be used automatically when a Repel runs out.
  • Fling_30 - The item can be thrown by the move Fling. The number is Fling's base power when used with the item. The number can be any number, but should be greater than 0.
  • NaturalGift_POISON_80 - The item can be used by the move Natural Gift. The type and number are Natural Gift's type and base power when used with the item. The type can be any type, and the number can be any number but should be greater than 0.
none
Move The ID of the move that this item teaches. For HMs, TMs and TRs only.

A Pokémon is compatible with a HM/TM/TR if and only if the move it teaches is listed a a Tutor Move for its species in the PBS file "pokemon.txt" (or in "pokemon_forms.txt" if appropriate). The species having access to that move via its level-up moveset or as an egg move will not count. See the page Learning moves for more information.

none
Description The item's description. Typically, HMs, TMs and TRs will have the same description as the moves they teach, but they don't need to. "???"

Item icons

Each item has a single icon, which is located in the folder "Graphics/Items" and called XXX.png, where XXX is the ID of that item.

If the icon for a machine item (a HM/TM/TR) does not exist, then it will instead try to use other icon(s):

  • TM - Tries the icon named machine_XXX.png, where XXX is the ID of the type of the move it teaches, e.g. machine_FLYING.png.
  • TR - Tries the icon named machine_tr_XXX.png, where XXX is the ID of the type of the move it teaches, e.g. machine_tr_FLYING.png. If this isn't found, it tries the icon that a TM would use, e.g. machine_FLYING.png.
  • HM - Tries the icon named machine_hm_XXX.png, where XXX is the ID of the type of the move it teaches, e.g. machine_hm_FLYING.png. If this isn't found, it tries the icon that a TM would use, e.g. machine_FLYING.png.

The item icon can be any size, although 48x48 pixels is traditional.

An item's icon can be animated. For it to be animated, its graphic should contain a number of frames in a row, and each frame must be exactly 48x48 pixels in size. No matter how many frames there are in the graphic, one complete cycle will last 1 second, so having more frames means less time is spent showing each individual frame. Both of these values (48 pixels and time per cycle) are defined as constants in class ItemIconSprite and are easily changeable; note that they apply to all item icons.

Items can also have unique small icons for display in the party screen when they are held by a Pokémon. These are located in the folder "Graphics/Pictures/Party" and called icon_item_XXX.png (for non-mail items) or icon_mail_XXX.png (for mail items), where XXX is the ID of that item. If there isn't a unique icon for an item, it will use the default icon_item.png or icon_mail.png instead.

Mail

In addition to the above, each Mail item also needs its own background picture. This picture is located in the folder "Graphics/Pictures/Mail" and called mail_XXX.png, where XXX is the ID of that item.

Mail background pictures should be the size of the game screen.

Advertisement