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. 

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

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.
