Skip to content

Items and shops

An item is a section of pbs/items.txt, in the PBS format of Essentials v21.1. Nothing in the engine lists items: a game has the items its file has. From the sample:

[SALVE]
Name = Salve
NamePlural = Salves
Pocket = 2
Price = 300
FieldUse = OnPokemon
BattleUse = OnPokemon
Flags = Fling_30
FieldEffect = Heal,20
Description = Restores 20 HP of one creature.

Pocket is the bag pocket: 1 items, 2 medicine, 3 balls, 4 machines, 5 berries, 6 mail, 7 battle items, 8 key items. Price is what a shop asks; SellPrice, when given, is what it pays (half the price otherwise, as Essentials has it). Description is the line the bag and the shop show. The data for real items is fetched, never stored in the repository (see Creatures, moves and data).

FieldEffect is this engine’s own key: what the item does when the player uses it from the bag. It is data because most field items are one of a few kinds, and a kind with a number covers every potion, every antidote and every repellent a game can invent.

Line The item
FieldEffect = Heal,20 Restores 20 HP (Heal,All: all of it)
FieldEffect = Cure,Poison Cures a status (Burn, Paralysis, Sleep, Freeze; Cure alone: any)
FieldEffect = Restore All HP and any status
FieldEffect = Revive,50 Brings a fainted creature back with half its HP
FieldEffect = Repel,100 Weaker wild creatures stay away for 100 steps
FieldEffect = PP,10, PPAll,10, PPUp,1 Restores PP of one move or all, or raises a move’s PP
FieldEffect = Boost,ATTACK,2 In battle, raises a stat stage of the creature out (an X item)

The healing kinds open the party screen to choose the creature. The sample’s Scent Bag is a repellent:

[SCENTBAG]
Pocket = 1
Price = 400
FieldUse = Direct
Flags = Repel,Fling_30
FieldEffect = Repel,100

An item with FieldUse = Direct and no FieldEffect runs a script when the player chooses “use”: the bag closes and the shared file’s on use hook starts. This is how key items work. From the sample’s scripts/common.pfs:

on use STATIONPASS {
lock
say "A staff pass for the field station.\nIt opens the door under the lamp."
release
}
on use BICYCLE {
if !fieldmove(bike) {
lock
say "There's no riding here."
release
}
}

An item without a hook says that it cannot be used here. A rod named in [world.fishing] rods casts by itself unless the game has an on use hook for it (see Wild encounters).

A machine is an item with FieldUse = TM (or HM, TR) and a Move = line. Used on a creature that can learn the move, it teaches it; a creature that knows four moves is asked which to forget. Whether the machine breaks comes from its record. Planned (plan 25): reusable machines as a game setting, since how many of each a game places is balanced on that rule. istm item asks whether an item is a machine, and buffer 0, tmmove, item names its move.

An item with Essentials’ identifier for a ball needs no extra line. A ball of your own names its rule with BallRule: Great, Ultra, Master, Fast, Level, Lure, Heavy, Love, Friend or Moon, with the newer generations’ rates. The sample’s Kindle Ball, which the hill’s craftsman makes from nuts, is a level ball:

[KINDLEBALL]
Name = Kindle Ball
Pocket = 3
BattleUse = OnFoe
Flags = PokeBall,Fling_10
BallRule = Level

The player’s bag in battle offers medicine and balls. Trainers use their Items line in pbs/trainers.txt: a healing item when their creature is low, a cure for its status, an X item on its first turn out (see Battles). The player’s own X items in battle are not built yet. [rules] no_battle_items = true limits the player’s bag in battle to balls (see Rules, options and cheats).

The bag’s shape is one game’s rules, chosen with bag in [rules]: "emerald", "platinum", "heartgold", "black2" or "modern". The preset sets the slots of each pocket, the stack sizes, how many items can be registered for the SELECT shortcut, and the free-space pocket (decision 274). Scripts ask the bag with hasitem, canhold and pocket, and change it with giveitem and takeitem.

Neither is a kind of its own. An item on the ground is an actor with a hide rule and a talk script; a hidden item is a spot with a read script. Both call the sample’s shared found_item script, which gives the item, plays a jingle and says what was found:

on read plant_tub {
lock
if GOT_TUB_COIN {
say "Damp soil."
} else {
temp(0) = OLDCOIN
temp(1) = 1
call found_item
if temp(7) { set GOT_TUB_COIN }
}
release
}

Why scripts and not a built-in kind: a creator decides what finding an item sounds and looks like, and the flag that keeps it gone is an ordinary flag.

A shop’s stock is a section of pbs/shops.txt, the items in the order they are offered:

[STATION_SHELF]
Items = SALVE,STRONGSALVE,WAKEROOT,TWINEBALL,SCENTBAG
[KIOSK]
Items = TWINEBALL

A script opens it and waits until the player leaves:

on read trolley {
lock
say "A supply trolley. A price list,\nand a tin for the money."
shop STATION_SHELF
release
}

The shop offers buy, sell and leave. shop KIOSK, percent: 200 charges double; what the shop pays for the player’s things is not multiplied. A list’s number is its place in the file; ploom pack writes the numbers into pack/game.sym, and a symbol file names them for scripts (shop STATION_SHELF = 0).

Planned (plan 46): an on shopstock hook that adds, removes or reprices items as a shop opens, for stock that grows with badges or a sale day.

graphics/items/ holds one picture an item, named by its identifier in lower case (salve.png). The bag shows the icon of the item under the cursor. A picture is a PNG of at most 32 × 32 pixels with at most 15 colours; an item without one shows none. The build says how many items have an icon and notes a picture that is no item’s.

Beside money a game may have up to eight currencies of its own: coins for a game corner, points for a battle facility. Each is declared in game.toml with its name on screen (a line of text.txt) and the most a player may hold. The sample:

[rules.currencies]
coins = { label = "cur_coins", max = 9999 }

Scripts use it by name: currency coins, givecurrency coins, 10, takecurrency coins, 3, currencyroom coins, and showcurrency coins puts the amount in the money box. Amounts start at 0 and are saved. A move tutor may charge in a currency (see Game systems). Every key is in the game.toml reference.