The item system manages all usable items, from Poké Balls and medicine to Technical Machines and key items.
Item IDs All items are defined in constants/item_constants.asm with unique IDs:
Poké Balls
Medicine
Evolution Stones
Battle Items
const_def const NO_ITEM ; $00 const MASTER_BALL ; $01 const ULTRA_BALL ; $02 const GREAT_BALL ; $03 const POKE_BALL ; $04 const SAFARI_BALL ; $08
There are 83 base items (NUM_ITEMS = 83) before TMs/HMs. Badges reuse item IDs internally for storage purposes.
Badge Overloading Badges share IDs with Safari Zone items:
const BOULDERBADGE ; $15 DEF SAFARI_BAIT EQU BOULDERBADGE ; overload const CASCADEBADGE ; $16 DEF SAFARI_ROCK EQU CASCADEBADGE ; overload
This is safe because badges are never in the player’s bag—they’re stored in a separate bit field. Safari Bait/Rock items only exist during Safari Zone battles.
TMs and HMs Technical Machines and Hidden Machines start at ID $C4:
HM Definitions
TM Definitions
DEF HM01 EQU const_value add_hm CUT ; $C4 add_hm FLY ; $C5 add_hm SURF ; $C6 add_hm STRENGTH ; $C7 add_hm FLASH ; $C8 DEF NUM_HMS EQU const_value - HM01
There are 50 TMs and 5 HMs, requiring 7 bytes (56 bits) to store compatibility flags per Pokémon. One bit remains unused.
TM/HM Move Mapping Each TM/HM defines three constants:
; Example: HM01 HM_CUT ; Item ID ($C4) CUT_TMNUM ; TM/HM flag number (51) HM01_MOVE ; Alias for move ID (equals CUT)
This allows the code to:
Reference the item by name (HM_CUT)
Check compatibility flags (CUT_TMNUM)
Know which move it teaches (HM01_MOVE)
Item Usage System Item effects are handled by engine/items/item_effects.asm via a jump table:
UseItem_: : ld a, 1 ld [wActionResultOrTookBattleTurn], a ; initialise to success value ld a, [wCurItem] cp HM01 jp nc, ItemUseTMHM ld hl, ItemUsePtrTable dec a add a ld c, a ld b, 0 add hl, bc ld a, [hli] ld h, [hl] ld l, a jp hl
Initialize Result
Sets action result to 1 (success) by default.
Check for TM/HM
If item ID ≥ HM01, jump to TM/HM handler.
Look Up Handler
Use item ID as index into ItemUsePtrTable.
Execute Handler
Jump to the appropriate item effect function.
Item Effect Table From engine/items/item_effects.asm:
Capture Items
Key Items
Medicine
Evolution Stones
Vitamins
ItemUsePtrTable: dw ItemUseBall ; MASTER_BALL dw ItemUseBall ; ULTRA_BALL dw ItemUseBall ; GREAT_BALL dw ItemUseBall ; POKE_BALL
Multiple items can share the same handler function. For example, all medicine items use ItemUseMedicine, which internally checks which specific item was used.
Unusable Items Some items in the bag cannot be used:
dw UnusableItem ; THUNDERBADGE dw UnusableItem ; RAINBOWBADGE dw UnusableItem ; NUGGET dw UnusableItem ; COIN dw UnusableItem ; GOLD_TEETH
These are either key items that activate automatically or sellable items with no use effect.
Item Categories Consumable Battle Items X Stats, Guard Spec, and Dire Hit:
dw ItemUseXStat ; X_ATTACK dw ItemUseXStat ; X_DEFEND dw ItemUseXStat ; X_SPEED dw ItemUseXStat ; X_SPECIAL dw ItemUseGuardSpec ; GUARD_SPEC dw ItemUseDireHit ; DIRE_HIT dw ItemUseXAccuracy ; X_ACCURACY
These items apply temporary stat boosts during battle and are consumed on use.
PP Restoration dw ItemUsePPRestore ; ETHER dw ItemUsePPRestore ; MAX_ETHER dw ItemUsePPRestore ; ELIXER dw ItemUsePPRestore ; MAX_ELIXER dw ItemUsePPUp ; PP_UP
Ether/Max Ether : Restore PP to one move (10 or full)Elixir/Max Elixir : Restore PP to all moves (10 each or full)PP Up : Permanently increase max PP by 1/5 of base value (up to 3 uses)
Fishing Rods dw ItemUseOldRod ; OLD_ROD dw ItemUseGoodRod ; GOOD_ROD dw ItemUseSuperRod ; SUPER_ROD
Each rod triggers fishing encounters with different wild Pokémon pools.
Key Items Key items are tracked with bit flags in data/items/key_items.asm:
KeyItemFlags: db BICYCLE db SURF db POKE_FLUTE db SECRET_KEY db CARD_KEY db LIFT_KEY db SILPH_SCOPE db - 1 ; end
Key items cannot be sold or tossed. They remain in the bag until the game is completed or a specific story event removes them.
Repel System dw ItemUseRepel ; REPEL dw ItemUseSuperRepel ; SUPER_REPEL dw ItemUseMaxRepel ; MAX_REPEL
Repel : 100 stepsSuper Repel : 200 stepsMax Repel : 250 steps
Repels prevent encounters with wild Pokémon lower level than the first Pokémon in the party.
Item Capacity Limits DEF NUM_ITEMS EQU const_value - 1 ; 83 regular items DEF NUM_TMS EQU 50 DEF NUM_HMS EQU 5 DEF NUM_TM_HM EQU NUM_TMS + NUM_HMS ; 55 total DEF MAX_HIDDEN_ITEMS EQU 112 DEF MAX_HIDDEN_COINS EQU 16
Regular bag slots are unlimited per item type
PC item storage is unlimited
Hidden items tracked via bit flags (max 112)
Hidden coins tracked separately (max 16)
Special Items Safari Zone Items dw ItemUseBait ; BOULDERBADGE (overloaded) dw ItemUseRock ; CASCADEBADGE (overloaded)
Bait and rocks only exist during Safari Zone battles:
Bait : Decreases catch rate, decreases flee chanceRock : Increases catch rate, increases flee chance
Field Effects
dw ItemUseEscapeRope ; ESCAPE_ROPE
Instantly exits dungeons, returning to the last Pokémon Center.
dw ItemUsePokeFlute ; POKE_FLUTE
Wakes sleeping Pokémon in battle and awakens Snorlax on the overworld.
dw ItemUseItemfinder ; ITEMFINDER
Detects hidden items nearby with an on-screen indicator.
dw ItemUsePokeDoll ; POKE_DOLL
Guaranteed escape from wild battles, including Ghost Marowak. Item Pricing Item prices are stored in data/items/prices.asm as 24-bit BCD (Binary Coded Decimal) values:
ItemPrices: bcd3 0 ; MASTER_BALL (cannot buy) bcd3 1200 ; ULTRA_BALL bcd3 600 ; GREAT_BALL bcd3 200 ; POKE_BALL
TM prices are in a separate table (data/items/tm_prices.asm) since TMs have different IDs.
Pokémon TM/HM compatibility
Battle Engine Battle item effects
Reference Item constants and data
Engine Modules Item engine implementation
Key Files
constants/item_constants.asm - Item IDs and TM/HM definitionsengine/items/item_effects.asm - Item usage handlersdata/items/names.asm - Item name stringsdata/items/prices.asm - Item pricesdata/items/key_items.asm - Key item flagsengine/items/ - Item-related engine code 