More documentation.
git-svn-id: svn://svn.code.sf.net/p/sc2/code/trunk@1840 8092fc87-c524-0410-9efc-e669fe64eaf9
This commit is contained in:
meep-eep
@@ -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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user