Changes: Defining an item

Revision as of 22:06, 9 May 2021

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 line in this file is one separate item.

Every line in this file follows the same format. Firstly, here are some examples:

1,REPEL,Repel,Repels,1,400,"An item that prevents weak wild Pokémon from appearing for 100 steps after its use.",2,0,0,
217,POTION,Potion,Potions,2,200,"A spray-type medicine for wounds. It restores the HP of one Pokémon by just 20 points.",1,1,0,
266,GREATBALL,Great Ball,Great Balls,3,600,"A good, high-performance Ball that provides a higher Pokémon catch rate than a standard Poké Ball.",0,4,4,
329,TM42,TM42,TM42s,4,10000,"An attack move that doubles its power if the user is poisoned, paralyzed, or has a burn.",3,0,0,FACADE
510,TOWNMAP,Town Map,Town Maps,8,0,"A very convenient map that can be viewed anytime. It even shows your present location.",2,0,6,

Each line is structured as follows, with commas separating each part:

Part	Information	Description
1	ID number	This number must be different for each item. It must be a whole number greater than 0. You can skip numbers (e.g. the sequence `23,24,25,197,198,199,...` is allowed). The order in which items are numbered is not important. ID numbers are obsolete and not used for anything.
2	ID	This must be different for each item. This is how the scripts refer to the item. Typically this is the same as the item name, but written in all capital letters and with no spaces or symbols. 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.
3	Name	The name of the item, as seen by the player.
4	Name plural	The plural form of the name of the item, as seen by the player. For example, "Potions".
5	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
6	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). If an item has a price of 0, the player cannot sell it.
7	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. If there are any commas in the description, you must surround the entire description with quote marks. If there are no commas in the description, there's no harm in having those quote marks anyway. If there are any quote marks in the description itself, you must put a backslash before each of them, e.g. `\"`. The same applies if there are any apostrophes in the description and you haven't surrounded it with quote marks.
8	Usability outside of battle	Is one of the following values: 0 - The item cannot be used outside of battle. 1 - The item can be used on a Pokémon, and disappears after use (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 and HMs, though. 2 - 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). 3 - The item is a TM. It teaches a move to a Pokémon, but does not disappear after use. 4 - 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. 5 - The item can be used on a Pokémon (like 1), but it does not disappear after use (e.g. Poké Flute). 6 - The item is a TR. It teaches a move to a Pokémon, and disappears after use.
9	Usability in battle	Is one of the following values: 0 - The item cannot be used in battle. 1 - The item can be used on one of your party Pokémon, and disappears after use (e.g. Potions, Elixirs). The party screen will appear when using this item, allowing you to choose the Pokémon to use it on. 2 - The item can be used on one of the moves known by one of your party Pokémon, and disappears after use (e.g. Ether). The party screen will appear when using this item, followed by a list of moves to choose from. 3 - The item is used on the Pokémon in battle that you are choosing a command for (e.g. X Accuracy). It disappears after use. 4 - The item is used on an opposing Pokémon in battle, and disappears after use (Poké Balls). If there is more than one opposing Pokémon, you will be able to choose which of them to use it on. 5 - The item is used with no target, and disappears after use (e.g. Poké Doll, Guard Spec.). 6 - Same as 1 but the item is not consumed after use (Blue Flute). 7 - Same as 2 but the item is not consumed after use. 8 - Same as 3 but the item is not consumed after use (Red/Yellow Flutes). 9 - Same as 4 but the item is not consumed after use 10 - Same as 5 but the item is not consumed after use (Poké Flute).
10	Special items	Is one of the following values: 0 - The item is none of the items below. 1 - The item is a Mail item. 2 - The item is a Mail item, and the images of the holder and two other party Pokémon appear on the Mail. 3 - The item is a Snag Ball (i.e. it can capture enemy trainers' Shadow Pokémon). 4 - The item is a Poké Ball item. 5 - The item is a berry that can be planted. 6 - The item is a Key Item. 7 - The item is an evolution stone. 8 - The item is a fossil that can be revived. 9 - The item is an Apricorn that can be converted into a Poké Ball. 10 - The item is an elemental power-raising Gem. 11 - The item is mulch that can be spread on berry patches. 12 - The item is a Mega Stone. This does NOT include the Red/Blue Orbs.
11	HM/TM/TR move	This field is for HMs, TMs and TRs only, and contains the ID of the move that it teaches. A species is compatible with a HM/TM/TR if and only if the move it teaches is listed a a Tutor Move for that species in the PBS file "pokemon.txt" (and in "pokemonforms.txt" if appropriate). The species having access to that move via its level-up moveset or as egg moves will not count. See the page Learning moves for more information.

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.
TR - Tries the icon named machine_tr_XXX.png, where XXX is the ID of the type of the move it teaches. If this isn't found, it tries the icon that a TM would use.
HM - Tries the icon named machine_hm_XXX.png, where XXX is the ID of the type of the move it teaches. If this isn't found, it tries the icon that a TM would use.

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.

@@ Line 32: / Line 32: @@
 ! ID number
 | This number must be different for each item. It must be a whole number greater than 0. You can skip numbers (e.g. the sequence <code>23,24,25,197,198,199,...</code> is allowed). The order in which items are numbered is not important.
+ID numbers are obsolete and not used for anything.
 |-
 ! 2
+! ID
-! Internal name
-| This is how the scripts refer to the item. Typically this is the same as the item name but written in all capital letters and with no spaces or symbols. The internal name is never seen by the player.
+| This must be different for each item. This is how the scripts refer to the item. Typically this is the same as the item name, but written in all capital letters and with no spaces or symbols. 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.
 |-
 ! 3
+! Name
-! Display name
 | The name of the item, as seen by the player.
 |-
 ! 4
+! Name plural
-! Plural display name
-| The plural form of the name of the item, as seen by the player.
+| The plural form of the name of the item, as seen by the player. For example, "Potions".
 |-
 ! 5
@@ Line 64: / Line 66: @@
 ! 7
 ! Description
-| The item's description. Typically, TMs and HMs will have the same description as the moves they teach, but they don't need to.
+| 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.
 If there are any commas in the description, you must surround the entire description with quote marks. If there are no commas in the description, there's no harm in having those quote marks anyway.
@@ Line 77: / Line 79: @@
 * 1 - The item can be used on a Pokémon, and disappears after use (e.g. Potions, Elixirs). The [[Party|party screen]] will appear when using this item, allowing you to choose the Pokémon to use it on. Not for TMs and HMs, though.
 * 2 - 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).
-* 3 - The item is a TM. It teaches a move to a Pokémon, and disappears after use (unless TMs are set to infinite use).
+* 3 - The item is a TM. It teaches a move to a Pokémon, but does not disappear after use.
 * 4 - 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.
 * 5 - The item can be used on a Pokémon (like 1), but it does not disappear after use (e.g. Poké Flute).
+* 6 - The item is a TR. It teaches a move to a Pokémon, and disappears after use.
 |-
 ! 9
@@ Line 89: / Line 92: @@
 * 2 - The item can be used on one of the moves known by one of your party Pokémon, and disappears after use (e.g. Ether). The [[Party|party screen]] will appear when using this item, followed by a list of moves to choose from.
 * 3 - The item is used on the Pokémon in battle that you are choosing a command for (e.g. X Accuracy). It disappears after use.
-* 4 - The item is used on an opposing Pokémon in battle, and disappears after use (Poké Balls). If there is more than one opposing Pokémon, you will be able to chose which of them to use it on.
+* 4 - The item is used on an opposing Pokémon in battle, and disappears after use (Poké Balls). If there is more than one opposing Pokémon, you will be able to choose which of them to use it on.
 * 5 - The item is used with no target, and disappears after use (e.g. Poké Doll, Guard Spec.).
 * 6 - Same as 1 but the item is not consumed after use (Blue Flute).
@@ Line 116: / Line 119: @@
 |-
 ! 11
-! TM/HM move
+! HM/TM/TR move
-| This field is for TMs and HMs only, and contains the internal name of the move that it teaches.
+| This field is for HMs, TMs and TRs only, and contains the ID of the move that it teaches.
+A species is compatible with a HM/TM/TR if and only if the move it teaches is listed a a Tutor Move for that species in the [[PBS file]] "pokemon.txt" (and in "pokemonforms.txt" if appropriate). The species having access to that move via its level-up moveset or as egg moves will not count. See the page [[Learning moves]] for more information.
 |}
-Each move that can be taught (by TMs, HMs and [[Special NPCs|Move Tutors]]) must have its own section in the [[PBS file]] "tm.txt", which lists all Pokémon capable of learning that move. See the page [[Learning moves]] for more information.
 == Item icons ==
-Each item has a single icon, which is located in the folder "Graphics/Icons" and called <code>itemXXX.png</code>, where <code>XXX</code> is the internal name of that item or its ID number padded to 3 digits (e.g. item number 6 would have an icon called "item006.png", item number 42 would have an icon called "item042.png").
+Each item has a single icon, which is located in the folder "Graphics/Items" and called <code>XXX.png</code>, where <code>XXX</code> 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):
-If the icon for a TM or HM item does not exist, then it will instead try to use an icon named <code>itemMachineXXX.png</code>, where <code>XXX</code> is the internal name of the type of the move it teaches (or the type's ID number padded to 3 digits).
+* TM - Tries the icon named <code>machine_XXX.png</code>, where <code>XXX</code> is the ID of the [[Defining a type|type]] of the move it teaches.
+* TR - Tries the icon named <code>machine_tr_XXX.png</code>, where <code>XXX</code> is the ID of the [[Defining a type|type]] of the move it teaches. If this isn't found, it tries the icon that a TM would use.
+* HM - Tries the icon named <code>machine_hm_XXX.png</code>, where <code>XXX</code> is the ID of the [[Defining a type|type]] of the move it teaches. If this isn't found, it tries the icon that a TM would use.
 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 at the top of the script section '''PItem_Sprites''' and are easily changeable; note that they apply to all item icons.
+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 <code>icon_item_XXX.png</code> (for non-mail items) or <code>icon_mail_XXX.png</code> (for mail items), where <code>XXX</code> is as above. If there isn't a unique icon for an item, it will use the default <code>icon_item.png</code> or <code>icon_mail.png</code> instead.
+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 <code>icon_item_XXX.png</code> (for non-mail items) or <code>icon_mail_XXX.png</code> (for mail items), where <code>XXX</code> is the ID of that item. If there isn't a unique icon for an item, it will use the default <code>icon_item.png</code> or <code>icon_mail.png</code> 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 <code>mail_XXX.png</code>, where <code>XXX</code> is the internal name of that item or its ID number padded to 3 digits.
+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 <code>mail_XXX.png</code>, where <code>XXX</code> is the ID of that item.
 Mail background pictures should be the size of the game screen.

Essentials Docs Wiki