Inter-Planetary Travel Module

This page is a discussion of the Interplanetary Travel module.

As the name suggests, the Interplanetary Travel module is designed to handle all issues pertaining to the space travel while the player's fleet is inside a star system (i.e. when they are not in hyperspace nor performing planetary exploration; this includes orbiting planets). The basic architecture of the module is similar to other modules within the game that handle basic data types (such as integers and strings) and hash tables / dictionaries. This module is utilized by the Starship Module while the player is in Maneuver Mode if their location is currently IN_SYSTEM, and is required to give some information to the Planetary Exploration Module when the player is selecting a landing site. The Interplanetary Travel module is important to the game for similar reasons to the Hyperspace Module; it is part of how the player travels to various locations (in this case to specific planets) to fulfill quest conditions. All code for the Interplanetary Travel module is located in the sf3_interplanetary.py file.

Summary Description
The Inter-planetary Travel module will be designed to handle all issues pertaining to the space travel while the player's fleet is inside a star system. Star system objects are held by Sector objects, and are called for information on planetary type and position when the player either launches from a planet's surface, launches from a Starport, or enters the star system from hyperspace. When this occurs, the routine will generate a map of the star system and will place the player's fleet at an appropriate point in that star system (either in orbit around the planet from which the fleet just launched, or along the appropriate edge of the star system map). The module will keep track of which direction the player wants to steer their fleet and will update their in-system position accordingly. If the player enters orbit around a planet, data on that planet will be called up and a terrain map for that planet will be generated. Likewise, data on any Starport objects indicated in the system will be generated if necessary. The star system remains active until the player either lands their fleet (at which point the Planetary Exploration Module assumes control of the game) or enters hyperspace (travels off the edge of the star system map, at which point the Hyperspace Module is activated).

Data Structure of the starSystem Object
The following list is an indication of the various variables and methods that will be included in a starSystem object. This list contains final variables included in the object; methods may be added as necessary. StarSystem objects are meant to be used as placeholders for data for both the Hyperspace and Inter-Planetary Travel Modules; the bulk of the data they contain involves the planets located within them, hence their inclusion in the Inter-Planetary Travel Modules. They inherit methods from the SF3Actor class, and have no child objects of their own. Multiple starSystem objects are meant to be used in the game, one for each star system located within a Sector. Data they are meant to be accessed at the game's onset and when an inter-sector flux has been traversed by the Hyperspace Module; this is mainly for the star's class and its position in hyperspace. They are also meant to be accessed by the Inter-Planetary Travel Module whenever the player enters the system, either from hyperspace or after launching from a planet located within the system. Their data structure is as follows:


 * Class: starSystem
 * Class: SF3Actor (for the data structure of the SF3Actor object, see the discussion under the Core Module.)
 * String: szStarClass (luminosity class, determines star's color)
 * Integer: xCoord (x-position in hyperspace)
 * Integer: yCoord (y-position in hyperspace)
 * List: vPlanets (holds planets and information)
 * Class: Planet (for the data structure of the Planet object, see the discussion under the Planetary Exploration Module.)
 * Dictionary: hPlanetLocations (holds the location of a planet within the star system, for use with the in-system map)
 * ''Key: Planet Orbit Number
 * Value (Tuple): Orbital Lane (radius), Azimuth (may use x,y coordinates if it turns out to be easier to code)''
 * Float (1 decimal): fMass (holds stellar mass)
 * Method: _init_(XML)
 * Method: setOrbits
 * Method: enterOrbit
 * Method: leaveOrbit

Interface
''The inter-planetary travel "interface" is not an interface in the normal manner of interfaces. Rather, it is a specific function of an already defined interface, the Starship Interface. Since travel through inter-planetary space is a reasonably lengthy topic and since it was not discussed under the Starship Module, a discussion of how inter-planetary travel will function graphically is warranted. The graphic being used was constructed from bits and pieces used in the old SF3 Navigation Demo, hence the old look and the use of a Wyltakin-class ship in in the graphics. Nevertheless, it is good enough to cover the basic concepts required for the discussion.''

As demonstrated in the graphic, inter-planetary travel specifically affects three areas of the Starship Interface (for details about the Starship Interface, refer to the discussion under the Starship Module. The affected areas are:
 * Main View Screen (MVS)
 * Auxiliary View Screen 2 (AVS2)

While Inter-planetary travel is occurring, AVS2 will display an in-system map. This will show the locations of all planets in the star system as well as their orbital lanes (in keeping with Starflight tradition, all planetary orbits will be elliptical and coplanar, to simplify coding). The system's primary is always located in the center of the map, and is usually represented as a larger icon than those used for planets. Star icons may either be color-coded or have their own icon, used to denote their stellar class. Planets may be color-coded to denote the planetary type at a glance, or small graphical representations of the planets may be used on this mini-map as well. Any starports in the system will not be denoted on the minimap; the player will not know of the presence of a starport in the system until they approach the planet around which the port is orbiting. The position of the player's fleet will be represented by a very small (4 pixel maximum) dot, which will move as the player moves their fleet around the system. If the player moves their fleet to a position past the "edge" of the system (i.e. to a position where their fleet would no longer be indicated on the minimap), the fleet will "jump to hyperspace"; the message "ENTERING HYPERSPACE" will appear in the Starship Interface and the Hyperspace Module will engage. Finally, if the player has access to a system scanner, any in-system encounters will be represented by small red dots (again, no larger than 4 pixels) which will move around the system as they track the player (or not).

The MVS, meanwhile, will show the player's fleet icon in its center. This icon will not leave the center of the screen as the player travels through the system; scrolling motion of the background star field will be used to give the player a sense of motion. When the player approaches a star or planet, the object will appear in the main view screen. Colliding the ship icon with either a planet or star icon will pause the action and trigger a message instructing the player to hit the space bar if they want to enter orbit. If the player continues to maneuver at that point, the message "OUTSIDE ORBITAL RANGE" will appear and the fleet icon will "jump" a short distance away from the planet (which should still be visible in the MVS, however). If the player hits the space bar, the MVS will change to an exterior view of the planet, while AVS2 will change over to the planetary Mercator map (which will involve a call to the Planetary Exploration Module to generate the map). The player will also be taken out of Maneuver mode at that point. The player may break orbit by re-entering Maneuver mode, at which point their fleet icon will appear relatively close to the planet icon in the MVS and AVS2 will return to the system map. Again, in this instance, the message "OUTSIDE ORBITAL RANGE" will be displayed. Orbiting a world that has an orbiting starport is slightly different: when the action is paused, a message will appear indicating the player may hit the space bar to orbit the planet, or the Enter key to dock at the Starport (in this way, the presence of a Starport around a world will not prevent the player from landing and exploring the world involved). Electing to dock at the Starport will engage the Starport Interface. In-system encounters will use a generic encounter icon when they appear in the MVS; colliding with this icon will call up the Tactical Interface and engage the Encounter Module. Finally, it is possible for a player to have an encounter when they assume orbit around a world. In that case, the standard encounter message "SCANNERS INDICATE UNIDENTIFIED CONTACT!" will appear, the encounter alarm will sound, and the Tactical Inteface will engage. This will override any orbital action or docking maneuver. Leaving the encounter will resume the desired action. I may need to fix this so that there are some encounters that must be resolved before the player will be allowed to orbit a planet, for example. Encounters may also occur anywhere else in a star-system. Encounters themselves remain invisible in the MVS, though they may show up on the radar if the player's Technology score is above 50; this will be accompanied by a message saying "MOVEMENT DETECTED AT (x)X BY (y)Y.", where x and y indicate how far away the encounter is along the two axis. The higher the Technology score, the further away encounters will be detected.

Maneuvering utilizes the set of keys indicated for Maneuver mode while the Starship Interface is active; the arrow keys, WASD keys, and numeric keypad may all be utilized to maneuver the fleet around. While in orbit, the normal set of keys and mouse clicks that apply to the Starship Interface will be activated. For more information, see the discussion under the Starship Module. The player may use either the &lt;Space Bar> or the &lt;Enter> key to drop out of Maneuver mode as usual.

Procedures and Notes
Mainly just picking out the things from Zharous's design doc that haven't got a great detail on the page for them already.

Solar System Components
The background space will either be black or nebula depending on if the player is in a nebula when they enter the solar system from hyperspace. If the solar system is a nebula then nebula conditions exist and the nebula graphic will be used instead of the starry black background for the star system view and for the background planet view from orbit.

Orbital Positions
When the player enters a solar system, the planets are placed in random positions on their orbital pathways. Either immediately or after a period of time, such as 10 days outside the solar system, these orbital positions are changed and the player will see planets in a different configuration when they reenter the system.

Alien Ship (Encounter) Behavior
Alien ships not specifically specified to exist in the solar system will be generated by the computer if the solar system is within that alien territories sphere of influence. If that sphere of influence moves, grows, or shrinks then the presence of alien ships in a solar system may be reduced, disappear completely, or be replaced by aliens of another race.

If the first method is used then alien ships can be set to always chase a player. To simulate more accurate behavior with either of the other methods than three state conditions may apply. Behavior in each condition is identical but the conditions are modified. When the alien ship is within a certain radius, it will turn to chase the player. Outside that radius it will ignore the player and simply wander or orbit a planet. When the player first enters a system all ships are in a neutral condition and will chase a player if they are within a moderate radius. If the first encounter ends in combat then all ships in the solar system enter a hostile condition and will chase the player as if the chase radius was infinite. If the first encounter ends peacefully, all ships in the system enter a friendly condition and the chase radius is greatly reduced. Any subsequent encounters ending in combat or not may change the classification from friendly to hostile or vice versa. This condition has no relevance to an alien's emotional index as used in the communication system.

After an alien encounter there should be a minimum time allowing the player to escape if he wishes before he meets another alien encounter or perhaps the same alien encounter a second time. Two different time counters, a larger one for meeting the same alien again and a smaller one for meeting a different alien encounter could be justified. Another method is to freeze an alien encounter that was just left and make it immobile for a second or two.

Alien ships can also be hidden in orbit around a certain planet or moon, only encounter-able when the player attempts to orbit. For these encounters two flags exist: infinite stack (aliens will call for reinforcements indefinitely and never run out of ships) and block orbit (fleeing the encounter forces the player to leave orbit, the player may not not enter orbit until all the ships are destroyed or the block orbit flight is changed.)

Orbit
Atmospheric thickness determines percentage of cloud cover. This topographical map will be overlaid on a sphere roughly a size proportional to the mass of the planet rotating continuously. The angle of the planet's axis is a randomly determined value between -90° and +90°. This angle will be visible as the angle seen from the planets orbit, which always approaches along the solar plane.

Landing Sequence
The landing sequence is a three-step animation which occurs with the player's controls locked. The first step is the approach to a partially cloud covered sphere. When close enough to hide the transition convert to a flat mercator view and continue filling in fractal generated details as the planet gets closer. The cloud cover layer should be pierced during this transition. The third step is converting flat detail to a three dimensional image of the terrain surface. When this occurs slowly rotate the player's viewpoint either to the right or to the left (determined randomly) and start to tilt the camera view downward while slowing descent. By the time the ship has "landed" the viewpoint should be 90° left or 90° right of the original angle and the camera viewpoint should be perfectly flat showing the terrain for a reasonable distance, and the Planetary Exploration Module controls will take over at that point. Launching obviously follows the exact reverse animation as the landing sequence.

Launching and landing both take exactly 0.25 cubic meters of fuel per gee of planetary gravity. This is merely for the launch to orbit and atmospheric entry; flying around in atmo will have its own fuel cost (as discussed in the Planetary Exploration Module).

_init_(XML)
''The argument flag is designed to be a way of indicating whether the game will be set to load data from XML files or from the saved toybox file. While the game is being tested, the flag should be set to True to load from XML. When the game is ready for public dissemination (including any public alpha tests), this flag should be set to False.''

Added 6/27/11. This method initializes a star system. This loads the star's position, luminosity and mass, as well as all the data on all planets present in the system.

(As the method is written, what it does should be written out procedurally)

setOrbits
Added 6/27/11. The purpose of this method is to set the locations of the planets located in a system when the player enters that system. First, the method will check to see if the player has entered the system before. If not, it will set the position of the planets randomly. Otherwise, the routine will check to see how long it has been since the player has entered the system, and move the planets along in their orbits by an amount set by our coders. ''This may ultimately require some additional variables to be present in the star system object. Checking to see if a player has entered a system before is easy...it'd simply require a check of the positions dictionary; and empty dictionary means the player hasn't been there before. However, this would be an additional piece of information that would require saving...''

(As the method is written, what it does should be written out procedurally)

enterOrbit
Added 6/27/2011. This method switches the player from flying around in a system to orbiting a specific planet. This will involve switching the player out of maneuver mode, generating an image of the planet being orbited, and loading up the data on the particular world. A planetary Mercator will likely be needed at this time, involving a call to the Planetary Exploration Module to generate such a worldwide map.

(As the method is written, what it does should be written out procedurally)

leaveOrbit
Added 6/27/11. Basically, this does the exact opposite of the enterOrbit method.

(As the method is written, what it does should be written out procedurally)

XML
The starSystem object, like most of the other objects in the game, is largely XML driven; this helps keep it flexible up until SF3's design is finalized (i.e. star systems can be added and removed from the game freely, based upon what data is available in the XML files). This particular object is unique in that it is required by a number of the game's different modules, including the Hyperspace Module (where the star system's position is required information for navigation) as well as the Planetary Exploration Module (which requires the information held in the object's vPlanets list to generate planetary surfaces). The starSystem object requires only one type of XML file, which is used to contain all the necessary data on the system and the planets within it (the file type "(sector_name).xml". This particular XML file type is discussed in detail in the XML discussion area of the Hyperspace Module.

Module Status
This is current as of June 27, 2011.

This module is currently in the final design phases; while specific descriptions of the intended functions of modules have yet to be written, the remainder of the module's basic description is complete at this point. Further design work on this module has been frozen for the time being, and will remain so until I'm ready to begin method descriptions for all remaining extant modules.

NEXT: Planetary Exploration Module PREVIOUS: Hyperspace Module / Inter-Stellar Travel TOP