More documentation.

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

sc2/doc/devel/generate

@@ -0,0 +1,127 @@
+The various universe related game data is generated through a call
+to a solar system dependant generation function.
+This function is of type PLAN_GEN_FUNC, which is a typedef to
+	void (*PLAN_GEN_FUNC) (BYTE control)
+, where the 'control' argument specifies what type of data needs to be
+generated (one of GENERATE_PLANETS, GENERATE_MOONS, GENERATE_ORBITAL,
+INIT_NPCS, REINIT_NPCS, UNINIT_NPCS, GENERATE_MINERAL, GENERATE_ENERGY,
+GENERATE_LIFE, or GENERATE_NAME).
+
+The generation function for a solar system is kept in the 'GenFunc'
+field of the SOLARSYS_STATE structure.
+The SOLARSYS_STATE structure contains the data for a solar system.
+Currently, only one SOLARSYS_STATE structure is used at once, and
+the global variable pSolarSysState points to the current one.
+The GenFunc field is initialised in ExploreSolarSys(), to the value
+returned by GenerateIP() in sc2code/gendef.c. Usually, this will be
+'GenerateRandomIP', but for some specific solar systems a (pointer to a)
+custom generation function is returned. This depends on the value of
+CurStarDescPtr->Index, which contains values such as SOL_DEFINED,
+MELNORME0_DEFINED, AQUA_HELIX_DEFINED, etc (see sc2code/encount.h
+for the complete list).
+The starmap_array in sc2code/plandata.c specifies Index for all
+the solar systems in the game.
+
+Following are the possible values of the 'control' argument to the
+generation function, with the description of how the generation function
+acts on this. As the custom generation functions often only need to
+change one specific aspect of this game data generation, they will
+often call GenerateRandomIP() for the rest.
+StarBases are handled as if they were moons.
+
+GENERATE_PLANETS
+Pre: the global variable pSolarSysState points to the relevant solar system.
+Pre: the RNG is initialised with a seed to be used for the generation.
+     In practice, this seed is generated from the HyperSpace coordinates
+     of the solar system (which are hardcoded in sc2code/plandata.c).
+Post: the RNG is in an undefined state.
+This function determines how many planets the system has, and fills in
+pSolarSysState->PlanetDesc[] for all planets, including the NumPlanets
+field, which determines how many moons the planet will have.
+It also sets the random seed that is used for data generated for this planet
+(including the number of moons), based on its coordinates (which are in the
+general case randomly determined themselves).
+
+GENERATE_MOONS
+Pre: the global variable pSolarSysState points to the relevant solar system,
+     which is initialised by a GENERATE_PLANETS call.
+Pre: the RNG is initialised with a seed to be used for the generation.
+     In practice, this seed is the seed stored by GENERATE_PLANETS
+     in the rand_seed field for the planet around which the moon(s) orbit.
+Pre: pSolarSysState->pBaseDesc points to the the relevant planet
+     of pSolarSysState->PlanetDesc[].
+Post: The RNG is in an undefined state.
+This function fills in pSolarSysState->MoonDesc[] for all moons around
+the planet pointed to by pSolarSysState->pBaseDesc.
+It also sets the random seed that is used for data generated for the moon
+based on its coordinates (which are in the general case randomly determined
+themselves).
+
+GENERATE_ORBITAL
+Pre: the global variable pSolarSysState points to the relevant solar system,
+     which is initialised by a GENERATE_PLANETS call.
+Pre: pSolarSysState->pOrbitalDesc points to the relevant planet or moon from
+     pSolarSysState->PlanetDesc[] or pSolarSysState->moonDesc[]
+Pre: the planet or moon that pSolarSysState->pOrbitalDesc points to
+     is initialised by a GENERATE_PLANETS or GENERATE_MOONS call.
+This function fills in pSolarSysState->SysInfo with the characteristics
+of the planet or moon, as seen from orbit.
+It also initialises the random seeds used for the generation of bio,
+minerals, and energy nodes on the surface.
+It also sets the discovery report string (if appropriate), initialises
+the surface graphics, and start the planet music.
+For specific planets, it may initiate race communication and possibly combat,
+and will only return once these are over.
+NB. The GENERATE_ORBITAL code should be split up into separate calculation
+and activation (graphics and music) parts.
+
+GENERATE_MINERAL, GENERATE_ENERGY, GENERATE_LIFE
+Pre: the global variable pSolarSysState points to the relevant solar system,
+     which is initialised by a GENERATE_PLANETS call.
+Pre: pSolarSysState->pOrbitalDesc points to the relevant planet or moon from
+     pSolarSysState->PlanetDesc[] or pSolarSysState->moonDesc[]
+Pre: the planet or moon that pSolarSysState->pOrbitalDesc points to
+     is initialised by a GENERATE_PLANETS or GENERATE_MOONS call.
+Pre: pSolarSysState->SysInfo is filled in by a GENERATE_ORBITAL call
+This function determines the properties of one mineral deposit, energy node,
+or life form on a planet or moon. On entry the caller sets
+pSolarSysState->CurNode to the index of the requested item. This function
+will then fill in SysInfoPtr->PlanetInfo.CurPt,
+SysInfoPtr->PlanetInfo.CurType, and in the case of minerals also
+SysInfoPtr->PlanetInfo.CurDensity.
+In case pSolarSysState->CurNode is set to a value larger than or equal to
+the number of items of the requested kind ((COUNT) ~0 in practice), it is
+set to the real number of nodes. In this case the CurXXX fields of
+pSolarSysState->PlanetInfo are set to the values corresponding to
+the largest valid CurNode index, but should probably be considered to be
+undefined.
+These functions may also change the game state, cause the lander
+to take off (by setting InTransit to true in the active PLANETSIDE_DESC
+structure), or mark an energy node as not retrieved, usually in response
+to an item having been picked up since the last call. The game makes
+a GENERATE_MINERAL, GENERATE_ENERGY or GENERATE_LIFE call (whatever
+is relevant) for each item right after it is picked up.
+
+GENERATE_NAME
+Pre: pSolarSysState is set to the relevant solar system.
+Pre: The planet is initialised by GENERATE_PLANETS.
+Pre: pSolarSysState->pBaseDesc points to the relevant planet, which should
+     be in the system.
+This function fills GLOBAL_SIS (PlanetName) with the name of the planet
+pointed to by pSolarSysState->pBaseDesc.
+It also sets the GAME_STATE flag BATTLE_PLANET to the type of this planet,
+so that it will be shown appropriately in melee if combat follows.
+There is no generate function for the names of moons. The few moons that
+are named (those in the Sol system), are handled as a special case of
+the routines that prints these names (PrintCoarseScan3DO and
+PrintCoraseScanPC).
+
+INIT_NPCS
+REINIT_NPCS
+UNINIT_NPCS
+[TODO]
+
+
+Initial version of this document created by Serge van den Boom, on 2005-07-11.
+
+

sc2/src/sc2code/planets/calc.c

@@ -220,6 +220,7 @@ CalcTilt (void)
 	return (tilt);
 }
 
+// NB. Returns the RNG to the state it found it in.
 DWORD
 DoPlanetaryAnalysis (SYSTEM_INFOPTR SysInfoPtr, PPLANET_DESC
 		pPlanetDesc)

sc2/src/sc2code/planets/lander.h

@@ -30,6 +30,8 @@
 typedef struct
 {
 	BOOLEAN InTransit;
+			// Landing on or taking of from a planet.
+			// Setting it while landed will initiate takeoff.
 
 	SOUND OldMenuSounds;
 

sc2/src/sc2code/planets/plandata.h

@@ -206,6 +206,8 @@ typedef struct
 			 */
 } ElementEntry;
 
+// PlanetFrame describes a type of planet. It is not used to describe
+// individual planets.
 typedef struct
 {
 	BYTE Type;
@@ -215,8 +217,8 @@ typedef struct
 			 *           CRATERED_ALGO, or GAS_GIANT_ALGO
 			 * bits 4-7: interplanetary color, one of BLUE_BODY, GREEN_BODY,
 			 *           ORANGE_BODY, RED_BODY, WHITE_BODY (same as
-			 *           GRAY_BODY), YELLOW_BODY, NUM_STAR_COLORS,
+			 *           GRAY_BODY), YELLOW_BODY, CYAN_BODY, PURPLE_BODY,
-			 *           CYAN_BODY, PURPLE_BODY, VIOLET_BODY)
+			 *           VIOLET_BODY)
              */
 	BYTE BaseTectonics;
 			/* Base constant for calculation of tectonic activity,
@@ -272,9 +274,27 @@ typedef struct
 
 	DWORD ScanSeed[NUM_SCAN_TYPES];
 	DWORD ScanRetrieveMask[NUM_SCAN_TYPES];
+
+	// The CurPt, CurDensity and CurType fields are filled in
+	// when a GENERATE_MINERAL, GENERATE_ENERGY, or GENERATE_LIFE
+	// call is made.
 	POINT CurPt;
+			// Position of the mineral/bio/energy node on the planet.
 	COUNT CurDensity;
+			// For bio and energy: undefined
+			// For minerals the low byte is the gross size of the
+			// deposit (this determines the image), and the high
+			// byte is the fine size (the actual quantity).
 	COUNT CurType;
+			// For minerals: the type of element
+			// For bio: the type of the creature.
+			//          0 through NUM_CREATURE_TYPES are normal creatures,
+			//          NUM_CREATURE_TYPES + 1 is an Evil One
+			//          NUM_CREATURE_TYPES + 2 is a Brainbox Bulldozer
+			//          NUM_CREATURE_TYPES + 3 is Zex' Beauty
+			// For energy: 0 - Liftoff on collision
+			//             1 - No liftoff on collision
+			//             2 - (special case) Fwiffo
 
 	STRING DiscoveryString;
 	FONT LanderFont;

sc2/src/sc2code/planets/planets.c

@@ -61,6 +61,12 @@ DrawScannedObjects (BOOLEAN Reversed)
 	}
 }
 
+// Initialise the surface graphics, and start the planet music.
+// Called from the GENERATE_ORBITAL case of an IP generation function
+// (when orbit is entered; either from IP, or from loading a saved game)
+// and when "starmap" is selected from orbit and then cancelled.
+// IsDefined is true only when the planet comes with its own bitmap,
+// namely for Earth.
 void
 LoadPlanet (BOOLEAN IsDefined)
 {
@@ -74,6 +80,9 @@ LoadPlanet (BOOLEAN IsDefined)
 
 	if (pSolarSysState->MenuState.flash_task == 0)
 	{
+		// The "rotate planets" task is not initialised yet.
+		// This means the call to LoadPlanet is made from a
+		// GENERATE_ORBITAL case of an IP generation function.
 		PPLANET_DESC pPlanetDesc;
 		extern void GeneratePlanetSide (void);
 

sc2/src/sc2code/planets/planets.h

@@ -153,17 +153,29 @@ typedef struct planet_orbit
 	DWORD *ScratchArray;
 }  PLANET_ORBIT;
 
+// See doc/devel/generate for information on how this structure is
+// filled.
 typedef struct solarsys_state
 {
 	MENU_STATE MenuState;
 
 	COUNT WaitIntersect;
-	PLANET_DESC SunDesc[MAX_SUNS], PlanetDesc[MAX_PLANETS], MoonDesc[MAX_MOONS];
+	PLANET_DESC SunDesc[MAX_SUNS];
-	PPLANET_DESC pBaseDesc, pOrbitalDesc;
+	PLANET_DESC PlanetDesc[MAX_PLANETS];
+			// Description of the planets in the system.
+			// Only defined after a call to GenFunc with GENERATE_PLANETS
+			// as its argument, and overwritten by subsequent calls.
+	PLANET_DESC MoonDesc[MAX_MOONS];
+			// Description of the moons orbiting the planet pointed to
+			// by pBaseDesc.
+			// Only defined after a call to GenFunc with GENERATE_MOONS
+			// as its argument, and overwritten by subsequent calls.
+	PPLANET_DESC pBaseDesc;
+	PPLANET_DESC 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
+			// image.origin.y, and PlanetDesc[LastPlanetIndex] has the
 			// highest image.origin.y.
 			// PlanetDesc[PlanetDesc[i].NextIndex] is the next planet
 			// after PlanetDesc[i] in the ordering.
@@ -179,6 +191,8 @@ typedef struct solarsys_state
 
 	COUNT CurNode;
 	PLAN_GEN_FUNC GenFunc;
+			// Function to call to fill in various parts of this structure.
+			// See doc/devel/generate.
 
 	FRAME PlanetSideFrame[6];
 	UWORD Tint_rgb;

sc2/src/sc2code/sis.h

@@ -204,6 +204,8 @@ typedef struct
 
 	DWORD FuelOnBoard;
 	COUNT CrewEnlisted;
+			// Number of crew on board, not counting the captain.
+			// Set to (COUNT) ~0 to indicate game over.
 	COUNT TotalElementMass, TotalBioMass;
 
 	BYTE ModuleSlots[NUM_MODULE_SLOTS];