Items and shops
Item data
Section titled “Item data”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 = SalveNamePlural = SalvesPocket = 2Price = 300FieldUse = OnPokemonBattleUse = OnPokemonFlags = Fling_30FieldEffect = Heal,20Description = 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).
Field use
Section titled “Field use”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 = 1Price = 400FieldUse = DirectFlags = Repel,Fling_30FieldEffect = Repel,100Key items
Section titled “Key items”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).
Machines
Section titled “Machines”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 BallPocket = 3BattleUse = OnFoeFlags = PokeBall,Fling_10BallRule = LevelBattle use
Section titled “Battle use”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.
Ground items
Section titled “Ground items”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 = TWINEBALLA 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.
Item icons
Section titled “Item icons”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.
Currencies
Section titled “Currencies”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.