Transcendence Community Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
=====Overview=====
Shields are installable [[<ItemType>|item types]] that absorb damage. The <Shields> element defines their characteristics.

=====Basic Attributes=====

//This section is incomplete.//

**powerUse**= The amount of power consumed while the shield is recharging, in tenths of megawatts.

**idlePowerUse=** The amount of power consumed while the shield is fully charged. Optional. Defaults to 10% of powerUse.//(New in 1.06)// \\ 
\\  Non-recharging shields consume 50% of the specified 'powerUse' value. 

=====Regeneration=====
There are two methods for specifying the regeneration rate of shields. The first uses the **regen** parameter:

**regen**= The number of hit points that the shield generates in 180 ticks. In 1.08c and above you may use a decimal value such as 1.5 or 5.3 for this field. The smallest possible valid value is 0.5.

Using this method, shields will recharge smoothly over time; that is, shield level will increment each tick by as much as necessary to reach the desired rate. Since hit points are integral (not fractional) the exact number of hit points per tick will vary in order to maintain the desired rate.

The second method for specifying regeneration uses a pair of parameters:

**regenTime**= This is the number of game seconds between regen events. Note that 1 game second is 0.5 ticks.

**regenHP**= This is the number of hit points recharged per regen event.

The second method allows you to regenerate shields in bursts, where the time between bursts is given by **regenTime** and the hit points gained on each burst is given by **regenHP**. regenTime and regenHP must be 0 or greater (if either value is 0, it means no recharge at all). Note that the smallest possible rate of recharge using this method is still 0.5 hit points per 180 ticks.

When shields drop to 0 there is a delay until they start to recharge. This delay is specified in different way depending on whether you use the **regen** attribute or the **regenTime** and **regenHP** attributes:

**depletionDelay**= If regen was specified with the **regen** attribute (see above) then this value is the number of ticks required before the shield starts to recharge after dropping to 0. If **regenTime** was used, then the ticks required is equal to the value of **depletionDelay** multiplied by **regenTime**. In either case, if depletionDelay is not specified it defaults to 360 ticks (12 real seconds).

=====Damage Adjustment=====
Normally shield level decreases by 1 hit point for every hit point of damage sustained. Depending on the shield and the [[damage type]] it was hit with, however, the shield level might decrease by more or less than 1 hp per point of damage. A shield that decreases by more than 1 hp per point of damage of a certain type is said to be //vulnerable// to that damage type. A shield that decreases by less than 1 hp per point of damage is said to be //resistant// to that damage type.

The relationship between shield hp and damage hp is specified as a **damageAdj** value. The value is the percent of the damage that goes into decreasing the level. At a value of 100, every point of damage done to the shield decreases its level by an equal number of points. 50 means that every point of damage drops the shield by 1/2 point. Conversely, 200 means that 1 point of damage causes a 2 point drop in shield level.

By default, all shields have different damage adjustments for each damage type depending on their level. For example, a level 1 shield takes 100% damage from lasers, but a level 5 shield only takes 80% damage. These defaults are set by the adventure.

There are three different ways to change the damage adjustments for individual shield types:

First, you can use the **damageAdjLevel** property to set the adjustment to a different level. For example, **damageAdjLevel="5"** sets the damage adjustments for a shield to the default for level 5 shields. You can use this property to make a level 1 shield resist damage as if it were a level 5 shield (or vice versa).

The second way is to use the **hpBonus** property to specify adjustments to individual damage types. For example:

**hpBonus="laser:+50;"**

hpBonus is expressed in as a hit point percent bonus to shields. The example above effectively adds 50% more hit points to total shield hit points when hit by lasers. That is, a 100 hp shield will behave like a 150 hp shield when it comes to lasers. Conversely, **hpBonus="laser:-50;"** will effectively decrease hp by 50% when hit by lasers.

You may specify multiple damage types on the same line:

**hpBonus="laser:+50; particle:+50; kinetic:-25; blast:-25;"**

Note that this bonus is in addition to any intrinsic damage adjustment due to the shield's level (either natural or set with damageAdjLevel).

The final way is to explicitly specify a damage adjustment:

**damageAdj="laser:90;"**

The example above sets the shield's damage adjustment to lasers to 90%. This means that for every 10 points of laser damage the shield level drops by only 9 of a points (90% of laser damage is passed to the shield). Note that this property overrides the intrinsic damage adjustment. For example, the above adjustment applied to a level 1 shield would increase the shield's resistance to laser (since it is normally 100). But if applied to a level 5 shield it would //decrease// the shield's resistance, since it normally would be 80.

Note: Placing the characters **<nowiki>***</nowiki>** in place of a number in these attributes indicates that the shield is completely immune to a damage type.
=====Additional Parameters=====

**maxHPBonus** If specified, this is the maximum HP bonus enhancement for the device. For example, a value of 100 means that the weapon cannot be enhanced beyond 100% bonus damage. The default is 150. **[API Version 17]**

=====Standard Stats=====
^ Level	| HP	| Regen	| Cost	| Power |
^1	|35	|12	|500	|10	|
^2	|45	|16	|1000	|20	|
^3	|60	|20	|2000	|50	|
^4	|80	|28	|4000	|100	|
^5	|100	|36	|8000	|200	|
^6	|135	|45	|16000	|300	|
^7	|175	|60	|32000	|500	|
^8	|225	|80	|65000	|1000	|
^9	|300	|100	|130000	|2000	|
^10	|380	|130	|250000	|3000	|
^11	|500	|170	|500000	|4000	|
^12	|650	|220	|-1	|6000	|
^13	|850	|290	|-2	|8000	|
^14	|1100	|370	|-4	|10000	|
^15	|1400	|490	|-8	|12000	|
^16	|1850	|630	|-16	|15000	|
^17	|2400	|820	|-32	|20000	|
^18	|3100	|1100	|-65	|25000	|
^19	|4000	|1400	|-130	|30000	|
^20	|5250	|1800	|-260	|35000	|
^21	|6850	|2350	|-525	|40000	|
^22	|9000	|3050	|-1000	|50000	|
^23	|12000	|4000	|-2100	|60000	|
^24	|15000	|5150	|-4200	|70000	|
^25	|20000	|6700	|-8400	|80000	|
=====Fields=====
  * **adjustedHP**
  * **balance**
  * **damageAdj**
  * **effectiveHP** The average adjusted hp of this shield for its level
  * **hp**
  * **hpBonus**
  * **power**
  * **regen**
  * **weaponSuppress**

=====Properties=====
  * **damageAdj** Returns a struct of damage adjustments, one for each damage type. The fields are the damage types as they are named in XML.
  * **hp** If the item is installed, returns the hp left. Otherwise, returns **maxHP**
  * **hpBonus** Returns a struct containing the individual **hpBonus** for each damage type. The fields are the damage types as they are named in XML.
  * **maxHP** Returns the max hp of the shield, including enhancements
//Inherits properties from [[Devices]]//
=====Events=====
Shield events can be added to the <Events> element of [[<ItemType>]].

===<GetMaxHP>===
This event is invoked to calculate the maximum hit point level of a shield item. The event must return either a non-negative number or Nil (to use the default value for max hit points).

**gSource** is the object on which the shield item is installed.

**gItem** is the shield item.

**aMaxHP** is the default value for max hit points, including all other enhancements and adjustments.

===<OnShieldDamage>===
This event is called when a projectile hits this shield.

If the event returns Nil, the shields process the damage normally.

If the event returns a list, then the list must have three elements. The first element is either the string "reflect" or Nil. The second element is the number of HP to subtract from the current shield level. The third element is the number of HP to do to armor.

**gSource** is the object that was hit by the projectile.

**aArmorDamageHP** is the number of hit points of damage that will be passed to armor after the shields absorb some.

**aArmorSeg** is the armor segment that would be hit if it penetrates overlay and shields.

**aAttacker** is the object that fired the projectile.

**aCause** is the projectile object.

**aDamageHP** is the amount of damage (in hit points) that reached the shield. It has not been adjusted for damage type.

**aDamageType** is the type of damage.

**aDeviceItem** is the shield item.

**aHitDir** is the absolute direction that the projectile came from.

**aHitPos** is the vector position where the shot hit.

**aOrderGiver** is the object that ordered the attacker.

**aOriginalArmorDamageHP** if the shot will be reflected, this is the number of hit points that would have been dealt to armor if the shot had not been reflected.

**aOriginalShieldDamageHP** if the shot will be reflected, this is the number of hit points that would have been dealt to shields if the shot had not been reflected.

**aShieldDamageHP** is the number of hit points of damage that the hit will do to shields.

**aShieldHP** is the current number of hit points on the shields.

**aShieldReflect** is the string "reflect" is the shield will reflect this projectile. Otherwise, its value is Nil.

**aWeaponType** is the UNID of the weapon (for missile weapons, this is the UNID of the missile).

===<OnShieldDown>===
This event is called on shield items when shield level has dropped to 0.

**gSource** is the object on which the shields are installed.

**gItem** is the shield item.

=====Summary=====
  * **<Shields>** Regenerative defense that protects a ship from damage. One per ship by default.
    * **absorbAdj=** List of percentages for each damage type that this shield will absorb the damage from
    * **armorShield=**
    * **damageAdj=** List of percentages for damage types the damage dealt is multiplied by.
    * **damageAdjLevel=** The level on the damage curve that this shield will inherit its adjustments from.
    * **depletionDelay=** Time in 1/30ths of second after HP reaches 0 during which regeneration is disabled
    * **hitEffect=**
    * **hitPoints=** Max HP of the shield
    * **idlePowerUse=** Power consumption in 1/10ths of MW while //not// recharging
    * **hasNonRegenHP=**
    * **hpBonus=** Bonus resistance/vulnerability to each damage type in addition to the standard curve
    * **HPBonusPerCharge=**
    * **maxCharges=**
    * **powerBonusPerCharge=**
    * **powerUse=** Power consumption in 1/10ths of MW while recharging
    * **reflect=**
    * **regen=** HP regenerated every 180 ticks (6 seconds)
    * **regenHP=** HP regenerated per regeneration event
    * **regenHPBonusPerCharge=**
    * **regenTime=** Time in 1/60ths of second between regeneration events
    * **weaponSuppress=**
    * **//maxHPBonus=//** Max percentage bonus hp that this shield can be enhanced to have
    * **<Events>**
      * **<GetMaxHP>**
        * **gSource**
        * **gItem**
        * **aMaxHP**
      * **<OnShieldDamage>**
        * **aArmorSeg**
        * **aCause**
        * **aAttacker**
        * **aOrderGiver**
        * **aHitPos**
        * **aHitDir**
        * **aDamageHP**
        * **aDamageType**
        * **aWeaponType**
        * **aShieldHP**
        * **aShieldDamageHP**
        * **aArmorDamageHP**
        * **aShieldReflect**
        * **aOriginalShieldDamageHP**
        * **aOriginalArmorDamageHP**
      * **<OnShieldDown>**
        * **gSource**
        * **gItem**