Fleet Configuration and Mechanic Interface and Module

This page is a discussion of the Fleet Configuration and Mechanic Module.

The Fleet Configuration and Mechanic Module is designed to handle the same functions as the Ship Configuration office from the original games, namely the management of the specific equipment installed on the player's ship. The renaming of the office to "Fleet Configuration" reflects the fact that the player is allowed to have more than one starship in their possession during the course of the game; the "Mechanic" reflects the addition of specific, customizable vehicles to the game. While these handle separate in-game functions, they will both be handled by the same general office at Starports.

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 should be required by the Starport Module only (unless a future decision is made that would allow the player to make ship upgrades at trading posts, which would then require the module be accessible by the Trading and Commerce module). As this module is the most direct way through which the player can increase their overall strength, it is a vitally important module to the game. All code for the Fleet Configuration and Mechanic Module is located in the sf3\_starport\_fleetconfig.py file.

## Summary Description

Ofc\_yard and ops\_mech objects are created and stored during the initialization of a Starport office if certain flags are set to True. When created, an ofc\_yard object will load in data on pieces of equipment available at the given Starport as well as specific ships available to the player; the ofc\_mech object will do much the same, but will handle the data for vehicles instead. When the player enters the appropriate office, an interface loads up which gives the player an overview of the current capabilities of their flagship and provides options to buy and sell equipment. The player may browse through the menus presented to buy or sell equipment as they choose, and may choose to switch to other ships in their fleet (if they have any). Menu options for starship will be greyed out if a Mechanic only is available; similarly, menu options regarding vehicles will be greyed out if only a Shipyard is available. Game control returns to the Starport concourse when the player selects the "Exit" button. The office objects remain in memory until the player leaves the star system in which the containing Starport is located, at which point they are destroyed (along with their parent Starport object).

## Data Structure of the Ofc\_yard Object

The following list is an indication of the various variables and methods that will be included in an ofc\_yard object. This list contains suggested methods and variables only; they should be updated as needed when finalized method and variable names are selected. Ofc\_yard objects are meant to be used as child objects of Starport objects, and have no child objects. Ofc\_yard objects are created during runtime when a player enters a star system and are subsequently destroyed when they leave that system. Thus, while there may be multiple ofc\_yard objects used in the game, only one will be in existence at a time (*per Starport located in a system; the Flornea system has two Starports in it and thus **may** have two ofc\_yard objects in it as well, one for each base*). Their data structure is as follows:

* Class: ofc\_yard
	+ Hash/Dictionary: Starship\_Equipment
	+ Hash/Dictionary: Stock\_Starships

## Data Structure of the Ofc\_mech Object

The following list is an indication of the various variables and methods that will be included in an ofc\_mech object. This list contains suggested methods and variables only; they should be updated as needed when finalized method and variable names are selected. Ofc\_mech objects are meant to be used as child objects of Starport objects, and have no child objects. Ofc\_mech objects are created during runtime when a player enters a star system and are subsequently destroyed when they leave that system. Thus, while there may be multiple ofc\_mech objects used in the game, only one will be in existence at a time (*per Starport located in a system; the Flornea system has two Starports in it and thus **may** have two ofc\_mech objects in it as well, one for each base*). Their data structure is as follows:

* Class: ofc\_mech
	+ Hash/Dictionary: Vehicle\_Upgrades
	+ Hash/Dictionary: Stock\_Vehicles

## Interface

   *My apologies to the design team; when I created the interface mockup, the only ship wireframe I could find was for the deprecated* Wyltakin*-class. The stats in the graphic are appropriate for that class with a human Captain as its only crewmember, but this is not actually a situation that will be in the final game. I will update the image if the opportunity presents itself. On the plus side, Panda will let you render a wireframe of a model when other elements of the screen need a solid rendering, so a separate "wireframe shader" will not be necessary.*

The Fleet Configuration and Mechanic Office interface consists of four main areas, as demonstrated in the graphic:

* Title Bar and Account Balance
* Equipment Selection Buttons
* Action Selection Buttons
* Information Area

The Title Bar and Account Balance area takes up a narrow strip along the top edge of the screen. This area merely contains the office's name and lets the player know how much money is currently in their account. While the player has no direct interaction with this area, the account balance will be updated as the player makes equipment selections.

Below this area along the left hand side of the screen are the Equipment Selection Buttons. This area takes up roughly a third of the width of the screen and two-thirds its total height. The area contains a total of twenty buttons, arranged in a grid of ten rows and two columns. The leftmost column contains the *Primary Equipment Selection Buttons*, which list general equipment categories. If an equipment category has multiple levels of specification (for example, Shields come in two types, Basic and Nebula), the main categorical list will be replaced with the specific categorical list for the selected piece of equipment in this column. The rightmost column contains the *Secondary Equipment Selection Buttons*, which display options when a specific type of equipment is finally selected in the *Primary Equipment Selection Button* column. The *Secondary Equipment Selection Button* column never displays anything other than specific final possible selections (classes for basic equipment types, specific types of pods, vehicles, vehicle upgrades, starship classes, or specific available repairs). Making a selection with the *Secondary Equipment Selection Buttons* constitutes a "final choice" and activates buttons in the Action Selection Buttons section of the screen.

Immediately below the Equipment Selection Buttons is the Action Selection Buttons area, which takes up the remaining portion of the left side of the screen along the bottom. This area consists of a large open space, with three buttons at the bottom arranged in a rough triangle shape, with two buttons available at the bottom. The two bottom buttons are labeled BUY and SELL, with the other button saying CONFIRM. The space is large enough to list any piece of equipment currently activated (based on the player's choices on the interface) along with the price to either buy or sell that equipment, depending upon whether they have activated the BUY or SELL button (defaults to BUY when the interface activates). Pushing CONFIRM will bring up one final sanity check; saying YES to this will activate the indicated transaction, subtracting from (or adding to) the player's available account balance, updating the information presented in the Information Area, and deactivating all selections on the page.

The final and most predominant area on the screen is the Information Area. This area takes up roughly the right two-thirds of the screen, extending just below the Title Bar and Account Balance area to the bottom of the screen. This area consists of a very large open space with three buttons at the bottom, labeled PREVIOUS, NEXT and EXIT. When the player first enters the office, data on their flagship (the ship currently under the command of the player's character) will be presented in this area and their flagship will be considered to be the "active" craft. Pressing PREVIOUS or NEXT will activate other ships in the player's fleet; these will cycle around in the order in which the ships were purchased. Pressing NEXT while the "last" ship in the player's fleet will bring up the data on the flagship, and vice versa for the PREVIOUS button (i.e. the data wraps around). Pressing the EXIT button will cause the interface to exit out; control of the game passes back to the Starport Consourse Module. The open space above these buttons lists current data on the "active" ship, starting at the top with the ship's name. Clicking on the ship's name will bring up a dialog that will enable the player to rename the ship. A wireframe model of the craft will be displayed immediately below this (*this image may be placed in a repeating loop that rotates the view over time, if we want to do that*), with the craft's type displayed immediately below the model. Immediately below that is the ship's summary equipment report; this lists what basic equipment is installed, the Discipline scores of the crew currently assigned to the ship, the number of pods the ship is hauling, the number of vehicles it is carrying (along with its available capacity), its total cargo capacity, and its performance characteristics (mass, acceleration and turn rate, *note that "turning acceleration" has been replaced with a turning rate since the graphic was created*). Finally, immediately below the equipment report and immediately above the buttons is the ship's fuel status, including the amount currently aboard as well as the type of fuel the ship is utilizing.

## General Procedures and Notes

### Vehicle and Starship Mass Calculations

* Corvette/Transport Chassis (Scout, *Intrepid*, *Challenger*) Base Mass = 10
* Destroyer/Frigate Chassis (Interceptor, *Xerxes*) Base Mass = 50
* Battlecruiser/Dreadnought Chassis (Warship, *Sleipnir*) Base Mass = 250
* Pods: 10 tons each (50 cm^3)
* Shields: 5 tons (regardless of class)
* Weapons: (see specific notes)
* Scout Engines: 10 tons (regardless of class)
* Interceptor Engines: 50 tons (regardless of class)
* Warship Engines: 250 tons (regardless of class)
* Armor Mass = (2\*class)^2 (Scout), increase to 3 for Interceptor and 4 for Warship.
* Accessories do not add mass. *Exception: Bulk Cargo Module will add an equivalent mass equal to the number of Cargo Pods necessary to carry the equivalent amount of junk. For example, a Bulk Cargo Module with a capacity of 1000 cubic meters is the equivalent of 20 cargo pods. Pods weigh 10 hectotonnes apiece, thus the Bulk Cargo module would add 200 hT of mass in this case.*

3/7/2011: The *Intrepid-II*, though on a Destroyer Chassis, is considered a Frigate/Corvette for purposes of its base mass. That explains what discrepancy exists. I'll need to figure a way programmatically to make this exception. Or ignore it...

Alien ships will be updated as necessary to approach Deus's design notes, at which point they can be tweaked to a final design. Starships will be placed under "Space Units" on each species profile page.

Vehicles:

* Shields: 5 tons (regardless of class)
* Missiles: 5 tons per launcher (turret or rack)
* Lasers: 5 tons per turret/1 ton per rack
* Planetary Vehicle Engines: 10 tons (regardless of class) (ITV/Anselmo)
* Light Space Vehicle Engines: 50 tons (regardless of class) (Galilei/Daystar)
* Heavy Space Vehicle Engines: 100 tons (regardless of class) (Viper/Avenger)
* Armor Mass = (2\*class)^2 (Planetary), increase to 3 for Light Space and 4 for Heavy Space.
* Base Mass = 0.5 tons per SC, round up.

Vehicle engine thrust system still needs refining. Current values:

* 100 TG = c1
* 200 TG = c2
* 300 TG = c3
* 400 TG = c4
* 500 TG = c5
* 600 TG = c6
* 700 TG = c7
* 800 TG = c8
* 900 TG = c9
* 1000 TG = cT

* Both starship and vehicle engines are reduced to one-tenth of their maximum thrust when in a planet's gravity well (can't say atmosphere)
* The turning rate of both vehicles and starships is calculated as (full space thrust \* 3), in degrees per second, *regardless* of location (a land vehicle would still use the full space thrust figure).

### Starship and Vehicle Repairs

1. For all ships and vehicles in the player's fleet, a check is made to see if any repairs are required when the player enters the Fleet Configuration Office.
	1. If no repairs are needed for a ship or any vehicles aboard, a routine runs that will display a NO REPAIRS NEEDED message if the REPAIR option is selected.
	2. All damaged systems are evaluated a repair cost equal to (equipment initial value X percent damaged X 1.25).
		1. All miscellaneous systems are evaluated a repair cost based on the costs indicated on the Player page.
		2. Vehicle miscellaneous systems are evalated at one-tenth the cost of corresponding starship miscellaneous systems.
	3. Once evaluated, repair costs for starships are placed into an itemized list and sorted by cost (highest cost appears first in the list).
		1. Vehicle repair costs are not itemized; repairs occur in one big thwack.
		2. Vehicle repairs appear after all starship system repairs in the itemized list.
	4. Repair time is also calculated and added to the itemized list. Equals equipment level, in hours.
		1. Miscellaneous systems repair time is evaluated at 5 hours, with 15 hours for hull repairs.
		2. Vehicles take one-half (rounded up) the time it takes to repair starships.
2. When the Repair Option is selected in the Primary Equipment Selection Buttons menu, the items in the itemized repair list appear in the Secondary Equipment Selection Buttons.
3. Upon selection of a specific item for repair, the amount for the repair appears in the Action Selection Buttons area along with the time required; BUY and SELL are greyed out while this is active.
4. If the player selects CONFIRM with a repair option active, a REPAIR takes place, provided the player can cover the cost of the repair.
	1. The REPAIR time is added to the amount of time passage before the player leaves Starport,
		1. This is done as the player leaves the Fleet Configuration Office.
		2. Should another repair be ordered, the repair time REPLACES the old repair time if and only if it is a greater value (all repairs at Starport occur simultaneously).
	2. The amount for the repair is subtracted from the player's account.
	3. The item is removed from the itemized list. All subsequent repairs move upwards on the list.
		1. If the itemized list is emptied, a NO FURTHER REPAIRS NEEDED message will appear in the Action Selection Buttons area and the CONFIRM button will be greyed out.
		2. Any item not originally appearing on the repair list now appears.

## XML

The starship and vehicle purchasing, record-keeping and upgrading processes are all XML driven; this gives the game's engines enormous flexibility, by allowing all craft and their on-board equipment to be added or removed from the game at will, based upon what data is available in the XML files. The Ofc\_yard object requires three different XML files to function properly, with one of those XML files used by the Starport concourse Module itself to limit the equipment available. The specific files are a file containing information on what equipment is available at the base (the file "(starport\_name).xml"), a file containing specific data on default starships and vehicles (the file "craft\_records.xml"), and the a file containing specific data on various equipment types, used to minimize the amount of data that must be stored in the craft records (the file "equipment.xml"). The following briefly goes over what data is located in these files.

### craft\_records.xml

The file "craft\_records.xml" is designed as the main information source on all craft (starships and vehicles of all types) that will be present in the game. Entries under the root element consist of one possibility, "species", with each entry containing one mandatory attribute, "name" (lists the name of the species that uses the described vehicle). Entries are not empty elements; they may contain two categorical sub-divisions, "starships" and "vehicles" (each of which contains the appropriate type of vehicle in them; its important that any given craft be put in the correct category, as their masses are handled differently in code). Both starship and vehicle entries contain "craft" elements, which describe specific craft entries and largely use the same set of possible attributes. Craft entries may or may not be empty elements. Entry attributes include "name" (the craft's common name, how its identified in longhand"), "type" (the craft's short name, used for how its represented on radar), "chassis" (the craft's frame, which sets many of its base properties), "engine" (the craft's engine class), "shield" (identifies the type of shield installed and its class, separated by a comma), "armor" (same as shield, but for the craft's armor), "beamrack" (includes the firing arc, number of hardpoints, weapon type and class of weaponry on beam weapon racks, all separated by commas; a craft may have multiple beamrack entries), "projrack" (same as beamrack, except for projectile weapon racks), "beamturret" (weapons installed on the craft's beam turrets, includes the number of turrets, weapon type and class, all separated by commas; craft may only have one beamturret attribute), "projturret" (same as beamturret, except for projectile turrets), "special" (identifies special weaponry installed), "permpodport" (identifies the number of permanent pod ports on the craft), "expodport" (same as permpodport, except for expendable pod ports), "permpod" (identifies a specific type and number of pods installed, separated by commas; a craft may have more than one permpod attribute), "expod" (same as permpod, but for expendable pods), "cargo" (the craft's base cargo capacity, without cargo modules), "hangar" (the craft's internal space for other vehicles, listed in terms of ITVs that can be placed aboard; one ITV equals four spaces), "vehicle(#)" (identifies the type and number of smaller vehicles currently aboard the craft, separated by commas; a craft may have more than one vehicle attribute), "element(#)" (identifies the name and amount of a constituent element for the craft, separated by commas; a craft may have up to three element attributes), "fuel" (identifies the material the craft uses for fuel and the amount it carries, separated by commas), "cost" (the monetary value of the craft), "size" (for starships, its size multiplier, times the size of an *Intrepid-II*-class starship; for vehicles, its size relative to an ITV), "crew" (the amount of crew the ship carries), "salvage" (whether the craft can conduct mining and salvage operations), and "mass" (needed only if any additional mass needs to be added to or subtracted from the craft; this contains the amount of adjustment). If a craft is not an empty entry, it may have one or more "modification" sub-elements (used to identify specific upgrades the craft may receive; this is used to power vehicle upgrades). Modification sub-elements must contain at least two attributes, "name" (the specific name of the modification, this is what appears in the vehicle's upgrade list) and "effect" (this lists which of the vehicle's attributes is affected and what change is needed to that attribute, separated by commas; a modification entry may have more than one effect attribute).

Sample structure of the craft\_records.xml file:

```

<?xml version="1.0" encoding="UTF-8"?>
 <root table-name="craft_records" version="0.1">
  <species name="Veloxi">
   <starships>
    <craft id="Frigate" type="Scout" chassis="m-ff" size="1" cost="2355880" engine="c5e" shield="c6s" armor="c5a" beamturret="2, c8PhaseStinger" projrack="Fore, 2, c4FlakCluster" special="None" crew="6" element1="Cobalt, 7.0" element2="Molybdenum, 2.0" fuel="shyneum, 3.0"  cargo="150" hangar="4" expodport="6" permpod="cargopod, 2" />
   </starships>
  </species>
  <species name="Empire">
   <vehicles>
    <craft id="Daystar" type="Light Fighter" chassis="vl-fighter" size="4" cost="157065" engine="c8e" shield="c2s" armor="c2a" beamrack="fore, 2, c2l" projrack="fore, 1, c1m" special="Countermeasure_Pods, 25" crew="1" element1="Titanium, 3.0" element2="Aluminum, 2.0" element3="Molybdenum, 1.5" fuel="shyneum, 1.5" cargo="1.83" >
     <modification name="Collapsible Sections" effect="size, //4" />
    </craft>
   </vehicles>
  </species>
 </root>

```

### equipment.xml

The file "equipment.xml" is designed the main information source on all equipment that will be present in the game from starships and vehicles (including information on chassis). Where possible, the game will take the approach of constructing derived data on craft, so it is important that as much information on equipment as is available be filled in the XML file. Entries under the root element are empty elements with the name "equipment". Equipment entries may have the following list of attributes associated with them:

* **id**: The equipment's identifier. This is used as a shorthand to identify the equipment pieces in the craft\_records.xml file.
* **type**: The type of equipment described, which can have a bearing as to the type of vehicle for which the equipment is available. Can have one of the following values:
	+ **chassis**: Indicates a chassis
	+ **engine**: Indicates an engine
	+ **shield**: Indicates a shield
	+ **armor**: Indicates armor
	+ **weapon**: Indicates a non-specific weapon type (usually used for special weaponry)
	+ **beamweapon**: Indicates a beam weapon
	+ **projweapon**: Indicates a projectile weapon
	+ **pod**: Indicates a pod. Can only be added to starships.
* **name**: The name of the equipment, as it will appear in the Equipment Selection Buttons portion of the interface
* **class**: Specific class of the equipment indicated.
* **cost**: Cost of the equipment, or base cost of a chassis
* **size**: Relative size class of the chassis (must be associated with a type="chassis" attribute), or the diameter of the collision sphere of a projectile weapon.
* **hd**: HD effect of the equipment. HD values are seperated by commas.
* **acc**: Number of accessories that may be installed (must be associated with a type="chassis" attribute). *Not sure what in-game effect this will have, if any.*
* **acdn**: Available accommodation space (must be associated with a type="chassis" attribute). *Not sure what in-game effect this will have, if any.*
* **cargo**: Available cargo space.
* **wepmax**: Maximum weapons class allowed (must be associated with a type="chassis" attribute).
* **defmax**: Maximum defenses (shield/armor) class allowed (must be associated with a type="chassis" attribute).
* **enginemax**: Maximum engine class allowed (must be associated with a type="chassis" attribute).
* **defacc#**: Indicates a default accessory. Listed by number. *Not sure what in-game effect this will have, if any.*
* **mass**: Mass of the equipment. Can be in T or hT, units separated from amount by comma.
* **pcmass**: Mass of the equipment if associated with a type="chassis" and class="corvette" attribute. Assumes use of hT units.
* **ddmass**: Mass of the equipment if associated with a type="chassis" and either a class="frigate" or class="destroyer" attribute. Assumes use of hT units.
* **bbmass**: Mass of the equipment if associated with a type="chassis" and either a class="cruiser" or class="dreadnought" attribute. Assumes use of hT units.
* **rackmass**: Mass of the equipment if mounted on a rack (associated with weaponry). Can be in T or hT.
* **turretmass**: Mass of the equipment if mounted on a turret (associated with weaponry). Can be in T or hT.
* **force**: Added amount of thrust force available. Usually associated with engines; can be associated with weaponry.
* **fueleff**: Fuel efficiency of the equipment (must be associated with a type="engine" attribute).
* **shpnorm**: Added amount of SHP available from equipment when not in a nebula.
* **shpneb**: Added amount of SHP available from equipment when in a nebula.
* **ahp**: Added amount of AHP available from equipment.
* **reflect**: Whether the equipment reflects damage, and how much damage it reflects (usually associated with a type="armor" attribute)
* **shielddmg**: Amount of damage an impact causes to the target's shields only (usually associated with a type="beamweapon", type="projweapon" or type="weapon" attribute)
* **dmg**: Amount of damage an impact causes to a target (usually associated with a type="beamweapon", type="projweapon" or type="weapon" attribute)
* **recharge**: The amount of time that must pass between uses (usually associated with weaponry).
* **range**: The maximum distance a target may be from the firing ship in order for a weapon to be effective.
* **energy**: The amount of fuel expended each time the system is used/fired. Usually associated with weaponry.
* **falloff**: The amount of damage lost or hit difficulty increased per range increment the firing starship is away from its target. Associated with weaponry.
* **spread**: The width of the cone within which a random vector will be given to each weapons shot
* **radius**: The blast radius of a weapon; damage falls off the further away a victim is from the epicenter.
* **wave**: The speed at which a weapon's blast wave expands.
* **stamina**: The amount of time a weapon will push or pull what it hits.
* **collide**: Whether or not a weapon terminates when it collides with something. Must be "true" or "false".
* **arc**: Whether or not a weapon "arcs out" (i.e. re-fires) towards another potential target when it collides with something. Must be "true" or "false".
* **proximity**: The range from its current target at which a weapon will detonate and cause damage.
* **penetrate**: What element(s) of a ship a weapon can pass through without causing damage or being blocked
* **salvage**: What element(s) of a ship a weapon will take hitpoints from and add to the corresponding element(s) of its own ship, if not already fully repaired
* **disable**: What system(s) of a ship a weapon will cause to malfunction immediately
* **discriminate**: Whether or not a weapon can damage friendly objects. Must be "true" or "false"
* **speed**: How fast a projectile weapon travels
* **turn**: The rate at which a projectile weapon turns
* **duration**: How long a weapon will remain on screen, provided it does not reach the limits of its range first.
* **effect**: A non-specific effect. Listed as variable affected first, value second, with a comma in between. Used with pods.

Note that all attributes are set to accept a numeric character at the end, in the event that multiple instances of that attribute are required for a specific piece of equipment.

Sample structure of the equipment.xml file:

```

<?xml version="1.0" encoding="UTF-8"?>
 <root table-name="equipment" version="0.1">
  <equipment id="vl-dd" type="chassis" name="Very Light Destroyer" cost="1000000" size1="16" size2="17" hd1="52, 53, 52" hd2="51,53,51" acc="27" wepmax="6" defmax="7" enginemax="6" acdn1="3000" cargo1="50" acdn2="5000" cargo2="100" mass="50">
  <equipment id="c5e" type="engine" name="Class Five Engine" class="5" cost="100000" hd="5,5,0" pcmass="10, hT" ddmass="50, hT" bbmass="250, hT" force="5000" fueleff="25">
  <equipment id="c6ns" type="shield" name="Class Six Nebula Shield" class="6" cost="375000" hd="6,6,6" mass="5, hT" shpnorm="2400" shpneb="2400">
  <equipment id="c3ra" type="armor" name="Class Three Reflective Armor" class="3" cost="12400" hd="-6,-6,-6" pcmass="36" ddmass="81" bbmass="144" ahp="1000" reflect="true, 0.5">
  <equipment id="bj" type="weapon" name="Battle Jumper" cost="8000000" falloff="0" energy="0.1" recharge="2" effect="teleport, true">
  <equipment id="c4PulseCannon" type="beamweapon" name="Class Four Pulse Cannon" class="4" cost="168750" rackmass="3, hT" turretmass="5, hT" dmg="28" recharge="6" range="999" energy="0.02" falloff="-150" penetrate1="shields, false" penetrate2="armor, false" disable="random">
  <equipment id ="plasmabolt" type="projweapon" name="Plasma Bolt" class="10" cost="16000000" rackmass="5, hT" turretmass="5, hT" dmg="4000" recharge="15" range="15" energy="0.1" speed="2" turn="15">
  <equipment id="cargopod" type="pod" name="Cargo Pod" cost="500" effect="cargo, 50">
 </root>

```

## Module Status

*This is current as of April 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: Personnel/Crew Assignment Interface and Module

PREVIOUS: Bank Module and Interface

TOP