Difference between revisions of "ShieldCycler"

From Elite Wiki
m (typo)
m (→‎Buyable Devices: Formatting)
 
(16 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
[[Image:OXPConfig_logo.png|150px|right]]
  
  +
'''Shield Cycler Next''' is the newest version of '''Shield Cycler'''
−
[[Image:CCL_logo.png|150px|right]]
  
 
== Description ==
  
== Description ==
   
−
Continually adjusts shield energy in automatic or manually chosen configuration.
 +
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
   
−
Both - Equal shields aft and forward
  
  +
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.
   
−
Forward - Max forward shield, remainder on aft shield
  
  +
All adjustments are instantaneous, but use some ship energy.
   
−
Aft - Max aft shield, remainder (if any) on forward shield
  
  +
The energy cost for changing the configuration is related to number of energy banks and the same for all types of cyclers.
   
−
Disabled : inactive
  
  +
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.
  +
  +
  +
{| class="wikitable"
  +
|+
  +
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₢, TL 2
  +
*: Works automatically (Equal setting).
  +
  +
* '''Manual Configurator Basic''' 200₢, 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₢, 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₢, 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₢, TL 14
  +
*: Requires Military Shields
  +
*: Reduced power loss
  +
*: Allows choosing of a specific setting on Launch
  +
  +
* '''Manual Configurator Advanced''', 146,400₢, 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₢, TL 1
  +
*: Removes all in-flight configuration devices and thus reverts all to the automatic version, 60% refund
  +
  +
* ''Sell Shield Cycler'', 100₢, 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 [http://aegidian.org/bb/viewtopic.php?f=4&t=9772) 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:
  +
  +
<code> 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</code>
  +
  +
=== Functions available for OXPs ===
  +
  +
The functions are in <code>worldScript["Shield Cycler"]</code>
  +
  +
Some functions expect indexes for the SC equipments, others expect an equipment key... both defined bellow:
  +
  +
{| class="wikitable"
  +
|+
  +
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
  +
|}
  +
  +
  +
;<code>_sc_get_sc_versions(versions)</code>
  +
:(MUST be called with the ship's script as context for NPCs)
  +
  +
:Get information about Shield Cycler devices; if the input parameter <code>versions</code> is <code>null</code>, returns info about the devices installed in the ship; if it's not <code>null</code>, it should be an object specifying the SC equipments to retrieve info on, like:
  +
  +
: <code>{ sc:<Shield Cycler index>, manual:<Manual Configurator index>}</code>
  +
  +
: where index for the equipments are the ones shown above.
  +
  +
:The output is an object like (example of the output with input parameter <code>versions==null</code> for a ship with no Shield Cycler equipment installed):
  +
<code> {
  +
sc_eqKey: null,
  +
version: 0,
  +
version_name: "None",
  +
manual_eqKey: null,
  +
manual_version: 0,
  +
manual_version_name: "None"
  +
}</code>
  +
  +
  +
;<code>_sc_award_equipment(eqKey)</code>
  +
:(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.
  +
  +
  +
;<code>_sc_equipment_setup(eqKey)</code>
  +
:(MUST be called with the ship's script as context for NPCs)
  +
  +
:Sets up a previously awarded Shield Cycler equipment.
  +
  +
  +
;<code>_sc_remove_manual()</code>
  +
:(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.
  +
  +
  +
;<code>_sc_remove_shield_cycler()</code>
  +
:(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.
  +
  +
  +
;<code>_sc_update_status() </code>
  +
:(Player's ship only)
  +
  +
:Updates Shield Cycler status on Manifest screen (F5).
  +
  +
  +
;<code>_sc_sc_adjust(init, caller)</code>
  +
:(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 <code>init</code> 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 <code>caller</code> 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.
  +
  +
  +
;<code>_sc_adjust(adjust)</code>
  +
:Lower level function to adjust the shields, kept for compatibility with N-Shields v0.7 - please use _sc_sc_adjust described above!
  +
  +
  +
;<code>_sc_stop()</code>
  +
:(MUST be called with the ship's script as context for NPCs)
  +
  +
:Disables Shield Cycler for the ship.
  +
  +
  +
;<code>_sc_start()</code>
  +
:(MUST be called with the ship's script as context for NPCs)
  +
  +
:Enables Shield Cycler for the ship.
  +
  +
  +
;<code>_sc_store_devices()</code>
  +
:(MUST be called with the ship's script as context for NPCs)
  +
  +
:Gets the Shield Cycler settings for storage.
  +
  +
:Returns an object like:
  +
<code> {
  +
json: <JSON string with Shield Cycler settings>,
  +
enc: ""
  +
}</code>
  +
  +
:;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.
   
−
All adjustments are instantaneous, but use some ship energy.
  
   
  +
;<code>_sc_retrieve_devices(settings_object)</code>
  +
:(MUST be called with the ship's script as context for NPCs)
   
−
Details, comments, bugreports [http://aegidian.org/bb/viewtopic.php?p=138226 in the forum].
  
  +
:Re-instates the stored settings in the ship. The input parameter <code>settings_object</code> must be the output of <code>_sc_store_devices</code>.
   
−
Note : the function descriptions below are valid for Shield Cycler Next 1.11.2+
  
  +
: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.
   
−
== Functions ==
 +
== License ==
−
=== _sc_stop() ===
  
−
{{CodeEx|codeex=worldScripts["Shield Cycler"]._sc_stop = function(device)}}
  
−
Stop SC devices
  
   
−
'''Parameters'''
  
  +
This OXP is licensed under the [https://creativecommons.org/licenses/by-sa/4.0/legalcode CC-BY-SA 4.0].
−
:;device :String.
 
−
:;values :
  
−
::"ALL" - stop all devices managed by Shield Cycler
  
−
::"SC" - stop SC devices only
  
−
:: for current versions of SC there is no difference in results of the 2 options, but this will change in future versions.
  
   
  +
== Downloads ==
   
−
'''Returns'''
  
  +
[[Media:ShieldCycler-2.1.oxz|Shield Cycler Next v2.1]]
−
:: -3 if Shield Cycler has been disabled
  
−
:: -2 if device was already stopped
  
−
:: -1 device == invalid value
  
−
:: 0 stopping was succesfull
  
   
−
=== _sc_start() ===
  
  +
Previous version:
−
{{CodeEx|codeex=worldScripts["Shield Cycler"]._sc_stop = function(device)}}
  
   
−
Start SC devices
  
  +
[[Media:ShieldCycler_1.12.oxz|Shield Cycler v1.12]]
   
−
'''Parameters'''
  
  +
== Version History ==
−
:;device :String.
 
−
:;values :
  
−
::"ALL" - start all devices managed by Shield Cycler
  
−
::"SC" - start SC devices only
  
−
:: for current versions of SC there is no difference in results of the 2 options, but this will change in future versions.
  
   
  +
v2.1 (by Dybal)
  +
* Fixes bug parsing the missionVariable when it holds an empty string.
  +
* Defines scriptInfo.towbar_max_salvage_price for Shield Cycler and Shield Cycler Manual Configurator Standard and Advanced.
   
−
'''Returns'''
  
  +
v2.0 (by Dybal)
−
:: -3 if Shield Cycler is in disabled status
  
  +
* Adds functions for other OXPs to award and remove Shield Cycler equipments to NPC ships.
−
:: -2 if device was already started
 
  +
* Higher level function to be used by other OXPs to adjust shields through Shield Cycler.
−
:: -1 device == invalid value
  
  +
* Feeds Shield Capacitors energy into the shields before adjusting if they are installed and charged for both player's ship and NPCs.
−
:: 0 starting was succesfull
  
  +
* Most functions for other OXPs are NPC-ready and should be called with the ship's script as context for NPCs.
  +
* EQ_SC_SHIELD_CYCLER_INTERNAL and EQ_SC_MANUAL_CONFIGURATOR_INTERNAL are not used anymore (but kept for backwards compatibility), the ship keeps the versioned EQ_SHIELD_CYCLER_<version> and EQ_SC_MANUAL_CONFIGURATOR_<version> equipments that are sold at Ship Outfitting (F3).
  +
* The installed equipments are the "source of truth" and the settings object will be adjusted to reflect them; for player's ship, that happens at every launch, for NPCs only when the _sc_award_equipment, _se_equipment_setup or _sc_retrieve_devices are called.
  +
* Doesn't refund the Shield Cycler equipment value when the player buys a new ship: if the old ship was part of the payment, the equipment value (EQ_SC_SHIELD_CYCLER_<version> and EQ_SC_MANUAL_CONFIGURATOR_<version> keep their acquisition price, while EQ_SC_<equipment>_INTERNAL had 1Cr for price) was factored in the old ship's resale value; if not part of the payment, the ship was stored in Hyperspace Hangar with the Shield Cycler equipment installed.
  +
* Energy cost is now proportional to the energy actually transferred between shields instead of a flat-fee for energy transfer range (that was prohibitive for the small transfers that occur after a little while in combat).
  +
* _sc_store_devices (used by Ship Storage Helper OXP) doesn't remove the Shield Cycler devices from the ship.
  +
* _sc_retrieve_devices (used by Ship Storage Helper OXP) is now functional, the bugs have been squashed.
  +
* Major code re-factoring and many small bug fixes.
  +
* Should still be backwards compatible, i.e., a savefile of a player ship with Shield Cycler v2.0 should still work with Shield Cycler Next 1.12.
  +
* Changes from OXPConfig to Library, drops use of Cabal Common Library.
  +
* Can be promoted from development to production version.
   
−
=== _sc_store_devices() ===
  
  +
v1.12.1
−
{{CodeEx|codeex=worldScripts["Shield Cycler"]._sc_store_devices = function()}}
  
  +
* upon repair, equipment wasn't removed which made consecutive repairs impossible
  +
* transfer needed in aft & forward setting was calulated wrong, this could sometimes result in unwanted free shield strength out of nowhere.
  +
* With capacitors and shieldcycler both active, there were some weird effects.
  +
* Although codewise they don't clash, i've changed the code so that SC will only cycle AFTER relevant capacitors are emptied.
   
−
Allow other oxps like Ship Storage Helper to store values of SC devices
  
  +
v1.12
  +
* new stable version
  +
* small fixes
   
−
'''Parameters'''
  
  +
v1.11.3
−
:;none
  
  +
* Upon buying a new ship, shield cycler devices were not removed anymore, corrected.
  +
* small fixes
   
−
'''Returns'''
  
  +
v1.11.2
−
:; an object with 2 strings
 
  +
* Cabal Common Library and OxpConfig are now required dependencies
−
:: first string holds SC values in JSON format
  
  +
* new external methods _sc_store_devices & _sc_retrieve_devices : allows Ship Storage Helper to store/retrieve ships with SC devices installed correctly
−
:: second string is encrypted version of 1st string
  
  +
  +
v1.11.1
  +
* bugfix in shipLaunchedEscapePod
  +
* implemented 1.82 functionality
  +
* Minimum Oolite version is now 1.81
   
−
=== _sc_retrieve_devices() ===
  
  +
v1.11
−
{{CodeEx|codeex=worldScripts["Shield Cycler"]._sc_retrieve_devices = function(sc_values)}}
  
  +
* switch from unbreakable equipment to loss of functionality when damaged; used schema :
  +
:every direct hit will reduce functionality by 10% , but it won't go below 40% functionality
  +
:since the presence / absence of shield booster and mil shields already influences SC performance, there is no additonal functionality loss when they are damaged
  +
* new repair option when docked (F3 screen)
  +
:repair price :
  +
::calculate total price of all installed SC devices
  +
::multiply by .5
  +
::multiply with (100 -functionality)/100
   
−
Allow other oxps like SSH to set SC devices
  
  +
v1.10.2
  +
* oxpcSettings : switched from Notify to DynamicNotify
  +
* conflicts with ShieldCycler 1.0 oxz
  +
* released as oxz
   
−
'''Parameters'''
  
  +
v1.10.1
−
:;sc_values : object as created by _sc_store_devices
  
  +
* small bugfixes
   
−
'''Returns'''
  
  +
v1.10
−
:; integer
  
  +
* Major rewrite: code split over many (currently 9) script files instead of 2 to improve maintainability / flexibility.
−
:: 0 - import successfull
  
  +
* objects are used to share information between scripts where possible
−
:: 1 - input != an object
  
  +
* oxp disables itself if savegame to old or to new.
−
:: 2 - sc_values has wrong structure
  
  +
* start/stop functionality changed
−
:: 3 - first string in sc_values is invalid json data
  
  +
* new option through oxpconfig to disable entire oxp (the options for pilots to disable Shield Cycler were limited and dependant on having certain equipment).
−
:: 4 - plain version doesn't match encrypted version
  
  +
* use JSON for missionvariables
−
:: 5 - stored data to old
  
  +
* add functionality for npc ships to use shield cycler (npc ships wanting to use this will need a custom ship script to give them shield functionality, an alternative would be to adjust customshields oxp to use this new functionality)
−
:: 6 - stored data to new
  
  +
* display device versions & damage level on F5+F5 screen (damage level won't change until 1.11.0 )
  +
* power loss for changing configuration was 2 * (nr_of_energybanks + 1) , this led to a ship with 8 banks loosing almost an entire bank of energy after just 3 changes. new formula : nr_of_energybanks + 5
  +
* added shipLaunchedEscapePod event
   
−
=== Downloads ===
  
  +
v1.0
  +
* added code to test for savegames created with 1.10+ (JSON)
  +
* minor fix in equipment.plist
  +
* license changed to CC-by-SA 4
  +
* released as oxz & oxp
   
−
Oolite 1.82+
  
  +
v0.31
  +
* new function : b-key sets shieldcycler back to whatever the launch setting is
  +
* optimizied & simplified code
  +
* updated CCL / OxpConfig requirements
  +
* added manifest.plist to oxp
  +
* requires Oolite 1.80
   
−
Stable version 1.12
  
  +
v0.30.3
  +
* adjusted to work with CCL 1.6 & OxpConfig 2.0.12
   
−
[https://app.box.com/s/6rl55tkwfh8kqpbk9gc9ng5wvgza1rhn ShieldCycler oxp v.1.12]
  
  +
v0.30.2
  +
* small fixes
  +
* updated to check for recent cabal_common & oxpconfig versions
  +
* auto-sell cycler devices when player buys a new ship
   
−
[[Media:ShieldCycler_1.12.oxz|here]] OXZ format (downloaded {{#downloads:ShieldCycler_1.12.oxz}} times).
  
  +
v0.30.1
  +
* bugfixes
  +
* encountered problems related to different JS execution contexts for equipment event handlers, shipscript event handlers and worldscript event handlers, rewrite has as side-benefit that the code no longer uses global vars ( except missionvars) .
  +
* added sc_stop & sc-start functions so other oxps can stop/start cycler functionality
  +
* more in-script documentation
   
−
Development version 1.12
  
  +
v0.21.2
  +
* added configurable options - requires Cabal Common Library 1.4.1 (or later) and OxpConfig2 2.03 (or later)
  +
* If CCL / OxpConfig2 are not present or to old, everything works but there will be no configure options
  +
* cleaned up/ optimised code
   
−
[https://app.box.com/s/lj8fwh3zjs0o73ru79511bzs3lkvjc35 ShieldCycler Next 1.12, oxp format]
  
  +
0.20.1
  +
* cycling to forward when forward shield was at full strength used energy, corrected.
   
−
[[Media:ShieldCycler_Next_1.12.oxz|oxz format]] (downloaded {{#downloads:ShieldCycler_Next_1.12.oxz}} times).
  
  +
v0.20
  +
* brought back disabled setting (was removed in 0.14 )
  +
* shipLaunchedFromStation didn't check if player has a shield cycler, fixed
  +
* Equipment names changed to EQ_SC_AAAAAA scheme
  +
* variables now all start with sc_
  +
* both automatic and manual versions are now available, see above for details
  +
* halved power needed for switching configuration, as old number meant 4 switches would drain a complete energybank
  +
* preparations to use OxpConfig for changing settings in later version
   
   
−
=== Older versions ===
  
  +
v0.14
  +
* Basic Shield cycler made incompatible with Shield Booster and Mil. Shields
  +
* Standard Shield cycler incompatible with Mil. Shields
  +
* cycling the configuration now subtracts 4 * # of energy banks from ship energy.
  +
* adjusting also uses shield energy, but the amount is now fixed and related to the transferred amount of shield energy.
   
−
Oolite 1.80+
  
−
Old version 1.0 :
 
   
−
[https://app.box.com/s/2rus854tuxius9e4788t ShieldCycler oxp v.1.0]
  
  +
v0.13
  +
* created basic, standard & advanced version incl. sell option.
  +
* cycling / adjusting uses ship energy
  +
* added EQ_Shield_Equalizer as incompatible equipment
  +
* clean / optimize code
   
−
[[Media:ShieldCycler_1.0.oxz|here]] OXZ format (downloaded {{#downloads:ShieldCycler_1.0.oxz}} times).
  
  +
v0.12
  +
* first public version with 1 device
   
−
Oolite 1.76 : [http://www.box.net/shared/n3hfrf5m93 ShieldCycler OXP v0.30.3].
  
  +
== Quick Facts ==
   
  +
{{OXPLevel|2}}
  +
{{IconOXP|ooVersion="1.81"|oxpCPU="Low"|oxpMEM="Low"|oxpGPU="Low"|oxpIsConfigurable=true|oxpIsAPI=true|oxpIsDocumented=true}}
  +
{|class="floatright" style="alignment:right;margin: 0 auto;"
  +
|[[Image:IconLib.png|48px|right|link=Library|alt=Config options available through 'Library']]
  +
|}
  +
{{Infobox OXPb| title Shield Cycler
  +
|version = 2.1
  +
|release = 2020-11-03
  +
|license = CC-BY-SA 4.0
  +
|features = Distributes shield energy between fore and aft shields.
  +
|category = Equipment OXPs
  +
|author = [[User:Lone_Wolf|Lone_Wolf]]
  +
|feedback = [http://aegidian.org/bb/viewtopic.php?f=4&t=9772 Oolite BB]
  +
}}
   
  +
== Gameplay and Balance indicator ==
  +
[[File:Tag-colour-blue.png]]
   
−
[[Category:OXPConfig-compatible OXPs]] [[Category:Equipment OXPs]] [[Category:Oolite_expansion_packs]] [[Category:Required_OXP-Cabal_Common_Library]]
  
  +
{{Equipment-OXP}}

Latest revision as of 16:44, 18 July 2021

Shield Cycler Next is the newest version of Shield Cycler

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₢, TL 2
    Works automatically (Equal setting).
  • Manual Configurator Basic 200₢, 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₢, 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₢, 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₢, TL 14
    Requires Military Shields
    Reduced power loss
    Allows choosing of a specific setting on Launch
  • Manual Configurator Advanced, 146,400₢, 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₢, TL 1
    Removes all in-flight configuration devices and thus reverts all to the automatic version, 60% refund
  • Sell Shield Cycler, 100₢, 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.

License

This OXP is licensed under the CC-BY-SA 4.0.

Downloads

Shield Cycler Next v2.1

Previous version:

Shield Cycler v1.12

Version History

v2.1 (by Dybal)

  • Fixes bug parsing the missionVariable when it holds an empty string.
  • Defines scriptInfo.towbar_max_salvage_price for Shield Cycler and Shield Cycler Manual Configurator Standard and Advanced.

v2.0 (by Dybal)

  • Adds functions for other OXPs to award and remove Shield Cycler equipments to NPC ships.
  • Higher level function to be used by other OXPs to adjust shields through Shield Cycler.
  • Feeds Shield Capacitors energy into the shields before adjusting if they are installed and charged for both player's ship and NPCs.
  • Most functions for other OXPs are NPC-ready and should be called with the ship's script as context for NPCs.
  • EQ_SC_SHIELD_CYCLER_INTERNAL and EQ_SC_MANUAL_CONFIGURATOR_INTERNAL are not used anymore (but kept for backwards compatibility), the ship keeps the versioned EQ_SHIELD_CYCLER_<version> and EQ_SC_MANUAL_CONFIGURATOR_<version> equipments that are sold at Ship Outfitting (F3).
  • The installed equipments are the "source of truth" and the settings object will be adjusted to reflect them; for player's ship, that happens at every launch, for NPCs only when the _sc_award_equipment, _se_equipment_setup or _sc_retrieve_devices are called.
  • Doesn't refund the Shield Cycler equipment value when the player buys a new ship: if the old ship was part of the payment, the equipment value (EQ_SC_SHIELD_CYCLER_<version> and EQ_SC_MANUAL_CONFIGURATOR_<version> keep their acquisition price, while EQ_SC_<equipment>_INTERNAL had 1Cr for price) was factored in the old ship's resale value; if not part of the payment, the ship was stored in Hyperspace Hangar with the Shield Cycler equipment installed.
  • Energy cost is now proportional to the energy actually transferred between shields instead of a flat-fee for energy transfer range (that was prohibitive for the small transfers that occur after a little while in combat).
  • _sc_store_devices (used by Ship Storage Helper OXP) doesn't remove the Shield Cycler devices from the ship.
  • _sc_retrieve_devices (used by Ship Storage Helper OXP) is now functional, the bugs have been squashed.
  • Major code re-factoring and many small bug fixes.
  • Should still be backwards compatible, i.e., a savefile of a player ship with Shield Cycler v2.0 should still work with Shield Cycler Next 1.12.
  • Changes from OXPConfig to Library, drops use of Cabal Common Library.
  • Can be promoted from development to production version.

v1.12.1

  • upon repair, equipment wasn't removed which made consecutive repairs impossible
  • transfer needed in aft & forward setting was calulated wrong, this could sometimes result in unwanted free shield strength out of nowhere.
  • With capacitors and shieldcycler both active, there were some weird effects.
  • Although codewise they don't clash, i've changed the code so that SC will only cycle AFTER relevant capacitors are emptied.

v1.12

  • new stable version
  • small fixes

v1.11.3

  • Upon buying a new ship, shield cycler devices were not removed anymore, corrected.
  • small fixes

v1.11.2

  • Cabal Common Library and OxpConfig are now required dependencies
  • new external methods _sc_store_devices & _sc_retrieve_devices : allows Ship Storage Helper to store/retrieve ships with SC devices installed correctly

v1.11.1

  • bugfix in shipLaunchedEscapePod
  • implemented 1.82 functionality
  • Minimum Oolite version is now 1.81

v1.11

  • switch from unbreakable equipment to loss of functionality when damaged; used schema :
every direct hit will reduce functionality by 10% , but it won't go below 40% functionality
since the presence / absence of shield booster and mil shields already influences SC performance, there is no additonal functionality loss when they are damaged
  • new repair option when docked (F3 screen)
repair price  :
calculate total price of all installed SC devices
multiply by .5
multiply with (100 -functionality)/100

v1.10.2

  • oxpcSettings : switched from Notify to DynamicNotify
  • conflicts with ShieldCycler 1.0 oxz
  • released as oxz

v1.10.1

  • small bugfixes

v1.10

  • Major rewrite: code split over many (currently 9) script files instead of 2 to improve maintainability / flexibility.
  • objects are used to share information between scripts where possible
  • oxp disables itself if savegame to old or to new.
  • start/stop functionality changed
  • new option through oxpconfig to disable entire oxp (the options for pilots to disable Shield Cycler were limited and dependant on having certain equipment).
  • use JSON for missionvariables
  • add functionality for npc ships to use shield cycler (npc ships wanting to use this will need a custom ship script to give them shield functionality, an alternative would be to adjust customshields oxp to use this new functionality)
  • display device versions & damage level on F5+F5 screen (damage level won't change until 1.11.0 )
  • power loss for changing configuration was 2 * (nr_of_energybanks + 1) , this led to a ship with 8 banks loosing almost an entire bank of energy after just 3 changes. new formula : nr_of_energybanks + 5
  • added shipLaunchedEscapePod event

v1.0

  • added code to test for savegames created with 1.10+ (JSON)
  • minor fix in equipment.plist
  • license changed to CC-by-SA 4
  • released as oxz & oxp

v0.31

  • new function : b-key sets shieldcycler back to whatever the launch setting is
  • optimizied & simplified code
  • updated CCL / OxpConfig requirements
  • added manifest.plist to oxp
  • requires Oolite 1.80

v0.30.3

  • adjusted to work with CCL 1.6 & OxpConfig 2.0.12

v0.30.2

  • small fixes
  • updated to check for recent cabal_common & oxpconfig versions
  • auto-sell cycler devices when player buys a new ship

v0.30.1

  • bugfixes
  • encountered problems related to different JS execution contexts for equipment event handlers, shipscript event handlers and worldscript event handlers, rewrite has as side-benefit that the code no longer uses global vars ( except missionvars) .
  • added sc_stop & sc-start functions so other oxps can stop/start cycler functionality
  • more in-script documentation

v0.21.2

  • added configurable options - requires Cabal Common Library 1.4.1 (or later) and OxpConfig2 2.03 (or later)
  • If CCL / OxpConfig2 are not present or to old, everything works but there will be no configure options
  • cleaned up/ optimised code

0.20.1

  • cycling to forward when forward shield was at full strength used energy, corrected.

v0.20

  • brought back disabled setting (was removed in 0.14 )
  • shipLaunchedFromStation didn't check if player has a shield cycler, fixed
  • Equipment names changed to EQ_SC_AAAAAA scheme
  • variables now all start with sc_
  • both automatic and manual versions are now available, see above for details
  • halved power needed for switching configuration, as old number meant 4 switches would drain a complete energybank
  • preparations to use OxpConfig for changing settings in later version


v0.14

  • Basic Shield cycler made incompatible with Shield Booster and Mil. Shields
  • Standard Shield cycler incompatible with Mil. Shields
  • cycling the configuration now subtracts 4 * # of energy banks from ship energy.
  • adjusting also uses shield energy, but the amount is now fixed and related to the transferred amount of shield energy.


v0.13

  • created basic, standard & advanced version incl. sell option.
  • cycling / adjusting uses ship energy
  • added EQ_Shield_Equalizer as incompatible equipment
  • clean / optimize code

v0.12

  • first public version with 1 device

Quick Facts

Levelindicator2.png
2-{{{2}}}

Minimum Oolite versionCPU usage lowMemory usage lowGPU usage lowisAPIisDocumentedisConfigurable

Config options available through 'Library'
Version Released License Features Category Author(s) Feedback
2.1 2020-11-03 CC-BY-SA 4.0 Distributes shield energy between fore and aft shields. Equipment OXPs Lone_Wolf Oolite BB

Gameplay and Balance indicator

Tag-colour-blue.png

Retrieved from "http://backup.witchspacewiki.org/index.php?title=ShieldCycler&oldid=67447"