From 9c63e5994b33fa2ba9455bc9fd44a34dbdd3e3bf Mon Sep 17 00:00:00 2001
From: Clownacy <Clownacy@users.noreply.github.com>
Date: Thu, 3 Sep 2020 21:52:05 +0100
Subject: [PATCH] Document SelStage.cpp a little

---
 src/ArmsItem.h   |  2 +-
 src/SelStage.cpp | 19 +++++++++++--------
 src/SelStage.h   |  4 +++-
 3 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/src/ArmsItem.h b/src/ArmsItem.h
index 9656a681..f21144e1 100644
--- a/src/ArmsItem.h
+++ b/src/ArmsItem.h
@@ -4,7 +4,7 @@
 
 // Limits for the amount of weapons and items
 #define ARMS_MAX 8
-#define ITEM_MAX 0x20
+#define ITEM_MAX 32
 
 // "Arms" is a synonym of "weapon" here
 // "Code" means "ID" here
diff --git a/src/SelStage.cpp b/src/SelStage.cpp
index b0c86c2c..c54b2d0c 100644
--- a/src/SelStage.cpp
+++ b/src/SelStage.cpp
@@ -12,7 +12,7 @@
 #include "Sound.h"
 #include "TextScr.h"
 
-PERMIT_STAGE gPermitStage[8];
+PERMIT_STAGE gPermitStage[STAGE_MAX];
 
 int gSelectedStage;
 int gStageSelectTitleY;
@@ -26,7 +26,7 @@ BOOL AddPermitStage(int index, int event)
 {
 	int i = 0;
 
-	while (i < 8)
+	while (i < STAGE_MAX)
 	{
 		if (gPermitStage[i].index == index)
 			break;
@@ -37,7 +37,7 @@ BOOL AddPermitStage(int index, int event)
 		++i;
 	}
 
-	if (i == 8)
+	if (i == STAGE_MAX)
 		return FALSE;
 
 	gPermitStage[i].index = index;
@@ -50,18 +50,18 @@ BOOL SubPermitStage(int index)
 {
 	int i;
 
-	for (i = 0; i < 8; ++i)
+	for (i = 0; i < STAGE_MAX; ++i)
 		if (gPermitStage[i].index == index)
 			break;
 
 #ifdef FIX_BUGS
-	if (i == 8)
+	if (i == STAGE_MAX)
 #else
-	if (i == 32)
+	if (i == 32) // Same value as 'ITEM_MAX'
 #endif
 		return FALSE;
 
-	for (++i; i < 8; ++i)
+	for (++i; i < STAGE_MAX; ++i)
 		gPermitStage[i - 1] = gPermitStage[i];
 
 	gPermitStage[i - 1].index = 0;
@@ -139,11 +139,14 @@ void PutStageSelectObject(void)
 
 		PutBitmap3(&rcView, stage_x + (gSelectedStage * 40), (WINDOW_HEIGHT / 2) - 56, &rcCur[flash / 2 % 2], SURFACE_ID_TEXT_BOX);
 
-		for (i = 0; i < 8; ++i)
+		for (i = 0; i < STAGE_MAX; ++i)
 		{
 			if (gPermitStage[i].index == 0)
 				break;
 
+			// Interestingly, there's code for reading multiple rows of icons
+			// from the 'StageImage.pbm' file when there are more than 8 stages,
+			// despite only 6 icons ever being used.
 			rcStage.left = (gPermitStage[i].index % 8) * 32;
 			rcStage.right = rcStage.left + 32;
 			rcStage.top = (gPermitStage[i].index / 8) * 16;
diff --git a/src/SelStage.h b/src/SelStage.h
index f06dc427..ee684438 100644
--- a/src/SelStage.h
+++ b/src/SelStage.h
@@ -2,13 +2,15 @@
 
 #include "WindowsWrapper.h"
 
+#define STAGE_MAX 8 // Note that Cave Story only has 5 stages
+
 typedef struct PERMIT_STAGE
 {
 	int index;
 	int event;
 } PERMIT_STAGE;
 
-extern PERMIT_STAGE gPermitStage[8];
+extern PERMIT_STAGE gPermitStage[STAGE_MAX];
 
 extern int gSelectedStage;
 extern int gStageSelectTitleY;