Some comments and a few cleanups I made while researching for the

Star Control II facts.


git-svn-id: svn://svn.code.sf.net/p/sc2/code/trunk@1373 8092fc87-c524-0410-9efc-e669fe64eaf9

sc2/src/sc2code/build.c

@@ -59,6 +59,29 @@ GetStarShipFromIndex (PQUEUE pShipQ, COUNT Index)
 	return (hStarShip);
 }
 
+/*
+ * What this function does depends on the value of the 'state' argument:
+ * SPHERE_TRACKING:
+ * 	The sphere of incluence for the race for 'which_ship' will be shown
+ * 	on the starmap in the future.
+ * 	The value returned is 'which_ship', unless
+ *  TODO
+ * SPHERE_KNOWN:
+ * 	The size of the fleet when last checked the starmap is returned.
+ * ESCORT_WORTH:
+ * 	The total value of all the ships escorting the SIS is returned.
+ * ESCORTING_FLAGSHIP:
+ * 	Test if a ship of type 'which_ship' is among the escorts of the SIS
+ * 	0 is returned if false, 1 if true.
+ * FEASIBILITY_STUDY:
+ * 	Test if the SIS can have an escort of type 'which_ship'.
+ * 	0 is returned if 'which_ship' is not available.
+ * 	Otherwise, the number of ships that can be added is returned.
+ * CHECK_ALLIANCE:
+ *
+ * something else:
+ * 	TODO
+ */
 COUNT
 ActivateStarShip (COUNT which_ship, SIZE state)
 {
@@ -219,10 +242,12 @@ ActivateStarShip (COUNT which_ship, SIZE state)
 				}
 				else
 				{
+					/* 'state > 0', add ships to the escorts */
 					BYTE which_window;
 					COUNT i;
 
 					which_window = 0;
+					/*  Must... resist... commenting on this code... */
 					for
 						(
 								i = 0;

sc2/src/sc2code/build.h

@@ -46,12 +46,17 @@ extern HSTARSHIP CloneShipFragment (COUNT shipIndex, PQUEUE pDstQueue, BYTE
 extern HSTARSHIP GetStarShipFromIndex (PQUEUE pShipQ, COUNT Index);
 extern BYTE NameCaptain (PQUEUE pQueue, STARSHIPPTR StarShipPtr);
 
+/* Possible values for the 'state' argument of
+ * COUNT ActivateStarShip (COUNT which_ship, SIZE state)
+ * See that function for more information.
+ */
 #define CHECK_ALLIANCE -2
 #define ESCORT_WORTH 9995
 #define SPHERE_KNOWN 9996
 #define SPHERE_TRACKING 9997
 #define ESCORTING_FLAGSHIP 9998
 #define FEASIBILITY_STUDY 9999
+		/* Check for how many escort ships there's still space */
 
 extern COUNT ActivateStarShip (COUNT which_ship, SIZE state);
 extern COUNT GetIndexFromStarShip (PQUEUE pShipQ, HSTARSHIP hStarShip);

sc2/src/sc2code/comm.c

@@ -2152,13 +2152,18 @@ InitCommunication (RESOURCE which_comm)
 	UnlockMutex (GraphicsLock);
 
 	if (GET_GAME_STATE (BATTLE_SEGUE) == 0)
+	{
+		// Not offered the chance to attack.
 		status = HAIL;
+	}
 	else if ((status = InitEncounter ()) == HAIL && LocDataPtr)
 	{
+		// The player chose to talk.
 		SET_GAME_STATE (BATTLE_SEGUE, 0);
 	}
 	else
 	{
+		// The player chose to attack.
 		status = ATTACK;
 		SET_GAME_STATE (BATTLE_SEGUE, 1);
 	}
@@ -2191,6 +2196,7 @@ InitCommunication (RESOURCE which_comm)
 				&& GetHeadLink (&GLOBAL (npc_built_ship_q)));
 		if (status)
 		{
+			// Start combat
 			BuildBattle (0);
 			EncounterBattle ();
 		}

sc2/src/sc2code/comm/pkunk/pkunkc.c

@@ -844,6 +844,7 @@ Intro (void)
 	Manner = GET_GAME_STATE (PKUNK_MANNER);
 	if (Manner == 2)
 	{
+		// Irreparably Pissed off the Pkunk.
 		NumVisits = GET_GAME_STATE (PKUNK_VISITS);
 		switch (NumVisits++)
 		{
@@ -867,6 +868,7 @@ Intro (void)
 	}
 	else if (Manner == 1)
 	{
+		// Bad relations with the Pkunk, but not irreparably.
 		NumVisits = GET_GAME_STATE (PKUNK_VISITS);
 		switch (NumVisits++)
 		{
@@ -890,6 +892,7 @@ Intro (void)
 	}
 	else if (GET_GAME_STATE (GLOBAL_FLAGS_AND_DATA) & (1 << 7))
 	{
+		// Encountering the Pkunk at their home world.
 		if (!GET_GAME_STATE (CLEAR_SPINDLE))
 		{
 			NPCPhrase (GIVE_SPINDLE);
@@ -974,6 +977,8 @@ Intro (void)
 	else if ((NumVisits = GET_GAME_STATE (PKUNK_MISSION)) == 0
 			|| !(NumVisits & 1))
 	{
+		// Encountering a Pkunk ship in space, while they are not
+		// migrating.
 		NumVisits = GET_GAME_STATE (PKUNK_VISITS);
 		if (Manner == 3)
 		{
@@ -1034,6 +1039,8 @@ Intro (void)
 	}
 	else
 	{
+		// Encountering a Pkunk ship in space, while they are
+		// migrating.
 		NumVisits = GET_GAME_STATE (PKUNK_MIGRATE_VISITS);
 		switch (NumVisits++)
 		{
@@ -1071,6 +1078,7 @@ ExitIntro:
 	;
 }
 
+// Called after combat or communications
 static COUNT
 uninit_pkunk (void)
 {
@@ -1107,13 +1115,17 @@ init_pkunk_comm (void)
 	if (GET_GAME_STATE (PKUNK_MANNER) == 3
 			|| LOBYTE (GLOBAL (CurrentActivity)) == WON_LAST_BATTLE)
 	{
+		// Enter communications immediately.
 		SET_GAME_STATE (BATTLE_SEGUE, 0);
 	}
 	else
 	{
+		// Ask the player whether to attack or talk.
 		SET_GAME_STATE (BATTLE_SEGUE, 1);
 	}
 	retval = &pkunk_desc;
 
 	return (retval);
 }
+
+

sc2/src/sc2code/encount.c

@@ -163,6 +163,12 @@ BuildBattle (COUNT which_player)
 	}
 }
 
+/*
+ * Encountering an alien.
+ * Draws the encounter screen, plays the red alert music, and
+ * waits for a decision of the player on how to handle the situation.
+ * Returns either HAIL or ATTACK.
+ */
 COUNT
 InitEncounter (void)
 {

sc2/src/sc2code/globdata.h

@@ -110,7 +110,9 @@ typedef NUMBER_SPEECH_DESC *NUMBER_SPEECH;
 typedef struct
 {
 	void (*init_encounter_func) (void);
+			/* Called when entering communications */
 	COUNT (*uninit_encounter_func) (void);
+			/* Called when leaving communications or combat */
 
 	FRAME AlienFrame;
 	FONT AlienFont;
@@ -185,7 +187,15 @@ START_GAME_STATE
 
 	ADD_GAME_STATE (SHOFIXTI_MAIDENS, 1) /* Did you find the babes yet? */
 	ADD_GAME_STATE (MAIDENS_ON_SHIP, 1)
-	ADD_GAME_STATE (BATTLE_SEGUE, 1) /* Does encounter require battle segue? */
+	ADD_GAME_STATE (BATTLE_SEGUE, 1)
+			/* Set to 0 in init_xxx_comm() if communications directly
+			 * follows an encounter.
+			 * Set to 1 in init_xxx_comm() if the player gets to decide
+			 * whether to attack or talk.
+			 * Set to 1 in communication when battle follows the
+			 * communication. It is still valid when uninit_xxx_comm() gets
+			 * called after combat or communication.
+			 */
 	ADD_GAME_STATE (PLANETARY_LANDING, 1)
 	ADD_GAME_STATE (PLANETARY_CHANGE, 1)
 
@@ -414,6 +424,13 @@ START_GAME_STATE
 	ADD_GAME_STATE (MYCON_FELL_FOR_AMBUSH, 1)
 
 	ADD_GAME_STATE (GLOBAL_FLAGS_AND_DATA, 8)
+			/* This state seems to be used to distinguish between different
+			 * places where one may have an conversation with an alien.
+			 * Like home world, other world, space.
+			 * Why this needs 8 bits I don't know. Only specific
+			 * combinations of bits seem to be used (0, 1, or all bits).
+			 * A closer investigation is desirable. - SvdB
+			 */
 
 	ADD_GAME_STATE (ORZ_VISITS, 3)
 	ADD_GAME_STATE (TAALO_VISITS, 3)
@@ -492,8 +509,14 @@ START_GAME_STATE
 	ADD_GAME_STATE (PKUNK_VISITS, 3)
 	ADD_GAME_STATE (PKUNK_HOME_VISITS, 3)
 	ADD_GAME_STATE (PKUNK_SHIP_MONTH, 4)
+			/* The month in PKUNK_SHIP_YEAR that new ships are available
+			 * from the Pkunk. */
 	ADD_GAME_STATE (PKUNK_SHIP_DAY, 5)
+			/* The day of the month in PKUNK_SHIP_MONTH in PKUNK_SHIP_YEAR
+			 * that new ships are available. */
 	ADD_GAME_STATE (PKUNK_SHIP_YEAR, 5)
+			/* The year that new ships are available from the Pkunk
+			 * (stored as an offset from the year the game starts). */
 	ADD_GAME_STATE (PKUNK_MISSION, 3)
 
 	ADD_GAME_STATE (SUPOX_VISITS, 3)
@@ -505,6 +528,12 @@ START_GAME_STATE
 	ADD_GAME_STATE (HELIX_UNPROTECTED, 1)
 	ADD_GAME_STATE (THRADD_CULTURE, 2)
 	ADD_GAME_STATE (THRADD_MISSION, 3)
+			/* 0 if the Thraddash fleet hasn't left the Thraddash home world.
+			 * 1 if the Thraddash are heading towards Kohr-Ah territory.
+			 * 2 if the Thraddash are fighting the Kohr-Ah.
+			 * 3 if the Thraddash are returning from Kohr-Ah territory.
+			 * 4 if the Thraddash fleet is back at the Thraddash home world.
+			 */
 
 	ADD_GAME_STATE (DRUUGE_VISITS, 3)
 	ADD_GAME_STATE (DRUUGE_HOME_VISITS, 3)
@@ -520,6 +549,11 @@ START_GAME_STATE
 	ADD_GAME_STATE (ZOQFOT_HOME_VISITS, 3)
 	ADD_GAME_STATE (MET_ZOQFOT, 1)
 	ADD_GAME_STATE (ZOQFOT_DISTRESS, 2)
+			/* 0 if the Zoq-Fot-Pik aren't in distress
+			 * 1 if the Zoq-Fot-Pik are under attack by the Kohr-Ah
+			 * 2 if the Zoq-Fot-Pik have been destroyed because of this
+			 *   attack (not by the Kohr-Ah final victory cleansing)
+			 */
 
 	ADD_GAME_STATE (EGG_CASE1_ON_SHIP, 1)
 	ADD_GAME_STATE (EGG_CASE2_ON_SHIP, 1)
@@ -578,6 +612,14 @@ START_GAME_STATE
 	ADD_GAME_STATE (THRADDASH_BODY_COUNT, 5)
 
 	ADD_GAME_STATE (UTWIG_SUPOX_MISSION, 3)
+			/* 0 if the Utwig and Supox fleet haven't left their home world.
+			 * 1 if the U&S are on their way towards the Kohr-Ah
+			 * 2 if the U&S are fighting the Kohr-Ah (first 80 days)
+			 * 3 does not occur
+             * 4 if the U&S are fighting the Kohr-Ah (second 80 days)
+			 * 5 if the U&S are returning home.
+			 * 6 if the U&S are back at their home world.
+			 */
 	ADD_GAME_STATE (SPATHI_INFO, 3)
 
 	ADD_GAME_STATE (ILWRATH_INFO, 2)
@@ -599,6 +641,14 @@ START_GAME_STATE
 	ADD_GAME_STATE (MYCON_INFO, 4)
 	ADD_GAME_STATE (MYCON_RAMBLE, 5)
 	ADD_GAME_STATE (KNOW_ABOUT_SHATTERED, 2)
+			/* 0 if the player doesn't known about shattered worlds
+			 * 1 if the player has encountered a shattered world
+			 * 2 if the player knows that shatterred worlds are caused
+			 *   by Mycon deep children.
+			 * 3 if the player has told the Syreen that Mycon Deep Children
+			 *   cause shattered worlds. Proof doesn't have to be presented
+			 *   yet at this time.
+			 */
 	ADD_GAME_STATE (MYCON_INSULTS, 3)
 	ADD_GAME_STATE (MYCON_KNOW_AMBUSH, 1)
 
@@ -618,6 +668,11 @@ START_GAME_STATE
 	ADD_GAME_STATE (REFUSED_ORZ_ALLIANCE, 1)
 
 	ADD_GAME_STATE (PKUNK_MANNER, 2)
+			/* 0 not met the Pkunk
+			 * 1 fought the Pkunk, but relations are still salvagable.
+			 * 2 hostile relations with the Pkunk, no way back.
+			 * 3 friendly relations with the Pkunk
+			 */
 	ADD_GAME_STATE (PKUNK_ON_THE_MOVE, 1)
 	ADD_GAME_STATE (PKUNK_FLEET, 2)
 	ADD_GAME_STATE (PKUNK_MIGRATE, 2)
@@ -820,7 +875,9 @@ typedef struct
 
 	DWORD BattleGroupRef;
 	QUEUE avail_race_q, npc_built_ship_q;
-	QUEUE encounter_q, built_ship_q;
+	QUEUE encounter_q;
+	QUEUE built_ship_q;
+			/* Queue of SIS escort ships */
 
 	BYTE GameState[(NUM_GAME_STATE_BITS + 7) >> 3];
 } GAME_STATE;

sc2/src/sc2code/libs/file/temp.c

@@ -153,8 +153,7 @@ initTempDir (void) {
 	num = ((DWORD) time (NULL));
 //	num = GetTimeCounter () % 0xffffffff;
 	tempPtr = tempDirName + len;
-	i = NUM_TEMP_RETRIES;
+	for (i = 0; i < NUM_TEMP_RETRIES; i++)
-	while (i--)
 	{
 		sprintf (tempPtr, "%08lx", num + i);
 		if (createDirectory (tempDirName, 0700) == -1)

sc2/src/sc2code/planets/planets.h

@@ -158,6 +158,12 @@ typedef struct solarsys_state
 	PLANET_DESC SunDesc[MAX_SUNS], PlanetDesc[MAX_PLANETS], MoonDesc[MAX_MOONS];
 	PPLANET_DESC pBaseDesc, pOrbitalDesc;
 	SIZE FirstPlanetIndex, LastPlanetIndex;
+			// The planets get sorted on their image.origin.y value.
+			// PlanetDesc[FirstPlanetIndex] is the planet with the lowest
+			// image.origin.y, and PlanetDesc[FirstPlanetIndex] has the
+			// highest image.origin.y.
+			// PlanetDesc[PlanetDesc[i].NextIndex] is the next planet
+			// after PlanetDesc[i] in the ordering.
 
 	BYTE turn_counter, turn_wait;
 	BYTE thrust_counter, max_ship_speed;

sc2/src/sc2code/races.h

@@ -137,19 +137,33 @@ enum
 typedef struct
 {
 	UWORD ship_flags;
-	BYTE days_left, growth_fract;
+	BYTE days_left;
+			/* Days left before the fleet reachers 'dest_loc'. */
+	BYTE growth_fract;
 	BYTE crew_level, max_crew;
 	BYTE energy_level, max_energy;
 	POINT loc;
+			/* Location of the fleet (center) */
 
 	STRING race_strings;
 	FRAME icons, melee_icon;
 
-	COUNT actual_strength, known_strength;
+	COUNT actual_strength;
+			/* Size of the fleet. 0 if none-existant. */
+	COUNT known_strength;
+			/* Size of the fleet when last checked the starmap.
+			 * 0 if not that fleet is not known. */
 	POINT known_loc;
+			/* Location of the fleet (center)  when last checked 
+			 * the starmap */
 
-	BYTE growth_err_term, func_index;
+	BYTE growth_err_term;
+	BYTE func_index;
+			/* Function index defined in clock.h (the same as in SetEvent())
+			 * for the function to call when the fleet reaches 'dest_loc'.
+			 * '(BYTE) ~0' means no function to call. */
 	POINT dest_loc;
+			/* Location to which the fleet (center) is moving. */
 } EXTENDED_SHIP_INFO;
 typedef EXTENDED_SHIP_INFO *PEXTENDED_SHIP_INFO;
 

sc2/src/sc2code/sis.h

@@ -172,6 +172,7 @@ enum
 #define SHIP_PIECE_OFFSET 12
 
 #define MAX_BUILT_SHIPS 12
+		/* Maximum number of ships escorting the SIS */
 #define MAX_LANDERS 10
 
 #define SUPPORT_SHIP_PTS \

sc2/src/sc2code/starcon.c

@@ -227,6 +227,7 @@ black_urquan_genocide (void)
 			dy = TemplatePtr->ShipInfo.loc.y - BlackUrquanPtr->ShipInfo.loc.y;
 			if (dx == 0 && dy == 0)
 			{
+				// Arrived at the victim's home world. Cleanse it.
 				TemplatePtr->ShipInfo.ship_flags &= ~(GOOD_GUY | BAD_GUY);
 				TemplatePtr->ShipInfo.actual_strength = 0;
 			}