Starport

This page is a discussion of the Starport module.

The Starport module is designed as a graphical interface through which the player may gain updates on their status, make upgrades to their fleet and train up their crew, and gather some crucial information on in-game events, and thus is it one of the more important modules in the game overall. 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 initially called and is therefore required by the Main Menu Module, and is also activated via the Starship Interface when the player leaves their ship while docked at Starport. All code for the Starport module is located in the starport.py file.

Because this will be a particularly large and complex module utilizing multiple interfaces for various in-game functions, this page will go over the overall features of Starport objects in general and will largely deal with the functioning of a Starport concourse. The various sub-modules have each been given their own page in this design document, as follows:


 * Operations Office Interface and Module
 * Bank Interface and Module
 * Fleet Configuration and Mechanic Interface and Module
 * Personnel/Crew Assignment Interface and Module
 * Trade Depot Interface and Module
 * Lounge Interface and Module
 * Casino Interface and Module

Summary Description
Instances of Starport Objects are meant to be loaded upon the start of a new game, or when needed by the Inter-Planetary Travel Module (in the event that there is a Starport located within a star system). The creation of the Starport object will set what services will be available at the port and will define which set of background graphics will be required if the player goes to the port for a visit. If they do use the port, the player may use the interface as a means to gather information, set, heal and train their crew, check their bank account, upgrade their fleet and vehicles, conduct trade and play mini-games, provided those services are available at the given port. The specific functioning of these "offices" will be discussed on individual sub-module pages.

Data Structure of the Starport Object
The following list is a rough indication of the various methods and variables that will be included in a Starport object's data. This is meant only as a guide; the names of the actual variables and methods may be different from what's listed here (any changes to variable names should be updated here ASAP). Starport objects are direct children of Star System objects. Immediate creation of a Starport object will be required during the initialization of a new game (since the Player begins the game at Starport Central). There may be several Starport objects used in a game; at this time, no less than half-a-dozen different Starports are indicated to be included in the game. Aside from Starport Central, Starport objects will be created upon their data being requested from the Inter-Planetary Travel Module. Their data structure is as follows:


 * Class: Starport
 * String: Name
 * String: Mesh (the file that indicates what graphic/model is used in-game for that particular Starport concourse.)
 * Integer: Law (law level; indicates likelihood that the player will be caught if hauling contraband/slaves, and severity of any penalties)
 * Array/Tuple: Coordinates
 * Integer: X-coordinate
 * Integer: Y-coordinate
 * Integer: Orbit
 * Hash/Dictionary: hServices
 * Class: ofc_Ops
 * Class: ofc_Per
 * Class: ofc_yard
 * Class: ofc_mech
 * Class: ofc_lounge
 * Class: ofc_casino
 * Flag: Library (not sure what exactly this will do in-game just yet)
 * Flag: Infirmary
 * List/Vector: No_Treatment (can set this up to prevent certain races from being healed at certain bases; Elowan bases may refuse to treat Thrynn, etc.)
 * Method: __init__ (szName, nCall)

Interface
''There is a current proposal in regards to Starports that would make them behave as some kind of navigable 3D scene, most likely in the style of a first-person shooter. Such an interface should behave similarly to the two-dimensional model as discussed herein; naturally, the underlying code will be somewhat different.''

The Starport Interface has three main components:
 * The Player Avatar (not indicated in the Interface example graphic)
 * The Concourse
 * Office Doors

The largest portion of the screen is the Concourse. This area is a simple piece of artwork; this artwork can be unique to a given Starport (for further details, see the XML section below). Players use the interface by means of a Player Avatar, a small model that moves around the Concourse at the discretion of the player. Control of the avatar is done of one of two ways, either via mouse clocks (the Player Avatar will move to whatever spot was clicked; if an Office Door is beyond that point, the indicated interface will activate as soon as the Player Avatar arrives at that location), or via the keyboards (control can be conducted through either the arrow keys, the WASD keys, or both simultaneously; selecting an Office Door requires the user to press either the &lt;Enter&gt; key or the &lt;Space Bar&gt;). The location of the Office Doors on screen are defined via XML, as are the functions of that office door. Scrolling over an Office Door with the mouse will bring up a small piece of text which identifies the specific office the door leads to. Moving the Player Avatar over an Office Door will bring up this text box permanently. Once an Office Door has been selected to activate, the Player Avatar moves to the indicated area (if not there already). The DOOR_WHOOSH tone is sounded, and game control passes to whatever Interface is appropriate for the selected office. A notable exception is when the player selects the "Docking Bay"; in that case, the TELEPORTATION tone is sounded, a "teleporter" animation shows on screen, and game control passes to the Starship Interface.

General Procedures and Notes
''3/27/11: It is now likely that Starport will be done in 3D from a first person perspective. WASD keys will control the player's avatar; the mouse will handle the movement of the player's "head" (the camera). A model will need to be associated with the player avatar; the camera height can be set based on the player character's height statistic. This may provide minimal effect to the overall game, but it'd still be a pretty nice little touch, IMHO.''

Sometimes, I could swear my world is a skybox.

__init__(szName, nCall)
The module's initializer may be called either by the Main Menu Module during the game's initial startup routine, or by the Inter-Planetary Travel Module upon entry into a system containing a Starport. The initializer begins by examining the szName argument and searching the current Sector data file for a Starport with a matching name. If it does not find one, the routine ends. When a match is found, the initializer creates the basic holder elements of the Starport object. It will then set those values equal to the data indicated by the data file (szName equal to Name, szMesh equal to Mesh, nLaw equal to Law and so forth). It will then begin searching the flags in the data file. For each flag set to True, an object of the appropriate type is created and placed in the hServices dictionary. The exceptions here are the Library and Infirmary flags; objects are not created for these entries but key-value pairs are appended to the hServices dictionary.

Next, the initializer will search for a corresponding auxiliary information file for the appropriate Starport. If one is not found, the routine stops at this point. Otherwise, the routine will go through each piece of data found and search for the presence of the appropriate "office area" under which to seed that data (for example, trade information would only be used by an ofc_Trade object). If the appropriate object type cannot be found in the dictionary, the routine skips over that information and moves on to the next piece of information. Should the routine find a "no_treat" data entry, the routine will check the current length of the vNoTreat list. If it equals one, the entry itself is checked; if it has a value of "ALL", the data is ignored. Otherwise, it is added to the list. If it equals zero, the status of the Infirmary flag is checked; if it is set to False, a value of "ALL" is appended to the list and the data is skipped. Otherwise, it is added to the list. If it is longer than one, the data is added to the list.

Once the auxiliary information file has been processed (if available), the Starport object has been completed and the initializer goes out of scope. The Starport object remains in memory until the player leaves the star system in which the specific Starport is located.

XML
The Starport object, like most of the other objects in the game, is largely XML driven; this will help keep it flexible up until SF3's design is finalized (i.e. starports can be added and removed from the game freely, based upon what data is available in the XML files). Starport objects require part of the data from two types of XML files, one containing basic information on the port such as its background graphics and available services (these are included in the Sector data XML files, "(sector_name).xml"; for more information on this file structure, see the XML discussion under the Hyperspace Module), and another XML file type which defines the on-screen coordinates/model coordinates of office locations on the concourse (the file type "(starport_name).xml"). The following briefly goes over the data located in these XML files.

(sector_name).xml
Basic information on Starport objects are located in the (sector_name).xml file types. This information is designed to give a Starport object most of its relevant data. The specific data is listed as a "starport" sub-element located under the "sector" element, which itself is under a root element called "world". "Starport" sub-elements are empty XML elements with several attributes. These attributes are "id" (used by the Sector Generator program; it should not be needed by the game nor will it be loaded by the game), "name" (the name of the port), "mesh" (the graphic or 3D model to be used as the concourse of that Starport), "pos" (the system coordinates in which the port is located within the Sector; Sector data is not required in this case, as the port should not be able to be loaded if the player is not currently located within the specified Sector), "orbit" (the orbital lane in which the port is located), "operations" (a flag indicating the presence of an Operations office), "personnel" (a flag indicating the presence of a Personnel/Crew Configuration Office), "bank" (a flag indicating the presence of a bank), "trade_depot" (a flag indicating the presence of a Trade Depot), "shipyard" (a flag indicating the presence of a Fleet Configuration office with services for starships), "mechanic" (a flag indicating the presence of a Fleet Configuration office with services for vehicles), "lounge" (a flag indicating the presence of a Lounge), "casino" (a flag indicating the presence of a Casino), "library" (a flag indicating the availability of library computer access), "infirmary" (a flag indicating the availability of crew healing while at the Starport), and "law" (an indication of the law level of the port). All of these attributes are required by the game routine (they are all auto-generated by the Sector Generator when a Starport is created by that routine).

Sample relevant structure of the (sector_name).xml file type:

&lt;?xml version="1.0" encoding="UTF-8"?&gt; &lt;world&gt; &lt;sector id="alpha_expanded"&gt; &lt;starport id="1" name="Starport Central" mesh="sc.blend" pos="125,100" orbit="3" operations="True" personnel="True" bank="True" trade_depot="True" shipyard="True" mechanic="True" lounge="True" casino="True" library="True" infirmary="True" law="9" /&gt; &lt;/sector&gt; &lt;/world&gt;

(starport_name).xml
The file type "(starport_name).xml" is designed as a listing of information that augments what can be automatically generated by the Sector Generator routine. Entries in the XML are one of the following empty categorical elements: "race" (used by the Personnel office for the list of available recruits), "no_treat" (used to seed the "no treatment" list), "buys" (used by the Trade Depot to seed the "trader_buys" dictionary), "sells" (used by the Trade Depot to seed the "trader_sells" dictionary; this is also used to denote what vehicles and ships may be purchased at the port.), "equip" (used by the Fleet Configuration office to denote available equipment), and "casino" (used to identify which casino XML file the Starport will utilize). Each entry must contain a "name" attribute, which will be used to denote specific instances of each category. Additionally, the "buys" and "sells" elements may have a "lock" attribute (a flag condition that must be set to "True" to be used, used to prevent the purchase or sale of particular goods without the player performing an "unlocking" condition), "equip" elements must have both a "range" attribute (which denotes the ranges of the Classes of said equipment) and a "scale" attribute (a string, with a value of either "vehicle" or "ship" used to denote what kind of craft the equipment is for).

Sample structure of the (starport_name).xml file type:

&lt;?xml version="1.0" encoding="UTF-8"?&gt; &lt;root table-name="Starport Central" version="0.1"&gt; &lt;race name="Human"/&gt; &lt;no_treat name="Gazurtoid"/&gt; &lt;buys name="Aluminum"/&gt; &lt;sells name="Glowing Pedestal" lock="True"/&gt; &lt;equip name="Laser Cannon" range="1,10" scale="starship"/&gt; &lt;game name="starport_central_casino.xml"/&gt; &lt;/root&gt;

Module Status
This is current as of December 15, 2010.

This module is currently in the completed design phase; specific descriptions of the intended functions of modules have been written at this point, but no actual code has been written related to the module as yet (with the possible exception of XML files). I'm not wholly certain whether additional methods will be necessary for this module or not (to account for the law and library functions), but for the time being I'm going to call the core Starport module complete. I may also need to reconsider how the data is being retrieved for Starport objects, particularly since these aren't objects that are being created when the game routine begins (unlike most of the other objects I've worked on to date).

NEXT: Operations Office Interface and Module PREVIOUS: Artificial Intelligence Module TOP