Encounter Module

This page focuses on the Encounter Module (certainly one of the more contentious portions of SF3's design).

In this context, "Encounters" focus specifically on encounters in space, involving communications and or combat on the starship-scale. They are important in setting the player's relationship with other races and for determining if certain clues will be divulged to the player or not (not to mention fulfillment of game victory conditions). 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 required by the Event Handler module specifically. All code for the Encounter object as well as the required child classes is located in the encounter.py file.

## Summary Description

An Encounter\_Handler object is intended to be loaded during the game's initial setup. This will load the game's list of communications messages and ship strengths/types into memory. The activation of a specific Encounter instance is done via the Event Handler object during the hourly check, and can occur while either the Hyperspace Module or Interplanetary Travel Modules are active. This routine will include a call to the Onomastikon Module to select an appropriate name for an alien commander and their ship, who will be involved if communications occur between the alien's fleet and the player's fleet. Strength of the alien fleet will be determined based upon the strength of the player's fleet and the skill scores of the crew of the player's flagship. Initial positions of the alien craft will be set by the routine, as will the craft in the player's fleet. Targets for each ship are determined by the routine. The routine will load up data on the current emotional disposition of the alien species encountered towards the player, and will set the behaviors of the alien fleet based on that information. If communications are indicated, game control will be passed to the Communications Engine. Any combat that may occur is handled by the Basic Combat module; the game will engage the Tactical Interface automatically in that event. Data on a specific Encounter object is kept for a specified period of game time after the player moves their flagship beyond encounter range.

## Data Structure of the Encounter\_Handler Object

The following list is an indication of the various variables and methods that will be included in an Encounter\_Handler object. This list contains suggested methods and variables. Encounter\_Handler objects are meant to be used as part of the game's fluid data structure, used by the Hyperspace, Inter-planetary Travel, and Event and Plot Handler Modules to determine if there is a chance the player will have an encounter at a given point during the course of the game. Encounter\_Handler objects have one type of child object, Encounter objects, which are used to handle specific encounters during the course of the game. As part of the game's data structure, only one Encounter\_Handler object is meant to be used in the game, and is loaded alongside the rest of the data structures by the Core Module during the initialization of the game's Toybox object. The Encounter\_Handler object's data structure is as follows:

* Class: Encounter\_Handler
	+ Class: Comms\_Handler (for details, see the Communications Mechanics, Interface and Engine page)
	+ Hash/Dictionary: SpeciesProbsHolder
	+ Hash/Dictionary: Starship\_Catalog
	+ Hash/Dictionary: Known\_Encounters
		- Class: Encounter
			* String: szID (used to identify unique, planned encounters)
			* Flag: Planned? (if set to True, the Encounter won't be wiped from memory)
			* Flag: Moves? (if set to True, the Encounter may be triggered on a range of nearby coordinates to those specified)
			* String: Race\_Name
			* String: Captain\_Name
			* String: Ship\_Name
			* Class: Fleet (for details about the data structure of Fleet objects, see the Player Module.)
			* Integer: Current\_Emotion\_Index
			* Integer: RSI (Relative Strength Index, a comparison of the player's TCSI to the other group's)
			* Method: calculateRSI()
	+ Method: \_init(XML)\_
	+ Method: setProbabilities(species, prob)
	+ Method: checkEncounters(ID)
	+ Method: generateEncounter()
	+ Method: moveEncounter()
	+ Method: destroyEncounter()

## Interface

   *This interface is written assuming encounters will be in 2D. Personally, I can see some utility in turning encounters into a 3D aspect of the game, though to my knowledge this has not been discussed as a possibility at any time in the project's development. This discussion will therefore assume 2D encounters, though this may be updated at a later date.*

The Tactical Interface consists of five separate areas, as demonstrated in the graphic:

* Target Status Display (Science View)
* Fleet Status Display (Status View)
* Radar Display (Navigation View)
* Communications Display (Communications View)
* Main Area (Main View)

The largest of the five interface areas is the Main Area, which is pretty much the entire screen except for the four semi-transparent overlay display panels (each of these are located in one corner of the screen, contain displays and controls, and have a specific purpose as detailed later in this discussion). An icon representing the selected ship from the player's fleet (the "flagship") is in the center of this view at all times, with all on-screen motion and headings calculated based upon this craft. The player has the option to shift this "focal ship" to any other ship in the encounter, including those of the encountered fleet. Any text messages displayed while the interface is active appear in an overlay at the bottom of the Main Area (the "Floating Text Area" indicated in the graphic); messages that appear here remain active for approximately two seconds, after which the overlay automatically closes.

The Radar Display, located in the upper-right hand corner, provides a long-range overview of the surroundings, view controls, current hyperspace coordinates (this is true with in-system encounters as well), the date and the current ship's fuel level. The radar acts as a sort of mini-map for the entire encounter. Objects in the radar are depicted as isosceles triangles that are color coded by their relationship to the player (blue are escorts, green are friendly, yellow are neutral/unknown, and red are hostile); the orientation of each triangle denotes the present heading of the object. As with the main view, clicking on escort vessels will select them, and clicking on a non-escort will make it the current ship's target. Selected escorts will have a square cyan selection border around them, and selected targets will have a square orange target border around it. Beam and projectile weaponry fire appears as lines and dots, respectively; various colors may be employed for specific types of weapons (e.g. a red line could denote laser fire, grey could denote tachyon fire, etc.). On the top of the panel is a "data bar" that gives the current location, date, and fuel level of the ship currently under the player's control. There will be a zoom control slider on the right side of the panel that controls the zoom level of the main view. Between the data bar and zoom slider is a button that activates normal view mode (the player ship is centered in the camera but the camera does not rotate with the ship), a button that activates ship view mode (the player ship is centered in the camera and the camera rotates with the ship, so that the ship always appears to be pointing "north,") and duel view mode (same as normal view, only the camera is centered between the player ship and the closest non-escort or target, if one is selected.) Above these four buttons is an "X" button that removes all panels from the screen, leaving only the main view. When the panels are removed, a button remains in the top right corner of the screen that brings back the four panels when clicked.

The Communications Display, located in the lower-right hand corner, has two panes (*Command* and *Communications*) which can be switched between using a pair of tabs. When an encounter begins, this display will default to showing the **Command** Pane. The **Command** pane has a number of displays, giving the damage status of the player's escort ships. Each one of these displays and its corresponding escort ship will be selected when clicked and unselected when clicked again. While escorts are selected, they can be given commands by pressing one of the three command buttons on this pane- "Return to Formation", "Search and Destroy", or "Attack Selected Target" (if there is no target selected for attack, a message will appear in the floating text area explaining this.) If one of these commands is issued while no escorts are selected, then all escorts are given that order. The **Communications** pane has a number of controls that allow for communications with a targeted non-escort vessel. The demeanor the player presents when communicating is selected by three buttons (only one of which can be selected at a time)- Friendly, Hostile, Obsequious (as with the Communications Officer's console in the Starship Interface; for more details, see the discussion under the Starship Module). Each posture will affect how the player's messages are delivered and different races will react differently to these different postures (for details, see the discussion under the Communications Engine). There are six message buttons for sending different question types to the target vessel, corresponding to normal question types. If the target vessel decides to respond to the message, then all other current activity is paused, a slide-out portrait overlay appears in the upper-center of the screen, and the message overlay in the floating text area appears; it will remain open until communications are closed. While in this mode, the player is free to dialogue with the target ship's captain/crew. Distress calls can be sent from the Communication pane as well.

The Fleet Status Display, located in the lower-left hand corner, has two panes (*Status* and *Cargo*) which can be switched between using a pair of tabs. When an encounter begins, this display will default to showing the **Status** Pane. The **Status** pane lists each ship in the player's fleet and has further buttons for battle status, systems status, and crew status displays; the player must select a ship in the fleet before any of these buttons become active, and only one may be selected at a time. A fourth button will return the view to the ship selection display; this button remains available at all times while the **Status** pane is active. The *Battle Status Display* shows the selected ship in wireframe. This wireframe shows color-coded damage to the Hull, Engines, Lasers, Missiles, Sensors and Communications (similarly to the Engineer's Damage Report display on the Starship Interface). Surrounding the wireframe is an ellipse that is color-coded to show the damage level of the ship's armor. Around that is a four-sectioned ellipse that is color coded to show the damage levels of the four shield arcs. Clicking the shield display will raise/lower the shields; when the shields are raised, their indicator will appear much brighter. Surrounding the shield display and corresponding to each arc are various laser and missile hardpoint displays, with recharge bars that show when they are ready to fire again. Clicking on one of them will arm/disarm weapons. When weapons are armed, their indicators will appear much brighter. If a hardpoint is destroyed, its hardpoint will disappear from the display. When weapons are armed, fire controls for lasers, missiles, and combat devices such as battle jumpers, cloaking devices and blastopods will appear. The *System Status* display has a display for each ship system-Shield, Armor, Hull, Engine, Laser, Missile, Sensor, and Communication. Each display shows the condition of that system via a percentage indicator. Clicking on a particular system will assign the ship's Engineer to repair that ship system. A border will appear around the display for that ship system, to show it is the one currently being repaired. The *Crew Status Display* has displays for each crew member, with the senior officers listed first in order by chain of command. Each display shows the condition of that crew member via a percentage indicator. Clicking on a particular officer will assign the ship's Doctor to concentrate on healing that crewmember. A border will appear around the display for that crewmember, to show they are the one currently being healed. The **Cargo** pane lists each ship in the player's fleet and has further buttons for switching between the cargo manifests and contains four buttons- Artifact, Mineral, Lifeform, and Goods. Each button selects what type of cargo is displayed in the cargo text menu list for the ship selected. There are five buttons that can be used when a cargo type has been selected in the cargo text menu list- Scan, Transfer, Transfer All, Drop, and Drop All. Scan gives an analysis of the cargo from the ship's Science Officer, Transfer allows the player to move the cargo to another ship in the fleet and allows them to specify how much of that cargo to transfer, Transfer All transfers all of that cargo to another ship in the fleet, Drop allows the player to decide how much of that cargo to jettison in the cargo text menu, and Drop will jettison all of that cargo. There is a Collect button near these buttons that will grab all Artifacts, Minerals, Lifeforms, and Goods in close proximity to the ship.

The final overlay is the Target Status Display, located in the upper-left hand corner. This panel has two panes, Status and Analysis, which can be switched between using a pair of tabs. When an encounter begins, this display will default to showing the **Status** Pane (*which will read "No Target" until the player selects one*). The **Status** pane displays the target's battle status. The battle status shows the target ship in wireframe. This wireframe shows color coded damage to the Hull, Engines, Lasers, Missiles, Sensors and Communications. Surrounding the wireframe is an ellipse that is color-coded to show the damage level of the ship's armor, and surrounding that is a four-sectioned ellipse that is color-coded to show the damage levels of the four shield arcs. When the shields are raised, the shield status display will appear much brighter. Surrounding the shield display and corresponding to each arc are various laser and missile hardpoint displays, with recharge bars that show when they are ready to fire. When weapons are armed, the recharge bars appear much brighter. If a weapons hardpoint is destroyed, it will disappear from the display. There will also be two displays that show the average condition of the target's energy readings (ship systems) and biological readings (crew members) via percentage indicators. The **Analysis** pane shows eight displays of the target's structure-Mass, Scale, Type, Constituents, Engine, Armor, Shield, Laser, Missile, and Special. Mass gives the mass in hectotonnes, Scale gives the relative scale compared to the player's ship, Type tells what class of ship it is (Scout, Warship, etc.), Engine gives the engine class, Armor gives the armor class, Shield gives the shield class, Laser gives the laser class, Missile gives the missile class, and Special tells what type of special weapon it has, if any (naturally, any analysis will be contingent up the success of a *Technology* Check; for details, see the Science Officer's discussion under the Starship Interface).

All of the action buttons referenced on the overlays may also be activated by keyboard hotkeys. Where possible, the same hotkey combinations used for the Starship Interface should activate the corresponding action button in the Tactical Interface (for example, a combination keypress of F7-F1 will toggle the shields). Each action button will also have a default set of hotkeys associated with it, and maneuvering controls will be made available to the player via the keyboard, as follows:

1. Key to make the interface panels visible/invisible. ("~")
2. Keys to zoom camera out (when not in duel view.) ("-", "numpad -")
3. Keys to zoom camera in (when not in duel view.) ("+", "numpad +",)
4. Keys to zoom radar view out ("<Ctrl>-", "<Ctrl>-numpad -")
5. Key to put camera in Normal View. ("F9")
6. Key to put camera in Ship View. ("F10")
7. Key to put camera in Duel View. ("F11")
8. Keys to thrust forward. ("w key" "up arrow", "numpad 8")
9. Keys to thrust backward. ("s key", "down arrow", "numpad 2")
10. Keys to thrust left. ("q key", "numpad 7")
11. Keys to thrust right. ("e key", "numpad 9")
12. Keys to turn left. ("a key", "left arrow", "numpad 4")
13. Keys to turn right. ("d key", "right arrow", "numpad 6")
14. Key to cycle through targets. ("t key")
15. Key to select closest target. ("r key")
16. Keys to select communications postures. ("F1" - friendly, "F2" - Obsequious, "F3" - Hostile)
17. Key to hail the current target ("F4")
18. Key to send a distress signal ("F5")
19. Key to toggle shields ("left-bracket")
20. Key to toggle weaponry ("right-bracket")
21. Key to cycle weaponry. ("Tab")
22. Key to fire weaponry. ("Space Bar")
23. Key to order escorts to Return to Formation. ("Backspace")
24. Key to order escorts to Search and Destroy, acquire targets and engage on their own. ("\")
25. Key to order escorts to attack selected target. ("Enter")
26. Key to salvage nearby cargo or board a nearby targeted, crippled vessel (the key must be held down for boarding.) ("Shift")
27. Key to Scan a Target ("numpad /")
28. Keys to transfer some/all of specified cargo to the target ("numpad \*", "CTRL-numpad \*" - All)
29. Keys to drop some/all of specified cargo ("ALT-numpad \*", "CTRL-ALT-numpad \*" - All)
30. Key to toggle the Communications Display between the Command and Comms Panels ("numpad 3")
31. Key to toggle the Target Status Display between the Status and Analysis Panels ("numpad 0")
32. Key to toggle the Fleet Status Display betwen the Status and Cargo Panels ("numpad 1")
33. Key to cycle through available Fleet Status Display reports ("numpad .")
34. Keys to cycle through systems requiring repair ("<", ">")
35. Keys to cycle through crewmen needing treatment ("CTRL-<", "CTRL->")

Finally, the mouse can also be used for certain actions. Left-clicking will direct the ship to proceed to the selected point and come to a stop. Left-clicking on a ship will select that ship; double-left clicking it will make it the current target. The mouse wheel can be used to cycle through weaponry; right-clicking fires the ship's weapons. For all of these actions to occur, the mouse's current position must be in the Main Area; these will not occur if the mouse is over one of the overlay panels. Left-clicking an action button in any of the overlay panels will activate that button.

While the Tactical Interface is active, game time passes at a reduced rate of 100 seconds of real-time per game hour.

## General Procedures and Notes

*This will be the only "in space" portion of the game to utilize quasi-realistic physics. There is a remote possibility that we may opt for a 3D encounter format at some point, but for now we're going with 2D space combat, as with the original games.*

When a player encounters another fleet they are drawn into a localized encounter space. If the player's fleet is recognized from previous encounters then a action may take place immediately, such as a friendly hail or a fight or flight reaction. Fight reactions occur immediately, often striking the player's ship before they have a chance to raise their shields, encouraging the player to preemptively raise shields in hostile territory. Friendly hails or any type of responses to hails take place in a random short period of time. Neutral or hostile/obsequious hails take place in a random long period of time.

Encounter Generation:

1. An encounter object is created by the hourlyCheck Method (for more details on this method, see its discussion under the Hyperspace Module). The encounter object's initializer method begins by calculating the player's current Total Composite Strength Index (TCSI). For each ship in the player's Fleet, the Composite Skill Score Value (CSSV) is calculated (a sum of the Disciplines of the main seven crew members) as well as the ship's Strength Index (SI) (a sum of the maximum SHP, maximum AHP, and maximum damage of its strongest available weapon). These values are added to the player's TCSI. Additionally, the highest CSSV value present in the player's fleet is kept; this value is used to determine the encounter's "difficulty", setting the CSSV of the ship's in the encountered fleet.
2. With the player's TCSI value calculated, the routine will determine exactly who may been encountered. The routine will check to see in which Sector the player is currently located, and will pull up the list of homeworlds for the Starfaring Age races in that sector. For each homeworld, the routine will calculate the distance from the player's ship to each homeworld in turn, storing the data as it's calculated. If a species has more than one homeworld in a Sector, the value for the closest of those homeworlds is kept; the others are discarded from further calculation. Next, all values stored in the SpeciesProbHolder dictionary are added to the calculated values. Then, the routine will sum up the remaining distances, and calculate a probability value for each species (using the formula ((total of all distances - distance to homeworld) / total of all distances). The current size of the species' SOI will also be factored into this probability value. If there are any Starfaring Age species in a Sector than have no homeworld (such as Minstrels, Mysterions, etc.), a fixed, artificial probability value will be utilized for that species. This value will start at .005 at the game's beginning, but encounters and time-addition variables may be used to increase this amount. Otherwise, the fractional value is subtracted from 1. In all cases, the result is rounded to three decimal points and multiplied by 1000. This will be used to produce a range of values that indicate a given species; for each species in the sequence, the result of all previous species fraction results are added to determine a set of "boundary values". The routine will then perform a "probability" check; a "die roll" of the total sum of probabilities will be rolled. The species indicated will be based on the result of this check; each species will have their boundary values checked in turn, with final selection being based on the probability check being higher than the minimal boundary value and lower than the maximum boundary value.
3. With the species encountered determined, ships are seeded into the encounter.
	1. The routine will start by checking to see if the current encounter's composite strength index (ESI) is within 500 points of the player's composite strength index (CSI). If the answer is no, the routine will check to see if the ESI is greater that the player's CSI. If not, another ship will be added to the encounter from the craft available to the encountered species, and the check is ran again (provided that the craft limit for the species has not yet been reached, with no additional craft being added if this limit has been reached); If so no additional ships are added to the encounter. Should the current ESI be within 500 points of the player's CSI, the game will check to see of another ship can be added to the encounter without going over the player's SI. All ships available to the encountered race are tested one by one; if a ship can be added, it will be added and a renewed check will be made to see if yet another ship can be added without going over the CSI. If a ship of more than one type could be added, the routine will give priority first to ships designated as dreadnoughts, then warships, scouts, and finally transports. If another ship cannot be added without going over the player's SI, the routine will stop adding ships. The final ESI module is compared to the player's CSI and the routine sets the encounter's initial RSI value.
4. Calls are made to the onomastikon module for a flagship captain's name, as well as a name for the flagship. This will provide information for any comm messages that require that data. The current emotion index of the species is also loaded as a piece of data into the encounter object.
5. The routine sets the initial coordinates of the encounter within close proximity of the player's fleet, and sets the Moves? flag to True; this allows the encounter to maneuver and attempt to trigger itself.

Encounter Movement:

1. Once an encounter is created, a *Stealth* Check is made, using the score for the Navigator in the player's fleet with the lowest *Stealth* score. A random number from 1-100 is picked; if the number is less than the indicated *Stealth* score, the encounter will remain stationary. Otherwise it will track the player.
	1. The same Check is made for any pre-existing stationary encounter that the player approaches within two hyperspace units.
2. Moving encounters will always move towards the player's fleet.
3. Moving encounters will track the player for up to 1d5 (1-5) hours, after which time they will become stationary. Once stationary, it will take a fresh *Stealth* Check for that encounter to gain the opportunity to become mobile again.
4. The speed at which an encounter moves will be determined by the composition of the ships in the encounter. The fleet may move at the rate indicated by the lowest Engine class present. Fuel consumption will not be considered for encounters.

Encounter Destruction:

1. An encounter is destroyed if all the ships in it are transformed into debris (i.e. all ships are destroyed).
2. Encounters are also destroyed if the local area gets too crowded; encounters may not be within five hyperspace coordinates of one another. If a new encounter would violate this rule, the older encounter is destroyed. The only exception to this rule is for planned encounters, in which case they take precedence. Hyperspace encounters and in-system encounters may also coexist within the five hyperspace coordiante boundary.

*The following are some older notes from a previous version of the SF3 Design document. They still appear to be valid, so I have moved them here; I'll still need to sift through them to see if anything is redundant.*

### Ship Maneuvering

A ship's rate of rotation increases as the Player or AI holds a turn in a certain direction, until it reaches its max turning rate. When the Player or AI decides to stop turning in that direction, the ship's rotation speed will decrease until it stops rotating altogether.

A ship can thrust in four directions- Forewards, Aftwards, Starboard (right) and Port (left) or Fore, Aft, Star and Port, for short. Foreward movement offers the full level of acceleration that the ship can produce, while thrusting in the other three directions produces half as much acceleration. A ship can use two thrusters at once, as long as they are not in opposite directions (which will simply cancel each other out.) In addition to thrusting, ships can actively decelerate, which means the ship automatically thrusts (at 50% the power of forward thrusting) in the opposite direction it is moving, until it comes to a dead stop or until the player (or AI) releases the decelerate key. *Ships may also turn clockwise or counterclockwise. If Encounters become 3D, ships will also need to be able to pitch and roll.*

Different ships have different turn rates and acceleration rates, based on ship mass, engine class, and engine damage.

In Vacuum space encounters, ships do not experience drag. While they still have a top speed, only active forces like thrusting or getting pushed/pulled by external forces can reduce their speed.

In Nebula space encounters, ships do experience drag. If left alone, they will decelerate until all speed is lost.

### Weaponry

Every ship can have a number of weapon hardpoints. Each hardpoint can fire once before needing to recharge and most require the same amount of time to recharge (the Black Orb is an exception.) How a hardpoint works is determined by two factors- rotation range and type.

A weapon hardpoint can have one of five different types of rotation ranges- Fore, Aft, Star, Port, Turret. Fore has a 90 degree range off the bow, Aft has a 90 degree range off the stern, Star has a 90 degree range off the starboard side, Port has a 90 degree range off the port side, and Turret can fire in any direction.

A weapon hardpoint can be one of two different types- Laser or Missile. Lasers have less range (with the exception of the Particle Beam) and do less damage than missiles, but they hit their targets or miss instantly, making them impossible to dodge. Missiles can hit targets at a greater distance than a normal laser and do more damage per class, but they take time to reach their target and thus can be dodged. *This, of course, has been replaced with the more general "Beam" and "Projectile" weaponry, of which multiple categories now exist, though in general the effects listed herein are still true.*

Weapons of both types fire shots in random directions within the accuracy angle. With lasers the middle of the accuracy angle is aimed at the Target, and with missiles the middle of the accuracy angle is aimed at the position the Target would be at by the time the missile got to it, given that it did not change course. The higher the level of accuracy, the narrower the accuracy angle is. Weapon accuracy is determined by the speed of the target, which reduces accuracy, and the ~~navigator's~~ *Tactical Officer's* skill level, which increases it.

When a weapon's fire intersects a ship's collision area (even if it is an escort) it delivers the appropriate amount of damage and the weapon's fire is terminated. Collision areas are elliptical or rectangular, so they can have one dimension longer than the other. *The way Panda is set up, it will be possible to set the collision area equal to the shape of the target ship.*

Note that in addition to hardpoint weaponry, there are special weapons and devices which ships can use offensively in combat (Blastopods, for example.)

### Gravitational Effects

Gravity and Anti-Gravity (*same thing, different mathematical sign*) can effect ships and/or missiles by pulling or pushing them. The force is stronger towards the epicenter of the Well. Wells can be emitted by a ship using a beam, or from the detonation of a missile. *Weaponry with with the "force" and "stamina" properties will have this effect.*

### Nebular Environment

When an encounter takes place within a nebula, ships will experience drag while maneuvering, shields will not regenerate~~, and Ion Storms will occur randomly (their chances of occurrence depend on the nebular weather of the nebula the encounter takes place within.) During an Ion Storm, all sensors are reduced by one class, and ships can get hit random by energy discharges, causing them to suffer damage~~. *Ion storms are a concept that's pretty much out at this point.*

### Components

*(This Section Undergoing Some Renovations)*
Classes exist for the following Ship Systems- Shield, Armor, Laser, Missile, Sensor, Communication. The higher the class of Shield and Armor, the higher their durability hitpoint value, as well as mass for Armor. The higher the class of Laser and Missile the higher their attack hitpoint value. ~~The higher the class of Sensor, the farther out the Navigation panel can see and the farther away ships can be targeted. A class 5 sensor will have no range limitations for targeting. The higher the class of Communication, the farther away escorts can be given orders and the farther away other vessels can be hailed. A class 5 Communication will have no range limitations for commanding escorts and communicating with other ships.~~ *Sensors and communications have no classes. The remainder of this section has more to do with other portions of the design document and has been generally covered elsewhere.*

~~Training exists for the following crew posts- Scientist, Navigator, Engineer, Communicator, Medic. The higher the training of a Scientist, the more details are given about targets on the Science panel. The higher the training of a Navigator, the more accurate the weapons will be. The higher the training of an Engineer, the faster the repair rate will be, while consuming repair materials at the same rate. The higher the training of a Communicator, the more types of attack orders can be given to escorts and the more information is translated when communicating with other vessels. The higher the training of a Medic, the faster the treatment rate will be.~~

~~Damage has four categories- Shields, Armor, Ship Systems and Crew Members.~~

~~Shields self-regenerate, unless they are completely destroyed. Shields can be raised or lowered. When raised, they usually take damage first. If a shield does not have the hitpoints to fully withstand an attack, the remaining damage is passed onto the armor, and if there is insufficient armor, it is passed onto the ship systems and the crew members. Every ship that is equipped with shields has four shield arcs- Fore, Aft, Star, Port. Fore has a 90 degree range off the bow, Aft has a 90 degree range off the stern, Star has a 90 degree range off the starboard side, and Port has a 90 degree range off the port side. Each shield arc has its own hitpoint system and thus takes damage individually. A single shield arc has the same hitpoints as armor of the same class.~~

~~Armor cannot be raised or lowered. It usually takes damage only when the shields do not have the hitpoints to withstand an attack, or are not raised. If the Armor does not have the hitpoints to fully withstand an attack, the remaining damage is passed onto the ship systems and the crew members. Armor has the same hitpoints as a shield arc of the same class.~~

~~Ship Systems usually do not take damage when there are sufficient levels of Shields and/or Armor in place. Damaged systems can be repaired by the engineer, as long as there is a supply of the repair materials Titanium, Aluminum, Molybdenum, Cobalt, and Promethium. Completely destroyed systems cannot be repaired. There are six categories of systems- Hull, Engine, Laser, Missile, Sensor and Communication. Hull damage does has no effect unless it is completely destroyed, at which point the ship itself is destroyed as well. Engine damage lowers the acceleration and turning rates of the ship, Laser damage increases the recharge time of the laser hardpoints, Missile damage increases the recharge time of the missile hardpoints, Sensor damage creates flashes of noise on the Navigation and Science panels as well as decreasing radar and scan range, and Communication damage creates flashes of noise on the Communication panel as well as decreasing the range that escorts and other vessels can be communicated with.~~

~~Crew Members usually do not take damage when there are sufficient levels of Shields and/or Armor in place. Injured Crew Members can be healed by the Medic. Dead Crew Members cannot be healed. There are six posts of Crew Members- Captain, Scientist, Navigator, Engineer, Communicator, and Medic. A Captain injury lowers some of the increased effectiveness that he/she would normally provide. A Scientist injury lowers his/her ability, making the information on your Science panel less detailed. A Navigator injury lowers his/her ability, making your weapons fire less accurately. An Engineer injury lowers his/her ability, making repairs take longer, while still consuming repair materials at the same rate. A Communicator injury lowers his/her ability, making it so that escorts do not always follow attack orders and less information is translated when communicating with other vessels. A Medic injury lowers his/her ability, making treatments take longer.~~

*Comments from ICC, Bio and Energy Thread, 4/8/2011*

So basically the player would get these four damage readings from a target:

* Shield (Remaining integrity, not shield "emitter" damage.)
* Armor
* Energy (Engines + Sensors + Com + Shield + Missile + Laser)
* Bio (Captain + Scientist + Navigator + Engineer + Communicator + Medic)

No indication of Hull integrity is given. The player can make a rough guess at this by looking at the Bio and Energy readings. The values given for each of the above can be relative in the form of a percentage or absolute hit point values (percentage would be more traditional and pass less information to the player, which may affect their tactical thinking).

It always kind of upset me how that (bio and energy) worked (in the original games). I always thought it should have been possible to kill off all the crew of an enemy ship without completely destroying it, especially since that can happen to you. I suppose technically you get the same result in the end where the enemy is defeated, but it would add a little more realism to be able to kill all life from a ship without utterly destroying it.

Should be so in SF3 as we'll be simulating NPC's stuff the same way as the player's. I'm sure the binary system's crew would have done it the same way if not for the technological limitations of the day.

There's also the possible feature of boarding and capturing ships that have been disabled in this and other ways. Or maybe salvaging cargo that wouldn't survive the destruction of the vessel. Or leaving a ship crippled instead of destroyed might mean less lost reputation with the race that owns it. So you could actually get different gameplay results from merely disabling a ship.

### Fleets

All ships belong to fleets. All ships within a fleet are considered escorts and will never fire on each other, but will target and attack ships from other fleets which are enemies of their fleet. When the player first enters an encounter, there can be any number of fleets, each with a number of ships, and each being aligned with a certain race. If the fleets of two opposing races are inside an encounter, they will attack each other. If the fleets of two allied races are inside an encounter, and one is attacked, the other will attack the aggressor on behalf of its ally.

When a player enters an encounter, there can be one or more different fleets. Whenever an AI controlled fleet goes beyond maximum range from the vessels of any other fleets, it leaves the encounter. If the player's ship gets beyond the maximum range (regardless of the positions of his escorts) he leaves the encounter and the game goes back into the navigation engine. New fleets can also enter an encounter, at random. The chances that a certain race's fleet will be in an encounter when the player first enters, or will enter the encounter later on, are determined by the fleet densities of the races that patrol the sector the encounter takes place in, and whether or not the encounter is taking place within the territory or territories of a race or races.

### Graphics

There are six categories of graphics used in the encounter engine- Interface, Background, Ship, Weapon, Hit, and Special.

Interface graphics in the Encounter engine are very similar to those used by the Navigation, Orbital, Planetary and Interior engines, and are described in detail, earlier on in this manual.

Background graphics have no effect on gameplay and consist of three pairs of layers that scroll at different rates. The lowest layer group scrolls the slowest, the middle layer group scrolls faster, and the highest layer group scrolls the fastest. Each layer group consists of a lower layer containing tiled art (such as a starfield) and a higher layer containing randomly placed art (such as a distant nebula or planet.)

Ship graphics are sprites that visually represent the craft of the encounter engine. When a ship turns, its sprite is rotated by the engine. Additionally, if it has turning animations, the relevant one will play forward while the ship is turning in that direction, and will play in reverse as it stops turning.

Weapon graphics include laser and missile effects. Laser effects are bitmaps which are placed head-to-toe to instantaneously create a line between the point from which their are fired, and the termination point of the beam. Missile effects are single bitmaps or sprites made up of a looping animation.

Hit graphics are explosion sprites which appear when a weapon hits a ship. Different animations will play depending on the weapon and the race which fired it. If the weapon hits a certain shield arc on a ship without penetrating it, a corresponding animation will play, showing that particular area of the shield lighting up. There are different shield hit animations for different races' ships.

Special graphics are miscellaneous sprites which illustrate the effects of special weapons, devices, and nebular ion storms.

Note, all graphics used in this engine are in PNG (Portable Network Graphics) format. *If we still go 2D. Even then, there may be some cause for the use of 2D sprites (such as for explosions); PNG will be the preferred file format in these instances, as discussed in the project's standards.*

## Methods

### \_init(XML)\_

Creates the dictionaries. Loads the data from the Toybox or the XML depending on what's passed to it.

### setProbabilities(species, prob)

Added 12/3/2010, referenced in Event Module. Method is intended to adjust the probability of encountering a species. Basically, when called, the amount passed in "prob" will be added to the currently existing value associated with "species", which acts as the key value for the SpeciesProbsHolder dictionary. The values in this dictionary are factored in for a given species whenever the routine is trying to determine if an encounter will be created.

### checkEncounters(ID)

Added 12/10/2010, referenced in Event Module. Checks for the ID string of an Encounter stowed in the Known\_Encounters dictionary. If it finds the Encounter, then it automatically triggers the Encounter immediately.

### generateEncounter()

Added 6/23/2011. Follows the procedure in the notes section to create encounters. Factors in values stowed in the SpeciesProbsHolder dictionary when figuring up the probabilities.

### moveEncounter()

Added 6/23/2011. Follows the procedure in the notes section to move encounters around, if necessary.

### destroyEncounter()

Added 6/23/2011. Checks conditions of an encounter at its conclusion to see if it needs to be removed from the list of known encounters. Follows the procedure in the notes section.

### calculateRSI()

Added 6/23/2011. While an encounter is running, this method calculates the RSI for that encounter and changes the posture of the encountered fleet if necessary.

## XML

The Encounter\_Handler object, like most of the other objects in the game, is based on XML-driven data; this will help keep the data utilized in the module's design flexible up until SF3's design is finalized (i.e. ships classes and encounters can be added and removed from the game freely, based upon what data is available in the XML files). The Encounter\_Handler object requires two different XML file types, one containing the list of the starships in the game and their stats (the file "craft\_records.xml"), and one containing a list of pre-defined encounters in the game (the file "encounters.xml"). The "craft\_records.xml" file is also required by the Fleet Configuration portion of the Starport Module, and is discussed in detail in its XML discussion area. The following briefly goes over what data is located in the "encounters.xml" file.

### encounters.xml

The file "encounters.xml" is designed as a catalog of pre-defined encounters, which is referenced such that the Event and Plot Handler can trigger the encounter given the correct set of initialization conditions. In SFRPG parlance, the encounters in this list are "tailored encounters", whose purpose is to advance the plot. Entries in the XML file are empty elements named "encounter". Encounter elements have the following set of attributes, all of which are mandatory:

* **id**: This lists a unique identifier for the encounter. If the encounter will be triggered at some point during the course of the game, this id value must match that supplied to the Event and Plot Handler (*for more details, see the Event and Plot Handler Module.*)
* **move**: This indicates whether or not the encounter moves (i.e. if the encounter will track and chase the player's fleet. It must have a value of True or False, with False indicating a stationary encounter.
* **race**: This indicates which race is encountered. This will be used to narrow down the craft that will appear in the encounter.
* **pos**: A tuple, this indicates the position at which the encounter is located. Four values must be included, indicating the Sector (this must match the name of a Sector map), x-coordinate, y-coordinate, and orbital lane (with a value of 999 indicating an encounter in hyperspace).
* **fleet**: Also a tuple, this indicates the specific ships that will be present in the encounter. The names of the craft provided in the fleet must match the ID values of the ships listed for the indicated race present in the craft\_records.xml file (*for information on this XML file, see the discussion under the Starport Fleet Configuration Office Sub-Module.*)

Sample structure of the encounters.xml file:

```

<?xml version="1.0" encoding="UTF-8"?>
 <root table-name="encounters" version="0.1">
  <encounter id="hh12" move="True" race="Humna Humna" pos="delta, 202, 107, 999" fleet="Transport, Frigate, Frigate">
  <encounter id="elthar-esh" move="False" race="Elthar Esh" pos="delta, 198, 154, 1" fleet="Warship">
 </root>

```

## Module Status

*This is current as of June 27, 2010*.

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: Communication Mechanics, Interface and Engine

PREVIOUS: Trading and Commerce Module

TOP