Document Apprentice

4 files changed, 44 insertions, 30 deletions

diff --git a/include/apprentice.h b/include/apprentice.h
index 44329b677..27ce0371e 100644
--- a/include/apprentice.h
+++ b/include/apprentice.h
@@ -5,7 +5,7 @@
 
 struct ApprenticeTrainer
 {
-    u8 name[6][PLAYER_NAME_LENGTH + 1]; // For all six languages.
+    u8 name[NUM_LANGUAGES - 1][PLAYER_NAME_LENGTH + 1]; // For all languages except the unused one.
     u16 otId;
     u8 facilityClass;
     u16 species[APPRENTICE_SPECIES_COUNT];
@@ -15,7 +15,7 @@ struct ApprenticeTrainer
 
 extern const struct ApprenticeTrainer gApprentices[];
 
-void CopyFriendsApprenticeChallengeText(u8 saveblockApprenticeId);
+void BufferApprenticeChallengeText(u8 saveApprenticeId);
 void Apprentice_EnableBothScriptContexts(void);
 void ResetApprenticeStruct(struct Apprentice *apprentice);
 void ResetAllApprenticeData(void);
diff --git a/include/constants/apprentice.h b/include/constants/apprentice.h
index 87b7b12f5..ec35a2361 100644
--- a/include/constants/apprentice.h
+++ b/include/constants/apprentice.h
@@ -1,8 +1,11 @@
 #ifndef GUARD_CONSTANTS_APPRENTICE_H
 #define GUARD_CONSTANTS_APPRENTICE_H
 
-#define APPRENTICE_SPECIES_COUNT 10
 #define NUM_APPRENTICES 16
+#define APPRENTICE_SPECIES_COUNT 10
+
+#define NUM_WHICH_MON_QUESTIONS  MULTI_PARTY_SIZE
+#define NUM_WHICH_MOVE_QUESTIONS 5
 
 #define APPRENTICE_LVL_MODE_50    (FRONTIER_LVL_50 + 1)
 #define APPRENTICE_LVL_MODE_OPEN  (FRONTIER_LVL_OPEN + 1)
@@ -10,10 +13,10 @@
 #define APPRENTICE_FUNC_GAVE_LVLMODE 0
 #define APPRENTICE_FUNC_SET_LVLMODE 1
 #define APPRENTICE_FUNC_SET_ID 2
-#define APPRENTICE_FUNC_3 3
-#define APPRENTICE_FUNC_4 4
+#define APPRENTICE_FUNC_SHUFFLE_SPECIES 3
+#define APPRENTICE_FUNC_RANDOMIZE_QUESTIONS 4
 #define APPRENTICE_FUNC_ANSWERED_QUESTION 5
-#define APPRENTICE_FUNC_6 6
+#define APPRENTICE_FUNC_IS_FINAL_QUESTION 6
 #define APPRENTICE_FUNC_MENU 7
 #define APPRENTICE_FUNC_PRINT_MSG 8
 #define APPRENTICE_FUNC_RESET 9
@@ -25,14 +28,14 @@
 #define APPRENTICE_FUNC_FREE_QUESTION_DATA 15
 #define APPRENTICE_FUNC_BUFFER_STRING 16
 #define APPRENTICE_FUNC_SET_MOVE 17
-#define APPRENTICE_FUNC_SET_FIRST_MON 18
+#define APPRENTICE_FUNC_SET_LEAD_MON 18
 #define APPRENTICE_FUNC_OPEN_BAG 19
-#define APPRENTICE_FUNC_20 20
-#define APPRENTICE_FUNC_21 21
+#define APPRENTICE_FUNC_TRY_SET_HELD_ITEM 20
+#define APPRENTICE_FUNC_SAVE 21
 #define APPRENTICE_FUNC_SET_GFX_SAVED 22
 #define APPRENTICE_FUNC_SET_GFX 23
 #define APPRENTICE_FUNC_SHOULD_LEAVE 24
-#define APPRENTICE_FUNC_25 25
+#define APPRENTICE_FUNC_SHIFT_SAVED 25
 
 #define APPRENTICE_MSG_PLEASE_TEACH            0
 #define APPRENTICE_MSG_REJECT           1
@@ -58,6 +61,15 @@
 #define APPRENTICE_QUESTION_WHAT_ITEM      4
 #define APPRENTICE_QUESTION_WIN_SPEECH     5
 
+// Would be redundant with the above if they used the same values
+//   but they do this to skip the "which mon" questions and store the below id in a 2 bit field
+// These IDs are randomly shuffled in an array to determine the order of questions asked by the Apprentice
+// The last question asked is always picking their win speech
+#define QUESTION_ID_WIN_SPEECH    0
+#define QUESTION_ID_WHAT_ITEM     1
+#define QUESTION_ID_WHICH_MOVE    2
+#define QUESTION_ID_WHICH_FIRST   3
+
 #define APPRENTICE_ASK_WHICH_LEVEL 0
 #define APPRENTICE_ASK_3SPECIES 1
 #define APPRENTICE_ASK_2SPECIES 2
@@ -74,6 +86,6 @@
 #define APPRENTICE_BUFF_NAME 6
 #define APPRENTICE_BUFF_WIN_SPEECH 7
 #define APPRENTICE_BUFF_LEVEL 8
-#define APPRENTICE_BUFF_FIRST_MON_SPECIES 9
+#define APPRENTICE_BUFF_LEAD_MON_SPECIES 9
 
 #endif // GUARD_CONSTANTS_APPRENTICE_H
diff --git a/include/constants/global.h b/include/constants/global.h
index c5dc86a12..3ee7650a8 100644
--- a/include/constants/global.h
+++ b/include/constants/global.h
@@ -18,12 +18,13 @@
 #define VERSION_GAMECUBE 15
 
 #define LANGUAGE_JAPANESE 1
-#define LANGUAGE_ENGLISH 2
-#define LANGUAGE_FRENCH 3
-#define LANGUAGE_ITALIAN 4
-#define LANGUAGE_GERMAN 5
-#define LANGUAGE_KOREAN 6 // 6 goes unused but the theory is it was meant to be Korean
-#define LANGUAGE_SPANISH 7
+#define LANGUAGE_ENGLISH  2
+#define LANGUAGE_FRENCH   3
+#define LANGUAGE_ITALIAN  4
+#define LANGUAGE_GERMAN   5
+#define LANGUAGE_KOREAN   6 // 6 goes unused but the theory is it was meant to be Korean
+#define LANGUAGE_SPANISH  7
+#define NUM_LANGUAGES     7
 
 #define GAME_VERSION (VERSION_EMERALD)
 #define GAME_LANGUAGE (LANGUAGE_ENGLISH)
@@ -49,6 +50,7 @@
 #define DECOR_MAX_SECRET_BASE 16
 #define DECOR_MAX_PLAYERS_HOUSE 12
 #define APPRENTICE_COUNT 4
+#define APPRENTICE_MAX_QUESTIONS 9
 
 #define PYRAMID_BAG_ITEMS_COUNT 10
 #define HALL_FACILITIES_COUNT 9 // 7 facilities for single mode + tower double mode + tower multi mode.
diff --git a/include/global.h b/include/global.h
index c00d71d8f..75a63cdb2 100644
--- a/include/global.h
+++ b/include/global.h
@@ -220,7 +220,7 @@ struct Apprentice
 {
     u8 id:5;
     u8 lvlMode:2; // + 1
-    u8 field_1;
+    u8 numQuestions;
     u8 number;
     struct ApprenticeMon party[MULTI_PARTY_SIZE];
     u16 speechWon[EASY_CHAT_BATTLE_WORDS_COUNT];
@@ -403,13 +403,13 @@ struct BattleFrontier
     /*0xEFC*/ struct FrontierMonData field_EFC[3];
 };
 
-struct Sav2_B8
+struct ApprenticeQuestion
 {
-    u8 unk0_0:2;
-    u8 unk0_1:2;
-    u8 unk0_2:2;
-    u8 unk0_3:2;
-    u16 unk2;
+    u8 questionId:2;
+    u8 monId:2;
+    u8 moveSlot:2;
+    u8 suggestedChange:2; // TRUE if told to use held item or second move, FALSE if told to use no item or first move
+    u16 data; // used both as an itemId and a moveId
 };
 
 struct PlayersApprentice
@@ -417,12 +417,12 @@ struct PlayersApprentice
     /*0xB0*/ u8 id;
     /*0xB1*/ u8 lvlMode:2;  //0: Unassigned, 1: Lv 50, 2: Open Lv
     /*0xB1*/ u8 questionsAnswered:4;
-    /*0xB1*/ u8 firstMonId:2;
-    /*0xB2*/ u8 field_B2_0:3;
-    /*0xB2*/ u8 field_B2_1:2;
-    /*0xB3*/ u8 field_B3;
-    /*0xB4*/ u8 monIds[MULTI_PARTY_SIZE];
-    /*0xB8*/ struct Sav2_B8 field_B8[9];
+    /*0xB1*/ u8 leadMonId:2;
+    /*0xB2*/ u8 party:3;
+    /*0xB2*/ u8 field_B2_1:2; 
+    /*0xB3*/ u8 unused;
+    /*0xB4*/ u8 speciesIds[MULTI_PARTY_SIZE];
+    /*0xB8*/ struct ApprenticeQuestion questions[APPRENTICE_MAX_QUESTIONS];
 };
 
 struct RankingHall1P