User Tools

Site Tools


This is an old revision of the document!


Shields are installable 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.


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


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


  • adjustedHP
  • balance
  • damageAdj
  • effectiveHP The average adjusted hp of this shield for its level
  • hp
  • hpBonus
  • power
  • regen
  • weaponSuppress


  • 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


Shield events can be added to the <Events> element of <ItemType>.


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.


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


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.


  • <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
    • 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
modding/xml/shields.1486320447.txt.gz · Last modified: 2017/02/05 18:47 by 0xabcdef