diff options
Diffstat (limited to 'doc/devel/orggenerate')
| -rw-r--r-- | doc/devel/orggenerate | 133 |
1 files changed, 133 insertions, 0 deletions
diff --git a/doc/devel/orggenerate b/doc/devel/orggenerate new file mode 100644 index 0000000..fce2207 --- /dev/null +++ b/doc/devel/orggenerate @@ -0,0 +1,133 @@ +Note: this file describes the way in which various things were generated +in the original source. See the file 'generate' for the current system. + +============================================================================ + +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), + followed by exactly one call to TFB_Random(). +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 pSolarSysState->SysInfo.PlanetInfo.CurPt, +pSolarSysState->SysInfo.PlanetInfo.CurType, and in the case of minerals also +pSolarSysState->SysInfo.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->SysInfo.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. + + |