From c346c82af40728533ea4e4b7d6f6f1590d4b513b Mon Sep 17 00:00:00 2001 From: meep-eep Date: Tue, 12 Jul 2005 01:37:03 +0000 Subject: [PATCH] More documentation. git-svn-id: svn://svn.code.sf.net/p/sc2/code/trunk@1840 8092fc87-c524-0410-9efc-e669fe64eaf9 --- sc2/doc/devel/generate | 127 +++++++++++++++++++++++++++++ sc2/src/sc2code/planets/calc.c | 1 + sc2/src/sc2code/planets/lander.h | 2 + sc2/src/sc2code/planets/plandata.h | 24 +++++- sc2/src/sc2code/planets/planets.c | 9 ++ sc2/src/sc2code/planets/planets.h | 20 ++++- sc2/src/sc2code/sis.h | 2 + 7 files changed, 180 insertions(+), 5 deletions(-) create mode 100644 sc2/doc/devel/generate diff --git a/sc2/doc/devel/generate b/sc2/doc/devel/generate new file mode 100644 index 000000000..d9231ec7d --- /dev/null +++ b/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. + + diff --git a/sc2/src/sc2code/planets/calc.c b/sc2/src/sc2code/planets/calc.c index 738754d9e..4db2648ab 100644 --- a/sc2/src/sc2code/planets/calc.c +++ b/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) diff --git a/sc2/src/sc2code/planets/lander.h b/sc2/src/sc2code/planets/lander.h index db2f0a606..890753080 100644 --- a/sc2/src/sc2code/planets/lander.h +++ b/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; diff --git a/sc2/src/sc2code/planets/plandata.h b/sc2/src/sc2code/planets/plandata.h index 3bfc0d74e..3536071a3 100644 --- a/sc2/src/sc2code/planets/plandata.h +++ b/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, - * CYAN_BODY, PURPLE_BODY, VIOLET_BODY) + * GRAY_BODY), YELLOW_BODY, CYAN_BODY, PURPLE_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; diff --git a/sc2/src/sc2code/planets/planets.c b/sc2/src/sc2code/planets/planets.c index 3cf2c3f1c..c10b7bb5d 100644 --- a/sc2/src/sc2code/planets/planets.c +++ b/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); diff --git a/sc2/src/sc2code/planets/planets.h b/sc2/src/sc2code/planets/planets.h index 56ce16d97..eef8f2854 100644 --- a/sc2/src/sc2code/planets/planets.h +++ b/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]; - PPLANET_DESC pBaseDesc, pOrbitalDesc; + PLANET_DESC SunDesc[MAX_SUNS]; + 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; diff --git a/sc2/src/sc2code/sis.h b/sc2/src/sc2code/sis.h index db62f7ba5..d3bcbf249 100644 --- a/sc2/src/sc2code/sis.h +++ b/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];