Expansion N-Shields

Content

• Warnings
• Manifest
• Documentation
• 2 Equipment
• 41 Ships
• 0 Models
• 3 Scripts

Also read http://wiki.alioth.net/index.php/N-Shields

Readme.txt

N-Shields OXP
-------------
v1.0.2, by 'Ngalo'


Gives NPCs simulated shields, with the default setting (as in CustomShields) being a 'fair' emulation of the player's shields.

Calls Shield Cycler (versions 2.x and above), if installed, to adjust shields after taking the damage from the shield.

Acts as a hub for handling damage to NPCs, calling damage handlers from other OXPs after the shields are depleted and the damage reach the ship's hull.

Awards Shield Cycler for a percentage of the ships that don't have them, configures Shield Booster and Military SHield Booster for NPCs that have them, apply shield recharge enhancements from Energy Grid (civillian and naval) for ships that have them.


Settings in the N-Shields.js script
-----------------------------------

* this._NPC_shields = true;
    Switch simulated shields on or off. If false, visual effects will be drawn based on energy level.
    
* this._Thargoid_shields = true;
    As above, but applies to Thargoids.
    
* this._Thargoid_energyReduction = true;
    Reduce Thargoids' energy banks to balance their new shields.

* this._NPC_flasherColours = 1;
    Pre-defined flasher list to use for standard NPC shields.
    Options:
        0: "_multicolour1", simple and bright
        1: "_multicolour2", slightly different colours, reduced alpha when low
        2: "_multicolour3", reverse colour order (red high, blue low)
        3: "_green", the Thargoid default (but can be used for other NPCs too)
        4: "_blue", various shades of blue
        
* this._Thargoid_flasherColours = 3;
    Colour for Thargoid shields, options as above.
    
* this._flasherScale = 1;
    Scale factor for flasher effects.


Notes For OXP Developers
------------------------

* script_info properties (in shipdata.plist):

    * npc_shields = "no";
        N-Shields ignores the ship and doesn't do anything.

    * NShields_flasherKeys = ("myRed1", "myRed2", "myRed3", "myRed3", "myRed4");
        A list of partial effectdata.plist keys, which will be prefixed with "N-Shields_flasher_" to obtain the full key for each flasher or other visualEffect.
        Ordered from lowest shield level to highest in 32-point increments.
    
    * NShields_flasherPreset = 3;
        Number indicating one of the pre-defined flasher lists.
        See above for available options.
        
    * max_shield_aft = 128;
    * max_shield_forward = 128;
    * shield_recharge_aft = 2.0;
    * shield_recharge_forward = 2.0;
        Customise shield levels and recharge rates for this ship.
        The example above shows the standard default shields.
        Note that these can apply to player ships as well as NPCs.
        For Thargoid vessels, use 'upper' and 'lower' instead of 'forward' and 'aft'.
    
    * NShields_energyReduction = 128;
        Specify an energy-bank reduction which will be applied when shields are set up.
        This is intended for two purposes:
        1) For mission ships, to prevent already-difficult opponents becoming impossible
        2) For ships which are 'supposed' to have strong shields, but 'fake it' with bigger energy banks when N-Shields is not installed.
    
    * NShields_exploders = ("NShields-explode-ring-red")
        Custom exploder effect list. The example would make your ship spawn red(ish) ring explosions when its shields are hit.
    
    * NShields_protect_subentities = "no";
        If defined as shown, shields will not protect frangible subentities on this ship.
        The subentities may be left exposed, or given their own shield configurations like any other ship.

    The script_info keys "NShields_config" and "NShields_colours" are no longer supported.
    

* Compatibility with other shipTakingDamage handler overrides

    N-Shields provides an array onto which other OXPs can push their NPC shipTakingDamage handlers instead of actually overriding the handler in the ship script. Functions in this array will imitate the player's world-script shipTakingDamage handler; that is, they are called for every hit but with the 'amount' parameter only conveying damage which actually penetrated the shields (0 if the hit was entirely absorbed by shields). This approach ensures your handler will be called in the same manner regardless of OXP loading order and avoids any need for your OXP to detect which shield was hit and whether it's still up.

    There are two ways to use this feature:

    1) In your script's startUp handler:

        if (worldScripts.NShields && worldScripts.NShields.$shipHasShields(ship)) {
            worldScripts.NShields._damageHandlers.push(my_shipTakingDamage_override) //replace my_shipTakingDamage_override with your handler name
        } else {
            //apply your handler override directly here
        }

       This approach applies your handler to all ships which have simulated shields, but not to those which don't. If you need to choose which ships get the handler yourself, use the other option:

    2) In your script's shipSpawned handler, once you have decided that a ship should get your shipTakingDamage override:

        if (worldScripts.NShields && worldScripts.NShields.$shipHasShields(ship)) {
            if (!ship.script._NShields_damageHandlers) ship.script._NShields_damageHandlers = []; //set up the array if N-Shields hasn't run its shipSpawned handler yet
            ship.script._NShields_damageHandlers.push(my_shipTakingDamage_override) //replace my_shipTakingDamage_override with your handler name
        } else {
            //apply your handler override directly here
        }
    
* function to configure NPC ship

    N-Shields makes available to other OXPs a function to configure the NPC's shields after awarding of any defense-related equipment to it:

    worldScripts.NShields.$configureShip(ship)

    This idempotent (i.e. can be called several times without adverse effects) function will configure the ship's shields taking into account any script_info properties defined and the equipments isntalled in the ship, like Shield Booster, Military Shield Enhancement, Energy Grid, Shield Cycler, etc.


License
-------

You may use, adapt, distribute etc. this Oolite Expansion Pack as permitted by the Creative Commons Attribution-NonCommercial-ShareAlike License (CC-BY-NC-SA).


Acknowledgements
----------------

This OXP owes most of its inspiration and a little code to CustomShields OXP by CommonSenseOTB.
phkb and Norby have been very helpful in finding and fixing bugs.


Version History
---------------

1.0.2
* Fixes bug: once fully recharged, NPC and Thargoid shidels didn't recharge anymore.

1.0.1 (by Dybal)
* Doesn't add shields to scoopable "ships" (that includes all variations of escape capsules, even if their primary role happens to be different from escape-capsule).
* Fixes bugs that broke idempotency of $configureShip (leading to infinite loops at damage handling if $configureShip was called twice on the same ship).
* Fixes bug that led to "invulnerable ship" if the ship's script had its own shipTakingDamage event handler.


1.0 (by Dybal)
* Drops support for Shield Cycler (and Shield Cycler Next) 1.x for NPCs.
* Creates idempotent function for OXPs to call to configure a NPC's shields.
* Encapsulates modifications of ship's energy to verify for NaN before assigning a value into ship.energy (to prevent "invulnerable ship" bug).
* Adds delay to shipSpawned before setting up the ship to allow other OXPs' shipSpawned to award equipments.
* Configures shield recharge rate with Energy Grid (civilian and naval) upgrades if the NPC has them installed.
* Configures both Military Shield Enhancement and Shield Enhancer for NPCs.
* Doesn't award Shield Cycler to NPCs that have Shield Equalizer.
* Fixes bugs in handling of damage to subentities.
* Standardizes script object properties names: functions references start with '$' (except event handlers), everything else starts with '_';

0.7.1    
* Fixed missing "use strict" in N-Shields.js.
* Removed Ship Configuration compatibility script entry from world-scripts.plist (the actual script was removed in 0.7.0).
* Reduced Thargoids' max shields (and compensatory energy reduction) slightly.

0.7
* Removed support for unusual/configurable shield types, except dorsal/ventral which now applies to Thargoids only, in order to simplify the scripts.
* Changed flashers from Ship entities to VisualEffects.
* Pre-defined flasher colour options: 3x Multicolour, Green, Blue.
* Hemisphere glow effects removed.
* New script_info keys NShields_flasherPreset, NShields_flasherKeys, max_shield_forward etc. to replace the now-unsupported NShields_colours, NShields_config.
* Config interface now works correctly (requires Oolite 1.83 or higher and Library OXP).
* Improved efficiency of hit-location code.
* Tentative support for Shield Cyclers on NPCs.

0.6.4
* Fixed bug in $locateHit cloaked-attacker handling (missing a ".position" or two).

0.6.3
* Fixed some bugs in NPC Equipment Damage compatibility code

0.6.2
* Fixed bug in manifest (missing "}").

0.6.1
* Added correctly functioning shipconfig version check and fixed small variable non-declaration in $drawSparks

0.6
* Added user-friendly configuration options via Library OXP.
* Hemisphere glow effects now work, although they still look awful.
* Added compatibility with NPC Equipment Damage OXP.

0.5.4
* Removed non-functioning version check; tested & corrected quaternion multiplication.

0.5.3
* Added version check in NShields-shipconfig-compatibility.js as requested by phkb

0.5.2
* Attempt to fix buggy aft shield effect orientation by using quaternion multiplication. Untested due to oolite-trunk launching error.

0.5.1
* Fixed bug in subentity shielding code which didn't check whether a shipTakingDamage handler had been stored before trying to call it
* Added hemisphere glow effects (disabled by default because very under-debugged & not really working yet)

0.5
* Added explosion-based shield effects.

0.4
* Improved recharge code for fore/aft shields works more like the core player version.
* Correct handling of heat damage (hopefully?).
* $locateHit now attempts to identify a cloaked attacker if the parameter passed is null.
* Added dorsal/ventral shield configuration option and changed Thargoid default to use this.
* Fixed bug in $configureShieldsFromArray which caused Thargoid shield config failure.

0.3
* New features: Player shield effects, NPC shields protect subentities, spark effects for unshielded hits.
* Support for Ship Configuration OXP's shield upgrades/downgrades.
* Fixed bug in recharge code which resulted in excessive energy drain.
* Not released.
    
0.2
* Extensive re-write implementing some configuration options.
* 'single' and 'fore/aft' shield types supported.
* Damage handler array added for compatibility with other OXPs.
* Not released.
    
0.1
* Very basic shield simulation. Not released.

notYetParsed

notYetParsed

this.name           = "NShields_flasher";
this.author         = "Ngalo";
this.copyright      = "(C) 2015 'Ngalo'.";
this.licence        = "CC-NC-by-SA 3.0";
this.description    = "handles scaling, moving and lifespan of N-Shields flasher effects";

this.effectSpawned = function _NShields_effectSpawned() {
    //log (this.ship)
    //this.visualEffect.scale(this.ship.collisionRadius / 8)
    this._removalTimer = new Timer(this, this.$removeEffect, 0.25);
    this._FCB = addFrameCallback(this.$update.bind(this))
}

/*this.effectRemoved = function()
{
    if (this.$removalTimer)
    {
        this.$removalTimer.stop()
        delete this.$removalTimer;
    }
}*/

this.$removeEffect = function _NShieds_removeEffect() {
    removeFrameCallback(this._FCB)
    this.visualEffect.remove()
}

this.$update = function _NShieds_update(delta) {
    if (this.$parent.isValid)
        this.visualEffect.position = this.visualEffect.position.add(this.$parent.velocity.multiply(delta));
}