Transcendence Wiki

Documenting the Universe.

User Tools

Site Tools


modding:xml:itemtype

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 armor for more info.

<AutoDefenseDevice>

This defines an auto-defense device, like the Longreach I autocannon. See AutoDefense devices for more info.

<CargoHoldDevice>

This defines a cargo hold device. See cargo_holds devices for more info.

<CyberDeckDevice>

This defines a cyberdeck device capable of launching remote hacking attacks. See CyberDeck devices for more info.

<DriveDevice>

This defines a propulsion drive device. See 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 misc devices for more info.

<ReactorDevice>

This defines a power-generating device. See reactors for more info.

<RepairerDevice>

This defines a device that can repair armor damage. See Repairer devices for more info.

<Shields>

This defines a shield generator device. See Shield devices for more info.

<SolarDevice>

This defines a device that accumulates solar energy. See SolarDevice for more info.

<Weapon>

This defines a weapon or launcher device. See 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: Armor. See: 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: Armor.

<OnDamageArmor>

<OnDamageOverlay>

<OnDamageShields>

<OnDisable>

The item was disabled.

gSource is the object on which the item is installed.

gItem is the item.

<OnFireWeapon>

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

<OnShieldDown>

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

modding/xml/itemtype.txt · Last modified: 2017/09/26 05:19 by nms