Document box user input handling #533

CharlesFolz4 · 2025-05-29T03:38:17Z

Initial box user input handling documentation

Document UnkEnum_021DFB94 as BoxMenuItem
Document ov19_021DF964 as box_menu
Document release mon state machine

lhearachel

This mostly looks good, just some little quibbles for polish and consistency.

lhearachel · 2025-06-01T03:12:15Z

include/overlay019/struct_box_menu.h

+    BOX_MENU_HEART,
+    BOX_MENU_STAR,
+    BOX_MENU_DIAMOND
+} BoxMenuItem;


note: We don't typedef enum in this project.

lhearachel · 2025-06-01T03:12:35Z

include/overlay019/struct_box_menu.h

+
+#define MAX_MENU_ITEMS 8
+
+typedef struct {


note: Tag the struct with the same name as its typedef.

lhearachel · 2025-06-01T03:12:59Z

include/overlay019/struct_ov19_021D4EE4.h

    u8 unk_02[2];
    BOOL compareButtonAnimationPressed;
    PCCompareMon compareMons[2];
-} UnkStruct_ov19_021D4EE4;
+} UnkStruct_ov19_021D4EE4; // BoxCompareMode


note: Feel free to name the struct if it feels apt.

lhearachel · 2025-06-01T03:13:14Z

include/struct_defs/struct_02042434.h

@@ -8,7 +8,7 @@
 typedef struct {
    SaveData *saveData;
    enum BoxMode boxMode;
-    BOOL unk_08;
+    BOOL RecordBoxUseInJournal;


polish: camelCase

src/overlay019/ov19_021D61B0.c

lhearachel · 2025-06-01T03:18:47Z

src/overlay019/box_menu.c

+
+void BoxMenu_FillYesNo(UnkStruct_ov19_021D4DF0 *param0, u32 menuItemIndex)
+{
+    BoxMenu *menu = &(param0->boxMenu);


polish: Unnecessary parens.

lhearachel · 2025-06-01T03:18:59Z

src/overlay019/box_menu.c

+
+        BoxMenu_AddMenuItem(menu, BOX_MENU_SUMMARY);
+
+        {


polish: Unnecessary scope block.

lhearachel · 2025-06-01T03:20:35Z

src/overlay019/box_menu.c

+    static const u16 v0[][4] = {
+        { BOX_MENU_FOREST, BOX_MENU_CITY, BOX_MENU_DESERT, BOX_MENU_SAVANNA },
+        { BOX_MENU_CRAG, BOX_MENU_VOLCANO, BOX_MENU_SNOW, BOX_MENU_CAVE },
+        { BOX_MENU_BEACH, BOX_MENU_SEAFLOOR, BOX_MENU_RIVER, BOX_MENU_SKY },
+        { BOX_MENU_POKECENTER, BOX_MENU_MACHINE, BOX_MENU_CHECKS, BOX_MENU_SIMPLE },
+    };


suggestion:

Suggested change

static const u16 v0[][4] = {

{ BOX_MENU_FOREST, BOX_MENU_CITY, BOX_MENU_DESERT, BOX_MENU_SAVANNA },

{ BOX_MENU_CRAG, BOX_MENU_VOLCANO, BOX_MENU_SNOW, BOX_MENU_CAVE },

{ BOX_MENU_BEACH, BOX_MENU_SEAFLOOR, BOX_MENU_RIVER, BOX_MENU_SKY },

{ BOX_MENU_POKECENTER, BOX_MENU_MACHINE, BOX_MENU_CHECKS, BOX_MENU_SIMPLE },

};

static const u16 sWallpaperPages[][4] = {

{ BOX_MENU_FOREST, BOX_MENU_CITY, BOX_MENU_DESERT, BOX_MENU_SAVANNA },

{ BOX_MENU_CRAG, BOX_MENU_VOLCANO, BOX_MENU_SNOW, BOX_MENU_CAVE },

{ BOX_MENU_BEACH, BOX_MENU_SEAFLOOR, BOX_MENU_RIVER, BOX_MENU_SKY },

{ BOX_MENU_POKECENTER, BOX_MENU_MACHINE, BOX_MENU_CHECKS, BOX_MENU_SIMPLE },

};

I also see a few raw 4s here that seem to be related to the number of items on a given page, so I think that's worth a shared constant.

lhearachel

Some additional preliminary feedback.

include/overlay019/struct_box_menu.h

lhearachel · 2025-06-07T00:37:38Z

include/overlay019/struct_box_menu.h

@@ -0,0 +1,91 @@
+#ifndef POKEPLATINUM_STRUCT_OV19_021DF964_H


polish: Update include guards on documented files.

lhearachel · 2025-06-07T00:38:41Z

include/overlay019/ov19_021D61B0.h

-void ov19_021D6594(UnkStruct_ov19_021D61B0 *param0, u32 param1);
-BOOL ov19_021D6600(UnkStruct_ov19_021D61B0 *param0, u32 param1);
-BOOL ov19_021D6628(UnkStruct_ov19_021D61B0 *param0);
+enum BoxFunctions {


question: Do all of these relate to graphics?

I also wouldn't mind these just being the function name prefixed with a tight abbreviation like FN.

I haven't confirmed in-depth every one of these functions, but I think it's safe to say that yes, these are probably all going to be box graphics functions.

lhearachel · 2025-06-07T00:41:38Z

src/overlay019/ov19_021D0D80.c

+    void (*boxApplicationAction)(struct UnkStruct_ov19_021D5DF8_t *param0, u32 *param1);
+    u32 cursorLocationHandlerState;
+    u32 boxApplicationActionState;
+    enum BoxMenuItem menuItem; // This stops being a BoxMenuItem in ov19_ReleaseMon, where it does something completely different and unrelated


suggestion: Given the comment here, maybe it's best to use an anonymous union for this field.

union { enum BoxMenuItem menuItem; int unk_1B8; };

Then, you can replace the uses in ov19_ReleaseMon, which makes it apparent that the usage is unknown.

lhearachel · 2025-06-07T00:45:22Z

src/overlay019/ov19_021D61B0.c

        u32 unk_04;
-    } v0[] = {
+    } functions[] = {


suggestion:

Pull this static table into module-level scope and prefix the name with s (e.g., sBoxTaskHandlers).

Use array-initializers so that the association with the parent enum is clear at-a-glance.

CharlesFolz4 · 2025-06-15T22:08:42Z

Declaring this ready for review now. I have cut out the non-trivial compare mode user input handling and touch screen user input handling, because properly documenting those would have involved more scope creep than I was prepared to deal with in the current PR.

lhearachel

LGTM; one polish-comment below. 😁

src/overlay019/ov19_021D61B0.c

Rename bopx actions to have -Action suffix to avoid duplicate function names

Reorganize state machine enums

CharlesFolz4 force-pushed the BoxUserInput branch from 8504d9b to a9c14f9 Compare May 31, 2025 01:10

lhearachel reviewed Jun 1, 2025

View reviewed changes

lhearachel self-assigned this Jun 1, 2025

CharlesFolz4 force-pushed the BoxUserInput branch from a9c14f9 to f97880a Compare June 3, 2025 13:27

lhearachel reviewed Jun 7, 2025

View reviewed changes

CharlesFolz4 force-pushed the BoxUserInput branch 2 times, most recently from c5157d8 to 567d82c Compare June 11, 2025 03:49

CharlesFolz4 marked this pull request as ready for review June 15, 2025 22:08

CharlesFolz4 changed the title ~~WIP document box user input handling~~ Document box user input handling Jun 15, 2025

lhearachel reviewed Jun 22, 2025

View reviewed changes

src/overlay019/ov19_021D61B0.c Outdated Show resolved Hide resolved

narf0708 and others added 19 commits June 22, 2025 16:44

Initial box user input handling documentation

de80fea

identify box heaps

bb99fe4

Document summary menu handling

d498208

Document mon markings menu state machine

91df980

Document wallpaper menu state machine

d41ad6d

Document box selection popup state machine

1e37e68

Document store mon state machine

6611dba

code cleanup

a20a448

Document box action function pointers, box jump state machine

d2ef5ce

Document Rename Box state machine

4f56d4b

Document pick up mon state machine,

3f63717

Rename bopx actions to have -Action suffix to avoid duplicate function names

Document withdraw mon state machine

0e94ad2

Document shift mon state machine

1a9157c

Document Place mon state machine

32e7ed6

Document Item menu action state machines

42bd885

Document multi-select state machine

1eba38d

Document mon cursor menu state machine,

379d3e4

Reorganize state machine enums

document box header menu state machine

f10f8ee

Document Continue Box Operations and Put Away Item state machines

7e25800

CharlesFolz4 added 6 commits June 22, 2025 16:47

Document box changing state machine

32d4f72

Document mon item menu and item info state machines

e83b9d9

Document close box state machines

6938a2f

Document cursor state machines

ed1617d

Remove comments, minor consistency edits

a4a52c0

struct name for BoxTaskParams

abba461

CharlesFolz4 force-pushed the BoxUserInput branch from 5d22645 to abba461 Compare June 22, 2025 20:50

lhearachel approved these changes Jun 22, 2025

View reviewed changes

lhearachel merged commit 8bbd22e into pret:main Jun 22, 2025
2 checks passed

github-actions bot pushed a commit that referenced this pull request Jun 22, 2025

Document box user input handling (#533)

3272d43

CharlesFolz4 deleted the BoxUserInput branch June 22, 2025 21:07

Document box user input handling #533

Document box user input handling #533

Uh oh!

Conversation

CharlesFolz4 commented May 29, 2025

Uh oh!

lhearachel left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lhearachel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

CharlesFolz4 commented Jun 15, 2025

Uh oh!

lhearachel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!