Emerald Scripting Reference

General scripting language

Defined in event.inc:

• end
  Terminates script execution

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

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

• goto destination:req
  Jumps to destination and continues script execution from there.

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

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

• gotostd function:req
  Jumps to the standard function at index function.

• callstd function:req
  Calls the standard function at index function.

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

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

• gotoram
  Executes a script stored in a default RAM location.

• killscript
  Terminates script execution and "resets the script RAM".

• setmysteryeventstatus value:req
  Sets some status related to Mystery Event.

• loadword destination:req, value:req
  Sets the specified script bank to value.

• loadbyte destination:req, value:req
  Sets the specified script bank to value.

• writebytetoaddr value:req, offset:req
  Sets the byte at offset to value.

• loadbytefromaddr destination:req, source:req
  Copies the byte value at source into the specified script bank.

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

• copylocal destination:req, source:req
  Copies the contents of bank source into bank destination.

• copybyte destination:req, source:req
  Copies the byte at source to destination, replacing whatever byte was previously there.

• setvar destination:req, value:req
  Changes the value of destination to value.

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

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

• copyvar destination:req, source:req
  Copies the value of source into destination.

• setorcopyvar destination:req, source:req
  If source is not a variable, then this function acts like setvar. Otherwise, it acts like copyvar.

• compare_local_to_local byte1:req, byte2:req
  Compares the values of script banks a and b, after forcing the values to bytes.

• compare_local_to_value a:req, b:req
  Compares the least-significant byte of the value of script bank a to a fixed byte value (b).

• compare_local_to_addr a:req, b:req
  Compares the least-significant byte of the value of script bank a to the byte located at offset b.

• compare_addr_to_local a:req, b:req
  Compares the byte located at offset a to the least-significant byte of the value of script bank b.

• compare_addr_to_value a:req, b:req
  Compares the byte located at offset a to a fixed byte value (b).

• compare_addr_to_addr a:req, b:req
  Compares the byte located at offset a to the byte located at offset b.

• compare_var_to_value var:req, value:req
  Compares the value of var to a fixed word value (b).

• compare_var_to_var var1:req, var2:req
  Compares the value of var1 to the value of var2.

• compare arg1:req, arg2:req
  Generic compare macro which attempts to deduce argument types based on their values. Any values between 0x4000 to 0x4FFF and 0x8000 to 0x8FFF are considered event variable identifiers.

• callnative func:req
  Calls the native C function stored at func.

• gotonative func:req
  Replaces the script with the function stored at func. Execution returns to the bytecode script when func returns TRUE.

• special function:req
  Calls a special function; that is, a function designed for use by scripts and listed in a table of pointers.

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

• specialvar_ output:req, functionId:req
  temporary solution

• waitstate
  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).

• delay time:req
  Blocks script execution for time (frames? milliseconds?).

• setflag a:req
  Sets a to 1.

• clearflag a:req
  Sets a to 0.

• checkflag a:req
  Compares a to 1.

• initclock hour:req, minute:req
  Initializes the RTC`s local time offset to the given hour and minute. In FireRed, this command is a nop.

• dotimebasedevents
  Runs time based events. In FireRed, this command is a nop.

• gettime
  Sets the values of variables 0x8000, 0x8001, and 0x8002 to the current hour, minute, and second. In FRLG, this command sets those variables to zero.

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

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

• playfanfare fanfare_number:req
  Plays the specified (fanfare_number) fanfare.

• waitfanfare
  Blocks script execution until all currently-playing fanfares finish.

• playbgm song_number:req, unknown:req
  Plays the specified (song_number) song. The byte is apparently supposed to be 0x00.

• savebgm song_number:req
  Saves the specified (song_number) song to be played later.

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

• fadenewbgm song_number:req
  Crossfades the currently-playng song into the specified (song_number) song.

• fadeoutbgm speed:req
  Fades out the currently-playing song.

• fadeinbgm speed:req
  Fades the previously-playing song back in.

• warp map:req, warp:req, X:req, Y:req
  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.

• warpsilent map:req, warp:req, X:req, Y:req
  Clone of warp that does not play a sound effect.

• warpdoor map:req, warp:req, X:req, Y:req
  Clone of warp that plays a door opening animation before stepping upwards into it.

• warphole map:req
  Warps the player to another map using a hole animation.

• warpteleport map:req, warp:req, X:req, Y:req
  Clone of warp that uses a teleport effect. It is apparently only used in R/S/E.

• setwarp map:req, warp:req, X:req, Y:req
  Sets the warp destination to be used later.

• setdynamicwarp map:req, warp:req, X:req, Y:req
  Sets the warp destination that a warp to Warp 127 on Map 127.127 will connect to. Useful when a map has warps that need to go to script-controlled locations (i.e. elevators).

• setdivewarp map:req, warp:req, X:req, Y:req
  Sets the destination that diving or emerging from a dive will take the player to.

• setholewarp map:req, warp:req, X:req, Y:req
  Sets the destination that falling into a hole will take the player to.

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

• getpartysize
  Retrieves the number of Pokemon in the player's party, and stores that number in variable 0x800D (LASTRESULT).

• giveitem index:req, quantity:req
  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.

• takeitem index:req, quantity:req
  Removes quantity of item index from the player's Bag.

• checkitemspace index:req, quantity:req
  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.

• checkitem index:req, quantity:req
  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.

• checkitemtype index:req
  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).

• givepcitem index:req, quantity:req
  Adds a quantity amount of item index to the player's PC. Both arguments can be variables.

• checkpcitem index:req, quantity:req
  Checks for quantity amount of item index in the player's PC. Both arguments can be variables.

• givedecoration decoration:req
  Adds decoration to the player's PC. In FireRed, this command is a nop. (The argument is read, but not used for anything.)

• takedecoration decoration:req
  Removes a decoration from the player's PC. In FireRed, this command is a nop. (The argument is read, but not used for anything.)

• checkdecor decoration:req
  Checks for decoration in the player's PC. In FireRed, this command is a nop. (The argument is read, but not used for anything.)

• checkdecorspace decoration:req
  Checks if the player has enough space in their PC to hold decoration. Sets variable 0x800D (LASTRESULT) to 0x0001 if there is room, or 0x0000 is there is no room. In FireRed, this command is a nop. (The argument is read, but not used for anything.)

• applymovement index:req, movements:req, map
  Applies the movement data at movements to the specified (index) Object. Also closes any standard message boxes that are still open. If no map is specified, then the current map is used.

• waitmovement index:req, map
  Blocks script execution until the movements being applied to the specified (index) Object finish. If the specified Object is 0x0000, then the command will block script execution until all Objects affected by applymovement finish their movements. If the specified Object is not currently being manipulated with applymovement, then this command does nothing. If no map is specified, then the current map is used.

• removeobject index:req, map
  Attempts to hide the specified (index) Object on the specified (map_group, map_num) map, by setting its visibility flag if it has a valid one. If the Object does not have a valid visibility flag, this command does nothing. If no map is specified, then the current map is used.

• addobject index:req, map
  Unsets the specified (index) Object's visibility flag on the specified (map_group, map_num) map if it has a valid one. If the Object does not have a valid visibility flag, this command does nothing. If no map is specified, then the current map is used.

• setobjectxy index:req, x:req, y:req
  Sets the specified (index) Object's position on the current map.

• showobjectat index:req, map:req
  ???

• hideobjectat index:req, map:req
  ???

• faceplayer
  If the script was called by an Object, then that Object will turn to face toward the metatile that the player is standing on.

• turnobject index:req, direction:req
  ???

• trainerbattle type:req, trainer:req, local_id:req, pointer1:req, pointer2, pointer3, pointer4
  If the Trainer flag for Trainer index is not set, this command does absolutely nothing.

• trainerbattle_single trainer:req, intro_text:req, lose_text:req, event_script=FALSE, music=TRUE
  Starts a single trainer battle, takes a trainer, intro text, loss text, and an optional event script when used with an event script, you can also pass in an optional flag to disable music

• trainerbattle_double trainer:req, intro_text:req, lose_text:req, not_enough_pkmn_text:req, event_script=FALSE, music=TRUE
  Starts a double trainer battle, takes a trainer, intro text, loss text, text for when you have too few pokemon and an optional event script, when used with an event script you can pass in an optional flag to disable music

• trainerbattle_rematch trainer:req, intro_text:req, lose_text:req
  Starts a rematch battle, takes a trainer, intro text and loss text

• trainerbattle_rematch_double trainer:req, intro_text:req, lose_text:req, not_enough_pkmn_text:req
  Starts a rematch double battle, takes a trainer, intro text, loss text, and text for when you have too few pokemon

• trainerbattle_no_intro trainer:req, lose_text:req
  Starts a trainer battle, skipping intro text, takes a trainer and loss text

• trainerbattlebegin
  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.

• gotopostbattlescript
  Goes to address after the trainerbattle command (called by the battle functions, see battle_setup.c)

• gotobeatenscript
  Goes to address specified in the trainerbattle command (called by the battle functions, see battle_setup.c)

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

• settrainerflag trainer:req
  Sets Flag (trainer + 0x500).

• cleartrainerflag trainer:req
  Clears Flag (trainer + 0x500).

• setobjectxyperm index:req, x:req, y:req
  ???

• moveobjectoffscreen index:req
  ???

• setobjectmovementtype word:req, byte:req
  ???

• waitmessage
  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.

• message text:req
  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.)

• closemessage
  Closes the current message box.

• lockall
  Ceases movement for all Objects on-screen.

• lock
  If the script was called by an Object, then that Object's movement will cease.

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

• release
  If the script was called by an Object, then that Object's movement will resume. This command also closes any standard message boxes that are still open.

• waitbuttonpress
  Blocks script execution until the player presses any key.

• yesnobox x:req, y:req
  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".

• multichoice x:req, y:req, list:req, b:req
  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.

• multichoicedefault x:req, y:req, list:req, default:req, b:req
  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.

• multichoicegrid x:req, y:req, list:req, per_row:req, B:req
  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.

• drawbox
  Nopped in Emerald.

• erasebox byte1:req, byte2:req, byte3:req, byte4:req
  Nopped in Emerald, but still consumes parameters.

• drawboxtext byte1:req, byte2:req, byte3:req, byte4:req
  Nopped in Emerald, but still consumes parameters.

• drawmonpic species:req, x:req, y:req
  Displays a box containing the front sprite for the specified (species) Pokemon species.

• erasemonpic
  Hides all boxes displayed with drawmonpic.

• drawcontestwinner a:req
  Draws an image of the winner of the contest. In FireRed, this command is a nop. (The argument is discarded.)

• braillemessage text:req
  Displays the string at pointer as braille text in a standard message box. The string must be formatted to use braille characters and needs to provide six extra starting characters that are skipped (in RS, these characters determined the box's size and position, but in Emerald these are calculated automatically).

• givemon species:req, level:req, item:req, unknown1:req, unknown2:req, unknown3:req
  Gives the player one of the specified (species) Pokemon at level level holding item. The unknown arguments should all be zeroes. .endm

• .endm
  iveegg species:req`

etmonmove index:req, slot:req, move:req`

• checkpartymove index:req
  Checks if at least one Pokemon 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 first Pokemon that knows the move. If not, LASTRESULT is set to 0x0006. Variable 0x8004 is also set to this Pokemon's species.

• bufferspeciesname out:req, species:req
  Writes the name of the Pokemon at index species to the specified buffer.

• bufferleadmonspeciesname out:req
  Writes the name of the species of the first Pokemon in the player's party to the specified buffer.

• bufferpartymonnick out:req, slot:req
  Writes the nickname of the Pokemon 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.

• bufferitemname out:req, item:req
  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.

• bufferdecorationname out:req, decoration:req
  Writes the name of the decoration at index decoration to the specified buffer. In FireRed, this command is a nop.

• buffermovename out:req, move:req
  Writes the name of the move at index move to the specified buffer.

• buffernumberstring out:req, input:req
  Converts the value of input to a decimal string, and writes that string to the specified buffer.

• bufferstdstring out:req, index:req
  Writes the standard string identified by index to the specified buffer. This command has no protections in place at all, so specifying an invalid standard string (e.x. 0x2B) can and usually will cause data corruption.

• bufferstring out:req, offset:req
  Copies the string at offset to the specified buffer.

• pokemart products:req
  Opens the Pokemart system, offering the specified products for sale.

• pokemartdecoration products:req
  Opens the Pokemart system and treats the list of items as decorations.

• pokemartdecoration2 products:req
  Apparent clone of pokemartdecoration.

• playslotmachine word:req
  Starts up the slot machine minigame.

• setberrytree tree_id:req, berry:req, growth_stage:req
  Sets a berry tree's specific berry and growth stage. In FireRed, this command is a nop.

• choosecontestmon
  This allows you to choose a Pokemon to use in a contest. In FireRed, this command sets the byte at 0x03000EA8 to 0x01.

• startcontest
  Starts a contest. In FireRed, this command is a nop.

• showcontestresults
  Shows the results of a contest. In FireRed, this command is a nop.

• contestlinktransfer
  Starts a contest over a link connection. In FireRed, this command is a nop.

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

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

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

• checkmoney value:req, check:req
  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.

• showmoneybox x:req, y:req, check:req
  Spawns a secondary box showing how much money the player has.

• hidemoneybox
  Hides the secondary box spawned by showmoney.

• updatemoneybox x:req, y:req
  Updates the secondary box spawned by showmoney. Consumes but does not use arguments.

• getpricereduction index:req
  Gets the price reduction for the index given. In FireRed, this command is a nop.

• fadescreen effect:req
  Fades the screen to and from black and white. Mode 0x00 fades from black, mode 0x01 fades out to black, mode 0x2 fades in from white, and mode 0x3 fades out to white.

• fadescreenspeed effect:req, speed:req
  Fades the screen to and from black and white. Mode 0x00 fades from black, mode 0x01 fades out to black, mode 0x2 fades in from white, and mode 0x3 fades out to white. Other modes may exist.

TODO setflashradius

Map specific data

Defined in map.inc:

Movement specific data

Defined in movement.inc: