Add a debug menu
May 2026 Edit: click here for updates to make this compatible again with Pret Pokeemerald
During development it's common for your game to be partially complete; even if it isn't, you probably don't want to spend a whole bunch of time playing through the game to get to the bit you need to test. As such, it's useful to have a debug menu with a collection of tools defined in code to do useful things for you which you don't expose to the players. However, pokeemerald reproduces the commercial release of Pokémon Emerald, so there's no debug functionality at all. Fortunately we're programmers, so we can fix that.
I assume a reasonable familiarity with C, so I won't be explaining things like preprocessor directives, include guards, what a structure or its fields are, or the like. If you want or need to look these things up, you now know what to search for.
There's no reason to expose the debug menu to the players, so it's a good idea to keep it behind a compile flag just like Game Freak did. This is technically optional, since you can just tell people not to hold R when pressing Start or whatever, but it's really easy to do. If you do choose to skip it, be sure when following the remainder of the tutorial to watch out for and ignore any #if DEBUGGING and #endif pairs.
Alter the Makefile like this.
ifeq ($(NODEP),1)
$(C_BUILDDIR)/%.o: c_dep :=
else
$(C_BUILDDIR)/%.o: c_dep = $(shell $(SCANINC) -I include $(C_SUBDIR)/$*.c)
endif
ifeq ($(DINFO),1)
override CFLAGS += -g
endif
+ifeq ($(DDEBUGGING),1)
+override ASFLAGS += --defsym DEBUGGING=1
+override CPPFLAGS += -D DEBUGGING=1
+endif
$(C_BUILDDIR)/%.o : $(C_SUBDIR)/%.c $$(c_dep)
@$(CPP) $(CPPFLAGS) $< -o $(C_BUILDDIR)/$*.i
@$(PREPROC) $(C_BUILDDIR)/$*.i charmap.txt | $(CC1) $(CFLAGS) -o $(C_BUILDDIR)/$*.s
@echo -e ".text\n\t.align\t2, 0\n" >> $(C_BUILDDIR)/$*.s
$(AS) $(ASFLAGS) -o $@ $(C_BUILDDIR)/$*.sFrom now on, when building your ROM hack for yourself, you'll want to run make DDEBUGGING=1 (note the double D!) rather than just make.
For this step we'll be working with the source file field_control_avatar.c and its associated header file field_control_avatar.h. Look in the header file for the definition of FieldInput; for me right now it looks like this.
struct FieldInput
{
bool8 pressedAButton:1;
bool8 checkStandardWildEncounter:1;
bool8 pressedStartButton:1;
bool8 pressedSelectButton:1;
bool8 heldDirection:1;
bool8 heldDirection2:1;
bool8 tookStep:1;
bool8 pressedBButton:1;
bool8 input_field_1_0:1;
bool8 input_field_1_1:1;
bool8 input_field_1_2:1;
bool8 input_field_1_3:1;
bool8 input_field_1_4:1;
bool8 input_field_1_5:1;
bool8 input_field_1_6:1;
bool8 input_field_1_7:1;
u8 dpadDirection;
};The fields whose names begin input_field_1_ are debug input flags; in Game Freak's debug builds these are switched on when the user inputs certain button combinations. I'll be using input_field_1_2 because it's what Game Freak used; it may be renamed in your copy of pokeemerald if you're reading this in the future, but it'll be in the same position in the structure so all you need to do is remember the name.
Switch to the source file and alter the end of the function FieldGetPlayerInput like this.
if (heldKeys & DPAD_UP)
input->dpadDirection = DIR_NORTH;
else if (heldKeys & DPAD_DOWN)
input->dpadDirection = DIR_SOUTH;
else if (heldKeys & DPAD_LEFT)
input->dpadDirection = DIR_WEST;
else if (heldKeys & DPAD_RIGHT)
input->dpadDirection = DIR_EAST;
+#if DEBUGGING
+ if ((heldKeys & R_BUTTON) && input->pressedStartButton)
+ {
+ input->input_field_1_2 = TRUE;
+ input->pressedStartButton = FALSE;
+ }
+#endif
}This defines the button combination to access the debug menu: hold R, press Start. You can change it if you like, but the number of sensible combinations is pretty limited.
Now scroll down and alter the end of the function ProcessPlayerFieldInput like this.
if (input->pressedSelectButton && UseRegisteredKeyItemOnField() == TRUE)
return TRUE;
+#if DEBUGGING
+ if (input->input_field_1_2)
+ {
+ PlaySE(SE_WIN_OPEN);
+ Debug_ShowMainMenu();
+ return TRUE;
+ }
+#endif
return FALSE;
}This is the payoff; if the user has pressed the button combination, we get a sound effect and (eventually) a menu. If you want, you can comment out the line Debug_ShowMainMenu(); and test the code as it is now; the sound effect is the same as when you open the Start menu, but no menu opens. Finally, edit the very top of the file like this.
#include "global.h"
#include "battle_setup.h"
#include "bike.h"
#include "coord_event_weather.h"
#include "daycare.h"
+#include "debug.h"
#include "faraway_island.h"If you search you'll find that there is no debug.h in the pokeemerald codebase; let's change that.
You're done editing Game Freak code; now you get to write some of your own. Before we create the new files, we have to add them to the ld_script.txt, first one around line 102:
src/util.o(.text);
src/daycare.o(.text);
+src/debug.o(.text);
src/egg_hatch.o(.text);
src/battle_interface.o(.text);Second one in ld_script.txt around line 486:
src/util.o(.rodata);
src/daycare.o(.rodata);
+src/debug.o(.rodata);
src/egg_hatch.o(.rodata);
src/battle_gfx_sfx_util.o(.rodata);Now create a header file include/debug.h and populate it as follows.
#ifndef GUARD_DEBUG_H
#define GUARD_DEBUG_H
#if DEBUGGING
void Debug_ShowMainMenu(void);
#endif
#endif // GUARD_DEBUG_HNow create a source file src/debug.c and populate it as follows.
#if DEBUGGING
#include "global.h"
#include "list_menu.h"
#include "main.h"
#include "map_name_popup.h"
#include "menu.h"
#include "script.h"
#include "sound.h"
#include "strings.h"
#include "task.h"
#include "constants/songs.h"
#define DEBUG_MAIN_MENU_HEIGHT 7
#define DEBUG_MAIN_MENU_WIDTH 11
void Debug_ShowMainMenu(void);
static void Debug_DestroyMainMenu(u8);
static void DebugAction_Cancel(u8);
static void DebugTask_HandleMainMenuInput(u8);
enum {
DEBUG_MENU_ITEM_CANCEL,
};
static const u8 gDebugText_Cancel[] = _("Cancel");
static const struct ListMenuItem sDebugMenuItems[] =
{
[DEBUG_MENU_ITEM_CANCEL] = {gDebugText_Cancel, DEBUG_MENU_ITEM_CANCEL}
};
static void (*const sDebugMenuActions[])(u8) =
{
[DEBUG_MENU_ITEM_CANCEL] = DebugAction_Cancel
};
static const struct WindowTemplate sDebugMenuWindowTemplate =
{
.bg = 0,
.tilemapLeft = 1,
.tilemapTop = 1,
.width = DEBUG_MAIN_MENU_WIDTH,
.height = 2 * DEBUG_MAIN_MENU_HEIGHT,
.paletteNum = 15,
.baseBlock = 1,
};
static const struct ListMenuTemplate sDebugMenuListTemplate =
{
.items = sDebugMenuItems,
.moveCursorFunc = ListMenuDefaultCursorMoveFunc,
.totalItems = ARRAY_COUNT(sDebugMenuItems),
.maxShowed = DEBUG_MAIN_MENU_HEIGHT,
.windowId = 0,
.header_X = 0,
.item_X = 8,
.cursor_X = 0,
.upText_Y = 1,
.cursorPal = 2,
.fillValue = 1,
.cursorShadowPal = 3,
.lettersSpacing = 1,
.itemVerticalPadding = 0,
.scrollMultiple = LIST_NO_MULTIPLE_SCROLL,
.fontId = 1,
.cursorKind = 0
};
void Debug_ShowMainMenu(void) {
struct ListMenuTemplate menuTemplate;
u8 windowId;
u8 menuTaskId;
u8 inputTaskId;
// create window
HideMapNamePopUpWindow();
LoadMessageBoxAndBorderGfx();
windowId = AddWindow(&sDebugMenuWindowTemplate);
DrawStdWindowFrame(windowId, FALSE);
// create list menu
menuTemplate = sDebugMenuListTemplate;
menuTemplate.windowId = windowId;
menuTaskId = ListMenuInit(&menuTemplate, 0, 0);
// draw everything
CopyWindowToVram(windowId, 3);
// create input handler task
inputTaskId = CreateTask(DebugTask_HandleMainMenuInput, 3);
gTasks[inputTaskId].data[0] = menuTaskId;
gTasks[inputTaskId].data[1] = windowId;
}
static void Debug_DestroyMainMenu(u8 taskId)
{
DestroyListMenuTask(gTasks[taskId].data[0], NULL, NULL);
ClearStdWindowAndFrame(gTasks[taskId].data[1], TRUE);
RemoveWindow(gTasks[taskId].data[1]);
DestroyTask(taskId);
EnableBothScriptContexts();
}
static void DebugTask_HandleMainMenuInput(u8 taskId)
{
void (*func)(u8);
u32 input = ListMenu_ProcessInput(gTasks[taskId].data[0]);
if (gMain.newKeys & A_BUTTON)
{
PlaySE(SE_SELECT);
if ((func = sDebugMenuActions[input]) != NULL)
func(taskId);
}
else if (gMain.newKeys & B_BUTTON)
{
PlaySE(SE_SELECT);
Debug_DestroyMainMenu(taskId);
}
}
static void DebugAction_Cancel(u8 taskId)
{
Debug_DestroyMainMenu(taskId);
}
#endifThat's a lot of code; let's go over it bit by bit.
static const u8 gDebugText_Cancel[] = _("Cancel");
enum {
DEBUG_MENU_ITEM_CANCEL,
};
static const struct ListMenuItem sDebugMenuItems[] =
{
[DEBUG_MENU_ITEM_CANCEL] = {gDebugText_Cancel, DEBUG_MENU_ITEM_CANCEL},
};
static void (*const sDebugMenuActions[])(u8) =
{
[DEBUG_MENU_ITEM_CANCEL] = DebugAction_Cancel,
};These define the list itself. sDebugMenuItems ties together the name and an ID number given by an enumeration, while sDebugMenuActions is a list of functions which are executed when the user presses A on that list item. It's important that the enumeration and arrays stay in the same order and have the same length, otherwise strange things will start happening. To add a new entry, follow this example.
static const u8 gDebugText_NewEntry[] = _("New Entry");
static const u8 gDebugText_Cancel[] = _("Cancel");
enum {
DEBUG_MENU_ITEM_NEW_ENTRY,
DEBUG_MENU_ITEM_CANCEL,
};
static const struct ListMenuItem sDebugMenuItems[] =
{
[DEBUG_MENU_ITEM_NEW_ENTRY] = {gDebugText_NewEntry, DEBUG_MENU_ITEM_NEW_ENTRY},
[DEBUG_MENU_ITEM_CANCEL] = {gDebugText_Cancel, DEBUG_MENU_ITEM_CANCEL},
};
static void (*const sDebugMenuActions[])(u8) =
{
[DEBUG_MENU_ITEM_NEW_ENTRY] = DebugAction_NewEntry,
[DEBUG_MENU_ITEM_CANCEL] = DebugAction_Cancel,
};Make sure to create the function DebugAction_NewEntry; its signature is static void DebugAction_NewEntry(u8 taskId). If you want the menu item to do nothing when the user presses A, use NULL instead of writing a function that does nothing.
static const struct WindowTemplate sDebugMenuWindowTemplate =
{
.bg = 0,
.tilemapLeft = 1,
.tilemapTop = 1,
.width = DEBUG_MAIN_MENU_WIDTH,
.height = 2 * DEBUG_MAIN_MENU_HEIGHT,
.paletteNum = 15,
.baseBlock = 1,
};This is a window template. A window is a box fringed by the border you chose in the options (the default is purple), and a window template determines the properties of that window. Most of these fields should be left alone, but the ones to know about are tilemapLeft and tilemapTop (the window's position relative to the left and top of the screen in tiles); width and height (unsurprisingly, the window's width and height in tiles) and baseBlock. baseBlock is used by the engine for placing the tiles for each window; since we know there are no other windows when the debug menu is opened its baseBlock is 1, but if you create a second window, its baseBlock needs to be at least equal to the product of the width and height fields of this one to avoid corruption.
static const struct ListMenuTemplate sDebugMenuListTemplate =
{
.items = sDebugMenuItems,
.moveCursorFunc = ListMenuDefaultCursorMoveFunc,
.totalItems = ARRAY_COUNT(sDebugMenuItems),
.maxShowed = DEBUG_MAIN_MENU_HEIGHT,
.windowId = 0,
.header_X = 0,
.item_X = 8,
.cursor_X = 0,
.upText_Y = 1,
.cursorPal = 2,
.fillValue = 1,
.cursorShadowPal = 3,
.lettersSpacing = 1,
.itemVerticalPadding = 0,
.scrollMultiple = LIST_NO_MULTIPLE_SCROLL,
.fontId = 1,
.cursorKind = 0
};This is a list menu template. A list menu is a sequence of items where the user scrolls up and down through the items and can pick one by pressing A; in much the same way that a window template determines the properties of a window, a list menu template determines the properties of a list menu. Most of these options look to me like sensible defaults; totalItems is the number of items on the list in total; maxShowed is the number of items you can see at any one time; scrollMultiple controls whether the user can scroll past multiple entries in the list at once, and how they do it (there are three possible values: LIST_NO_MULTIPLE_SCROLL for no fast-scrolling, LIST_MULTIPLE_SCROLL_DPAD for fast-scrolling by pressing left and right on the D-pad, and LIST_MULTIPLE_SCROLL_L_R for fast-scrolling by pressing the L and R buttons).
void Debug_ShowMainMenu(void) {
struct ListMenuTemplate menuTemplate;
u8 windowId;
u8 menuTaskId;
u8 inputTaskId;
// create window
HideMapNamePopUpWindow();
LoadMessageBoxAndBorderGfx();
windowId = AddWindow(&sDebugMenuWindowTemplate);
DrawStdWindowFrame(windowId, FALSE);
// create list menu
menuTemplate = sDebugMenuListTemplate;
menuTemplate.windowId = windowId;
menuTaskId = ListMenuInit(&menuTemplate, 0, 0);
// draw everything
CopyWindowToVram(windowId, 3);
// create input handler task
inputTaskId = CreateTask(DebugTask_HandleMainMenuInput, 3);
gTasks[inputTaskId].data[0] = menuTaskId;
gTasks[inputTaskId].data[1] = windowId;
}This is the function that gets called in field_control_avatar.c. It first creates both a window and a list menu, which we've already discussed, and then creates a task to handle user input. A task is just a function which is invoked each frame. The task for this menu is the function DebugTask_HandleMainMenuInput, which checks for user input and delegates to the functions specified in sDebugMenuActions.
You should now be able to compile and run your game and open and close the debug menu. At this point my work is done; it's up to you now to decide what functionality to provide in your debug menu.
This guide is thanks to Ketsuban
This is my implementation of a debug menu based on this (Ketsuban's) tutorial and some code from Pyredrid, AsparagusEduardo and Ghoulslash.
Utility
Heal player party
Clock: check and set
Fly to all cities: ----------------------------Warp to any map warp: --------------Check saveblock space:
Check weekday: does nothing, left in as a simple spot to add some test stuff for you guys
Flags:
Added some usefull debug flags like ignore collision, no wild encounters (Immortal) and no trainers attacking you.
Toggle any flag ingame: -------------Toggle specific usefull flags
Vars:
Read and change any vars ingame:
Give:
Items:
Pokemon in 2 versions:
---Simple: only takes the ID (source code, not ingame) and a level:
---Complex: ID, level, shiny?, nature and 1 value for all IVs:
Add and clone it into your repo:
git remote add xaman https://github.com/TheXaman/pokeemerald/
git pull xaman tx_debug_system
make clean
make debuggingor check out the commits of the repo yourself LINK.
Access ingame: From now one if you want the menu to show up you have to run your "make" command with the addition parameter: debugging or debugging_modern, for example make debugging -j8. Those parameters already include DINFO=1. To access ingame press R + Start.
That it, now enjoy and if you find any bugs or if you write some cool additions you think others could profit from, please let me know.
Credits: If you use this, you have to give credit to all following people!
TheXaman
Ketsuban
Pyredrid
AsparagusEduardo
Ghoulslash
exposneed
(I'd suggest still pulling from TheXaman's tx_debug_system first and then making these changes)
git remote add xaman https://github.com/TheXaman/pokeemerald/
git pull xaman tx_debug_system
-
gflib/string_util.cis nowsrc/string_util.c -
gflib/string_util.his nowinclude/string_util.h
ld_script.txt should be ld_script.ld
-- you may be asked to "commit or stash changes" when pulling this even if you haven't edited this file.
-- if your file is unedited, replace with
tx_debug_systemversion
-- or manually add this to your file so they are in alphabetical order:
(around lines 112 and 113)
src/debug.o(.text);
src/debug_pokemon_creator.o(.text);
(around lines 500 and 501)
src/debug.o(.rodata);
src/debug_pokemon_creator.o(.rodata);
change line 446
u8 SendMonToPC(struct Pokemon* mon);
to
u8 CopyMonToPC(struct Pokemon* mon);
in section static void CB2_InitBattleInternal(void)
(around line 673)
change
#if TX_DEBUG_SYSTEM_ENABLE == FALSE
gBattleTerrain = BattleSetup_GetTerrainId();
#else
if (!gIsDebugBattle)
gBattleTerrain = BattleSetup_GetTerrainId();
#endif
to
#if TX_DEBUG_SYSTEM_ENABLE == FALSE
gBattleEnvironment = BattleSetup_GetEnvironmentId();
#else
if (!gIsDebugBattle)
gBattleEnvironment = BattleSetup_GetEnvironmentId();
#endif
in section void DoStandardWildBattle_Debug(void)
(around line 456)
change
if (InBattlePyramid())
{
VarSet(VAR_TEMP_E, 0);
gBattleTypeFlags |= BATTLE_TYPE_PYRAMID;
to
if (CurrentBattlePyramidLocation() != PYRAMID_LOCATION_NONE)
{
VarSet(VAR_TEMP_PLAYING_PYRAMID_MUSIC, 0);
gBattleTypeFlags |= BATTLE_TYPE_PYRAMID;
in section static void DebugAction_Give_Pokemon_ComplexCreateMon(u8 taskId)
(around line 3562)
change
if (i >= PARTY_SIZE)
sentToPc = SendMonToPC(&mon);
else
to
if (i >= PARTY_SIZE)
sentToPc = CopyMonToPC(&mon);
else
in section static const struct EditPokemonStruct DebugPkmCreator_Options[]
(around line 348)
change
[VAL_RIBBON_FATEFUL] = {Str_Fateful, EDIT_BOOL, 0, 1, 0, MON_DATA_EVENT_LEGAL, 1},
to
[VAL_RIBBON_FATEFUL] = {Str_Fateful, EDIT_BOOL, 0, 1, 0, MON_DATA_MODERN_FATEFUL_ENCOUNTER, 1},
in section static void DebugPkmCreator_Init_SetNewMonData(bool8 setMoves)
in case VAL_ABILITY:
(around line 658)
change
if (gBaseStats[sDebugPkmCreatorData.data[0]].abilities[1])
to
if (gSpeciesInfo[sDebugPkmCreatorData.data[0]].abilities[1])
in section static void DebugPkmCreator_EditModeRedraw(u32 digit, u8 editIndex)
in case: VAL_LEVEL:
(around line 1314)
change
//u32 newExp = gExperienceTables[gBaseStats[sDebugPkmCreatorData.data[VAL_SPECIES]].growthRate][DebugPkmCreator_editingVal[editIndex]];
to
//u32 newExp = gExperienceTables[gSpeciesInfo[sDebugPkmCreatorData.data[VAL_SPECIES]].growthRate][DebugPkmCreator_editingVal[editIndex]];
in section static void DebugPkmCreator_EditModeProcessInput(u8 taskid)
in case: VAL_SPECIES:
(around line 1809)
change
SetMonData(&sDebugPkmCreatorData.mon, MON_DATA_EXP, &gExperienceTables[gBaseStats[DebugPkmCreator_editingVal[i]].growthRate][sDebugPkmCreatorData.data[15]]);
to
SetMonData(&sDebugPkmCreatorData.mon, MON_DATA_EXP, &gExperienceTables[gSpeciesInfo[DebugPkmCreator_editingVal[i]].growthRate][sDebugPkmCreatorData.data[15]]);
a few lines down in the same section
in case VAL_LEVEL:
(around line 1820)
change
SetMonData(&sDebugPkmCreatorData.mon, MON_DATA_EXP, &gExperienceTables[gBaseStats[sDebugPkmCreatorData.data[VAL_SPECIES]].growthRate][sDebugPkmCreatorData.data[VAL_LEVEL]]);
to
SetMonData(&sDebugPkmCreatorData.mon, MON_DATA_EXP, &gExperienceTables[gSpeciesInfo[sDebugPkmCreatorData.data[VAL_SPECIES]].growthRate][sDebugPkmCreatorData.data[VAL_LEVEL]]);
in section static u8 DebugPkmCreator_GiveToPlayer(void)
(around line 2044)
change
return SendMonToPC(mon);
to
return CopyMonToPC(mon);
-- important note: if
CopyMonToPChas already been changed toSendMonToPC, change it back toCopyMonToPC.
in the headers section
-- there is no line
static u8 SendMonToPC(struct Pokemon *mon);anymore so ignore this change
(around line 73)
change
static u8 CopyMonToPC(struct Pokemon *mon);
to
u8 CopyMonToPC(struct Pokemon *mon);
around line 4433
-- there is no line
static u8 SendMonToPC(struct Pokemon *mon)anymore so ignore this change
change
static u8 CopyMonToPC(struct Pokemon *mon)
to
u8 CopyMonToPC(struct Pokemon *mon)
in section string generate_map_constants_text(string groups_filepath, Json groups_data) {
(around line 522)
replace the entire section with:
string file_dir = file_parent(groups_filepath) + sep;
string guard_name = "CONSTANTS_MAP_GROUPS";
ostringstream text;
text << get_include_guard_start(guard_name) << get_generated_warning("data/maps/map_groups.json", false);
text << "enum\n{\n";
int group_num = 0;
vector<int> map_count_vec; //DEBUG
for (auto &group : groups_data["group_order"].array_items()) {
vector<string> map_ids;
string groupName = json_to_string(group);
text << " // " << groupName << "\n";
size_t max_length = 0; //DEBUG
int map_count = 0; //DEBUG
for (auto &map_name : groups_data[groupName].array_items()) {
string map_filepath = file_dir + json_to_string(map_name) + sep + "map.json";
string err_str;
Json map_data = Json::parse(read_text_file(map_filepath), err_str);
if (map_data == Json())
FATAL_ERROR("%s: %s\n", map_filepath.c_str(), err_str.c_str());
string id = json_to_string(map_data, "id", true);
map_ids.push_back(id);
if (id.length() > max_length)
max_length = id.length();
map_count++; //DEBUG
}
int map_id_num = 0;
for (string map_id : map_ids) {
text << " " << map_id << string(max_length - map_id.length(), ' ')
<< " = (" << map_id_num++ << " | (" << group_num << " << 8)),\n";
}
text << "\n";
group_num++;
map_count_vec.push_back(map_count); //DEBUG
}
text << "};\n\n";
text << "#define MAP_GROUPS_COUNT " << group_num << "\n\n";
text << "// static const u8 MAP_GROUP_COUNT[] = {"; //DEBUG
for(int i=0; i<group_num; i++){ //DEBUG
text << map_count_vec[i] << ", "; //DEBUG
} //DEBUG
text << "0};\n\n"; //DEBUG
text << "#endif // GUARD_CONSTANTS_MAP_GROUPS_H\n";
return text.str();
}