Warning: This is a mirror of http://sphericalice.com/romhacking/documents/script/ . It will probably get out of date and stuff (last updated 2014-12-31 20:47)

Pokémon FireRed Scripting Commands

original document created by DavidJCobb with some revisions

This document is meant to serve as a comprehensive reference to each scripting command. The information is FireRed-centric and includes detailed descriptions of what the commands do, the locations of their ASM code, and more.

Commands above 0xD5 are not listed because they do not exist in FireRed.

Some revisions have been added in. They are styled like so. Want to make a contribution? PM Spherical Ice on PokéCommunity, or e-mail him.

Table of contents

  1. List of data types
  2. List of script commands

    Filter:

    1. 0x00 nop
    2. 0x01 nop1
    3. 0x02 end
    4. 0x03 return
    5. 0x04 call
    6. 0x05 goto
    7. 0x06 if1 (if)
    8. 0x07 if2 (if)
    9. 0x08 gotostd
    10. 0x09 callstd
    11. 0x0A gotostdif
    12. 0x0B callstdif
    13. 0x0C jumpram
    14. 0x0D killscript
    15. 0x0E setbyte
    16. 0x0F loadpointer (acts like "setbank")
    17. 0x10 setbyte2
    18. 0x11 writebytetooffset
    19. 0x12 loadbytefrompointer
    20. 0x13 setfarbyte
    21. 0x14 copyscriptbanks
    22. 0x15 copybyte
    23. 0x16 setvar
    24. 0x17 addvar
    25. 0x18 subvar
    26. 0x19 copyvar
    27. 0x1A copyvarifnotzero (acts like "copyorsetvar")
    28. 0x1B comparebanks
    29. 0x1C comparebanktobyte
    30. 0x1D comparebanktofarbyte
    31. 0x1E comparefarbytetobank
    32. 0x1F comparefarbytetobyte
    33. 0x20 comparefarbytes
    34. 0x21 compare
    35. 0x22 comparevars
    36. 0x23 callasm
    37. 0x24 cmd24
    38. 0x25 special
    39. 0x26 special2
    40. 0x27 waitstate
    41. 0x28 pause
    42. 0x29 setflag
    43. 0x2A clearflag
    44. 0x2B checkflag
    45. 0x2C cmd2c (nop)
    46. 0x2D checkdailyflags (nop)
    47. 0x2E resetvars
    48. 0x2F sound
    49. 0x30 checksound (acts like "waitsound")
    50. 0x31 fanfare
    51. 0x32 waitfanfare
    52. 0x33 playsong
    53. 0x34 playsong2
    54. 0x35 fadedefault
    55. 0x36 fadesong
    56. 0x37 fadeout
    57. 0x38 fadein
    58. 0x39 warp
    59. 0x3A warpmuted
    60. 0x3B warpwalk
    61. 0x3C warphole
    62. 0x3D warpteleport
    63. 0x3E warp3
    64. 0x3F setwarpplace
    65. 0x40 warp4
    66. 0x41 warp5
    67. 0x42 getplayerpos
    68. 0x43 countPokémon
    69. 0x44 additem
    70. 0x45 removeitem
    71. 0x46 checkitemroom
    72. 0x47 checkitem
    73. 0x48 checkitemtype
    74. 0x49 addpcitem
    75. 0x4A checkpcitem
    76. 0x4B adddecoration (nop)
    77. 0x4C removedecoration (nop)
    78. 0x4D testdecoration (nop)
    79. 0x4E checkdecoration (nop)
    80. 0x4F applymovement
    81. 0x50 applymovementpos
    82. 0x51 waitmovement
    83. 0x52 waitmovementpos
    84. 0x53 hidesprite
    85. 0x54 hidespritepos
    86. 0x55 showsprite
    87. 0x56 showspritepos
    88. 0x57 movesprite
    89. 0x58 spritevisible
    90. 0x59 spriteinvisible
    91. 0x5A faceplayer
    92. 0x5B spriteface
    93. 0x5C trainerbattle
    94. 0x5D repeattrainerbattle (acts like "dotrainerbattle")
    95. 0x5E endtrainerbattle
    96. 0x5F endtrainerbattle2
    97. 0x60 checktrainerflag
    98. 0x61 cleartrainerflag (acts like "settrainerflag")
    99. 0x62 settrainerflag (acts like "cleartrainerflag")
    100. 0x63 movesprite2
    101. 0x64 moveoffscreen
    102. 0x65 spritebehave
    103. 0x66 waitmsg
    104. 0x67 preparemsg
    105. 0x68 closeonkeypress
    106. 0x69 lockall
    107. 0x6A lock
    108. 0x6B releaseall
    109. 0x6C release
    110. 0x6D waitkeypress
    111. 0x6E yesnobox
    112. 0x6F multichoice
    113. 0x70 multichoice2
    114. 0x71 multichoice3
    115. 0x72 showbox
    116. 0x73 hidebox
    117. 0x74 clearbox
    118. 0x75 showpokepic
    119. 0x76 hidepokepic
    120. 0x77 showcontestwinner (nop)
    121. 0x78 braille
    122. 0x79 givePokémon
    123. 0x7A giveegg
    124. 0x7B setpkmnpp
    125. 0x7C checkattack
    126. 0x7D bufferPokémon
    127. 0x7E bufferfirstPokémon
    128. 0x7F bufferpartyPokémon
    129. 0x80 bufferitem
    130. 0x81 bufferdecoration (nop)
    131. 0x82 bufferattack
    132. 0x83 buffernumber
    133. 0x84 bufferstd
    134. 0x85 bufferstring
    135. 0x86 pokemart
    136. 0x87 pokemart2
    137. 0x88 pokemart3
    138. 0x89 pokecasino
    139. 0x8A cmd8a (nop)
    140. 0x8B choosecontestpkmn
    141. 0x8C startcontest (nop)
    142. 0x8D showcontestresults (nop)
    143. 0x8E contestlinktransfer (nop)
    144. 0x8F random
    145. 0x90 givemoney
    146. 0x91 paymoney
    147. 0x92 checkmoney
    148. 0x93 showmoney
    149. 0x94 hidemoney
    150. 0x95 updatemoney
    151. 0x96 cmd96 (nop)
    152. 0x97 fadescreen
    153. 0x98 fadescreendelay
    154. 0x99 darken
    155. 0x9A lighten
    156. 0x9B preparemsg2
    157. 0x9C doanimation
    158. 0x9D setanimation
    159. 0x9E checkanimation (acts like "waitanimation")
    160. 0x9F sethealingplace
    161. 0xA0 checkgender
    162. 0xA1 cry
    163. 0xA2 setmaptile
    164. 0xA3 resetweather
    165. 0xA4 setweather
    166. 0xA5 doweather
    167. 0xA6 cmda6 (acts like "settilemanager")
    168. 0xA7 setmapfooter
    169. 0xA8 spritelevelup
    170. 0xA9 restorespritelevel
    171. 0xAA createsprite
    172. 0xAB spriteface2
    173. 0xAC setdooropened
    174. 0xAD setdoorclosed
    175. 0xAE doorchange
    176. 0xAF setdooropened2
    177. 0xB0 setdoorclosed2
    178. 0xB1 cmdb1 (nop)
    179. 0xB2 cmdb2 (nop)
    180. 0xB3 checkcoins
    181. 0xB4 givecoins
    182. 0xB5 removecoins
    183. 0xB6 setwildbattle
    184. 0xB7 dowildbattle
    185. 0xB8 setvirtualaddress
    186. 0xB9 virtualgoto
    187. 0xBA virtualcall
    188. 0xBB virtualgotoif
    189. 0xB9 virtualcallif
    190. 0xB9 virtualmsgbox
    191. 0xB9 virtualloadpointer
    192. 0xB9 virtualbuffer
    193. 0xC0 showcoins
    194. 0xC1 hidecoins
    195. 0xC2 updatecoins
    196. 0xC3 cmdc3
    197. 0xC4 warp6
    198. 0xC5 waitcry
    199. 0xC6 bufferboxname
    200. 0xC7 textcolor
    201. 0xC8 cmdc8
    202. 0xC9 cmdc9
    203. 0xCA signmsg
    204. 0xCB normalmsg
    205. 0xCC comparehiddenvar
    206. 0xCD setobedience
    207. 0xCE checkobedience
    208. 0xCF executeram
    209. 0xD0 setworldmapflag
    210. 0xD1 warpteleport2
    211. 0xD2 setcatchlocation
    212. 0xD3 braille2 (acts like "getbraillewidth")
    213. 0xD4 bufferitems
    214. 0xD5 cmdd5 (nop)
    X complete out of Y documented out of Z
  3. Appendix

List of data types

byte

A single-byte value.

word

A two-byte value.

dword

A four-byte value.

pointer

A dword. The value should be the offset (in ROM or RAM) of some piece of data that the command needs.

variable

The two-byte numeric identifier of any valid script variable; that is, a word value greater than 0x3FFF.

In most cases, commands that accept variables will extract the variables' values and use those values as input. Sometimes, a command will actually act on the variable itself rather than on its value (i.e. setvar).

It should be noted that variables 0x5084 to 0x7FFF are not actually valid scripting variables, and modifying them may overwrite game data (including Pokémon stored in the PC).[source] Variables 0x4100 to 0x4180 may also be unsafe; a list of all safe variables hasn't been created yet.

Check out this document by karatekid552 on safe variables and flags.

flag

The two-byte numeric identifier of any valid script flag; that is, a word value lower than 0x0900.

It should be noted that many flags have been reserved by the game engine. Flags 0x500 to 0x700 are trainer flags, flags 0x890 to 0x8FD are world map flags, and many others are used as well.

bank

The single-byte numeric identifier of one of the four zero-indexed script banks.

buffer

The single-byte numeric identifier of one of the three zero-indexed string buffers.

hidden-variable

The single-byte numeric identifier of one of the game's 64 hidden variables.

pointer-or-bank

If the supplied argument is between 0x00000000 and 0x00000003 (inclusive), then it will be treated as a reference to a script bank. Otherwise, it is treated as a four-byte pointer to data.

pointer-or-bank-0

A pointer or script bank 0 may be used, but the other script banks may not be used.

flag-or-variable

If the supplied argument is a variable, then the game will use its value to locate the proper flag. Otherwise, the argument itself is treated as a flag identifier.

word-or-variable

If the supplied argument is a variable, then the game will extract that variable's value and use that as the input. Otherwise, the argument itself becomes the input.

byte-or-variable

If the supplied argument is a variable, then the game will extract that variable's value and use that as the input. Otherwise, the argument itself becomes the input. Either way, the input must be a word but is converted to a single-byte value (all bytes except the least-significant byte are discarded; 0xYYZZ -> 0x00ZZ).


List of script commands

  1. 00 nop

    Does nothing.

  2. 01 nop1

    Does nothing.

  3. 02 end

    Terminates script execution.

  4. 03 return

    Jumps back to after the last-executed call statement, and continues script execution from there.

  5. 04 call

    Arguments:
    • pointer destination

    Jumps to destination and continues script execution from there. The location of the calling script is remembered and can be returned to later.

    The maximum script depth (that is, the maximum nested calls you can make) is 20. When this limit is reached, the game starts treating call as goto.[source]

  6. 05 goto

    Arguments:
    • pointer destination

    Jumps to destination and continues script execution from there.

  7. 06 if1

    Arguments:
    • byte condition
    • pointer destination

    If the result of the last comparison matches condition (see Comparison operators), jumps to destination and continues script execution from there.

    XSE automatically converts the slightly-more-readable form if condition goto pointer to an if1.

  8. 07 if2

    Arguments:
    • byte condition
    • pointer destination

    If the result of the last comparison matches condition (see Comparison operators), calls destination.

    XSE automatically converts the slightly-more-readable form if condition call pointer to an if2.

  9. 08 gotostd

    Arguments:
    • byte function

    Jumps to the standard function at index function.

  10. 09 callstd (a.k.a. boxset)

    Arguments:
    • byte function

    Calls the standard function at index function.

  11. 0A gotostdif

    Arguments:
    • byte condition
    • byte function

    If the result of the last comparison matches condition (see Comparison operators), jumps to the standard function at index function.

  12. 0B callstdif

    Arguments:
    • byte condition
    • byte function

    If the result of the last comparison matches condition (see Comparison operators), calls the standard function at index function.

  13. 0C jumpram [details needed]

    Executes a script stored in a default RAM location.

  14. 0D killscript [details needed]

    Terminates script execution and "resets the script RAM".

  15. ASM (FR): 0x0806A275

    0E setbyte [details needed]

    Arguments:
    • byte value

    Pads the specified value to a dword, and then writes that dword to a predefined address (0x0203AAA8).

    (What does that RAM offset do?)

  16. 0F loadpointer

    Arguments:
    • bank destination
    • dword value

    Sets the specified script bank to value.

    (The function is named "loadpointer" because it was originally used to store pointers to strings in script banks, in preparation for certain dialog box-related standard functions. "Setbank" would have been a better name.)

  17. 10 setbyte2

    Arguments:
    • bank destination
    • byte value

    Sets the specified script bank to value.

  18. 11 writebytetooffset

    Arguments:
    • byte value
    • pointer offset

    Sets the byte at offset to value.

  19. 12 loadbytefrompointer

    Arguments:
    • bank destination
    • pointer source

    Copies the byte value at source into the specified script bank.

  20. 13 setfarbyte [details needed]

    Arguments:
    • bank source
    • pointer destination

    Not sure. Judging from XSE's description I think it takes the least-significant byte in bank source and writes it to destination.

  21. 14 copyscriptbanks

    Arguments:
    • bank destination
    • bank source

    Copies the contents of bank source into bank destination.

  22. 15 copybyte

    Arguments:
    • pointer destination
    • pointer source

    Copies the byte at source to destination, replacing whatever byte was previously there.

  23. 16 setvar

    Arguments:
    • variable destination
    • word value

    Changes the value of destination to value.

  24. 17 addvar

    Arguments:
    • variable destination
    • word value

    Changes the value of destination by adding value to it. Overflow is not prevented (0xFFFF + 1 = 0x0000).

  25. 18 subvar

    Arguments:
    • variable destination
    • word-or-variable value

    Changes the value of destination by subtracting value to it. Overflow is not prevented (0x0000 - 1 = 0xFFFF).

  26. 19 copyvar

    Arguments:
    • variable destination
    • variable source

    Copies the value of source into destination.

  27. 1A copyvarifnotzero

    Arguments:
    • variable destination
    • word-or-variable source

    If source is not a variable, then this function acts like setvar. Otherwise, it acts like copyvar.

    ("Copyvarifnotzero" is a misnomer. This function was previously thought to act like copyvar if source was a variable with a non-zero value, and to do nothing otherwise.)

  28. ASM (FR): 0x0806A42D

    1B comparebanks

    Arguments:
    • bank a
    • bank b

    Compares the values of script banks a and b, after forcing the values to bytes.

    Warning: XSE has it wrong. The arguments are bytes, not words. This means that you will need to use #raw to compile a script that uses this command, and that such scripts will not decompile properly.

  29. 1C comparebanktobyte

    Arguments:
    • bank a
    • byte b

    Compares the least-significant byte of the value of script bank a to a fixed byte value (b).

  30. 1D comparebanktofarbyte

    Arguments:
    • bank a
    • pointer b

    Compares the least-significant byte of the value of script bank a to the byte located at offset b.

  31. 1E comparefarbytetobank

    Arguments:
    • pointer a
    • bank b

    Compares the byte located at offset a to the least-significant byte of the value of script bank b.

  32. 1F comparefarbytetobyte

    Arguments:
    • pointer a
    • byte b

    Compares the byte located at offset a to a fixed byte value (b).

  33. 20 comparefarbytes

    Arguments:
    • pointer a
    • pointer b

    Compares the byte located at offset a to the byte located at offset b.

  34. 21 compare

    Arguments:
    • variable a
    • word b

    Compares the value of a to a fixed word value (b).

  35. 22 comparevars

    Arguments:
    • variable a
    • variable b

    Compares the value of a to the value of b.

  36. 23 callasm

    Arguments:
    • pointer code

    Calls the ASM routine stored at code. Script execution is blocked until the ASM returns (bx lr, mov pc, lr, etc.). Remember to add 1 to the offset when calling THUMB code.

  37. ASM (FR): 0x08069EE5

    24 cmd24 [details needed]

    Arguments:
    • pointer asm_pointer

    Replaces a pointer in the script engine RAM with asm_pointer.

    (The pointer points to a THUMB routine... What effect does replacing it have?)

  38. 25 special

    Arguments:
    • word function

    Calls a special function; that is, a piece of ASM code designed for use by scripts and listed in a table of pointers.

    The special table is located at 0x0815FD60.

  39. 26 special2

    Arguments:
    • variable output
    • word function

    Calls a special function. That function's output (if any) will be written to the variable you specify.

  40. 27 waitstate [details needed]

    Blocks script execution until a command or ASM code manually unblocks it. Generally used with specific commands and specials. If this command runs, and a subsequent command or piece of ASM does not unblock state, the script will remain blocked indefinitely (essentially a hang).

  41. 28 pause [details needed]

    Arguments:
    • word time

    Blocks script execution for time (frames? milliseconds?).

    (According to some movement tutorials on the web, a value of 0x0010 represents the amount of time it takes for a walking NPC to move one tile.)

  42. 29 setflag

    Arguments:
    • flag-or-variable a

    Sets a to 1.

  43. 2A clearflag

    Arguments:
    • flag-or-variable a

    Sets a to 0.

  44. 2B checkflag

    Arguments:
    • flag-or-variable a

    Compares a to 1.

  45. ASM (FR): 0x0806A9D5

    2C cmd2c

    In FireRed, this command is a nop.

    Warning: XSE has it wrong. The function has no arguments. This means that you may need to use #raw to compile a script that uses this command, and that such scripts will not decompile properly.

  46. ASM (FR): 0x0806A9D9

    2D checkdailyflags

    In FireRed, this command is a nop.


    In R/S/E, it had something to do with flags and the real-time clock.

  47. 2E resetvars

    Resets the values of variables 0x8000, 0x8001, and 0x8002.

  48. 2F sound

    Arguments:
    • word sound_number

    Plays the specified (sound_number) sound. Only one sound may play at a time, with newer ones interrupting older ones.

    If you specify sound 0x0000, then all music will be muted. If you specify the number of a non-existent sound, no new sound will be played, and currently-playing sounds will not be interrupted. A comprehensive list of sound numbers may be found on PokeCommunity.

    Note that when using older versions of VisualBoyAdvance, the sound channel used for this command (and, sometimes, in music) will be completely muted after loading from a savestate.

  49. 30 checksound [details needed]

    Blocks script execution until the currently-playing sound (triggered by sound) finishes playing.

    (Does this also block until cries finish playing? The manner in which it's used by default scripts suggests that it might.)

  50. 31 fanfare [details needed]

    Arguments:
    • word-or-variable fanfare_number

    Plays the specified (fanfare_number) fanfare.

    (Is it limited to one fanfare at a time, like sound?)

  51. 32 waitfanfare

    Blocks script execution until all currently-playing fanfares finish.

  52. 33 playsong [details needed]

    Arguments:
    • word song_number
    • byte unknown

    Plays the specified (song_number) song. The byte is apparently supposed to be 0x00.

    (I need to test this command to see it has any quirks... And does it accept a variable?)

  53. 34 playsong2 [details needed]

    Arguments:
    • word song_number

    Plays the specified (song_number) song.

    (I need to test this command to see it has any quirks... Among other things, it's failed to work for me in situations where playsong has worked. And does it accept a variable?)

  54. 35 fadedefault [details needed]

    Crossfades the currently-playing song into the map's default song.

    (I need to test this command to see it has any quirks...)

  55. 36 fadesong [details needed]

    Arguments:
    • word song_number

    Crossfades the currently-playng song into the specified (song_number) song.

    (I need to test this command to see it has any quirks... And does it accept a variable?)

  56. 37 fadeout [details needed]

    Arguments:
    • byte speed

    Fades out the currently-playing song.

    (I need to test this command to see it has any quirks... And what unit of measurement is used for speed? And does it accept a variable?)

  57. 38 fadein [details needed]

    Arguments:
    • byte speed

    Fades the currently-playing song back in.

    (I need to test this command to see it has any quirks... And what unit of measurement is used for speed? And does it accept a variable?)

  58. ASM (FR): 0x0806AA65

    39 warp [details needed]

    Arguments:
    • byte bank
    • byte map
    • byte warp
    • byte-or-variable X
    • byte-or-variable Y

    Sends the player to Warp warp on Map bank.map. If the specified warp is 0xFF, then the player will instead be sent to (X, Y) on the map.

    This command will also play Sappy song 0x0009, but only if the bytes at 0x02031DD8 and 0x0203ADFA are not equal to 0x00 and 0x02, respectively.

    (Function terminates script execution?)

  59. ASM (FR): 0x0806AAED

    3A warpmuted

    Clone of warp that does not play a sound effect.

  60. 3B warpwalk [details needed]

    Clone of warp that uses "a walking effect".

    (Any other differences?)

  61. 3C warphole [details needed]

    Arguments:
    • byte bank
    • byte map

    Warps the player to another map using a hole animation. It doesn't accept warp numbers or X/Y coordinates, so where does it send the player? Same (X, Y) as when the command is triggered?

  62. 3D warpteleport [details needed]

    Clone of warp that uses a teleport effect. It is apparently only used in R/S/E.[source]

    (Any other differences?)

  63. ASM (FR): 0x0806AD8D

    3E warp3 [details needed]

    Clone of warp. Used by an (unused?) Safari Zone script to return the player to the gatehouse and end the Safari Game.

    The only difference between this and warp/warpmuted are that those two commands write 01 01 00 to 0x02031DD4 when they finish, but this command does not. I don't yet know what this difference means.

  64. 3F setwarpplace [details needed]

    Arguments:
    • byte bank
    • byte map
    • byte warp
    • word X
    • word Y

    Sets a default warp place. If a warp tries to send the player to Warp 127 on Map 127.127, they will instead be sent here. Useful when a map has warps that need to go to script-controlled locations (i.e. elevators).

    (Does this accept variables for X and Y?)

  65. ASM (FR): 0x0806AE91

    40 warp4 [details needed]

    Clone of warp3, except that this writes data to different offsets...

    With normal warp commands, the stats for the map being entered replace data starting at 0x02031DBC (RAM: current map)... But this warp command instead writes to 0x02031DC4.

    (With that in mind, could this have been used internally for DIVE?)

  66. ASM (FR): 0x0806AF11

    41 warp5 [details needed]

    Clone of warp3, except that this writes data to different offsets...

    With normal warp commands, the stats for the map being entered replace data starting at 0x02031DBC (RAM: current map)... But this warp command instead writes to 0x02031DCC.

    (With that in mind, could this have been used internally for DIVE?)

  67. 42 getplayerpos

    Arguments:
    • variable X
    • variable Y

    Retrieves the player's zero-indexed X- and Y-coordinates in the map, and stores them in the specified variables.

  68. 43 countPokémon

    Retrieves the number of Pokémon in the player's party, and stores that number in variable 0x800D (LASTRESULT).

  69. 44 additem

    Arguments:
    • word-or-variable index
    • byte-or-variable quantity

    Attempts to add quantity of item index to the player's Bag. If the player has enough room, the item will be added and variable 0x800D (LASTRESULT) will be set to 0x0001; otherwise, LASTRESULT is set to 0x0000.

  70. 45 removeitem

    Arguments:
    • word-or-variable index
    • byte-or-variable quantity

    Removes quantity of item index from the player's Bag.

    If you attempt to remove more of the item than the player actually has, then this command will do absolutely nothing, and they will keep the item. (For example, attempting to remove 6 Master Balls when the player only has 5 will result in them keeping all 5.)

  71. 46 checkitemroom

    Arguments:
    • word-or-variable index
    • byte-or-variable quantity

    Checks if the player has enough space in their Bag to hold quantity more of item index. Sets variable 0x800D (LASTRESULT) to 0x0001 if there is room, or 0x0000 is there is no room.

  72. 47 checkitem

    Arguments:
    • word-or-variable index
    • byte-or-variable quantity

    Checks if the player has quantity or more of item index in their Bag. Sets variable 0x800D (LASTRESULT) to 0x0001 if the player has enough of the item, or 0x0000 if they have fewer than quantity of the item.

  73. 48 checkitemtype

    Arguments:
    • word-or-variable index

    Checks which Bag pocket the specified (index) item belongs in, and writes the value to variable 0x800D (LASTRESULT). This script is used to show the name of the proper Bag pocket when the player receives an item via callstd (simplified to giveitem in XSE).

    Return values:

    1. 0x0001 Items Pocket
    2. 0x0002 Key Items Pocket
    3. 0x0003 Poke Balls Pocket
    4. 0x0004 TM Case
    5. 0x0005 Berry Pouch
  74. 49 addpcitem

    Arguments:
    • word-or-variable index
    • word-or-variable quantity

    Adds a quantity amount of item index to the player's PC. Both arguments can be variables.

  75. 4a checkpcitem

    Arguments:
    • word-or-variable index
    • word-or-variable quantity

    Checks for quantity amount of item index in the player's PC. Both arguments can be variables.

    Return values:

  76. ASM (FR): 0x0806A7DD

    4B adddecoration

    Arguments:
    • word-or-variable a

    In FireRed, this command is a nop. (The argument is read, but not used for anything.)


    In R/S/E, it added one of the specified (a) decoration to the player's PC, and stored something in variable 0x800D (LASTRESULT) -- apparently, a value determining whether the decoration was successfully added (0x0001) or not (0x0000).

  77. ASM (FR): 0x0806A7F1

    4C removedecoration

    Arguments:
    • word-or-variable a

    In FireRed, this command is a nop. (The argument is read, but not used for anything.)


    In R/S/E, it removed one of the specified (a) decoration from the player's PC.

  78. ASM (FR): 0x0806A819

    4D testdecoration

    Arguments:
    • word-or-variable a

    In FireRed, this command is a nop. (The argument is read, but not used for anything.)


    In R/S/E, it checked to see if the player's PC could store one more of the specified (a) decoration.

  79. ASM (FR): 0x0806A805

    4E checkdecoration

    Arguments:
    • word-or-variable a

    In FireRed, this command is a nop. (The argument is read, but not used for anything.)


    In R/S/E, it checked to see if the player's PC contained at least one of the specified (a) decoration.

  80. 4F applymovement

    Arguments:
    • byte-or-variable index
    • pointer movements

    Applies the movement data at movements to the specified (index) Person event. Also closes any standard message boxes that are still open.

    Indices 0xFF and 0x7F refer to the player and the camera, respectively. Running this command from a Script event will crash the game unless that Script event's "Unknown" field (in AdvanceMap) is "$0003" and its "Var number" field refers to a valid script variable.

  81. 50 applymovementpos [details needed]

    Arguments:
    • word variable containing Person event ID
    • pointer movements

    Apparent clone of applymovement. Oddly, it doesn't seem to work at all if applied to any Person other than the player (0xFF), and the X and Y arguments don't seem to do anything.
    This command in fact uses variables to access the Person event ID. So, for example, if you setvar 0x8000 to 0x3, and then use applymovementpos 0x8000 @move1, Person event 3 will have the movements at @move1 applied to them. Thank you Shiny Quagsire for bringing this to my attention.

  82. 51 waitmovement

    Arguments:
    • byte-or-variable index

    Blocks script execution until the movements being applied to the specified (index) Person event finish. If the specified Person event is 0x0000, then the command will block script execution until all Person events affected by applymovement finish their movements. If the specified Person event is not currently being manipulated with applymovement, then this command does nothing.

  83. 52 waitmovementpos [details needed]

    Arguments:
    • byte-or-variable index
    • byte X
    • byte Y

    Apparent clone of waitmovement. Oddly, it doesn't seem to work at all if applied to any Person other than the player (0xFF), and the X and Y arguments don't seem to do anything.

  84. 53 hidesprite

    Arguments:
    • byte-or-variable local_ID

    Attempts to hide the specified (local_ID, a local ID) Person event on the current map, by setting its visibility flag if it has a valid one. If the Person does not have a valid visibility flag, this command does nothing.

    (For example, if Person event no. 7 has a "Person number" of 8 and a "Person ID" of $0015, then hidesprite 0x8 will hide that Person event by setting flag 0x015.)

    Supplying a local ID of 0xFF (the player) will result in the player taking control of a random Person event on the map, and map drawing will break (drawing chunks of terrain from the player's original position, along with chunks from their new position). This effect lasts until the player exits the map via a warp (I don't know what map connections would do).

  85. 54 hidespritepos [details needed]

    Arguments:
    • byte-or-variable index
    • byte X
    • byte Y

    Clone of hidesprite that also moves the Person? Test it!

  86. 5A faceplayer

    If the script was called by a Person event, then that Person will turn to face toward the tile that the player is stepping off of.

  87. ASM (FR): 0x0806C2C5

    5C trainerbattle [details needed]

    Arguments:
    • byte type
    • word index
    • word local_id
    • pointer intro
    • pointer loss
    • pointer extra
    • pointer extra2

    If the Trainer flag for Trainer index is not set, this command does absolutely nothing.

    Otherwise, this command will prepare and then indirectly initiate a trainer battle, blocking script execution until the battle ends. The effects of the battle (and even the number of arguments that the command accepts) differ depending on the first argument (the battle type).

    For most types, if the player defeats the Trainer, then they say the text at loss on the battle screen, their Trainer flag is cleared automatically, and script execution is terminated immediately; if the player loses, they whiteout and script execution terminates.

    I'm not too sure what the local_id is used for; most battle types "prefer" it set to 0x0000, while setting it to 0x0003 with battle type 9 enables Oak's narration. (Actually, any local ID that, when bitwise-and 3, doesn't equal zero will trigger the narration in a type-9 battle.)

    trainerbattle 0x2 is not identical to trainerbattle 0x1; the former (0x2) plays encounter music, while the latter (0x1) does not.

    Arguments and effects depending on type
    Type (hover for info) intro loss extra extra2
    0 Normal Pre-battle text Player win text UNUSED UNUSED
    1 Run Script After Win Pre-battle text Player win text Post-battle script offset
    (run on player win only)
    UNUSED
    2 Run Script After Win
    3 Continue Caller Pre-battle text UNUSED UNUSED UNUSED
    4 Double Pre-battle text Player win text Not enough PKMN text UNUSED
    5 Rematch Clone of 00 with rematch functionality.
    6 Double-Special Pre-battle text Player win text Not enough PKMN text Unknown, but it is used.
    7 Double-Rematch Clone of 04 with rematch functionality.
    8 Double-Special Clone of 06.
    9 Tutorial (Can't Lose) Pre-battle text Player win text UNUSED UNUSED
    All Other Values Treated as Type 0.

    Additional details: rematch battles

    The "Rematch" types check the specified trainer flag. If that trainer has already been battled, the game will use a table (at 0x0845318C) to find trainer flags associated with rematches against the trainer. The game will search for the earliest cleared rematch flag; it will then check if that rematch is usable based on...

    • If Flag 0x292 (flag function not known) is set, rematch 1 is enabled for all trainers.
    • If Flag 0x896 (Celadon City world map flag) is set, rematch 2 is enabled for all trainers.
    • If Flag 0x897 (Fuchsia City world map flag) is set, rematch 3 is enabled for all trainers.
    • If Flag 0x82C (Elite Four defeated) is set, rematch 4 is enabled for all trainers.
    • If Flag 0x844 (R/S/E trading enabled) is set, rematch 5 is enabled for all trainers.

    If the found rematch flag is usable, then the command uses that flag instead of the specified one, and starts a battle. If the found rematch flag is unusable, or if all rematch flags are set, then no battle begins. Essentially, the game will automatically handle rematches for you based on the player's progress through the game world and on how many times the trainer has been defeated.

    If you wish to change which flags enable rematches, you need only edit the dwords at 0x0810CCD8, 0x0810CCE0, 0x0810CCE8, 0x0810CCF0, and 0x0810CD10. If you wish to modify the rematch table, a section in the Appendix describes its structure and function.

    (Can the trainer index be a variable? (Check that empirically using an actual script, not ASM examination.) Verify that the unknown word can be used to enable Oak's tutorial narration.)

  88. ASM (FR): 0x0806C2D9

    5D repeattrainerbattle

    Starts a trainer battle using the battle information stored in RAM (usually by trainerbattle, which actually calls this command behind-the-scenes), and blocks script execution until the battle finishes.

    If no battle information has been prepared, the player will fight a nameless "PKMN TRAINER" (Aqua Leader Archie's sprite) equipped with a team of ?????????? (null Pokémon). The battle type used appears to be 0x00, with empty strings used by the trainer.

  89. ASM (FR): 0x0806C30D

    60 checktrainerflag

    Arguments:
    • word-or-variable trainer

    Compares Flag (trainer + 0x500) to 1. (If the flag is set, then the trainer has been defeated by the player.)

  90. ASM (FR): 0x0806C331

    61 cleartrainerflag

    Arguments:
    • word-or-variable trainer

    Sets Flag (trainer + 0x500). (I didn't make a mistake. The command names actually are backwards.)

  91. ASM (FR): 0x0806C34D

    62 settrainerflag

    Arguments:
    • word-or-variable trainer

    Clears Flag (trainer + 0x500). (I didn't make a mistake. The command names actually are backwards.)

  92. 66 waitmsg

    If a standard message box (or its text) is being drawn on-screen, this command blocks script execution until the box and its text have been fully drawn.

  93. 67 preparemsg

    Arguments:
    • pointer-or-bank-0 text

    Starts displaying a standard message box containing the specified text. If text is a pointer, then the string at that offset will be loaded and used. If text is script bank 0, then the value of script bank 0 will be treated as a pointer to the text. (You can use loadpointer to place a string pointer in a script bank.)

    This function is not blocking; script execution will continue while the message box is still being displayed. Use waitmsg to block.

  94. 68 closeonkeypress

    Holds the current message box open until the player presses a key. The message box is then closed.

  95. 69 lockall [details needed]

    Ceases movement for all OWs on-screen.

    (Does this also affect OWs not on-screen? Viewing OAM data at run-time or possibly using a move-camera script could allow us to check.)

  96. 6A lock

    If the script was called by a Person event, then that Person's movement will cease.

  97. 6B releaseall

    Resumes normal movement for all OWs on-screen, and closes any standard message boxes that are still open.

  98. 6C release

    If the script was called by a Person event, then that Person's movement will resume. This command also closes any standard message boxes that are still open.

  99. 6D waitkeypress

    Blocks script execution until the player presses any key.

  100. 6E yesnobox

    Arguments:
    • byte X
    • byte Y

    Displays a YES/NO multichoice box at the specified coordinates, and blocks script execution until the user makes a selection. Their selection is stored in variable 0x800D (LASTRESULT); 0x0000 for "NO" or if the user pressed B, and 0x0001 for "YES".

  101. 6F multichoice

    Arguments:
    • byte X
    • byte Y
    • byte list
    • byte B

    Displays a multichoice box from which the user can choose a selection, and blocks script execution until a selection is made. Lists of options are predefined and the one to be used is specified with list. If B is set to a non-zero value, then the user will not be allowed to back out of the multichoice with the B button.

    The user's selection is stored as a zero-indexed integer in variable 0x800D (LASTRESULT). If they backed out with B, LASTRESULT will be 0x7F.

  102. 70 multichoice2

    Arguments:
    • byte X
    • byte Y
    • byte list
    • byte default
    • byte B

    Displays a multichoice box from which the user can choose a selection, and blocks script execution until a selection is made. Lists of options are predefined and the one to be used is specified with list. The default argument determines the initial position of the cursor when the box is first opened; it is zero-indexed, and if it is too large, it is treated as 0x00. If B is set to a non-zero value, then the user will not be allowed to back out of the multichoice with the B button.

    The user's selection is stored as a zero-indexed integer in variable 0x800D (LASTRESULT). If they backed out with B, LASTRESULT will be 0x7F.

  103. 71 multichoice3

    Arguments:
    • byte X
    • byte Y
    • byte list
    • byte per_row
    • byte B

    Displays a multichoice box from which the user can choose a selection, and blocks script execution until a selection is made. Lists of options are predefined and the one to be used is specified with list. The per_row argument determines how many list items will be shown on a single row of the box.

    The total number of options must be divisible by the number of options per row. "Orphaned" options will not be displayed or selectable. If the number of options per row is greater than the total number of options, then no choices will be visible or selectable.

    The user's selection is stored as a zero-indexed integer in variable 0x800D (LASTRESULT). If they backed out with B, LASTRESULT will be 0x7F.

  104. 75 showpokepic

    Arguments:
    • word-or-variable species
    • byte X
    • byte Y

    Displays a box containing the front sprite for the specified (species) Pokémon species.

  105. 76 hidepokepic

    Hides all boxes displayed with showpokepic.

    If this command is called too quickly after showpokepic, then it will fail to hide the Pokémon picture box and it will hang the script engine. My guess is that problems specifically happen if this command runs while the game is still trying to draw the showpokepic box.

  106. ASM (FR): 0x0806BBF9

    77 showcontestwinner

    Arguments:
    • byte a

    In FireRed, this command is a nop. (The argument is discarded.)


    In R/S/E, it displayed the paintaing of the winner of the specified (a) Pokémon Contest.

  107. 78 braille

    Arguments:
    • pointer-or-bank-0 text

    Displays the string at pointer as braille text in a standard message box. The string must be formatted to use braille characters.

    Note that the \l and \p string control codes are not supported, and braille text is too large to use \n. To show multi-line or multi-part braille messages, you must use a clever scripting technique involving the braille2 command. You can see the script technique if you decompile Signpost scripts used in the Ruby and Sapphire chambers in Mt. Ember.

  108. 79 givePokémon [details needed]

    Arguments:
    • word-or-variable species
    • byte level
    • word item
    • dword unknown1
    • dword unknown2
    • byte unknown3

    Gives the player one of the specified (species) Pokémon at level level holding item. The unknown arguments should all be zeroes.

    This function will also modify certain script variables to indicate the result of the command. Variable 0x800D (LASTRESULT) will be set to 0x0000 if the Pokémon was stored in the party; 0x0001 if the Pokémon was transferred to the PC; and 0x0002 if there was no room in the party or the PC. Variable 0x4037 appears to be set to the number of the PC Box that the Pokémon was sent to (if it was boxed). Flag 0x843 may be cleared (and then set) if the Pokémon was boxed.

    (Confirm that this command specifically modifies var 0x4037.)

  109. 7C checkattack [details needed]

    Arguments:
    • word index

    Checks if at least one Pokémon in the player's party knows the specified (index) attack. If so, variable 0x800D (LASTRESULT) is set to the (zero-indexed) slot number of the Pokémon that knows the move. If not, LASTRESULT is set to 0x0006.

    (Does this accept a variable? If multiple Pokémon in the party know the attack, what is written to LASTRESULT?)

  110. 7D bufferPokémon

    Arguments:
    • buffer out
    • word-or-variable species

    Writes the name of the Pokémon at index species to the specified buffer.

    ...Specifically, the game tries to read a string starting at 0x08245EE0 + (0xB * species), the offset in that formula being a table of Pokémon names padded to ten bytes and separated by 0xFFs. The game does not validate the species number; if it is larger than the number of Pokémon in the game, the game ends up trying to read from the data after the table, resulting in garbled strings or even a crash.

  111. 7E bufferfirstPokémon [details needed]

    Arguments:
    • buffer out

    Writes the name of the first Pokémon in the player's party to the specified buffer.

    (Does this buffer nicknames, if present? What happens if the player has no Pokémon?)

  112. 7F bufferpartyPokémon [details needed]

    Arguments:
    • buffer out
    • word-or-variable slot

    Writes the name of the Pokémon in slot slot (zero-indexed) of the player's party to the specified buffer. If an empty or invalid slot is specified, ten spaces ("          ") are written to the buffer.

    (Does this buffer nicknames, if present?)

  113. 80 bufferitem

    Arguments:
    • buffer out
    • word-or-variable item

    Writes the name of the item at index item to the specified buffer. If the specified index is larger than the number of items in the game (0x176), the name of item 0 ("????????") is buffered instead.

    A tip: if the item is a Poke Ball (0x0004) or any Berry except the Enigma Berry (0x0085 - 0x00AE), you can pluralize the name with bufferitems.

  114. ASM (FR): 0x0806BE35

    81 bufferdecoration

    Arguments:
    • byte a
    • word-or-variable b

    In FireRed, this command is a nop. (The first argument is discarded immediately. The second argument is read, but not used for anything.)


    In R/S/E, this command wrote the name of the decoration at index b to the specified (a) buffer.

  115. 82 bufferattack

    Arguments:
    • buffer out
    • word-or-variable attack

    Writes the name of the attack at index attack to the specified buffer.

    ...Specifically, the game tries to read a string starting at 0x08247094 + (0xD * attack), the offset in that formula being a table of attack names padded unevenly but such that each first letter is 0xD bytes apart. The game does not validate the attack number; if it is larger than the number of attacks in the game (0x162), the game ends up trying to read from the data after the table, resulting in garbled strings or even a reset.

  116. 83 buffernumber

    Arguments:
    • buffer out
    • word-or-variable input

    Converts the value of input to a decimal string, and writes that string to the specified buffer.

  117. 84 bufferstd

    Arguments:
    • buffer out
    • word-or-variable index

    Writes the standard string identified by index to the specified buffer. Specifying an invalid standard string (e.x. 0x2B) can and usually will cause data corruption (I've observed destruction of the stored player name and crashes when entering/exiting certain menu screens).

    These are the standard strings in Pokémon FireRed (BPRE):

    1. 0x00 COOL
    2. 0x01 BEAUTY
    3. 0x02 CUTE
    4. 0x03 SMART
    5. 0x04 TOUGH
    6. 0x05 COOL
    7. 0x06 BEAUTY
    8. 0x07 CUTE
    9. 0x08 SMART
    10. 0x09 TOUGH
    11. 0x0A ITEMS
    12. 0x0B KEY ITEMS
    13. 0x0C POKe BALLS
    14. 0x0D TMs & HMs
    15. 0x0E BERRIES
    16. 0x0F BOULDERBADGE
    17. 0x10 CASCADEBADGE
    18. 0x11 THUNDERBADGE
    19. 0x12 RAINBOWBADGE
    20. 0x13 SOULBADGE
    21. 0x14 MARSHBADGE
    22. 0x15 VOLCANOBADGE
    23. 0x16 EARTHBADGE
    24. 0x17 COINS
    25. 0x18 ITEMS POCKET
    26. 0x19 KEY ITEMS POCKET
    27. 0x1A POKe BALLS POCKET
    28. 0x1B TM CASE
    29. 0x1C BERRY POUCH
    30. 0x1D Trade Pokémon with another playe (longer than the buffer supports)
      The buffer does indeed support this string: "Trade POKéMON with another player using a GBA GAME LINK cable."
    31. 0x1E You may battle another TRAINER
    32. 0x1F Cancels the selected MENU item.
    33. 0x20 You may trade your Pokémon here
    34. 0x21 You may battle with your friends (longer than the buffer supports)
      The buffer does indeed support this string: "You may battle with your friends here."
    35. 0x22 Two to five TRAINERS can make
    36. 0x23 Cancels the selected MENU item.
    37. 0x24 You may trade your Pokémon here
    38. 0x25 You may battle with your friends (longer than the buffer supports)
      The buffer does indeed support this string: "You may battle with your friends here."
    39. 0x26 Cancels the selected MENU item.
  118. 85 bufferstring

    Arguments:
    • buffer out
    • pointer offset

    Copies the string at offset to the specified buffer.

  119. 86 pokemart

    Arguments:
    • pointer products

    Opens the Pokemart system, offering the specified products for sale.

    The products argument should point to a list of words. Each word is the identifier of an item to be sold. 0x0000 terminates the list.

  120. 87 pokemart2

    Arguments:
    • pointer products

    Apparent clone of pokemart.

  121. 88 pokemart3

    Arguments:
    • pointer products

    Apparent clone of pokemart.

  122. ASM (FR): 0x0806C411

    8A cmd8a

    In FireRed, this command is a nop.

    Warning: XSE has it wrong. The function has no arguments. This means that you may need to use #raw to compile a script that uses this command, and that such scripts will not decompile properly.

  123. ASM (FR): 0x0806C419

    8B choosecontestpkmn [details needed]

    In FireRed, this command sets the byte at 0x03000EA8 to 0x01. I do not know what that means.


    In R/S/E, it prompted the player to choose a Pokémon to enter into a Pokémon Contest.

  124. ASM (FR): 0x0806C425

    8C startcontest

    In FireRed, this command is a nop.


    In R/S/E, it started a Pokémon Contest.

  125. ASM (FR): 0x0806C429

    8D showcontestresults

    In FireRed, this command is a nop.


    In R/S/E, it showed the results of a Pokémon Contest.

  126. ASM (FR): 0x0806C42D

    8E contestlinktransfer

    In FireRed, this command is a nop.


    In Emerald, it apparently started a Pokémon Contest over a wireless connection.

  127. 8F random

    Arguments:
    • word-or-variable limit

    Stores a random integer between 0 and limit in variable 0x800D (LASTRESULT).

    The number will always be less than limit.

  128. 90 givemoney [details needed]

    Arguments:
    • dword value
    • byte check

    If check is 0x00, this command adds value to the player's money.

    (Can this overflow?)

  129. 91 paymoney [details needed]

    Arguments:
    • dword value
    • byte check

    If check is 0x00, this command subtracts value from the player's money.

    (Can this overflow?)

  130. 92 checkmoney

    Arguments:
    • dword value
    • byte check

    If check is 0x00, this command will check if the player has value or more money; script variable 0x800D (LASTRESULT) is set to 0x0001 if the player has enough money, or 0x0000 if the do not.

  131. 93 showmoney [details needed]

    Arguments:
    • byte X
    • byte Y

    Spawns a secondary box showing how much money the player has.

    The box does not update automatically. If you change how much money the player has after using showmoney, you must use updatemoney to display the new amount. The box can be hidden using hidemoney.

    (Need to test this to find its quirks...)

  132. 94 hidemoney

    Arguments:
    • byte X
    • byte Y

    Hides the secondary box spawned by showmoney.

    (Does this discard its arguments like hidecoins does?)

  133. 95 updatemoney [details needed]

    Arguments:
    • byte X
    • byte Y

    Updates the secondary box spawned by showmoney. (What does it do with its arguments?)

    You'd want to use this if you change how much money the player has after using showmoney.

  134. ASM (FR): 0x0806C415

    96 cmd96

    In FireRed, this command is a nop.

    Warning: XSE has it wrong. The function has no arguments. This means that you may need to use #raw to compile a script that uses this command, and that such scripts will not decompile properly.

  135. 97 fadescreen [details needed]

    Arguments:
    • byte effect

    Fades the screen to black or back, using the specified effect. Effect 0x00 fades in, and effect 0x01 fades out. I don't know if other effects exist.

    If effect 0x00 is used when the screen isn't actually faded to black, then the screen will be immediately blackened and then faded back in, producing a "blinking" effect.

    (Does this block?)

  136. 9C doanimation [details needed]

    Arguments:
    • word animation

    Executes the specified field move animation.

    The animations are defined in a table stored in the ROM, and they use their own scripting engine. More information can be found in a post on PokeCommunity.

    These are the animations that have been found in Pokémon FireRed (BPRE):

    1. 0x01 CUT (grass)? (black Pokémon bar + leaf spiral) I can confirm.
    2. 0x02 CUT
    3. 0x03 Part of the FLY animation sequence.
    4. 0x06 Part of the FLY animation sequence.
    5. 0x08 Buggy SURF-Pokémon sprite appears on map
    6. 0x09 SURF
    7. 0x19 PokeCenter healing machine
    8. 0x1E Part of the FLY animation sequence. (takeoff)
    9. 0x1F Part of the FLY animation sequence. Calls animation 0x3B.
    10. 0x20 Part of the FLY animation sequence.
    11. 0x22 Landing (after FLY)
    12. 0x23 FLY (crashes, probably because destination isn't set)
    13. 0x25 ROCK SMASH
    14. 0x26 TELEPORT? (black Pokémon bar)
    15. 0x28 STRENGTH
    16. 0x2B WATERFALL
    17. 0x2C DIVE (crashes, probably because destination/directionality isn't set)
    18. 0x2D Shows a buggy message box in the top-left corner
    19. 0x33 SWEET SCENT? I can confirm.
    20. 0x3B Part of the FLY animation sequence.
    21. 0x3E Hall of Fame registration machine
    22. 0x3F Teleports to player's home? Teleports to the flying spot for the sethealingplace map.
    23. 0x41 VS SEEKER (crashes)
    24. 0x45 White flash

    (Does it accept a variable? Test and confirm 01, 1E, 26, 3F, 41.)

  137. 9D setanimation [details needed]

    Arguments:
    • byte animation
    • word-or-variable slot

    Tells the game which party Pokémon to use for the next field move animation.

    (What does the byte do?)

  138. 9E checkanimation [details needed]

    Arguments:
    • word animation

    Blocks script execution until all playing field move animations complete.

    (What does the word do?)

  139. 9F sethealingplace [details needed]

    Arguments:
    • word flightspot

    Sets which healing place the player will return to if all of the Pokémon in their party faint. A list of available healing places can be found on PokeCommunity.

    (Does it accept a variable? And what happens if we supply a value of 0x00?)

  140. A0 checkgender

    Checks the player's gender. If male, then 0x0000 is stored in variable 0x800D (LASTRESULT). If female, then 0x0001 is stored in LASTRESULT.

  141. A1 cry [details needed]

    Arguments:
    • word-or-variable species
    • word effect

    Plays the specified (species) Pokémon's cry. You can use waitcry to block script execution until the sound finishes.

    (What is the effect? Can it be a variable?)

  142. A2 setmaptile [details needed]

    Arguments:
    • word X
    • word Y
    • word tile_number
    • word tile_attrib

    Changes the tile at (X, Y) on the current map.

    (Can some or all arguments be variables? What is tile_attrib? It's usually 0x0 or 0x1, but I don't think it's a movement permission.)

  143. A3 resetweather [details needed]

    Queues a weather change to the default weather for the map.

    (Only one weather change can be queued at once?)

  144. A4 setweather [details needed]

    Arguments:
    • word type

    Queues a weather change to type weather.

    (Only one weather change can be queued at once?)

    (Does this accept variables?)

  145. A5 doweather [details needed]

    Executes the weather change queued with resetweather or setweather. The current weather will smoothly fade into the queued weather.

    (Does this block?)

  146. ASM (FR): 0x0806AA31

    A6 cmda6

    Arguments:
    • byte subroutine

    This command manages cases in which maps have tiles that change state when stepped on (specifically, cracked/breakable floors).

    Think of cmda6 as a script-friendly way to access Game Freak's official walking script implementation (but with ASM instead of scripts). This command allows you to select which one of eight predefined ASM subroutines should be enabled.

    Subroutine effects in FireRed
    Number Used In Function
    0 Unused/Nop. Returns immediately without doing anything.
    1 Route 113 R/S/E leftover. Crippled in FireRed -- it does nothing.

    When the player steps on Tile 20A (ash-covered tall grass), it changes into Tile 212 (normal grass).
    2 Unused/Nop. Returns immediately without doing anything.
    3
    4 Icefall Cave

    When the player steps on a tile with behavior byte 0x26 (uncracked ice), it changes into Tile 35A (cracked ice). When they step on a tile with behavior byte 0x27 (cracked ice), it changes into Tile 35B (hole) after a four-frame delay and script variable 0x4001 is set to 0x0001.

    This subroutine also compares the player's coordinates to a set of nine X/Y coordinate pairs stored at 0x083A7330, and sets one of the temporary script flags (0x001 - 0x009) if there's a match. Each coordinate pair corresponds exactly to a breakable ice tile in Icefall Cave; in combination with a level script, I think this saves tile states when the game is saved.

    5 Unused/Nop. Returns immediately without doing anything.
    6
    7 Granite Cave
    Sky Pillar
    R/S/E leftover. Crippled in FireRed -- it does nothing.

    When the player steps on Tile 22F (cracked floor), it changes into Tile 206 (hole). At some point, script variable 0x4030 is set to 0x0000.
    Others Treated as Subroutine 0

    Additional details: How does this command work?

    At 0x03005090, there is an execution queue -- a list of ASM functions to be executed on every frame. (Each list item also has a small amount of space to use to maintain its state.) Cmda6 checks the queue to see if a specific ASM routine, the walking routine manager at 0x0806E811, is there. If so, cmda6 clears the state data for that queue item, and then inserts the argument you specify into the state data.

    When the walking routine manager runs (once every frame), it reads the injected state data and uses that to determine which walking subroutine it should call. (Eight are allowed, three of which are defined and one of which actually works.) It then calls the selected walking subroutine, which will generally perform some action if the player has taken a step (usually, changing the tile under their feet).

    Bundled in this resource's ZIP should be a file, CmdA6, disassembled and rewritten.txt. (If I've forgotten to include it, remind me.) That file contains the assembly code for CmdA6, the tile manager routine, and the three subroutines (rewritten in a pseudosyntax which you may or may not find more readable). Studying that should provide you with most of the information you would need to, say, add a subroutine of your own to create a cmda6-managed walking function that is accurate to the frame.

  147. AC setdooropened [details needed]

    Arguments:
    • word X
    • word Y

    Queues the opening of the door tile at (X, Y) with an animation.

    (Does this accept variables? What happens if it's used on a tile that isn't a door?)

  148. AD setdoorclosed [details needed]

    Arguments:
    • word X
    • word Y

    Queues the closing of the door tile at (X, Y) with an animation.

    (Does this accept variables? What happens if it's used on a tile that isn't a door?)

  149. AE doorchange [details needed]

    Executes the state changes queued with setdooropened, setdoorclosed, setdooropened2, and setdoorclosed2.

    (Does this block for animated door changes? For both?)

  150. AF setdooropened2 [details needed]

    Arguments:
    • word X
    • word Y

    Queues the opening of the door tile at (X, Y) without an animation.

    (Does this accept variables? What happens if it's used on a tile that isn't a door?)

  151. B0 setdoorclosed2 [details needed]

    Arguments:
    • word X
    • word Y

    Queues the closing of the door tile at (X, Y) without an animation.

    (Does this accept variables? What happens if it's used on a tile that isn't a door?)

  152. ASM (FR): 0x0806C725

    B1 cmdb1

    In FireRed, this command is a nop.

    Warning: XSE has it wrong. The function has no arguments. This means that you may need to use #raw to compile a script that uses this command, and that such scripts will not decompile properly.

  153. ASM (FR): 0x0806C729

    B2 cmdb2

    In FireRed, this command is a nop.

  154. ASM (FR): 0x0806C369

    B6 setwildbattle [details needed]

    Arguments:
    • word species
    • byte level
    • word item

    Prepares to start a wild battle against a species at Level level holding item. Running this command will not affect normal wild battles. You start the prepared battle with dowildbattle.

    To be specific, this command will automatically generate a 100-byte Pokémon matching the provided arguments, and store it at 0x0202402C (the RAM location of the first enemy in a battle). The RAM for enemies 2-6 is also cleared. This allows a script to generate a wild Pokémon before initiating a battle.

    The uses for generating a Pokémon in this manner are many and varied. Hypothetically speaking, one could call this command, use writebytetooffset to pre-damage the generated Pokémon, and then run dowildbattle.

    (Can the item be a variable?) Tests would suggest that, no, items cannot be set through variables.

  155. B7 dowildbattle

    Starts a wild battle against the Pokémon generated by setwildbattle. Blocks script execution until the battle finishes.

    If the Pokémon created by setwildbattle was invalid, then this command will hang and a battle will not start.

    (Nonexistent species such as 0x4000 are known to cause invalid Pokémon... But would other Pokémon (i.e. broken checksums, or stats in the last 20 bytes being modified) cause problems as well?)

  156. C0 showcoins

    Arguments:
    • byte X
    • byte Y

    Spawns a secondary box showing how many Coins the player has.

    The box does not update automatically. If you change how many Coins the player has after using showcoins, you must use updatecoins to display the new amount. The box can be hidden using hidecoins.

  157. C1 hidecoins

    Arguments:
    • byte X
    • byte Y

    Hides the secondary box spawned by showcoins. It doesn't appear to use its arguments, but they are still required.

  158. C2 updatecoins [details needed]

    Arguments:
    • byte X
    • byte Y

    Updates the secondary box spawned by showcoins. (What does it do with its arguments?)

    You'd want to use this if you change how many Coins the player has after using showcoins.

  159. ASM (FR): 0x0806A871

    C3 cmdc3

    Arguments:
    • hidden-variable a

    Increases the value of the specified hidden variable by 1. The hidden variable's value will not be allowed to exceed 0x00FFFFFF.

    The PokeCenter nurses use this to increment hidden variable 15 (0xF) just after you pick "YES" to heal your party. I don't know why.

  160. C4 warp6

    Clone of warp... Except that it doesn't appear to have any effect when used in some of FireRed's default level scripts. (If it did, Berry Forest would be impossible to enter...)

  161. C5 waitcry

    Blocks script execution until cry finishes.

  162. C6 bufferboxname

    Arguments:
    • buffer out
    • word-or-variable box

    Writes the name of the specified (box) PC box to the specified buffer.

  163. C7 textcolor [details needed]

    Arguments:
    • byte color

    Sets the color of the text in standard message boxes. 0x00 produces blue (male) text, 0x01 produces red (female) text, 0xFF resets the color to the default for the current OW's gender, and all other values produce black text.

    This command does not affect braille text. Colors specified with this command will be overriden by colors specified by control codes in the string.

    (The command writes a byte to 0x020370DA, and that byte is reset to 0xFF every frame.)

  164. ASM (FR): 0x0806B829

    C8 cmdc8 [details needed]

    Arguments:
    • pointer-or-bank-0 string

    The exact purpose of this command is unknown, but it is related to the blue help-text box that appears on the bottom of the screen when the Main Menu is opened.

    This command will load the appropriate palette and tiles for a help-text box containing the specified string. It also writes data for a new dialog box into RAM. However, the dialog box is not displayed.

    Note that when this command loads the palette and tiles, it overwrites the frame tiles in use by any standard message boxes that may already be on-screen. Their frames change into (improperly-displayed) help-text frames, though the text remains completely unchanged.

    Warning: XSE has it wrong. The function has one four-byte argument. This means that you will need to use #raw to compile a script that uses this command, and that such scripts will not decompile properly.

  165. ASM (FR): 0x0806B851

    C9 cmdc9 [details needed]

    The exact purpose of this command is unknown, but it is related to the blue help-text box that appears on the bottom of the screen when the Main Menu is opened.

    This command appears to unload most of the text and frame tiles that cmdc8 loads into memory, though it will not restore overwritten frame tiles used by other dialog boxes.

  166. CA signmsg

    After using this command, all standard message boxes will use the signpost frame.

  167. CB normalmsg

    Ends the effects of signmsg, returning message box frames to normal.

  168. ASM (FR): 0x0806A889

    CC comparehiddenvar [details needed]

    Arguments:
    • hidden-variable a
    • dword value

    Compares the value of a hidden variable to a dword.

    Warning: XSE has it wrong. The second argument is a dword, not a word. This means that you will need to use #raw to compile a script that uses this command, and that such scripts will not decompile properly.

  169. CD setobedience [details needed]

    Arguments:
    • word slot

    Makes the Pokémon in the specified slot of the player's party obedient. It will not randomly disobey orders in battle.

    (Can the slot be a variable?)

  170. CE checkobedience

    Arguments:
    • word-or-variable slot

    Checks if the Pokémon in the specified slot of the player's party is obedient. If the Pokémon is disobedient, 0x0001 is written to script variable 0x800D (LASTRESULT). If the Pokémon is obedient (or if the specified slot is empty or invalid), 0x0000 is written.

  171. ASM (FR): 0x0806A28D

    CF executeram [details needed]

    Depending on factors I haven't managed to understand yet, this command may cause script execution to jump to the offset specified by the pointer at 0x020370A4.

    This command uses what appear to be checksums at [0x03005008] + 0x32E0 and [0x03005008] + 0x361C to validate data pointed to by pointers at [0x03005008] + 0x32E4 (target is 332 bytes) and [0x03005008] + 0x3620 (target is either 1000 or 1004 bytes), respectively. If this validation fails, the command does nothing. Unfortunately, I've looked at the ASM every way I can; unless someone figures out what's at those DMA-protected RAM offsets, this command's function will remain a mystery.

  172. ASM (FR): 0x0806A8C1

    D0 setworldmapflag

    Arguments:
    • flag-or-variable worldmapflag

    Sets worldmapflag to 1. This allows the player to Fly to the corresponding map, if that map has a flightspot.

    Specifically, the command will set the specified flag if all of the following requirements are met, and will apparently do nothing if one or more of the requirements are not met:

    1. The byte at 0x0203ADFA is greater than 0x03.
    2. The specified flag is on a list (at 0x08456C50, with 0x10 two-byte entries) of world map flags that can actually be flown to.
  173. D1 warpteleport2

    Clone of warpteleport? It is apparently only used in FR/LG, and only with specials.[source]

  174. D2 setcatchlocation

    Arguments:
    • word-or-variable slot
    • byte location

    Changes the location where the player caught the Pokémon in the specified slot of their party. A list of valid catch locations can be found on PokeCommunity.

  175. ASM (FR): 0x0806BC41

    D3 braille2

    Arguments:
    • pointer-or-bank-0 text

    Sets variable 0x8004 to a value based on the width of the braille string at text.

    Because braille strings do not support the \p or \l control codes, Game Freak had to create a "fake" message cursor every time they wanted to show multi-part or multi-line braille strings. To facilitate this, they created special 0x1B2, which draws a cursor on the screen at a position specified by variables 0x8004 (X) and 0x8005 (Y).

    This command, braille2, will calculate the length of a specified braille string, and then set 0x8004 to a value based on that length. If you then show that string in a message box and call special 0x1B2, a cursor will appear exactly at the end of the braille string.

  176. ASM (FR): 0x0806BD91

    D4 bufferitems [details needed]

    Arguments:
    • buffer out
    • word-or-variable item
    • word-or-variable quantity

    Writes the name of the specified (item) item to the specified buffer. If the specified item is a Berry (0x85 - 0xAE) or Poke Ball (0x4) and if the quantity is 2 or more, the buffered string will be pluralized ("IES" or "S" appended). If the specified item is the Enigma Berry, I have no idea what this command does (but testing showed no pluralization). If the specified index is larger than the number of items in the game (0x176), the name of item 0 ("????????") is buffered instead.

    (The Enigma Berry is treated as a special case and handled with ASM that, among many other things, appears to conditionally read from a table at 0x083DF7CC. What the hell is this command doing for Enigma Berries?)

  177. ASM (FR): 0x08069ED1

    D5 cmdd5

    In FireRed, this command is a nop.

    Warning: XSE has it wrong. The function has no arguments. This means that you may need to use #raw to compile a script that uses this command, and that such scripts will not decompile properly.


Appendix

Comparison operators

The condition byte supplied to the if1 and if2 commands determines what is done with the result of the previous comparison.

Dialog boxes

The dialog box types that I have identified in FireRed are as follows:

Standard message box
This message box can be accessed and displayed directly with script code. Its frame can be changed to resemble a signpost using certain scripting commands. Only one may display at a time.
Secondary box
This box is the product of showcoins, showmoney, and similar commands. It displays two strings: a left-aligned header, and a right-aligned body string with a smaller font size. Its size and contents cannot be manipulated without writing ASM code.
Multichoice box
This box has a thick black frame, and is used to display lists of options. A cursor appears within the box and can be controlled with the D-Pad; A can be used to select an option, and in some cases B can be used to cancel without selecting an option.

Finding the offset of a command's ASM (FireRed)

To find the offset of a given script command's ASM, the game looks it up from a table. In BPRE, this table is located at 0x0815F9B4, and to find the pointer for a given command, you left-shift that command by 2 and then add the result to the table's offset. There, you'll find a pointer to the command's ASM.

For example, the command byte for showcoins is 0xC0. Left-shifting that by two gives us 0x300; adding that to the table offset gives us 0x0815FCB4, and the pointer at that offset is 0x0806C259 -- a pointer to showcoins' ASM with the THUMB bit set.

Hidden variables

FireRed maintains 64 "hidden variables" in one of its DMA-protected RAM sections (specifically, they overlap the RAM used for script variables 0x4100 - 0x417F, at [0x03005008] + 0x1200). Each of these variables is a dword whose value has been encrypted with a dword key stored at [0x0300500C] + 0xF20. Of these sixty-four variables, scripts have access to all but the last six (vars 0x00 to 0x33).

The purpose of these hidden variables is not yet clear. Hidden variable 5 appears to be a pedometer, and PokeCenters use hidden variable 15 (0xF) for something.

Person event terminology

For the sake of consistency and to save on explanations in the command descriptions, I shall use the following terminology when discussing commands that deal with Person events on maps:

local ID

This is what AdvanceMap calls the "Person event no". It is a single-byte identifier that serves to differentiate one Person event from another within the current map. Most of the commands that deal with Person events require you to specify a Person using its local ID.

Local IDs must be unique within the map. That is, two Person events on the same map cannot have the same local IDs, but two Person events on different maps can. The player uses local ID 0x00 internally but is identified by local ID 0xFF in scripts; the camera is identified by local ID 0x7F in scripts. Person IDs are zero-indexed, but (as I just said) 0 is reserved for the player's OW.

visibility flag

This is what AdvanceMap calls the "Person ID". It is a scriptable flag that, if set, hides the Person event from the map. Commands like hidesprite modify the states of these flags.

Visibility flags do not have to be unique; multiple Person events can share the same visibility flag, even if on the same map. (They will all be affected by the flag's state.) However, the flag 0x0000 cannot be used; a Person event that has been set to use it ("Person ID" is "$0000" in AdvanceMap) effetively has no visibility flag.

Script banks

A script bank is a four-byte storage area. Four such banks are available. They are usually used to load pointers that certain commands (or ASM code) can make use of.

Standard functions

The Advance games contain "standard functions". These are reusable scripts that have been given a single-byte identifier. They can be invoked using gotostd, callstd, gotostdif, and callstdif.

Most standard functions display different types of message boxes, or handle the process of obtaining a visible item from the overworld. A thread on PokeCommunity describes the standard functions in detail, lists each of Emerald's standard functions, and describes how to add your own standard function to any of the Pokémon Advance-generation games.

Trainer battles: the rematch flag table

FireRed has a data table at 0x0845318C, which associates a "base" trainer flag with up to five other trainer flags. These other flags are used for rematches; their trainers are rematch versions of the trainer associated with the "base" flag.

The table is limited to 0xDC (zero-indexed) rows. A single row in the table is structured in the following manner:

0xFFFF in a row means that there is no rematch for that slot. 0x0000 in a row means that no rematches are defined for that slot or any of the ones after it (and the slots after it should be 0x0000 as well).

Additional details: How is the table read?

When initiating a rematch battle via trainerbattle, the game will attempt to select the appropriate rematch flag, which will be used to start the battle.

First, the command locates the rematch table row for the input trainer flag (by searching for a row whose first flag is equal to the input trainer flag). The ASM will then loop through each rematch flag in the row, checking their states and retrieving the earliest cleared (non-defeated) rematch flag. If the ASM encounters an 0xFFFF entry, that entry will be skipped. If the ASM encounters 0x0000 at any point in the row, it will stop looping and select the last valid flag it looped over.

The game saves the number of the selected rematch flag (0 - 5), and uses that to check one of five different flags that enable rematches based on the player's progress through the game; we'll cause these five flags "state flags". If the state flag that would enable this rematch flag is cleared, then the game will select the previous rematch flag. (If the previous rematch flag is 0xFFFF, then the game loops backwards through the row until it finds a valid flag; that flag is then selected.)

Finally, the game will take the selected flag and check its state. If it is cleared, trainerbattle will call a script (different one for each battle type), and that script will start the battle by calling repeattrainerbattle (or an equivalent special). If the selected flag is set, on the other hand, then trainerbattle will return without doing anything and the calling script will continue.

Additional details: What would I need to modify to extend the table?

The limit to 0xDC rows is the result of a comparison at 0x0810D1BC. As far as I know you can change that to any single-byte value without problems, though you'll probably have to repoint the table so you can extend it. (Multi-byte values would require rearranging some RAM and some ASM.)

The trainerbattle command's pointer to the table is at 0x0810CEA4. There may be other pointers to the table elsewhere in the ROM, but so far as I can discern, that's the only pointer used by trainerbattle.

The limit to five rematch flags per row is the result of:


Sources

  1. Post by JPAN in Quick Research/Development Thread
  2. Post by JPAN in Quick Research/Development Thread
  3. Post by HackMew in [Scripting] Command Database Naming
back to top