Manipulating items

This page describes how to manipulate items in the game, including how to give/take items, count how many of an item a player has, check what kind of item an item is, and so forth.

Giving the player an item

There are three ways to give the player an item:

Script	What it does
pbReceiveItem(:POTION)	This gives the player an item. As elsewhere, "POTION" is the ID of the item to be given. Note the colon just before it. Two messages are shown: one states that the item has been received (and if it's a TM/TR/HM, the move it teaches is also stated), and the second message states that the player has put it in the appropriate pocket of their Bag. If the item is Leftovers, the first message will refer to it as "some Leftovers" rather than "a Potion"/"an Oran Berry". This script should be used when receiving an item from an NPC, because it displays the message that the player has "obtained" it (i.e. from another person, rather than finding it).
pbItemBall(:POTION)	This works the same as pbReceiveItem, except that the first message shown states that the player has "found" the item (rather than "obtained" it). Also, if the item cannot be added to the Bag, the second message instead says the Bag is full, and the item is not picked up. It is used in item balls. When making an item ball, this script is set up in that item ball event automatically when the game is compiled, so you will typically not need to use it yourself.
$bag.add(:POTION, 5)	This is used by the above two methods. It does the actual adding of the item to the Bag, and does not display any messages. The first parameter is the item to add, and the second is the quantity (default: 1). If the Bag becomes full in the middle of adding several items, then as many as possible of the item will be added (the rest are ignored), but it will be treated as if no items had been picked up (i.e. the method will still return FALSE) because it didn't add as many items as it wanted to. You should check beforehand whether the player has enough space to store all the items to be added. This won't normally be a problem, though, as by default all Bag pockets are infinite in size. This script is useful for giving the player 'default' items during the very start of the game.

All three scripts above will return TRUE if the item has been added to the player's Bag, and FALSE if it hasn't.

A slot in the Bag can only hold a maximum of 999 of an item (by default; this value is defined in the setting BAG_MAX_PER_SLOT in the script section Settings). If you attempt to give the player more than this amount, the excess will start filling up a new slot. For example, if the player has 997 Potions and the game gives them 5 more, 2 of the extra Potions will go into the existing slot and the other 3 will go into a new slot.

Giving multiple items

The first two scripts in the table above can also give more than 1 of an item. Here are examples of this:

pbReceiveItem(:POKEBALL, 5)
pbReceiveItem(:ORANBERRY, 3)
pbItemBall(:POTION, 4)
pbItemBall(:WISEGLASSES, 2)

The two parameters are the item itself and the quantity (default is 1 if not stated). The name of the item as stated in the message will be the plural form of the item's name (if the quantity is greater than 1) as defined in the PBS file "items.txt".

Deleting an item from the Bag

To delete an item that the player has, use the following script:

$bag.remove(:POTION)

To delete several of the same item, add the quantity as a second parameter like so:

$bag.remove(:POTION, 5)

This script returns TRUE if the item has been removed, and FALSE if it hasn't. It does not display any messages to indicate whether the item has been removed.

Note that if you try to delete more of an item than there are in the Bag, then as many as possible of that item will be deleted (i.e. all of them), but then this script will still return FALSE (because it didn't manage to delete as many as it should have).

Before deleting an item, you should check that the player has at least as many of that item as you want to delete, so that the script can execute fully.

Counting items in the Bag

If you want to check if the player has at least 1 of an item, you can use this:

$bag.has?(:POTION)

This is how items like Key Cards work. They have no effects themselves, but doors open when interacted with so long as the player has the item in their Bag. This is done by using this line of code in a Conditional Branch and making the door open within that Conditional Branch (i.e. if they have at least 1 of the item).

If you want to check if the player has at least a certain quantity of an item, you can use this:

$bag.has?(:POTION, 5)

This will return TRUE if the player has 5 or more Potions in their Bag, and FALSE if not.

To determine how many of a particular item the player currently has, use the following script:

$bag.quantity(:POTION)

This script returns a value, and does nothing else on its own. It should either be stored as a variable or be used as part of a check comparing this value to another value, e.g.

item_qty = $bag.quantity(:POTION)
$game_variables[42] = $bag.quantity(:POTION)
if $bag.quantity(:POTION) == 5
if $bag.quantity(:POTION) > 0

Choosing an item from the Bag

To make the player choose an item from the Bag, use either version of the following script:

pbChooseItem
pbChooseItem(1)

This method returns the ID of the chosen item (or nil if no item was chosen). The argument is optional, and is the number of the Game Variable in which the item's ID is stored (it will store :NONE instead of nil in that Game Variable, but will still return nil).

To make the player choose from a specific list of items, use the following script:

pbChooseItemFromList(_I("Choose an item"), 1, :POTION, :REPEL, :POKEBALL)

This method returns the ID of the chosen item (or nil if the choice was cancelled). The second argument (the number 1 here) is the Game Variable in which the returned value is stored (in addition to the method itself returning that value).

Any number of items can be listed. Only items which the player has at least 1 of will appear in the list. If the player has none of the listed items, then the method will immediately return/store nil without displaying the message or listing anything.

pbChooseApricorn
pbChooseFossil

These two methods are used to choose an Apricorn/Fossil item from the Bag. No other items will be shown in the Bag while choosing.

Other checks

Below is a list of other ways in which an item can be checked for or manipulated.

Script	Description
$bag.can_add?(:POTION) $bag.can_add?(:POTION, 5)	Returns TRUE if there is space in the Bag for the given amount of the given item (1 if an amount is not given); returns FALSE if there isn't.
GameData::Item.get(:POTION).name	Returns the name of the item.
GameData::Item.get(:POTION).price	Returns the money value of the item, i.e. the price the player would pay when buying it. The selling price of an item is half its buying price.
GameData::Item.get(:POTION).pocket	Returns the Bag pocket number that the item is stored in.
GameData::Item.get(:POTION).is_key_item?	Returns TRUE if the item is a Key Item (i.e. it has the "KeyItem" flag); returns FALSE otherwise.
GameData::Item.get(:POTION).is_important?	Returns TRUE if the item is a Key Item, a HM or a TM (i.e. something that cannot be tossed/sold); returns FALSE otherwise. Note that one-use TMs are treated as TRs and are not important items.
GameData::Item.get(:POTION).is_TM?	Returns TRUE if the item is a TM; returns FALSE otherwise.
GameData::Item.get(:POTION).is_TR?	Returns TRUE if the item is a TR (a single-use TM); returns FALSE otherwise.
GameData::Item.get(:POTION).is_HM?	Returns TRUE if the item is a HM; returns FALSE otherwise.
GameData::Item.get(:POTION).is_machine?	Returns TRUE if the item is a TM, a TR or a HM; returns FALSE otherwise.
GameData::Move.get(:CUT).hidden_move?	Returns TRUE if the move can be taught by any HM; returns FALSE otherwise.
GameData::Item.get(:POTION).is_berry?	Returns TRUE if the item is a berry; returns FALSE otherwise.
GameData::Item.get(:POTION).is_poke_ball?	Returns TRUE if the item is a Poké Ball or a Snag Ball; returns FALSE otherwise.
GameData::Item.get(:POTION).is_snag_ball?	Returns TRUE if the item is a Snag Ball, or if it is a Poké Ball while $player.has_snag_machine = true; returns FALSE otherwise.
GameData::Item.get(:POTION).is_mail?	Returns TRUE if the item is a Mail item; returns FALSE otherwise.
pbClosestHiddenItem	Returns the location of the nearest hidden item; returns nil if there is none in range. Used by the Itemfinder.

Activating item effects

There are a few ways to activate the effects of a given item.

Script	Description
ItemHandlers.triggerUseInField(:REPEL)	Triggers the activation of a given item type without consuming it.
pbUseKeyItemInField(:REPEL)	Triggers the activation of a given item type and consumes it.