00 nop
Does nothing.
01 nop1
Does nothing.
02 end
Terminates script execution.
03 return
Jumps back to after the last-executed call statement, and continues script execution from there.
04 call
- 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]
05 goto
- pointer destination
Jumps to destination and continues script execution from there.
06 if1
- 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.
07 if2
- 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.
08 gotostd
- byte function
Jumps to the standard function at index function.
09 callstd (a.k.a. boxset)
- byte function
Calls the standard function at index function.
0A gotostdif
- byte condition
- byte function
If the result of the last comparison matches condition (see Comparison operators), jumps to the standard function at index function.
0B callstdif
- byte condition
- byte function
If the result of the last comparison matches condition (see Comparison operators), calls the standard function at index function.
0C jumpram [details needed]
Executes a script stored in a default RAM location.
0D killscript [details needed]
Terminates script execution and "resets the script RAM".
0E setbyte [details needed]
- 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?)
0F loadpointer
- 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.)
10 setbyte2
- bank destination
- byte value
Sets the specified script bank to value.
11 writebytetooffset
- byte value
- pointer offset
Sets the byte at offset to value.
12 loadbytefrompointer
- bank destination
- pointer source
Copies the byte value at source into the specified script bank.
13 setfarbyte [details needed]
- 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.
14 copyscriptbanks
- bank destination
- bank source
Copies the contents of bank source into bank destination.
15 copybyte
- pointer destination
- pointer source
Copies the byte at source to destination, replacing whatever byte was previously there.
16 setvar
- variable destination
- word value
Changes the value of destination to value.
17 addvar
- variable destination
- word value
Changes the value of destination by adding value to it. Overflow is not prevented (0xFFFF + 1 = 0x0000).
18 subvar
- variable destination
- word-or-variable value
Changes the value of destination by subtracting value to it. Overflow is not prevented (0x0000 - 1 = 0xFFFF).
19 copyvar
- variable destination
- variable source
Copies the value of source into destination.
1A copyvarifnotzero
- 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.)
1B comparebanks
- 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.
1C comparebanktobyte
- bank a
- byte b
Compares the least-significant byte of the value of script bank a to a fixed byte value (b).
1D comparebanktofarbyte
- bank a
- pointer b
Compares the least-significant byte of the value of script bank a to the byte located at offset b.
1E comparefarbytetobank
- pointer a
- bank b
Compares the byte located at offset a to the least-significant byte of the value of script bank b.
1F comparefarbytetobyte
- pointer a
- byte b
Compares the byte located at offset a to a fixed byte value (b).
20 comparefarbytes
- pointer a
- pointer b
Compares the byte located at offset a to the byte located at offset b.
21 compare
- variable a
- word b
Compares the value of a to a fixed word value (b).
22 comparevars
- variable a
- variable b
Compares the value of a to the value of b.
23 callasm
- 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.
24 cmd24 [details needed]
- 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?)
25 special
- 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.
26 special2
- variable output
- word function
Calls a special function. That function's output (if any) will be written to the variable you specify.
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).
28 pause [details needed]
- 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.)
29 setflag
- flag-or-variable a
Sets a to 1.
2A clearflag
- flag-or-variable a
Sets a to 0.
2B checkflag
- flag-or-variable a
Compares a to 1.
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.
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.
2E resetvars
Resets the values of variables 0x8000, 0x8001, and 0x8002.
2F sound
- 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.
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.)
31 fanfare [details needed]
- word-or-variable fanfare_number
Plays the specified (fanfare_number) fanfare.
(Is it limited to one fanfare at a time, like sound?)
32 waitfanfare
Blocks script execution until all currently-playing fanfares finish.
33 playsong [details needed]
- 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?)
34 playsong2 [details needed]
- 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?)
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...)
36 fadesong [details needed]
- 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?)
37 fadeout [details needed]
- 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?)
38 fadein [details needed]
- 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?)
39 warp [details needed]
- 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?)
3A warpmuted
Clone of warp that does not play a sound effect.
3B warpwalk [details needed]
Clone of warp that uses "a walking effect".
(Any other differences?)
3C warphole [details needed]
- 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?
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?)
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.
3F setwarpplace [details needed]
- 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?)
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?)
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?)
42 getplayerpos
- variable X
- variable Y
Retrieves the player's zero-indexed X- and Y-coordinates in the map, and stores them in the specified variables.
43 countPokémon
Retrieves the number of Pokémon in the player's party, and stores that number in variable 0x800D (LASTRESULT).
44 additem
- 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.
45 removeitem
- 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.)
46 checkitemroom
- 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.
47 checkitem
- 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.
48 checkitemtype
- 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:
0x0001Items Pocket0x0002Key Items Pocket0x0003Poke Balls Pocket0x0004TM Case0x0005Berry Pouch
49 addpcitem
- 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.
4a checkpcitem
- 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:
4B adddecoration
- 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).
4C removedecoration
- 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.
4D testdecoration
- 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.
4E checkdecoration
- 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.
4F applymovement
- 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.
50 applymovementpos [details needed]
- 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.
51 waitmovement
- 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.
52 waitmovementpos [details needed]
- 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.
53 hidesprite
- 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).
- Gallery
-
Two OWs prior to using hidesprite.
-
The change in flags, revealed via script.
-
Used on the player. Hidesprite gave them control of another Person.
54 hidespritepos [details needed]
- byte-or-variable index
- byte X
- byte Y
Clone of hidesprite that also moves the Person? Test it!
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.
5C trainerbattle [details needed]
- 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.
| 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.)
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.
60 checktrainerflag
- word-or-variable trainer
Compares Flag (trainer + 0x500) to 1. (If the flag is set, then the trainer has been defeated by the player.)
61 cleartrainerflag
- word-or-variable trainer
Sets Flag (trainer + 0x500). (I didn't make a mistake. The command names actually are backwards.)
62 settrainerflag
- word-or-variable trainer
Clears Flag (trainer + 0x500). (I didn't make a mistake. The command names actually are backwards.)
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.
67 preparemsg
- 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.
68 closeonkeypress
Holds the current message box open until the player presses a key. The message box is then closed.
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.)
6A lock
If the script was called by a Person event, then that Person's movement will cease.
6B releaseall
Resumes normal movement for all OWs on-screen, and closes any standard message boxes that are still open.
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.
6D waitkeypress
Blocks script execution until the player presses any key.
6E yesnobox
- 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".
6F multichoice
- 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.
70 multichoice2
- 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.
- Gallery
-
0x01was the default. -
0x05was the default. -
0x06was the default.
71 multichoice3
- 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.
- Gallery
-
Valid number of options per row.
-
Orphaned options become unusable.
-
.PNG)
One too many options per row.
-
Three too many options per row.
75 showpokepic
- word-or-variable species
- byte X
- byte Y
Displays a box containing the front sprite for the specified (species) Pokémon species.
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.
77 showcontestwinner
- 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.
78 braille
- 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.
79 givePokémon [details needed]
- 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.)
7C checkattack [details needed]
- 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?)
7D bufferPokémon
- 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.
7E bufferfirstPokémon [details needed]
- 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?)
7F bufferpartyPokémon [details needed]
- 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?)
80 bufferitem
- 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.
81 bufferdecoration
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.
82 bufferattack
- 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.
83 buffernumber
- buffer out
- word-or-variable input
Converts the value of input to a decimal string, and writes that string to the specified buffer.
84 bufferstd
- 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):
0x00COOL0x01BEAUTY0x02CUTE0x03SMART0x04TOUGH0x05COOL0x06BEAUTY0x07CUTE0x08SMART0x09TOUGH0x0AITEMS0x0BKEY ITEMS0x0CPOKe BALLS0x0DTMs & HMs0x0EBERRIES0x0FBOULDERBADGE0x10CASCADEBADGE0x11THUNDERBADGE0x12RAINBOWBADGE0x13SOULBADGE0x14MARSHBADGE0x15VOLCANOBADGE0x16EARTHBADGE0x17COINS0x18ITEMS POCKET0x19KEY ITEMS POCKET0x1APOKe BALLS POCKET0x1BTM CASE0x1CBERRY POUCH0x1DTrade 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."0x1EYou may battle another TRAINER0x1FCancels the selected MENU item.0x20You may trade your Pokémon here0x21You may battle with your friends (longer than the buffer supports)
The buffer does indeed support this string: "You may battle with your friends here."0x22Two to five TRAINERS can make0x23Cancels the selected MENU item.0x24You may trade your Pokémon here0x25You may battle with your friends (longer than the buffer supports)
The buffer does indeed support this string: "You may battle with your friends here."0x26Cancels the selected MENU item.
85 bufferstring
- buffer out
- pointer offset
Copies the string at offset to the specified buffer.
86 pokemart
- 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.
87 pokemart2
- pointer products
Apparent clone of pokemart.
88 pokemart3
- pointer products
Apparent clone of pokemart.
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.
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.
8C startcontest
In FireRed, this command is a nop.
In R/S/E, it started a Pokémon Contest.
8D showcontestresults
In FireRed, this command is a nop.
In R/S/E, it showed the results of a Pokémon Contest.
8E contestlinktransfer
In FireRed, this command is a nop.
In Emerald, it apparently started a Pokémon Contest over a wireless connection.
8F random
- word-or-variable limit
Stores a random integer between 0 and limit in variable 0x800D (LASTRESULT).
The number will always be less than limit.
90 givemoney [details needed]
- dword value
- byte check
If check is 0x00, this command adds value to the player's money.
(Can this overflow?)
91 paymoney [details needed]
- dword value
- byte check
If check is 0x00, this command subtracts value from the player's money.
(Can this overflow?)
92 checkmoney
- 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.
93 showmoney [details needed]
- 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...)
94 hidemoney
- byte X
- byte Y
Hides the secondary box spawned by showmoney.
(Does this discard its arguments like hidecoins does?)
95 updatemoney [details needed]
- 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.
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.
97 fadescreen [details needed]
- 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?)
9C doanimation [details needed]
- 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):
0x01CUT (grass)? (black Pokémon bar + leaf spiral) I can confirm.0x02CUT0x03Part of the FLY animation sequence.0x06Part of the FLY animation sequence.0x08Buggy SURF-Pokémon sprite appears on map0x09SURF0x19PokeCenter healing machine0x1EPart of the FLY animation sequence. (takeoff)0x1FPart of the FLY animation sequence. Calls animation 0x3B.0x20Part of the FLY animation sequence.0x22Landing (after FLY)0x23FLY (crashes, probably because destination isn't set)0x25ROCK SMASH0x26TELEPORT? (black Pokémon bar)0x28STRENGTH0x2BWATERFALL0x2CDIVE (crashes, probably because destination/directionality isn't set)0x2DShows a buggy message box in the top-left corner0x33SWEET SCENT? I can confirm.0x3BPart of the FLY animation sequence.0x3EHall of Fame registration machine0x3FTeleports to player's home? Teleports to the flying spot for the sethealingplace map.0x41VS SEEKER (crashes)0x45White flash
(Does it accept a variable? Test and confirm 01, 1E, 26, 3F, 41.)
9D setanimation [details needed]
- 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?)
9E checkanimation [details needed]
- word animation
Blocks script execution until all playing field move animations complete.
(What does the word do?)
9F sethealingplace [details needed]
- 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?)
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.
A1 cry [details needed]
- 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?)
A2 setmaptile [details needed]
- 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.)
A3 resetweather [details needed]
Queues a weather change to the default weather for the map.
(Only one weather change can be queued at once?)
A4 setweather [details needed]
- word type
Queues a weather change to type weather.
(Only one weather change can be queued at once?)
(Does this accept variables?)
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?)
A6 cmda6
- 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.
| 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 |
| 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.
AC setdooropened [details needed]
- 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?)
AD setdoorclosed [details needed]
- 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?)
AE doorchange [details needed]
Executes the state changes queued with setdooropened, setdoorclosed, setdooropened2, and setdoorclosed2.
(Does this block for animated door changes? For both?)
AF setdooropened2 [details needed]
- 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?)
B0 setdoorclosed2 [details needed]
- 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?)
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.
B2 cmdb2
In FireRed, this command is a nop.
B6 setwildbattle [details needed]
- 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.
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?)
C0 showcoins
- 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.
C1 hidecoins
byte Xbyte Y
Hides the secondary box spawned by showcoins. It doesn't appear to use its arguments, but they are still required.
C2 updatecoins [details needed]
- 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.
C3 cmdc3
- 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.
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...)
C5 waitcry
Blocks script execution until cry finishes.
C6 bufferboxname
- buffer out
- word-or-variable box
Writes the name of the specified (box) PC box to the specified buffer.
C7 textcolor [details needed]
- 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.)
- Gallery
-
Usually, an OW's gender controls the text color.
-
Textcolor is one of many ways to override that.
C8 cmdc8 [details needed]
- 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.
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.
CA signmsg
After using this command, all standard message boxes will use the signpost frame.
CB normalmsg
Ends the effects of signmsg, returning message box frames to normal.
CC comparehiddenvar [details needed]
- 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.
CD setobedience [details needed]
- 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?)
CE checkobedience
- 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.
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.
D0 setworldmapflag
- 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:
- The byte at
0x0203ADFAis greater than0x03. - The specified flag is on a list (at
0x08456C50, with0x10two-byte entries) of world map flags that can actually be flown to.
D1 warpteleport2
Clone of warpteleport? It is apparently only used in FR/LG, and only with specials.[source]
D2 setcatchlocation
- 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.
D3 braille2
- 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.
D4 bufferitems [details needed]
- 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?)
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.