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=====
<ItemType> defines the properties and behavior of a type of [[item]]. Weapons, shields, and armor are all considered items.

=====Basic Properties=====
**UNID=** The [[UNID]] of the item type.

**name=** The name of the item type. Use [[name syntax]] to express both the singular and plural forms (if necessary).

**level=** The [[level]] of the item, expressed as a number from 1 to 25.

**value=** The price of a single item of this type, in credits.

**mass=** The mass of a single item, in kilograms.

**description=** The description of the item type.

**[[attributes]]=** The categories that the item type belongs to. [Note: Previous versions used the attribute **modifiers=**, but this has been deprecated to be consistent with all other design types.]

**frequency=** The relative chance of encountering this item randomly. This can be one of the following values:

  * common
  * uncommon
  * rare
  * veryrare
  * notrandom

**numberAppearing=** The number of items that will usually be found, expressed as a [[dice range]]. Both **frequency=** and **numberAppearing=** are used to compute the probability of generating this item type inside a [[<RandomItem>]] structure. Number appearing effects what items are bought and sold by stations. Stations use this to calculate what they will buy based on the number they already have. The more they have the lower the price gets til it hits zero and they are no longer willing to buy that item.

**virtual=** If this attribute is set to **true** then the item is considered virtual, which means that it does not show up as an item to the player. I.e., it cannot be looted, sold, bought, or jettisoned.

**sortName=** The string used to determine the display order in item screens.

**showReference=** This attribute is obsolete in RC1 and later.

**data=** This is a user-defined field that contains data appropriate to the item. For example, fuel items use this to store the amount of fuel units contained in the item. In general though, <StaticData> is a more flexible way of accomplishing the same thing and should be preferred.

**reverseArticle=** Nouns that start with a vowel generally use the indefinite article "an", whereas those that start with a consonant use "a". However, for nouns that do not follow these rules use reverseArticle="true". For example, "uranium" and "R5 deflector".

**inherit=** The UNID of the item that this item inherits from.

=====Charges=====
An item can have //charges// to reflect consumables. For example, a battery item could have 10 charges. Every time you use the battery, you use up one charge. When the item reaches 0 charges, it stops working. Much of the implementation of charges is in the definition of specific items such as weapons and shields, but some of the properties are on the item itself:

**charges=** The number of initial charges in an item of this type, expressed as a [[dice range]].

**massBonusPerCharge=** This is a positive integer value representing the number of kilograms to add to the mass of the item for each charge. For example, if charges are being used to keep track of the number of missiles in a launcher item, then this property could be used to simulate the mass decrease as each missile is expended.

**valueBonusPerCharge=** This is an integer value that increases or decreases the value of the item by the given amount per charge. For example, if the value of the item is set to 100 and valueBonusPerCharge="10" and the item has 5 charges, then the value of the item will be 150. This value may be negative to decrease the value of the item, but the value of the item will never be less than 0.

**valueCharges=** If set to **true**, the value of the item is proportional to the number of charges left (relative to the maximum value of the **charges** attribute). Do not use this with **valueBonusPerCharge** (use one or the other).


=====Devices & Armor=====
Use one (and only one) of the following structures to define an armor or device item.

===<Armor>===
This defines a segment of armor suitable for installation on a ship. See [[modding:xml:armor]] for more info.

===<AutoDefenseDevice>===
This defines an auto-defense device, like the Longreach I autocannon. See [[modding:xml:AutoDefense devices]] for more info.

===<CargoHoldDevice>===
This defines a cargo hold device. See [[modding:xml:cargo_holds]] devices for more info.

===<CyberDeckDevice>===
This defines a cyberdeck device capable of launching remote hacking attacks. See [[modding:xml:CyberDeck devices]] for more info.

===<DriveDevice>===
This defines a propulsion drive device. See [[modding:xml:Drive devices]] for more info.

===<EnhancerDevice>===
This defines a device that confers enhancements to other devices (such as weapons and shields). See [[Enhancer devices]] for more info.
* Attribute Note: enhancementType is only used to prevent two devices with the same one from enhancing the same weapon ... each enhancer should just have a unique one unless there's something clever going on

===<MiscellaneousDevice>===
This defines a miscellaneous device. See [[modding:xml:misc devices]] for more info.

===<ReactorDevice>===
This defines a power-generating device. See [[modding:xml:reactors]] for more info.

===<RepairerDevice>===
This defines a device that can repair armor damage. See [[modding:xml:Repairer devices]] for more info.

===<Shields>===
This defines a shield generator device. See [[modding:xml:Shield devices]] for more info.

===<SolarDevice>===
This defines a device that accumulates solar energy. See [[modding:xml:SolarDevice]] for more info.

===<Weapon>===
This defines a weapon or launcher device. See [[modding:xml:Weapon devices]] for more info.

=====Useable Items=====
There are two kinds of useable items: items that bring up a dock screen when used, and items that do not.

**useScreen=**

**useKey=**

**useInstalledOnly=**

**useUninstalledOnly=**

===<Invoke>===

===<DockScreens>===

=====Unknown Items=====
**unknownType=**

===<Names>===
The <Names> structure is used to define a list of random names for the unknown type.

=====Fields=====
====ItemStruct====
====ItemType====
  * averageCount
  * category
  * cost
  * description
  * deviceSlots
  * frequency
  * fuelCapacity
  * imageDesc
  * installCost
  * level
  * mass
  * name
  * reference
  * shortName
  * slotCategory
  * treasureValue
  * unknownType
  * useKey
=====Properties=====
====ItemStruct====
  * **category**
  * **charges**
  * **components**
  * **damaged** Applies to devices and armor segments only. Reduces the functionality and value of the item.
    * A damaged weapon has a 10% chance of firing normally, 60% chance of jamming, 20% chance of misfiring, and 10% chance of a damaging weapon chamber explosion.
    * Damaged shields have a 10% chance of absorbing only 75% of damage, leaving the armor underneath to take the remaining 25%. They have a 15% chance of taking double the adjusted damage. Additionally, every 10 ticks, there is a 5% chance that they may deplete themselves.
    * A damaged Armor segment has half as much hp when installed.
    * A damaged SolarDevice is half as effective as normal.
    * A damaged RepairerDevice does not work at all.
    * A damaged DriveDevice has 75% as much **maxSpeed**, 50% as much **thrust**, 30% greater **powerUse**, and cannot be inertialess.
    * A damaged ReactorDevice has 80% as much **maxPower** and **efficiency**
    * A damaged EnhancerDevice does not work at all.
    * A damaged CyberDeckDevice does not work at all.
  * **description**
  * **disrupted** Applies to devices and armor segments only. Same effect as **damaged**, but temporary.
  * **incCharges** Can only be set; increments the item's charges by the set amount.
  * **installed** Devices and armor segments only
  * **level**
  * **maxCharges**
  * **maxLevel** The maximum level that this item can have
  * **minLevel** The minimum level that this item can have
  * **massBonusPerCharge** The mass increase (in kg) when the item gains one charge
  * **valueBonusPerCharge** The value increase when the item gains one charge
  * **weaponTypes**
====ItemType====
  * category
  * components
  * currency
  * description
  * frequency
  * level
  * maxCharges
  * maxLevel
  * minLevel
  * massBonusPerCharge
  * valueBonusPerCharge
  * weaponTypes
=====Events=====

===<CanBeInstalled>===
This event is raised when an item is about to be installed.

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

**gItem** is the item.

**aItemToReplace** is the item that will be removed.

The event may return True to indicate that installation should proceed. Alternatively, it can return a text string, to indicate that installation has failed. The string is the text to display to the player explaining the reason for the failure.

Note that this event must not have any side-effects. In particular, you must not change gItem in this event.

===<CanBeUninstalled>===
This event is raised when an item is about to be uninstalled.

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

**gItem** is the item.

The event may return True to indicate that uninstallation should proceed. They event may return a text string to indicate that the item cannot be uninstalled. The string is displayed to the player to explain the reason for the failure.

Note that this event must not have any side-effects. In particular, you must not change gItem in this event.

===<GetDescription>===
**[apiVersion 14]** Use this event to dynamically compute the description of an item. The result is the description for the item.

**gItem** is the item.

===<GetMaxHP>===
See: [[modding:xml:Armor]].
See: [[modding:xml:Shield_devices]].

===<GetName>===
Use this event to dynamically compute the name of the item at runtime. The result from this event may be one of the following:
  * A string, representing the name of the item (use [[name syntax]] if necessary).
  * A list, whose first element is the name of the item (use [[name syntax]] if necessary), and whose second element is an integer representing the [[name usage flags]].

**gItem** is the item.

===<GetTradePrice>===
Use this event to dynamically compute the price of the item at runtime. The result of the event is the price of a single item of this type in [[credits]].

**gSource** is the object that is valuing the item (not necessarily the object on which the item resides).

**gItem** is the item.

===<OnAddedAsEnhancement>===
Indicates that the item type was used to enhance another item using the [[objAddItemEnhancement]] function.

**gSource** is the object that carries the item that was enhanced.

**gItem** is the item that was enhanced (not the enhancer).

**aResult** is a code describing the result of the enhancement:

  * 0 = The enhancement was successful
  * 4 = The enhancement replaced a harmful enhancement
  * 6 = The enhancement replaced a beneficial enhancement

===<OnAIUpdate>===
Called every 30 ticks. Perform AI tasks here.

===<OnArmorDamage>===
See: [[modding:xml:Armor]].

===<OnDamageArmor>===
See: [[modding:xml:Weapon devices]].

===<OnDamageOverlay>===
See: [[modding:xml:Weapon devices]].

===<OnDamageShields>===
See: [[modding:xml:Weapon devices]].

===<OnDisable>===
The item was disabled.

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

**gItem** is the item.

===<OnFireWeapon>===
See: [[modding:xml:Weapon devices]].

===<OnEnable>===
The item was enabled or installed on an object.

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

**gItem** is the item.

===<OnInstall>===
The item was installed on an object.

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

**gItem** is the item that was installed.

This event is called after the item is installed, but before bonuses and enhancements are computed (thus you may apply an enhancement).

===<OnObjDestroyed>===
The object that the item is on was destroyed.

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

  * **gItem** is the item

  * **aObjDestroyed** is the object that was destroyed (generally the same as gSource).

  * **aDestroyer** is the object that destroyed us.

  * **aOrderGiver** is the object that ordered the destruction. Generally this is the same as **aDestroyer** but in the case of autons, this is the controller of the auton.

  * **aWreckObj** if not **Nil** this is the wreck object that resulted from the destruction.

  * **aDestroyReason** this is the destruction cause.

===<OnReactorOverload>===
An object's reactor overloaded.

**gItem** is the item that has the event.

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

===<OnRefuel>===
This event is called when the item is used to refuel a ship.

**gSource** is the ship being refueled.

**gItem** is the item.

===<OnRemovedAsEnhancement>===
Indicates that the item type was removed from another item.

**gSource** is the object that carries the item that was enhanced.

**gItem** is the item that was enhanced (not the enhancer).

===<OnShieldDamage>===
See: [[modding:xml:Shield devices]].

===<OnShieldDown>===
See: [[modding:xml:Shield devices]].

===<OnUninstall>===
The item was uninstalled from an object.

**gSource** is the object from which the item was uninstalled.

**gItem** is the item that was uninstalled.

This event is called just before the item is uninstalled. In versions prior to 1.0 RC3 you must not alter any of the items on the ship inside this call. [This bug was fixed in RC3.]

===<OnUpdate>===
Called every 30 ticks.

**gSource** is the object that the item is in.

**gItem** is the item that has the onUpdate event.

===See also===

Return to [[..:XML|Tags list]].
=====Notes=====
  * <OnFireWeapon> was introduced in RC4. In RC5, its return value was defined.
  * <OnAddedAsEnhancement>, and <OnRemovedAsEnhancement> were introduced in RC3.
  * <GetMaxHP> was introduced in RC3.

=====Credit=====
This page was created by George Moromisato, before being moved to its current location.