It's highly recommended to type commands exclusively in lowercase, and anything #defined in caps. All examples in this manual assume you include std.rbh in the compilation process. This can be done by checking "Include STD" in Diamond Cutter, or simply adding "stb.rbh" to your batch file, if you use one.
You can also compile many files in one go. The headers are included in the same way:
rbc /o myrom.gba std.rbh script1.rbc script2.rbc script3.rbc
Preproc directives
#include
#include sFile
Include another file in the compilation process. Double quotes are automatically removed.
Example:
#include "mydefs.rbh"
#define
#define sSymbol iNumber
Allows you to define symbols to replace numbers. Only numbers are allowed but they can be any size from byte to dword. It's good practice to use uppercase symbol names.
Example:
#define MASTERBALL 1
#org
Aliases: #seek
Set the compiler's write cursor to the specified location in ROM.
Example:
#org 0x605040 'continue (or start) writing somewhere in the empty space.
#autobank
#autobank [on|off]
Some might prefer to include the trailing 0x08 in pointers, others may not. When turned on, the extra 0x08 is automajickally added
to any pointer. Only #org is not affected since, as a file, the ROM always starts at bank 0x00.
Example:
#autobank on
message 0x604020 'becomes 0F00 08604020
#autobank off
message 0x604020 'becomes 0F00 00604020, which is a bad thing.
#raw
Aliases: #binary
#raw aLot
Inserts a load of raw data into the ROM. This can be used for unsupported commands as well as movement data. To determine which data type to use, simply add in the type's name before any values that follow. The sequence always defaults to byte. You can use hex prefixes (0x and &H) if you must, but this command does not need them.
Possible data types are:
- byte (also char)
- word (also int or integer)
- dword (also long)
- pointer (also ptr)
Example:
#binary 12 69 word 1234 dword 12345678 pointer 0xABCDEF
This example would output two bytes, one word, one dword and a pointer. Note how the pointer is affected by the AutoBank system and the DWord is not.
=
= sText
Raw text inserter.
Example:
= Hello! I'm so happy!\cHappy happy happy...
General commands
nop (00, 01 and C6)
nop
Absolutely nothing.
end (02)
end
End execution of the script.
return (03)
return
Return from where you were called from. Kinda like Basic's GOSUB...RETURN system.
call (04)
call ptrTarget
Call another script. You can return from there with Return.
Example:
call JUMP_BAGISFULL
goto (05)
goto ptrTarget
Continue execution from ptrTarget. Return is not allowed.
if (06)
if bCondition action ptrTarget
If the last comparison returned a certain value, jump or goto another script. Action can be "goto" or "gosub". If no action is specified "gosub" is assumed and Return can be used.
Possible condition values are:
00 - Lower (<<), also FALSE
01 - Equal (==), also TRUE
02 - Bigger (>>)
03 - Lower or equal (>=)
04 - Bigger or equal (<=)
05 - Not equal (!=)
Example:
compare LASTRESULT 0x4
if TRUE goto JUMP_BAGISFULL
boxset (09)
Aliases: callstd
boxset bValue
Calls a standard function. Mostly used to display dialogue with parameters 0x04 and 0x06 or yes/no questions with 0x05.
Example:
message 0x604000 'normal stuff
boxset 4 'don't close after keypress
message 0x604020 'question
boxset BOXSET_YESNO
if LASTRESULT NO 0x600020 'goto "no" handler
'"yes" handler goes here
...
break
#org 0x600020
'"no" handler goes here
...
break
message (0F)
Aliases: loadpointer
message lPointer
loadpointer bBank lPointer
Prepares a pointer for use by commands like BoxSet. Mostly used to load dialogue text. The LoadPointer alias has been added for technical correctness.
Example:
message 0x604020
boxset 0x06 'close after button press
setvar (16)
Aliases: setvar1
setvar iVar iValue
Set a variable to a certain value.
Analogous to Basic's A = 4.
copyvar (19)
Aliases: setvar2
copyvar iVar iVar
Copy the value of one variable to another.
Analogous to Basic's A = B.
copyvarifnotzero (1A)
Aliases: setvar3
copyvarifnotzero iVar iVar
Copy the value of one variable to another, but only if the new variable's value is not zero.
Analogous to Basic's IF B > 0 THEN A = B.
compare (21)
compare iVar iValue
Compares a variable with a value. Used in conjunction with if and mostly with LASTRESULT as a parameter.
Example:
compare LASTRESULT 0x4
if TRUE JUMP_BAGISFULL
special (25)
special iEvent
Triggers a special event to occur.
Example:
special SPECIAL_WALLYCATCH 'Play back movie of Wally catching a Ralts.
special2 (26)
special2 iVar iIndex
Check special stuff? Is used for rematch battles and stuff.
pause (28)
pause iVal
setflag (29)
setflag iFlag
Sets a flag.
Example:
setflag 0x64
checkflag 0x64
compare LASTRESULT YES
if 1 0x600020 'goto "yes" handler
'"no" handler goes here
...
break
#org 0x600020
'"yes" handler goes here
...
break
clearflag (2A)
clearflag iFlag
Clears a flag.
checkflag (2B)
checkflag iFlag
Checks if iFlag is set. For an example, see setflag.
cry (30)
cry iSpecies iUnknown
Plays back the cry of the specified Pokémon. Normally used for tame Pokémon such as the movers in R/S.
Example:
cry PKMN_PIKACHU
fanfare (31)
fanfare iSong
Play back a song as a jingle.
waitfanfare (32)
waitfanfare
Wait for the jingle started by Fanfare to finish
playsound (33)
playsound iIndex
Abruptly switch to another music track.
fadedefault (35)
fadedefault
Gently switch to the map's default music track.
fadesound (36)
fadesound iIndex
Gently switch to another music track.
fadeout (37)
fadeout
Gently fade out the currently playing track.
fadein (38)
fadein
Gently fade the currently playing track back in.
warp (39)
warp bBank bMap bExit
checkitem (47)
checkitem iItem
Checks if the player carries at least one instance of the specified item.
Example:
checkitem ITEM_MAXPOTION
compare LASTRESULT YES
if TRUE 0x604020
applymovement (4F)
applymovement iSprite lPointer
Applies the movement data at lPointer to the specified sprite.
Example:
movement 0x5 0x604020
wait 0x0 'wait for movement to complete
movesprite (57)
movesprite iIndex iX iY
TODO: Write this.
faceplayer (5A)
faceplayer
Turns the caller towards the player.
trainerbattle (5C)
trainerbattle bKind iBattle ptrIntro ptrDefeat
Starts a trainer battle.
bKind is 0x00 for normal battles, 0x04 for 2-on-2 and 0x05 for rematches.
You'll need to add an extra parameter, ptrSpecial, for 2-on-2 battles and gym leaders.
2-on-2 battles require ptrSpecial to point to extra dialogue, and gym leaders need it to point to more code.
2-on-2 dialogue should tell the player that he or she needs at least two Pokémon to fight.
Gym leaders should give defeat gifts like badges. Check out your favorite leader in Scripted 1.0.1 to see an example of the gym gift code.
Example:
trainerbattle 0 MYBATTLEINTRO MYBATTLEDEFEAT
message MYBATTLEAFTERWARDS
boxset 4
jingle (69)
jingle
Plays a little sound effect.
lock (6A)
lock
Locks down movement for the caller.
release (6C)
release
Resumes movement for the caller.
multi (6F)
multi bLeft bTop bList bCancel
Puts up a list of choices for the player to make. Available choices depend on the value of bList. bCancel determines wether the player can press the B button to select the last item, if yes the last item should be "Cancel". As always, the player's choice is stored in LASTRESULT.
Example:
message 0x604020 '"What city do you like best?"
choice 2 2 13 0 'items available are littleroot, slateport and lilycove
compare LASTRESULT 1
if 0 0x600030 'goto littleroot handler
if 1 0x600050 'goto slateport handler
'lilycove handler starts right here, no "if LASTRESULT 3" needed.
givepokemon (79)
givepokemon iSpecies bLevel iItem
Gives the player a Pokémon of any given species and level, holding an item if iItem > 0.
pokemart (86)
pokemart ptrItemList
Opens the PokéMart shop system with the item/price list found at ptrItemList.
For more information on price lists, check the big pile of doggie doo.
fadescreen (97)
fadescreen bInOrOut
Fades the screen in or out.
checkgender (A0)
checkgender
Simply puts 1 in in LASTRESULT if the player is a girl or 0 if he's a boy.
setmaptile (A2)
setmaptile iX iY iTileNo iTileAttr
Sets a tile on the map. You must somehow refresh that part, can be done by scrolling out of view and back in or by calling this command from a Level Script.
setweather (A4)
setweather bWeather
Gently changes the weather.
Values tested with results:
00 - Nothing
03 - Rain
04 - Snow, doesn't stay long.
05 - Thunderstorm
06 - Fog
07 - Ash
08 - Sandstorm
09 - Different fog
0A - Light fog
0B - Darkness (here's your nighttime effect!)
0C - Hot sun
0D - Thunderstorm
0E - Underwater
0F - Nothing
doweather (A5)
doweather
Triggers the weather change set with setweather.
Constructs
wildbattle
wildbattle iSpecies iLevel bStyle
Originally a true command, now a construct.
Style can be any of these:
0 normal wild pokémon battle
1 ground legend battle, zigzag wipe
2 grass legend battle, zigzag wipe
3 boxtwirl wiped battle
Example:
wildbattle 0x196 70 3 'fight a level 70 Rayquaza!
giveitem
giveitem iItem iQuantity
Gives the player an item.
This is a construct that converts to two setvarifnotzero commands.
Example:
giveitem ITEM_SODAPOP 1
Hardcore commands
jumpstd (08)
jumpstd bValue
Jumps to a standard function. Kinda like BoxSet, only with slightly different logic, like Basic's GOSUB compared to GOTO.
comparevars (1B)
comparevars iVar iVar
Compares a variable with another variable.
comparevartobyte (1C)
comparevartobyte iVar bVal
Compares a variable with a byte value.
comparevartofarbyte (1D)
comparevartofarbyte iVar lPointer
Compares a variable with a byte at some location.
comparefarbytetovar (1E)
comparefarbytetovar lPointer iVar
Compares a byte at some location with a variable.
comparefarbytetobyte (1F)
comparefarbytetobyte lPointer bVal
Compares a byte at some location with a byte value.
comparefarbytetofarbyte (20)
comparefarbytetofarbyte lPointer lPointer
Compares a byte at some location with another byte at some location.
Predefined variables and constants in STD.RBH
B_YES, B_NO, B_TRUE, B_FALSE, B_BOY and B_GIRL
I like booleans. They're comfy and easy to #define.
B_<<, B_==, B_>>, B_<=, B_>= and B_!=
Like B_TRUE and B_FALSE above, but for experienced coders who want full logical power.
BOXSET_DONTCLOSE, BOXSET_YESNO and BOXSET_NORMAL
The three most common BoxSet parameters.
MENU_PARTY, MENU_POKEDEX and MENU_NAVIGATOR
SetFlag parameters to enable their respective menu items. Can also be cleared to, for example, make Grunts steal your kit.
0x800D - LASTRESULT
Nearly every time something is checked, the answer is stored in this variable.
SPRITEMOVE_INDEX
SPRITEMOVE_NEWXPOS
SPRITEMOVE_NEWYPOS
Combine these three with SetVar to move a sprite to a proper position on the map.
This is used in Littleroot to move Mom to either the left or right hand house door depending on the player's gender.
APPLYMOVE_PLAYER
Because it makes more sense than 0xFF. Use it in ApplyMovement to control the player.
JUMP_BAGISFULL
A predefined label for Ruby to write ye olde standard error message when the player's inventory is completely filled. See goto for an example. Assumes Autobanking is ON.
You can also compile many files in one go. The headers are included in the same way:
rbc /o myrom.gba std.rbh script1.rbc script2.rbc script3.rbc
Preproc directives
#include
#include sFile
Include another file in the compilation process. Double quotes are automatically removed.
Example:
#include "mydefs.rbh"
#define
#define sSymbol iNumber
Allows you to define symbols to replace numbers. Only numbers are allowed but they can be any size from byte to dword. It's good practice to use uppercase symbol names.
Example:
#define MASTERBALL 1
#org
Aliases: #seek
Set the compiler's write cursor to the specified location in ROM.
Example:
#org 0x605040 'continue (or start) writing somewhere in the empty space.
#autobank
#autobank [on|off]
Some might prefer to include the trailing 0x08 in pointers, others may not. When turned on, the extra 0x08 is automajickally added
to any pointer. Only #org is not affected since, as a file, the ROM always starts at bank 0x00.
Example:
#autobank on
message 0x604020 'becomes 0F00 08604020
#autobank off
message 0x604020 'becomes 0F00 00604020, which is a bad thing.
#raw
Aliases: #binary
#raw aLot
Inserts a load of raw data into the ROM. This can be used for unsupported commands as well as movement data. To determine which data type to use, simply add in the type's name before any values that follow. The sequence always defaults to byte. You can use hex prefixes (0x and &H) if you must, but this command does not need them.
Possible data types are:
- byte (also char)
- word (also int or integer)
- dword (also long)
- pointer (also ptr)
Example:
#binary 12 69 word 1234 dword 12345678 pointer 0xABCDEF
This example would output two bytes, one word, one dword and a pointer. Note how the pointer is affected by the AutoBank system and the DWord is not.
=
= sText
Raw text inserter.
Example:
= Hello! I'm so happy!\cHappy happy happy...
General commands
nop (00, 01 and C6)
nop
Absolutely nothing.
end (02)
end
End execution of the script.
return (03)
return
Return from where you were called from. Kinda like Basic's GOSUB...RETURN system.
call (04)
call ptrTarget
Call another script. You can return from there with Return.
Example:
call JUMP_BAGISFULL
goto (05)
goto ptrTarget
Continue execution from ptrTarget. Return is not allowed.
if (06)
if bCondition action ptrTarget
If the last comparison returned a certain value, jump or goto another script. Action can be "goto" or "gosub". If no action is specified "gosub" is assumed and Return can be used.
Possible condition values are:
00 - Lower (<<), also FALSE
01 - Equal (==), also TRUE
02 - Bigger (>>)
03 - Lower or equal (>=)
04 - Bigger or equal (<=)
05 - Not equal (!=)
Example:
compare LASTRESULT 0x4
if TRUE goto JUMP_BAGISFULL
boxset (09)
Aliases: callstd
boxset bValue
Calls a standard function. Mostly used to display dialogue with parameters 0x04 and 0x06 or yes/no questions with 0x05.
Example:
message 0x604000 'normal stuff
boxset 4 'don't close after keypress
message 0x604020 'question
boxset BOXSET_YESNO
if LASTRESULT NO 0x600020 'goto "no" handler
'"yes" handler goes here
...
break
#org 0x600020
'"no" handler goes here
...
break
message (0F)
Aliases: loadpointer
message lPointer
loadpointer bBank lPointer
Prepares a pointer for use by commands like BoxSet. Mostly used to load dialogue text. The LoadPointer alias has been added for technical correctness.
Example:
message 0x604020
boxset 0x06 'close after button press
setvar (16)
Aliases: setvar1
setvar iVar iValue
Set a variable to a certain value.
Analogous to Basic's A = 4.
copyvar (19)
Aliases: setvar2
copyvar iVar iVar
Copy the value of one variable to another.
Analogous to Basic's A = B.
copyvarifnotzero (1A)
Aliases: setvar3
copyvarifnotzero iVar iVar
Copy the value of one variable to another, but only if the new variable's value is not zero.
Analogous to Basic's IF B > 0 THEN A = B.
compare (21)
compare iVar iValue
Compares a variable with a value. Used in conjunction with if and mostly with LASTRESULT as a parameter.
Example:
compare LASTRESULT 0x4
if TRUE JUMP_BAGISFULL
special (25)
special iEvent
Triggers a special event to occur.
Example:
special SPECIAL_WALLYCATCH 'Play back movie of Wally catching a Ralts.
special2 (26)
special2 iVar iIndex
Check special stuff? Is used for rematch battles and stuff.
pause (28)
pause iVal
setflag (29)
setflag iFlag
Sets a flag.
Example:
setflag 0x64
checkflag 0x64
compare LASTRESULT YES
if 1 0x600020 'goto "yes" handler
'"no" handler goes here
...
break
#org 0x600020
'"yes" handler goes here
...
break
clearflag (2A)
clearflag iFlag
Clears a flag.
checkflag (2B)
checkflag iFlag
Checks if iFlag is set. For an example, see setflag.
cry (30)
cry iSpecies iUnknown
Plays back the cry of the specified Pokémon. Normally used for tame Pokémon such as the movers in R/S.
Example:
cry PKMN_PIKACHU
fanfare (31)
fanfare iSong
Play back a song as a jingle.
waitfanfare (32)
waitfanfare
Wait for the jingle started by Fanfare to finish
playsound (33)
playsound iIndex
Abruptly switch to another music track.
fadedefault (35)
fadedefault
Gently switch to the map's default music track.
fadesound (36)
fadesound iIndex
Gently switch to another music track.
fadeout (37)
fadeout
Gently fade out the currently playing track.
fadein (38)
fadein
Gently fade the currently playing track back in.
warp (39)
warp bBank bMap bExit
checkitem (47)
checkitem iItem
Checks if the player carries at least one instance of the specified item.
Example:
checkitem ITEM_MAXPOTION
compare LASTRESULT YES
if TRUE 0x604020
applymovement (4F)
applymovement iSprite lPointer
Applies the movement data at lPointer to the specified sprite.
Example:
movement 0x5 0x604020
wait 0x0 'wait for movement to complete
movesprite (57)
movesprite iIndex iX iY
TODO: Write this.
faceplayer (5A)
faceplayer
Turns the caller towards the player.
trainerbattle (5C)
trainerbattle bKind iBattle ptrIntro ptrDefeat
Starts a trainer battle.
bKind is 0x00 for normal battles, 0x04 for 2-on-2 and 0x05 for rematches.
You'll need to add an extra parameter, ptrSpecial, for 2-on-2 battles and gym leaders.
2-on-2 battles require ptrSpecial to point to extra dialogue, and gym leaders need it to point to more code.
2-on-2 dialogue should tell the player that he or she needs at least two Pokémon to fight.
Gym leaders should give defeat gifts like badges. Check out your favorite leader in Scripted 1.0.1 to see an example of the gym gift code.
Example:
trainerbattle 0 MYBATTLEINTRO MYBATTLEDEFEAT
message MYBATTLEAFTERWARDS
boxset 4
jingle (69)
jingle
Plays a little sound effect.
lock (6A)
lock
Locks down movement for the caller.
release (6C)
release
Resumes movement for the caller.
multi (6F)
multi bLeft bTop bList bCancel
Puts up a list of choices for the player to make. Available choices depend on the value of bList. bCancel determines wether the player can press the B button to select the last item, if yes the last item should be "Cancel". As always, the player's choice is stored in LASTRESULT.
Example:
message 0x604020 '"What city do you like best?"
choice 2 2 13 0 'items available are littleroot, slateport and lilycove
compare LASTRESULT 1
if 0 0x600030 'goto littleroot handler
if 1 0x600050 'goto slateport handler
'lilycove handler starts right here, no "if LASTRESULT 3" needed.
givepokemon (79)
givepokemon iSpecies bLevel iItem
Gives the player a Pokémon of any given species and level, holding an item if iItem > 0.
pokemart (86)
pokemart ptrItemList
Opens the PokéMart shop system with the item/price list found at ptrItemList.
For more information on price lists, check the big pile of doggie doo.
fadescreen (97)
fadescreen bInOrOut
Fades the screen in or out.
checkgender (A0)
checkgender
Simply puts 1 in in LASTRESULT if the player is a girl or 0 if he's a boy.
setmaptile (A2)
setmaptile iX iY iTileNo iTileAttr
Sets a tile on the map. You must somehow refresh that part, can be done by scrolling out of view and back in or by calling this command from a Level Script.
setweather (A4)
setweather bWeather
Gently changes the weather.
Values tested with results:
00 - Nothing
03 - Rain
04 - Snow, doesn't stay long.
05 - Thunderstorm
06 - Fog
07 - Ash
08 - Sandstorm
09 - Different fog
0A - Light fog
0B - Darkness (here's your nighttime effect!)
0C - Hot sun
0D - Thunderstorm
0E - Underwater
0F - Nothing
doweather (A5)
doweather
Triggers the weather change set with setweather.
Constructs
wildbattle
wildbattle iSpecies iLevel bStyle
Originally a true command, now a construct.
Style can be any of these:
0 normal wild pokémon battle
1 ground legend battle, zigzag wipe
2 grass legend battle, zigzag wipe
3 boxtwirl wiped battle
Example:
wildbattle 0x196 70 3 'fight a level 70 Rayquaza!
giveitem
giveitem iItem iQuantity
Gives the player an item.
This is a construct that converts to two setvarifnotzero commands.
Example:
giveitem ITEM_SODAPOP 1
Hardcore commands
jumpstd (08)
jumpstd bValue
Jumps to a standard function. Kinda like BoxSet, only with slightly different logic, like Basic's GOSUB compared to GOTO.
comparevars (1B)
comparevars iVar iVar
Compares a variable with another variable.
comparevartobyte (1C)
comparevartobyte iVar bVal
Compares a variable with a byte value.
comparevartofarbyte (1D)
comparevartofarbyte iVar lPointer
Compares a variable with a byte at some location.
comparefarbytetovar (1E)
comparefarbytetovar lPointer iVar
Compares a byte at some location with a variable.
comparefarbytetobyte (1F)
comparefarbytetobyte lPointer bVal
Compares a byte at some location with a byte value.
comparefarbytetofarbyte (20)
comparefarbytetofarbyte lPointer lPointer
Compares a byte at some location with another byte at some location.
Predefined variables and constants in STD.RBH
B_YES, B_NO, B_TRUE, B_FALSE, B_BOY and B_GIRL
I like booleans. They're comfy and easy to #define.
B_<<, B_==, B_>>, B_<=, B_>= and B_!=
Like B_TRUE and B_FALSE above, but for experienced coders who want full logical power.
BOXSET_DONTCLOSE, BOXSET_YESNO and BOXSET_NORMAL
The three most common BoxSet parameters.
MENU_PARTY, MENU_POKEDEX and MENU_NAVIGATOR
SetFlag parameters to enable their respective menu items. Can also be cleared to, for example, make Grunts steal your kit.
0x800D - LASTRESULT
Nearly every time something is checked, the answer is stored in this variable.
SPRITEMOVE_INDEX
SPRITEMOVE_NEWXPOS
SPRITEMOVE_NEWYPOS
Combine these three with SetVar to move a sprite to a proper position on the map.
This is used in Littleroot to move Mom to either the left or right hand house door depending on the player's gender.
APPLYMOVE_PLAYER
Because it makes more sense than 0xFF. Use it in ApplyMovement to control the player.
JUMP_BAGISFULL
A predefined label for Ruby to write ye olde standard error message when the player's inventory is completely filled. See goto for an example. Assumes Autobanking is ON.