License
-------

This work is licensed under the Creative Commons Attribution-Share Alike 4.0 Unported License.
To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to Creative Commons, 171 Second Street, Suite 300, San Francisco, California, 94105, USA. 

--------------------------------------------------------------

Now Fully Configurable !

Thanks to Svengali and everyone that contributed to the Library OXP.

Background
----------

Why do spaceships have 2 shields and not 1 (round ship) or 12 (dodecahedron station) ?

Early shields could not protect a whole spaceship, only small areas of the ship. Engines, power core, cockpit, crew quarters were among the first areas to get shields protection. Soon this let to many small isolated shield pockets throughout the ship, and that was not managable.

The military (well known for having the 'right' priorities) decided that the crucial parts of a spaceship were 
powercore and cockpit. Without power your weapons are useless, and you also need someone to press the trigger (or repair the powercore ...).

In all existing shipdesigns at the time the powercore was at the back of the ship, and the cockpit at the front side (there was no weapon powerful enough to damage a space station, so they didn't have shields at all). This resulted in aft shields and forward shields.

As shield technology improved, more and more of the ship got shield protection. The closer the aft and forward shielded parts got together, the more they influenced and weakened each other.

A new device was proposed to deal with these problems : a shield inhibitor.

The idea was to put many of these devices in speficic locations in the ship to achieve the desired effect.

During Proof of Concept small scale lab tests of the inhibitor, an intern messed up some settings. Instead of 2 separate shields they had 1 shield for about 2 minutes.

The designer was informed of this, checked and realised he had used simplified algorithms for the basic components. By using the latest quantum physics algortihms for the components, he was able to proof both combining and separation of shields were possible.

Converting the algorithm to a solution usable in a device however was much harder. Analysis showed that solving the combining equations would take atleast 1000 times the computer effort needed for the separation. Guess what solution was chosen by the military ?

Location:

"The Loving Feline", a Seedy Space Bar somewhere in Santaari

While sipping Zaquession evil juice, commander Lone_Wolf (rated competent) reflected upon his trip here.

During the voyage from the witchpoint to the main station, his cobbie had become the target of 10 pirates at once. Injectors saved the cobbie, but while running 6 equipment items had been damaged.

Lone_Wolf was an engineer before he chose a new career path as a bountyhunter/trader and had repaired the items with succes.

What bothered him however was that when the damage occurred, his forward shields were still at full strength. Only the aft shield was depleted.

He knew the shield technology history, but computers had become much more powerful since that choice was made.

"A combining inhibitor would have saved me a lot of work today, and likely have saved the lives of many pilots". 

A few tables further a mixed group of 5 pilots was talking, all were rated dangerous or higher. "Time to ask more experienced pilots"

From the experiended pilots Lone_Wolf learned that there were rumours about a "Shield Equalizer" being in development. No details about it were known though, not even the name of the designer or company.

Lone_Wolf decided it was best to start a design by himself and see if he could find more info.

Fortunately the Loving Feline had a high enough tech level and good hyperspace communications, so he decided to stay there a while. (the presence of both clean and pirate ships near would help with testing).

The first prototype of LW's "Shield Cycler" was ready soon, and worked ok, but lacked options for control and finetuning.
A few weeks later a redesigned prototype was ready for it's first in-flight tests, but no clean pilots were available to help with testing. Lone_Wolf decided to take a break and do some research.

He found out the hypermail address of the developer of "Shield Equalizer" , CommonSenseOTB, and contacted him.

It turned out this guy was indeed working on a similar device, but felt it should be fully automated and need very little pilot control. He also planned to combine the equalizer with a capacitor that stored shield energy & indicated he planned to use the Shield Equalizer as the starting point for a company.

LW had no interest in starting a company, but intended to release the design into the public domain, so engineers everywhere could build it. LW and CSOTB did agree to make their designs compatible, so pilots could use both but their goals were to different to make 1 device.


Shield Cycler
-------------
by Lone_Wolf

Continually adjusts shield energy in automatic or manually chosen configuration:

Equal: equal shields aft and forward
Forward: max forward shield, remainder on aft shield
Aft: max aft shield, remainder (if any) on forward shield
Disabled: inactive

Threshold, launch configuration and enabling/disabling manual cycler settings can be done through Config for AddOns at F4 Station Interfaces while docked if an appropriate version of the Manual Configurator is installed in the player ship.

All adjustments are instantaneous, but use some ship energy.

The energy cost for changing the configuration is related to number of energy banks and the same for all types of cyclers.

Shield adjusting has an energy cost that is a percentage of the amount of energy that needs to be transferred and differs between cycler versions, and the higher versions of the Manual Configurator reduce this energy cost.

Energy cost table for shield adjustments:
(values for no manual configurator installed - higher versions of manual configurators will reduce the energy cost)

Transferred Energy            < 64    64 - 127    128 - 191   192 - 255   256 - 319   > 320
Shield Cycler Basic           6.0%      8.40%       11.76%      16.46%      23.05%    32.27%
Shield Cycler Standard        4.5%      5.85%        7.60%       9.89%      12.85%    16.71%
Shield Cycler Advanced        3.0%      3.60%        4.32%       5.18%       6.22%     7.46%

Shield Cycler and Manual Configurator devices can be damaged, although NOT destroyed. When damaged they will still work, but with reduced functionality. There is a repair option, accessible from the Ship Outfitting F3 screen.

None of the Shield Cycler and Manual Configurator devices are visible in the Equipment screen (F5), they are however visible in tha Manifest screen (F5+F5).

The basic versions of Shield Cycler and Manual Configurator lay the groundwork which the other versions need, that's the main reason why the standard/advanced versions are listed as upgrades. Removal is done by downgrading, but to make it easier for pilots the tech will combine several downgrades into one.

To enjoy all options ShieldCycler offers, you should have 2 other oxps installed :
    Library v1.7.1 or later


Buyable Devices
---------------

Shield Cycler Basic, 100 credits , TL 2
    Works automatically (Equal setting).

Manual Configurator Basic 200 credits, TL 1
    Requires SC Basic or better
    Primable with Shift+n
    Allows in-flight manual switching between Equal/Forward/Aft/Disabled configurations

Shield Cycler Standard, 24900 credits, TL 11
    Reduced power loss
    Requires Shield Booster, compatible with Military Shields
    Allows the setting of a threshold that determines when adjustments begins
    
Manual Configurator Standard, 36600 credits, TL 11
    Requires SC Standard or Advanced
    Primable with Shift+n
    Reduces power loss for shield adjusting by 50%
    Allows in-flight manual switching between Equal/forward/Aft/Disabled configuration
    Power loss for each in-flight change is 2*(number of energy banks)

Shield Cycler Advanced, 61500 credits, TL 14
    Requires Military Shields
    Reduced power loss
    Allows choosing of a specific setting on Launch
    
Manual Configurator Advanced, 146400 credits, TL 14
    Requires SC Advanced
    Primable with Shift+n
    Reduces power loss for shield adjusting by 80%
    Allows disabling any of the possible modes (Equal, Forward, Aft), though at least one needs to be enabled
    Power loss for each in-flight change is 2*(number of energy banks)
    
Sell in-flight configurator, 100 credits, TL 1
    Removes all in-flight configuration devices and thus reverts all to the automatic version, 60% refund

Sell Shield Cycler, 100 credits, TL 1
    Removes all automatic shield cycler devices, 60% refund
    Will only be visible if you have no manual configurator anymore


Notes for OXP delevopers 
------------------------

There are two great changes from v1.x to v2.0:

* In v1.x the Shield Cycler equipments bought were removed, "internal" equipments were kept in ship.equipment and the settings object was the source of truth, i.e., defined the actual SC versions installed (or not) in the ship; in v2.0, the internal SC equipments are there for backwards compatibility only (so a save file from v2.0 can still be used with v1.x), but the equipments bought are kept and the source of truth are the installed equipments, i.e., the settings object will be populated to reflect the Shield Cycler and Manual Configurator versions installed in the ship as seen in ship.equipment. This way, if anything mess up the settings object (like bugs in Ship Storage Helper...), the only thing that happens are configurations like functional %, threshold, initial mode and position in the mode cycle being reset to defaults, but the equipment themselves are not lost and remain functional.

* Version 2.0 was tweaked to make its functionality available to NPC ships; to do that a settings object was placed in the ship's script for NPCs, and the context MUST be set to the ship's script when calling the SC functions (for the player ship the context must be the "Shield Cycler" worldScript).

* The Shield Cycler settings object is meant to be opaque, so it can be changed as needed without raising compatibility issues with other OXPs. Please use the supplied functions to interact with this OXP and contact the maintainer through the Oolite Bulletin Board (http://aegidian.org/bb/viewtopic.php?f=4&t=9772) if they are not enough for your needs.

To make Shield Cycler available to a NPC ship, call worldScripts["Shield Cycler"]._sc_award_equipment with the ship's script as context and passing the equipment key as parameter:

    let ret = worldScripts["Shield Cycler"]._sc_award_equipment.call(this, "EQ_SC_SHIELD_CYCLER_BASIC");
    if (ret)
        // Shield Cycler was awarded and set up
    else
        // Shield Cycler NOT awarded


Functions available for OXPs from worldScripts["Shield Cycler"]
---------------------------------------------------------------

Some functions expect indexes for the SC equipments, others expect an equipment key... both defined bellow:

Version    Shield Cycler                      Manual Configurator
           index/key                          index/key
None       0/None                             0/None
Basic      1/EQ_SC_SHIELD_CYCLER_BASIC        1/EQ_SC_MANUAL_CONFIGURATOR_BASIC
Standard   2/EQ_SC_SHIELD_CYCLER_STANDARD     2/EQ_SC_MANUAL_CONFIGURATOR_STANDARD
Advanced   3/EQ_SC_SHIELD_CYCLER_ADVANCED     3/EQ_SC_MANUAL_CONFIGURATOR_ADVANCED


* _sc_get_sc_versions(versions) (MUST be called with the ship's script as context for NPCs)

Get information about Shield Cycler devices; if the input parameter versions is null, returns info about the devices installed in the ship; if it's not null, it should be an object specifying the SC equipments to retrieve info on, like { sc:<Shield Cycler index>, manual:<Manual Configurator index>}, where index for the equipments are the ones shown above.

The output is an object like (example of the output with input parameter versions==null for a ship with no Shield Cycler equipment installed):
    {
        sc_eqKey: null,
        version: 0,
        version_name: "None",
        manual_eqKey: null,
        manual_version: 0,
        manual_version_name: "None"
    }


* _sc_award_equipment(eqKey) (MUST be called with the ship's script as context for NPCs)

Awards and sets up Shield Cycler equipment (both Shield Cycler devices and Manual Configurator devices); returns true if succeeds, false otherwise.


* _sc_equipment_setup(eqKey) (MUST be called with the ship's script as context for NPCs)

Sets up a previously awarded Shield Cycler equipment.


* _sc_remove_manual() (MUST be called with the ship's script as context for NPCs)

Removes any Shield Cycler Manual Configurator device the ship has installed and resets relevant settings in the ship's script.


* _sc_remove_shield_cycler() (MUST be called with the ship's script as context for NPCs)

Removes any Shield Cycler device the ship has installed and resets the Shield Cycler settings in the ship's script.


* _sc_update_status() (Player's ship only)

Updates Shield Cycler status on Manifest screen (F5).


* _sc_sc_adjust(init, caller) (MUST be called with the ship's script as context for NPCs)

Adjusts the shields, i.e., transfers energy between them if necessary and possible, according to the settings in the ship's script for NPCs or the "Shield Cycler" worldScript for the player's ship. It uses the Shield Capacitors if installed, functional and charged.

The input parameter 'init' is a boolean that should be true whenever a change was made to the Shield Cycler mode (Equal, Forward, Aft or Disabled), and false otherwise. The input parameter 'caller' is a string identifying the caller OXP for logging purposes.

This function updates the ship's properties with the new shield strengths and deducts any energy cost from the ship's energy.


* _sc_adjust(adjust)

Lower level function to adjust the shields, kept for compatibility with N-Shields v0.7 - please use _sc_sc_adjust described above!


* _sc_stop() (MUST be called with the ship's script as context for NPCs)

Disables Shield Cycler for the ship.


* _sc_start() (MUST be called with the ship's script as context for NPCs)

Enables Shield Cycler for the ship.


* _sc_store_devices() (MUST be called with the ship's script as context for NPCs)

Gets the Shield Cycler settings for storage.

Returns an object like:
    {
        json: <JSON string with Shield Cycler settings>,
        enc: ""
    }

Compatibility notes:
    * the return object was kept as is for compatibility reasons, but its property 'enc', that in previous versions had an encrypted version of the JSON settings string, is now empty (Cabal Common Library, used for encryption, is deprecated);
    * in previous versions calling this function would remove the Shield Cycler and Manual Configurator devices from the ship - THAT IS NOT TRUE ANYMORE... calling this function now doesn't change anything in the ship... if the equipments really are to be removed, the caller must calli the _sc_remove_* functions after calling this function.


* _sc_retrieve_devices(setting_object) (MUST be called with the ship's script as context for NPCs)

Re-instates the stored settings in the ship. The input parameter 'settings_object' must be the output of _sc_store_devices.

If the settings being re-instated are from a 1.x version of Shield Cycler, this function will award the Shield Cycler equipments specified in the settings to the ship, otherwise it will use the auxiliary settings (like thresholds and functional %) from the settings and look at the Shield Cycler equipments previously awarded to the ship and set them up.
