ShieldCycler

Description

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
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%

(values for no manual configurator installed - higher versions of manual configurators will reduce the energy cost)

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 Library v1.7.1 or later installed.

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, 24,900 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, 36,600 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, 61,500 credits, TL 14
Requires Military Shields

Reduced power loss

Allows choosing of a specific setting on Launch

Manual Configurator Advanced, 146,400 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 developers

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 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

The functions are in worldScript["Shield Cycler"]

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

Indexes and Equipment Keys
Version	Shield Cycler (index/key)	Manual Configurator (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(settings_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.