Difference between revisions of "Modding:Item"
From DoomRL Wiki
Game Hunter (Talk | contribs) (moved and updated item flags) |
Game Hunter (Talk | contribs) (updated for 0995) |
||
Line 4: | Line 4: | ||
New items are created from item prototypes. Think of an item prototype as a recipe for creating new items. There can be multiple pistols, but they all came from the same prototype. Prototypes are declared by passing a table with the desired properties to the Items function. The available properties depend on the item type. [[#Engine Hooks|Engine hooks]] may also be included in the prototype. Mostly, the prototype's properties just describe items' initial properties (occasionally with different names). Items' properties can also mostly be changed after they are instantiated. Required fields are underlined. Sometimes required fields can safely be omitted, but this will generate a message in the log file. All item prototypes are stored in a global table called items. This table can be indexed by id or nid. | New items are created from item prototypes. Think of an item prototype as a recipe for creating new items. There can be multiple pistols, but they all came from the same prototype. Prototypes are declared by passing a table with the desired properties to the Items function. The available properties depend on the item type. [[#Engine Hooks|Engine hooks]] may also be included in the prototype. Mostly, the prototype's properties just describe items' initial properties (occasionally with different names). Items' properties can also mostly be changed after they are instantiated. Required fields are underlined. Sometimes required fields can safely be omitted, but this will generate a message in the log file. All item prototypes are stored in a global table called items. This table can be indexed by id or nid. | ||
− | {| | + | {{drltable|Item Prototype|3|{{Table3Col |
− | + | ||
− | + | ||
|es=background: #333; | |es=background: #333; | ||
|c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | |c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | ||
|c2=vertical-align:top; padding:0px 2px; | |c2=vertical-align:top; padding:0px 2px; | ||
|c3=padding:0px 2px; | |c3=padding:0px 2px; | ||
− | | | + | |{{modarg|string}}|<u>name</u>|This is the item's name. |
− | | | + | |{{modarg|string}}|id|This is the item's sid. It must be distinct from other string ids. (The numeric id is automatically generated and stored in the nid field of the prototype.) It defaults to the first word of the name in all lowercase. |
− | | | + | |{{modarg|value list}}|overlay|This describes of color transformation of the item's sprite. It is only used in the graphical version. This will create overlay_red, overlay_blue, overlay_green, and overlay_alpha attributes for the prototype. |
− | | | + | |{{modarg|Color}}|color|This is the item's color. The default is LIGHTGRAY. |
− | | | + | |{{modarg|string}}|color_id|For the purpose of custom color bindings, this id will be used for the item. Multiple items (like levers) can have the same color_id to prevent them from being distinguished. |
− | | | + | |{{modarg|integer}}|level|This is an [[Item Generation|item generation]] parameter. The default is 0. |
− | | | + | |{{modarg|integer}}|<u>weight</u>|This is an [[Item Generation|item generation]] parameter. |
− | | | + | |{{modarg|integer}}|<u>sprite</u>|This is the item's sprite. This field is only relevant to the graphical version; use 0 for no sprite. |
− | | | + | |{{modarg|value list}}|coscolor|Some sprites (such as armor and boots) are color-neutral to begin: ''coscolor'' determines the color of the sprite in these cases. The list must be written in this form: {red,green,blue,alpha}, where all of these values range from 0.0 to 1.0. |
− | | | + | |{{modarg|value list}}|glow|Creates a customized "glow" effect around the sprite. See ''coscolor'' for table specifications. |
− | | | + | |{{modarg|Item Flag List}}|flags|The flags in this list will automatically be included in the item's flag set. The default is an empty list. Some flags may be added automatically. The prototype will automatically be given a flagSet property containing the flags in set format. |
− | + | |{{modarg|ItemSet ID}}|set|If included, this item will belong to the given item set. This will modify the item's OnEquip and OnRemove hooks. | |
− | + | |{{modarg|string}}|firstmsg|If included, this message will be displayed when the an item with this prototype is picked up for the first time. This will modify the item's OnFirstPickup hook. | |
− | | | + | |{{modarg|integer}}|res_bullet|This is the item's res_bullet. The default is 0. |
− | | | + | |{{modarg|integer}}|res_melee|This is the item's res_melee. The default is 0. |
− | | | + | |{{modarg|integer}}|res_shrapnel|This is the item's res_shrapnel. The default is 0. |
− | | | + | |{{modarg|integer}}|res_acid|This is the item's res_acid. The default is 0. |
− | | | + | |{{modarg|integer}}|res_fire|This is the item's res_fire. The default is 0. |
− | | | + | |{{modarg|integer}}|res_plasma|This is the item's res_plasma. The default is 0. |
+ | |{{modarg|ItemType}}|<u>type</u>|This is the item's itype. It also determines which other properties can be used in the prototype. | ||
|}} | |}} | ||
− | + | }} | |
=== Armor or Boots === | === Armor or Boots === | ||
These are the fields used by ITEMTYPE_ARMOR and ITEMTYPE_BOOTS. | These are the fields used by ITEMTYPE_ARMOR and ITEMTYPE_BOOTS. | ||
− | {| | + | {{drltable|Armor or Boots Prototype|3|{{Table3Col |
− | + | ||
− | + | ||
|es=background: #333; | |es=background: #333; | ||
|c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | |c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | ||
|c2=vertical-align:top; padding:0px 2px; | |c2=vertical-align:top; padding:0px 2px; | ||
|c3=padding:0px 2px; | |c3=padding:0px 2px; | ||
− | | | + | |{{modarg|string}}|<u>desc</u>|This is the armor's description that is displayed in the inventory screen. |
− | | | + | |{{modarg|integer}}|<u>armor</u>|This is the armor's armor property. |
− | | | + | |{{modarg|integer}}|durability|This is the armor's maxdurability as well as its initial durability. The default is 100. (This should still be 100 for armors with no durability, as no durability is achieved by a flag.) |
− | | | + | |{{modarg|integer}}|knockmod|This is the armor's knockmod. The default is 0. |
− | | | + | |{{modarg|integer}}|movemod|This is the armor's movemod. The default is 0. |
− | | | + | |{{modarg|string}}|ascii|This is the armor's picture. It should be a length one string. The default is "[" for body armor and ";" for boots. |
|}} | |}} | ||
− | + | }} | |
=== Consumable === | === Consumable === | ||
These are the fields used by ITEMTYPE_PACK. This includes mods and relics. | These are the fields used by ITEMTYPE_PACK. This includes mods and relics. | ||
− | {| | + | {{drltable|Consumable Prototype|3|{{Table3Col |
− | + | ||
− | + | ||
|es=background: #333; | |es=background: #333; | ||
|c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | |c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | ||
|c2=vertical-align:top; padding:0px 2px; | |c2=vertical-align:top; padding:0px 2px; | ||
|c3=padding:0px 2px; | |c3=padding:0px 2px; | ||
− | | | + | |{{modarg|string}}|<u>desc</u>|This is the pack's description that is displayed in the inventory screen. |
− | | | + | |{{modarg|string}}|mod_letter|This is the shorthand letter by which the pack will be recognized as a mod. Do not fill this value unless this item is meant to be a mod pack. |
− | | | + | |{{modarg|function}}|<u>OnUse</u>|Packs must provide an OnUse hook. |
+ | |{{modarg|string}}|ascii|This is the pack's picture. It should be a length one string. The default is "+". | ||
|}} | |}} | ||
− | + | }} | |
− | === | + | === Powerup === |
These are the fields used by ITEMTYPE_POWER. | These are the fields used by ITEMTYPE_POWER. | ||
− | {| | + | {{drltable|Powerup Prototype|3|{{Table3Col |
− | + | ||
− | + | ||
|es=background: #333; | |es=background: #333; | ||
|c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | |c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | ||
|c2=vertical-align:top; padding:0px 2px; | |c2=vertical-align:top; padding:0px 2px; | ||
|c3=padding:0px 2px; | |c3=padding:0px 2px; | ||
− | | | + | |{{modarg|function}}|<u>OnPickup</u>|Powerups must provide an OnPickup hook. |
− | | | + | |{{modarg|string}}|ascii|This is the powerup's picture. It should be a length one string. The default is "^". |
|}} | |}} | ||
− | + | }} | |
=== Ammo === | === Ammo === | ||
These are the fields used by ITEMTYPE_AMMO. | These are the fields used by ITEMTYPE_AMMO. | ||
− | {| | + | {{drltable|Ammo Prototype|3|{{Table3Col |
− | + | ||
− | + | ||
|es=background: #333; | |es=background: #333; | ||
|c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | |c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | ||
|c2=vertical-align:top; padding:0px 2px; | |c2=vertical-align:top; padding:0px 2px; | ||
|c3=padding:0px 2px; | |c3=padding:0px 2px; | ||
− | | | + | |{{modarg|string}}|<u>desc</u>|This is the ammo's description that is displayed in the inventory screen. |
− | | | + | |{{modarg|integer}}|<u>ammo</u>|This is the ammo's initial ammo property. |
− | | | + | |{{modarg|integer}}|<u>ammomax</u>|This is the ammo's ammomax property. |
− | | | + | |{{modarg|string}}|ascii|This is the ammo's picture. It should be a length one string. The default is "|". |
|}} | |}} | ||
− | + | }} | |
=== Ammo Pack === | === Ammo Pack === | ||
These are the fields used by ITEMTYPE_AMMOPACK. | These are the fields used by ITEMTYPE_AMMOPACK. | ||
− | {| | + | {{drltable|Ammo Pack Prototype|3|{{Table3Col |
− | + | ||
− | + | ||
|es=background: #333; | |es=background: #333; | ||
|c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | |c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | ||
|c2=vertical-align:top; padding:0px 2px; | |c2=vertical-align:top; padding:0px 2px; | ||
|c3=padding:0px 2px; | |c3=padding:0px 2px; | ||
− | | | + | |{{modarg|string}}|<u>desc</u>|This is the ammo pack's description that is displayed in the inventory screen. |
− | | | + | |{{modarg|integer}}|<u>ammo</u>|This is the ammo pack's initial ammo property. |
− | | | + | |{{modarg|integer}}|<u>ammomax</u>|This is the ammo pack's ammomax property. |
− | | | + | |{{modarg|string}}|<u>ammo_id</u>|This is the ammo pack's ammoid property. |
− | | | + | |{{modarg|string}}|ascii|This is the ammo pack's picture. It should be a length one string. The default is "!". |
|}} | |}} | ||
− | + | }} | |
=== Ranged Weapon === | === Ranged Weapon === | ||
These fields are used by ITEMTYPE_RANGED. | These fields are used by ITEMTYPE_RANGED. | ||
− | {| | + | {{drltable|Ranged Weapon Prototype|3|{{Table3Col |
− | + | ||
− | + | ||
|es=background: #333; | |es=background: #333; | ||
|c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | |c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | ||
|c2=vertical-align:top; padding:0px 2px; | |c2=vertical-align:top; padding:0px 2px; | ||
|c3=padding:0px 2px; | |c3=padding:0px 2px; | ||
− | | | + | |{{modarg|string}}|<u>desc</u>|This is the weapon's description that is displayed in the inventory screen. |
− | | | + | |{{modarg|string}}|<u>damage</u>|This should be a string like "2d4"; the weapon's damage_dice and damage_sides will be parsed from this. |
− | | | + | |{{modarg|DamageType}}|<u>damagetype</u>|This is the weapon's damagetype. |
− | | | + | |{{modarg|string}}|<u>psprite</u>|This is the projectile sprite used with the weapon. It is only relevant in the graphical version. |
− | | | + | |{{modarg|string}}|<u>group</u>|This is the weapon's group for purposes of kill counting. The used weapon groups are "weapon-melee", "weapon-pistol", "weapon-shotgun", "weapon-chain", "weapon-rocket", "weapon-plasma", and "weapon-bfg". The default is "weapon-other". |
− | | | + | |{{modarg|string}}|<u>ammo_id</u>|This is the weapon's ammoID. |
− | | | + | |{{modarg|integer}}|fire|This is the weapon's usetime. The default is 10. |
− | | | + | |{{modarg|integer}}|acc|This is the weapon's acc. The default is 0. |
− | | | + | |{{modarg|integer}}|<u>ammomax</u>|This is the weapon's ammomax and the weapon's initial ammo. |
− | | | + | |{{modarg|integer}}|radius|This is the weapon's blastradius. The default is 0. |
− | | | + | |{{modarg|integer}}|shots|This is the weapon's shots. The default is 0 (which will still give one shot). |
− | | | + | |{{modarg|integer}}|shotcost|This is the weapon's shotcost. The default is 0 (which will still require one ammo). |
− | | | + | |{{modarg|AltFire}}|altfire|This is the weapon's altfire. The default is ALT_NONE. |
− | | | + | |{{modarg|AltReload}}|altreload|This is the weapon's altreload. The default is RELOAD_NONE. |
− | | | + | |{{modarg|string}}|altfirename|This is the name the game uses for the weapon's alternate fire mode. Most of the AltFire constants provide defaults. |
− | | | + | |{{modarg|string}}|altreloadname|This is the name the game uses for the weapon's alternate reload mode. Most of the AltReload constants provide defaults. |
− | | | + | |{{modarg|string}}|sound_id|The sound_id will be used to look up sounds if there are no sounds defined for the weapon's actual id. By convention, this is set as the usual wielder's id when applicable. |
− | | | + | |{{modarg|Missile ID}}|overcharge|This field is currently unused. |
+ | |{{modarg|Missile ID}} or {{modarg|Missile Prototype}}|<u>missile</u>|This is the weapon's missile. (It will be translated into an nid. To use a shotgun missile, the weapon must have the IF_SHOTGUN flag.) If this property is a table, it will be used to declare a new missile with the same id as the weapon. | ||
+ | |{{modarg|string}}|ascii|This is the weapon's picture. It should be a length one string. The default is "}". | ||
|}} | |}} | ||
− | + | }} | |
=== Natural Ranged Weapon === | === Natural Ranged Weapon === | ||
− | These fields are used by ITEMTYPE_NRANGED. Natural ranged weapons are usually defined inline in a | + | These fields are used by ITEMTYPE_NRANGED. Natural ranged weapons are usually defined inline in a {{modarg|Being}} definition. |
− | {| | + | {{drltable|Natural Ranged Weapon Prototype|3|{{Table3Col |
− | + | ||
− | + | ||
|es=background: #333; | |es=background: #333; | ||
|c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | |c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | ||
|c2=vertical-align:top; padding:0px 2px; | |c2=vertical-align:top; padding:0px 2px; | ||
|c3=padding:0px 2px; | |c3=padding:0px 2px; | ||
− | | | + | |{{modarg|string}}|<u>damage</u>|This should be a string like "2d4"; the weapon's damage_dice and damage_sides will be parsed from this. |
− | | | + | |{{modarg|DamageType}}|<u>damagetype</u>|This is the weapon's damagetype. |
− | | | + | |{{modarg|string}}|<u>group</u>|This is the weapon's group for purposes of kill counting. The used weapon groups are "weapon-melee", "weapon-pistol", "weapon-shotgun", "weapon-chain", "weapon-rocket", "weapon-plasma", and "weapon-bfg". The default is "weapon-other". |
− | | | + | |{{modarg|integer}}|fire|This is the weapon's usetime. The default is 10. |
− | | | + | |{{modarg|integer}}|acc|This is the weapon's acc. The default is 0. |
− | | | + | |{{modarg|integer}}|radius|This is the weapon's blastradius. The default is 0. |
− | | | + | |{{modarg|integer}}|shots|This is the weapon's shots. The default is 0 (which will still give one shot). |
− | | | + | |{{modarg|string}}|sound_id|The sound_id will be used to look up sounds if there are no sounds defined for the weapon's actual id. By convention, a natural weapon's soundID is the usual wielder's id. |
− | | | + | |{{modarg|Missile ID}} or {{modarg|Missile Prototype}}|<u>missile</u>|This is the weapon's missile. (It will be translated into an nid. To use a shotgun missile, the weapon must have the IF_SHOTGUN flag.) If this property is a table, it will be used to declare a new missile with the same id as the weapon. |
− | | | + | |{{modarg|string}}|ascii|This is the weapon's picture. It should be a length one string. The default is "?". |
|}} | |}} | ||
− | + | }} | |
=== Melee Weapon === | === Melee Weapon === | ||
These fields are used by ITEMTYPE_MELEE. | These fields are used by ITEMTYPE_MELEE. | ||
− | {| | + | {{drltable|Melee Weapon Prototype|3|{{Table3Col |
− | + | ||
− | + | ||
|es=background: #333; | |es=background: #333; | ||
|c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | |c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | ||
|c2=vertical-align:top; padding:0px 2px; | |c2=vertical-align:top; padding:0px 2px; | ||
|c3=padding:0px 2px; | |c3=padding:0px 2px; | ||
− | | | + | |{{modarg|string}}|<u>desc</u>|This is the weapon's description that is displayed in the inventory screen. |
− | | | + | |{{modarg|string}}|<u>damage</u>|This should be a string like "2d4"; the weapon's damage_dice and damage_sides will be parsed from this. |
− | | | + | |{{modarg|DamageType}}|<u>damagetype</u>|This is the weapon's damagetype. |
− | | | + | |{{modarg|string}}|<u>psprite</u>|This is the projectile sprite used with the weapon. It is only relevant in the graphical version. |
− | | | + | |{{modarg|string}}|<u>group</u>|This is the weapon's group for purposes of kill counting. The used weapon groups are "weapon-melee", "weapon-pistol", "weapon-shotgun", "weapon-chain", "weapon-rocket", "weapon-plasma", and "weapon-bfg". The default is "weapon-other". |
− | | | + | |{{modarg|integer}}|fire|This is the weapon's usetime. The default is 10. |
− | | | + | |{{modarg|integer}}|acc|This is the weapon's acc. The default is 0. |
− | | | + | |{{modarg|integer}}|shotcost|This is the weapon's shotcost. The default is 0 (which will still require one ammo). |
− | | | + | |{{modarg|AltFire}}|altfire|This is the weapon's altfire. The default is ALT_NONE. |
− | | | + | |{{modarg|string}}|altfirename|This is the name the game uses for the weapon's alternate fire mode. Most of the AltFire constants provide defaults. |
− | | | + | |{{modarg|Missile ID}} or {{modarg|Missile Prototype}}|missile|This is the missile used if for the throw alternate fire mode. |
+ | |{{modarg|Item ID}}|throw_id|In the case where the melee weapon can be thrown, this is the item that appears after the item is thrown. It defaults to the item itself. | ||
+ | |{{modarg|string}}|ascii|This is the weapon's picture. It should be a length one string. The default is "\". | ||
|}} | |}} | ||
− | + | }} | |
=== Lever === | === Lever === | ||
These fields are used by ITEMTYPE_LEVER. DoomRL levers usually also have a target_area custom property. | These fields are used by ITEMTYPE_LEVER. DoomRL levers usually also have a target_area custom property. | ||
− | {| | + | {{drltable|Lever Prototype|3|{{Table3Col |
− | + | ||
− | + | ||
|es=background: #333; | |es=background: #333; | ||
|c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | |c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | ||
|c2=vertical-align:top; padding:0px 2px; | |c2=vertical-align:top; padding:0px 2px; | ||
|c3=padding:0px 2px; | |c3=padding:0px 2px; | ||
− | | | + | |{{modarg|string}}|<u>desc</u>|This is the full description of the lever used if the player has BF_LEVERSENSE2. |
− | | | + | |{{modarg|string}}|<u>good</u>|This is the qualitative description of the lever used if the player has BF_LEVERSENSE1. By convention, this should be "beneficial", "neutral", or "dangerous". |
− | | | + | |{{modarg|integer}}|fullchance|The level generation code will set the lever's target_area to the full map fullchance percent of the time. The default is 0. (To be fair, the level generation code won't generate custom levers.) |
− | | | + | |{{modarg|string}}|warning|This message will be displayed by the level generation code if the fullchance roll succeeds. |
|null|<u>color_id</u>|This field is required for levers. By convention, it is set to "lever". | |null|<u>color_id</u>|This field is required for levers. By convention, it is set to "lever". | ||
− | |null| | + | |null|sound_id|If the particular lever doesn't have sound bindings, the game will use the sound ID to look for sound bindings. By default, this is "lever". |
− | | | + | |{{modarg|string}}|ascii|This is the lever's picture. It should be a length one string. The default is "&". |
|}} | |}} | ||
− | + | }} | |
=== Teleporter === | === Teleporter === | ||
These fields are used by ITEMTYPE_TELE. The built-in teleport item has a custom target property. This can be set to any coord to control the destination. | These fields are used by ITEMTYPE_TELE. The built-in teleport item has a custom target property. This can be set to any coord to control the destination. | ||
− | {| | + | {{drltable|Teleporter Prototype|3|{{Table3Col |
− | + | ||
− | + | ||
|es=background: #333; | |es=background: #333; | ||
|c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | |c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | ||
|c2=vertical-align:top; padding:0px 2px; | |c2=vertical-align:top; padding:0px 2px; | ||
|c3=padding:0px 2px; | |c3=padding:0px 2px; | ||
− | | | + | |{{modarg|function}}|<u>OnEnter</u>|This hook is required for teleporters. |
− | | | + | |{{modarg|string}}|ascii|This is the teleporter's picture. It should be a length one string. The default is "*". |
|}} | |}} | ||
− | + | }} | |
=== Flags === | === Flags === | ||
Line 281: | Line 265: | ||
|c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | |c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | ||
|c2=padding:0px 2px; | |c2=padding:0px 2px; | ||
− | | | + | |{{modarg|boolean}}|[[#item_OnCreate|OnCreate]]({{modarg|Item}} self) |
− | | | + | |{{modarg|boolean}}|[[#item_OnPickup|OnPickup]]({{modarg|Item}} self, {{modarg|Being}} getter) |
− | | | + | |{{modarg|boolean}}|[[#item_OnFirstPickup|OnFirstPickup]]({{modarg|Item}} self, {{modarg|Being}} getter) |
− | | | + | |{{modarg|boolean}}|[[#item_OnPickupCheck|OnPickupCheck]]({{modarg|Item}} self, {{modarg|Being}} getter) |
− | | | + | |{{modarg|boolean}}|[[#item_OnUse|OnUse]]({{modarg|Item}} self, {{modarg|Being}} user) |
− | | | + | |{{modarg|boolean}}|[[#item_OnUseCheck|OnUseCheck]]({{modarg|Item}} self, {{modarg|Being}} user) |
− | | | + | |{{modarg|boolean}}|[[#item_OnReload|OnReload]]({{modarg|Item}} self, {{modarg|Being}} reloader) |
− | | | + | |{{modarg|boolean}}|[[#item_OnAltFire|OnAltFire]]({{modarg|Item}} self, {{modarg|Being}} firer) |
− | | | + | |{{modarg|boolean}}|[[#item_OnAltReload|OnAltReload]]({{modarg|Item}} self, {{modarg|Being}} reloader) |
− | | | + | |{{modarg|boolean}}|[[#item_OnEquip|OnEquip]]({{modarg|Item}} self, {{modarg|Being}} equipper) |
− | | | + | |{{modarg|boolean}}|[[#item_OnEquipTick|OnEquipTick]]({{modarg|Item}} self, {{modarg|Being}} wearer) |
− | | | + | |{{modarg|boolean}}|[[#item_OnEquipCheck|OnEquipCheck]]({{modarg|Item}} self, {{modarg|Being}} equipper) |
− | | | + | |{{modarg|boolean}}|[[#item_OnRemove|OnRemove]]({{modarg|Item}} self, {{modarg|Being}} wearer) |
− | | | + | |{{modarg|boolean}}|[[#item_OnKill|OnKill]]({{modarg|Item}} self, {{modarg|Being}} dier, {{modarg|Being}} wearer) |
− | | | + | |{{modarg|boolean}}|[[#item_OnHitBeing|OnHitBeing]]({{modarg|Item}} self, {{modarg|Being}} attacker, {{modarg|Being}} target) |
− | | | + | |{{modarg|boolean}}|[[#item_OnEnter|OnEnter]]({{modarg|Item}} self, {{modarg|Being}} enterer) |
− | | | + | |{{modarg|boolean}}|[[#item_OnFire|OnFire]]({{modarg|Item}} self, {{modarg|Being}} firer) |
− | | | + | |{{modarg|boolean}}|[[#item_OnFired|OnFired]]({{modarg|Item}} self, {{modarg|Being}} firer) |
|}} | |}} | ||
|} | |} | ||
{{Anchor|item_OnCreate}} | {{Anchor|item_OnCreate}} | ||
− | ;OnCreate( | + | ;OnCreate({{modarg|Item}} self) |
:This hook is called when the item is created. For ammo, beware: the game creates and destroys ammo items liberally as a normal part of ammo management. | :This hook is called when the item is created. For ammo, beware: the game creates and destroys ammo items liberally as a normal part of ammo management. | ||
---- | ---- | ||
{{Anchor|item_OnPickup}} | {{Anchor|item_OnPickup}} | ||
− | ;OnPickup( | + | ;OnPickup({{modarg|Item}} self, {{modarg|Being}} getter) |
:When an item is picked up, this hook is called with the being that is picking the item up. This is most commonly used to implement powerups. | :When an item is picked up, this hook is called with the being that is picking the item up. This is most commonly used to implement powerups. | ||
---- | ---- | ||
{{Anchor|item_OnFirstPickup}} | {{Anchor|item_OnFirstPickup}} | ||
− | ;OnFirstPickup( | + | ;OnFirstPickup({{modarg|Item}} self, {{modarg|Being}} getter) |
:When an item with a given id is picked up for the first time, the function is called. This only works for items that go into the inventory. | :When an item with a given id is picked up for the first time, the function is called. This only works for items that go into the inventory. | ||
---- | ---- | ||
{{Anchor|item_OnPickupCheck}} | {{Anchor|item_OnPickupCheck}} | ||
− | ;OnPickupCheck( | + | ;OnPickupCheck({{modarg|Item}} self, {{modarg|Being}} getter) → '''boolean''' |
:When a being tries to pick up an item, this function is called with the being that is trying to pick it up. If the return value is true, then the being is allowed to pick the item up, otherwise the being can't. For the player, both cases include the item in the player's previously found items. (This can affect OnFirstPickup.) | :When a being tries to pick up an item, this function is called with the being that is trying to pick it up. If the return value is true, then the being is allowed to pick the item up, otherwise the being can't. For the player, both cases include the item in the player's previously found items. (This can affect OnFirstPickup.) | ||
---- | ---- | ||
{{Anchor|item_OnUse}} | {{Anchor|item_OnUse}} | ||
− | ;OnUse( | + | ;OnUse({{modarg|Item}} self, {{modarg|Being}} user) → '''boolean''' |
:This hook is called when levers are used and when packs are used with the being that it using the item. For packs, if the return value is true, the item is consumed, otherwise it is left in the inventory. For levers, the return value is ignored and it is safe not to have a return value. | :This hook is called when levers are used and when packs are used with the being that it using the item. For packs, if the return value is true, the item is consumed, otherwise it is left in the inventory. For levers, the return value is ignored and it is safe not to have a return value. | ||
---- | ---- | ||
{{Anchor|item_OnUseCheck}} | {{Anchor|item_OnUseCheck}} | ||
− | ;OnUseCheck( | + | ;OnUseCheck({{modarg|Item}} self, {{modarg|Being}} user) → '''boolean''' |
:This hook is called called before OnUse for levers and packs. If the return value is false, then the being can't use the item, otherwise it can. For levers, this can control whether the lever statistic is increased. | :This hook is called called before OnUse for levers and packs. If the return value is false, then the being can't use the item, otherwise it can. For levers, this can control whether the lever statistic is increased. | ||
---- | ---- | ||
{{Anchor|item_OnReload}} | {{Anchor|item_OnReload}} | ||
− | ;OnReload( | + | ;OnReload({{modarg|Item}} self, {{modarg|Being}} reloader) → '''boolean''' |
:If it is declared, this hook is called when a weapon is reloaded. If the return value is false, then the normal reload procedure is aborted. This can be used to prevent reloading or to implement a custom reloading mechanism (like for the [[Acid Spitter]]). If true is returned, the weapon is reloaded normally afterwards. | :If it is declared, this hook is called when a weapon is reloaded. If the return value is false, then the normal reload procedure is aborted. This can be used to prevent reloading or to implement a custom reloading mechanism (like for the [[Acid Spitter]]). If true is returned, the weapon is reloaded normally afterwards. | ||
---- | ---- | ||
{{Anchor|item_OnAltFire}} | {{Anchor|item_OnAltFire}} | ||
− | ;OnAltFire( | + | ;OnAltFire({{modarg|Item}} self, {{modarg|Being}} firer) → '''boolean''' |
:This hook works exactly like the OnFire hook, except it is called when the weapon's alternate fire mode is used for weapons with ALT_SCRIPT altfire. | :This hook works exactly like the OnFire hook, except it is called when the weapon's alternate fire mode is used for weapons with ALT_SCRIPT altfire. | ||
---- | ---- | ||
{{Anchor|item_OnAltReload}} | {{Anchor|item_OnAltReload}} | ||
− | ;OnAltReload( | + | ;OnAltReload({{modarg|Item}} self, {{modarg|Being}} reloader) |
:If the weapon's altreload is RELOAD_SCRIPT, then this hook is called with when the weapon's alternate reload mode is used. | :If the weapon's altreload is RELOAD_SCRIPT, then this hook is called with when the weapon's alternate reload mode is used. | ||
---- | ---- | ||
{{Anchor|item_OnEquip}} | {{Anchor|item_OnEquip}} | ||
− | ;OnEquip( | + | ;OnEquip({{modarg|Item}} self, {{modarg|Being}} equipper) |
:This hook is called when the item is equipped in any equipment slot. Due to a bug, equipper is the active being. This is always correct during normal play, but modders must be careful when manually equipping items with this hook. | :This hook is called when the item is equipped in any equipment slot. Due to a bug, equipper is the active being. This is always correct during normal play, but modders must be careful when manually equipping items with this hook. | ||
---- | ---- | ||
{{Anchor|item_OnEquipTick}} | {{Anchor|item_OnEquipTick}} | ||
− | ;OnEquipTick( | + | ;OnEquipTick({{modarg|Item}} self, {{modarg|Being}} wearer) |
:While this item is equipped in any slot (including the prepared slot), this function is called on each of the being's actions. (Despite the name, it probably won't be called on every tick; it depends on the being's speed.) | :While this item is equipped in any slot (including the prepared slot), this function is called on each of the being's actions. (Despite the name, it probably won't be called on every tick; it depends on the being's speed.) | ||
---- | ---- | ||
{{Anchor|item_OnEquipCheck}} | {{Anchor|item_OnEquipCheck}} | ||
− | ;OnEquipCheck( | + | ;OnEquipCheck({{modarg|Item}} self, {{modarg|Being}} equipper) → '''boolean''' |
:This function is called (before OnEquip) when the player tries to equip an item. If the return value is true, then the player is allowed to equip the item; otherwise the player isn't allowed to equip the item. | :This function is called (before OnEquip) when the player tries to equip an item. If the return value is true, then the player is allowed to equip the item; otherwise the player isn't allowed to equip the item. | ||
---- | ---- | ||
{{Anchor|item_OnRemove}} | {{Anchor|item_OnRemove}} | ||
− | ;OnRemove( | + | ;OnRemove({{modarg|Item}} self, {{modarg|Being}} wearer) |
:This hook is called when a being unequips the item, or when the item is otherwise removed from the being's equipment. This includes armor being destroyed by damage. Like OnEquip, this is called with the active being which can cause problems especially if this hook is called for armor destruction. | :This hook is called when a being unequips the item, or when the item is otherwise removed from the being's equipment. This includes armor being destroyed by damage. Like OnEquip, this is called with the active being which can cause problems especially if this hook is called for armor destruction. | ||
---- | ---- | ||
{{Anchor|item_OnKill}} | {{Anchor|item_OnKill}} | ||
− | ;OnKill( | + | ;OnKill({{modarg|Item}} self, {{modarg|Being}} dier, {{modarg|Being}} wearer) |
:When a being dies, this hook is called on all of the active being's equipment. This includes the prepared slot. (Weapons can check what slot they are in inside of this hook.) | :When a being dies, this hook is called on all of the active being's equipment. This includes the prepared slot. (Weapons can check what slot they are in inside of this hook.) | ||
---- | ---- | ||
{{Anchor|item_OnHitBeing}} | {{Anchor|item_OnHitBeing}} | ||
− | ;OnHitBeing( | + | ;OnHitBeing({{modarg|Item}} self, {{modarg|Being}} attacker, {{modarg|Being}} target) → '''boolean''' |
:For weapons with no blastradius, this hook is called whenever a being is hit with the weapon. This hook is called before applying damage. If the return value is true, damage is applied as usual. Otherwise, the damage phase is skipped. | :For weapons with no blastradius, this hook is called whenever a being is hit with the weapon. This hook is called before applying damage. If the return value is true, damage is applied as usual. Otherwise, the damage phase is skipped. | ||
---- | ---- | ||
{{Anchor|item_OnEnter}} | {{Anchor|item_OnEnter}} | ||
− | ;OnEnter( | + | ;OnEnter({{modarg|Item}} self, {{modarg|Being}} enterer) |
:This function is called whenever a being enters a cell that has the item lying on the floor. For the player, this supresses the usual "There is an item lying here" message. This is used in DoomRL to implement teleports. | :This function is called whenever a being enters a cell that has the item lying on the floor. For the player, this supresses the usual "There is an item lying here" message. This is used in DoomRL to implement teleports. | ||
---- | ---- | ||
{{Anchor|item_OnFire}} | {{Anchor|item_OnFire}} | ||
− | ;OnFire( | + | ;OnFire({{modarg|Item}} self, {{modarg|Being}} firer) → '''boolean''' |
:This hook is called when a weapon is fired. This only works for normal firing, not alternative firing (see OnAltFire). This hook is called before a target is selected. If the return value is true, then the rest of the normal firing operation is aborted. If the return value is false, then it continues as usual. | :This hook is called when a weapon is fired. This only works for normal firing, not alternative firing (see OnAltFire). This hook is called before a target is selected. If the return value is true, then the rest of the normal firing operation is aborted. If the return value is false, then it continues as usual. | ||
---- | ---- | ||
{{Anchor|item_OnFired}} | {{Anchor|item_OnFired}} | ||
− | ;OnFired( | + | ;OnFired({{modarg|Item}} self, {{modarg|Being}} firer) |
:This hook is called after a weapon is fired. This is after the entire usual firing procedure including damage, etc. Currently, this only works for the player. | :This hook is called after a weapon is fired. This is after the entire usual firing procedure including damage, etc. Currently, this only works for the player. | ||
Line 377: | Line 361: | ||
Items also have all the [[Modding:Thing|Thing]] properties in addition to those listed below. For items, the meaning of the resistance fields vary depending on the item type. For armor and boots, the resistances are applied only to attacks to the corresponding target. For other equipment, the resistance applies to all attacks. For non-equipment, the resistances aren't used. Also, some properties are only valid for armor, and some are only valid for weapons. For these purposes, armor are items with itype ITEMTYPE_ARMOR and ITEMTYPE_BOOTS and weapons are items with itype ITEMTYPE_AMMO, ITEMTYPE_MELEE, ITEMTYPE_NRANGED, ITEMTYPE_RANGED, and ITEMTYPE_AMMOPACK. Properties of the incorrect type are always indexable, but they may share a memory address with properties of the opposite type, so modders should only use this feature very carefully. The type of such properties is noted. Also, the meaning of many fields is slightly different depending on the itype; these differences are also described. | Items also have all the [[Modding:Thing|Thing]] properties in addition to those listed below. For items, the meaning of the resistance fields vary depending on the item type. For armor and boots, the resistances are applied only to attacks to the corresponding target. For other equipment, the resistance applies to all attacks. For non-equipment, the resistances aren't used. Also, some properties are only valid for armor, and some are only valid for weapons. For these purposes, armor are items with itype ITEMTYPE_ARMOR and ITEMTYPE_BOOTS and weapons are items with itype ITEMTYPE_AMMO, ITEMTYPE_MELEE, ITEMTYPE_NRANGED, ITEMTYPE_RANGED, and ITEMTYPE_AMMOPACK. Properties of the incorrect type are always indexable, but they may share a memory address with properties of the opposite type, so modders should only use this feature very carefully. The type of such properties is noted. Also, the meaning of many fields is slightly different depending on the itype; these differences are also described. | ||
− | {| | + | {{drltable|Item|3|{{Table3Col |
− | + | ||
− | + | ||
|es=background: #333; | |es=background: #333; | ||
|c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | |c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | ||
|c2=vertical-align:top; padding:0px 2px; | |c2=vertical-align:top; padding:0px 2px; | ||
|c3=padding:0px 2px; | |c3=padding:0px 2px; | ||
− | | | + | |{{modarg|ItemType}}|itype|This determines the basic features of the item. ITEMTYPE_NONE has no features; it can't be picked up or used. ITEMTYPE_RANGED can be picked up and wielded as a ranged weapon. ITEMTYPE_NRANGED is like ITEMTYPE_RANGED, but it isn't designed to exist on the map. ITEMTYPE_ARMOR can be picked up and equipped as armor. ITEMTYPE_MELEE can be picked up and wielded as a melee weapon. ITEMTYPE_AMMO is always a new ammo type that can be picked up and stacked. ITEMTYPE_PACK items can be picked up and used. ITEMTYPE_POWER items are consumed when they are picked up. ITEMTYPE_BOOTS can be picked up and worn as boots. ITEMTYPE_TELE have no special features, but by convention they interact with OnEnter. ITEMTYPE_LEVER have special description routines, and they can be used while on the floor. ITEMTYPE_AMMOPACK can be picked up and wielded in the prepared slot. They provide reloading benefits. While it is possible to change an item's itype, this should almost never be done. If it is done, care must be taken to account for overlapping weapon and armor properties. |
− | | | + | |{{modarg|byte}}|armor|For armor and boots, this is the amount of [[protection]] provided at full durability. Weapons in the main slot may also provide a (universal) protection bonus with this field. |
− | | | + | |{{modarg|word}}|durability|For armor and boots, this is the current amount of durability of the item. This property is armor-specific. |
− | | | + | |{{modarg|word}}|maxdurability|For armor and boots, this is the maximum amount of durability. Most effects won't raise the durability above maxdurability. This property is armor-specific. |
− | | | + | |{{modarg|integer}}|movemod|For armor and boots, this percentage movement speed modifier is applied while the item is equipped. This property is armor-specific. |
− | | | + | |{{modarg|integer}}|knockmod|For armor and boots, this percentage [[knockback]] modifier is applied while the item is equipped. This property is armor-specific. |
|[[Modding:Item|Item ID]]|ammoid|This must always be a number id. For ranged weapons, this is the item id of the kind of ammo the weapon uses. For ammo packs, this is the kind of ammo provided by the pack. This property is weapon-specific. | |[[Modding:Item|Item ID]]|ammoid|This must always be a number id. For ranged weapons, this is the item id of the kind of ammo the weapon uses. For ammo packs, this is the kind of ammo provided by the pack. This property is weapon-specific. | ||
− | | | + | |{{modarg|word}}|ammo|For ranged weapons, this is the amount of currently-loaded ammo. For ammo packs and ammo stacks, this is the amount of ammo inside. This property is weapon-specific. |
− | | | + | |{{modarg|word}}|ammomax|For ranged weapons, this is the size of the magazine. For ammo stacks, this is the maximum stack size (unaffected by BF_BACKPACK). For ammo packs, this is the initial amount of ammo. This property is weapon-specific. |
− | | | + | |{{modarg|word}}|acc|For ranged and melee weapons, this is an [[accuracy]] modifier applied to attacks with the weapon. This property is weapon-specific. |
− | | | + | |{{modarg|word}}|damage_sides|For weapons, this is the number of dice rolled for damage (e.g. the X of XdY). This property is weapon-specific. |
− | | | + | |{{modarg|word}}|damage_dice|For weapons, this is the number of sides on each die rolled for damage (e.g. the Y of XdY). This property is weapon-specific. |
− | | | + | |{{modarg|integer}}|damage_add|For weapons, this is a flat bonus added to all damage rolls. This property is weapon-specific. |
− | | | + | |{{modarg|Missile ID}}|missile|This must always be a number id. For ranged weapons, this is the missile used by the weapon. For melee weapons, this is the missile used by the throw alternate fire mode (if any). This property is weapon-specific. |
− | | | + | |{{modarg|byte}}|blastradius|This is the [[Distance|radius]] of the explosion caused by a ranged weapon. This should be 0 for weapons with no explosion. This property is weapon-specific. |
− | | | + | |{{modarg|byte}}|shots|This is the number of shots fired by a rapid-fire ranged weapon. This should be 0 (not 1) for single-shot weapons. This property is weapon-specific. |
− | | | + | |{{modarg|byte}}|shotcost|This is the amount of ammo consumed by each shot with a ranged weapon. This should be 0 (not 1) for weapons that take only one ammo per shot. This property is weapon-specific. |
− | | | + | |{{modarg|byte}}|reloadtime|This is the number of 0.1s intervals it takes (without modifiers) to reload a ranged weapon. This property is weapon-specific. |
− | | | + | |{{modarg|byte}}|usetime|This is the number of 0.1s intervals it takes (without modifiers) to fire/use a weapon. This property is weapon-specific. |
− | | | + | |{{modarg|DamageType}}|damagetype|This is the [[Damage type|type]] of the damage caused by a weapon. This property is weapon-specific. |
− | | | + | |{{modarg|AltFire}}|altfire|This is the alternate fire mode of a weapon. For ALT_SCRIPT, the details depend on the OnAltFire hook. This property is weapon-specific. |
− | | | + | |{{modarg|AltReload}}|altreload|This is the alternate reload mode of a ranged weapon. For RELOAD_SCRIPT, the details depend on the OnAltReload hook. This property is weapon-specific. |
− | | | + | |{{modarg|string}}|desc|This is the string used to describe the item in the inventory list. For the description in the inventory sidebar, use .proto.desc. This property is read-only. |
− | | | + | |{{modarg|Item Prototype}}|__proto|This is the item's prototype. You can access item prototype fields using this (e.g., item.__proto.color). |
|}} | |}} | ||
− | + | }} | |
== API == | == API == | ||
Line 419: | Line 401: | ||
|c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | |c1=font-weight:bold; text-align:right; vertical-align:top; padding:0px 2px; | ||
|c2=padding:0px 2px; | |c2=padding:0px 2px; | ||
− | | | + | |{{modarg|Item}}|{{moddef|list|new|dot||Item ID|iid}} |
− | | | + | |{{modarg|boolean}}|{{moddef|list|add_mod|cln||string|modletter}} |
− | | | + | |{{modarg|boolean}}|{{moddef|list|can_mod|cln||string|modletter}} |
− | | | + | |{{modarg|integer}}|{{moddef|list|get_mod|cln||string|modletter}} |
− | | | + | |{{modarg|boolean}}|{{moddef|list|clear_mods|cln}} |
− | | | + | |{{modarg|boolean}}|{{moddef|list|is_damaged|cln}} |
− | | | + | |{{modarg|boolean}}|{{moddef|list|fix|cln||integer|amount}} |
− | | | + | |{{modarg|table}}|{{moddef|list|get_mods|cln}} |
− | | | + | |{{modarg|table}}|{{moddef|list|get_mod|ids|cln}} |
− | | | + | |{{modarg|boolean}}|{{moddef|list|can_overcharge|cln}} |
+ | |{{modarg|boolean}}|{{moddef|list|check_mod_array|cln||string|nextmod|integer|techbonus}} | ||
|}} | |}} | ||
|} | |} | ||
− | {{ | + | {{moddef|desc|new|dot|Item|Item ID|iid}} |
− | + | ||
:This returns a newly allocated item create from the specified prototype. This item doesn't exist in the game yet; it must be dropped on the level, added to an inventory, or equipped. | :This returns a newly allocated item create from the specified prototype. This item doesn't exist in the game yet; it must be dropped on the level, added to an inventory, or equipped. | ||
---- | ---- | ||
− | {{ | + | {{moddef|desc|add_mod|cln|boolean|string|modletter}} |
− | + | ||
:Adds a mod to the item's mod list and sets the IF_MODIFIED flag. This does not apply any affects of the mod, it is only a primitive operation for accessing the mod list. ''modletter'' should be a single uppercase letter representing the mod. This will check modding restrictions (as [[#item_can_mod|can_mod]]) and return true on success, false on failure. | :Adds a mod to the item's mod list and sets the IF_MODIFIED flag. This does not apply any affects of the mod, it is only a primitive operation for accessing the mod list. ''modletter'' should be a single uppercase letter representing the mod. This will check modding restrictions (as [[#item_can_mod|can_mod]]) and return true on success, false on failure. | ||
---- | ---- | ||
− | {{ | + | {{moddef|desc|can_mod|cln|boolean|string|modletter}} |
− | + | ||
:Determines if the given mod can be added to the item. ''modletter'' should be a single uppercase letter representing the mod. This will always use the player's techbonus. It also accounts for limits on the number of mods of a given type and various modability item flags. | :Determines if the given mod can be added to the item. ''modletter'' should be a single uppercase letter representing the mod. This will always use the player's techbonus. It also accounts for limits on the number of mods of a given type and various modability item flags. | ||
---- | ---- | ||
− | {{ | + | {{moddef|desc|get_mod|cln|integer|string|modletter}} |
− | + | ||
:Counts the number of the given mod that have already been added to the item. ''modletter'' should be a single uppercase letter representing the mod. | :Counts the number of the given mod that have already been added to the item. ''modletter'' should be a single uppercase letter representing the mod. | ||
---- | ---- | ||
− | {{ | + | {{moddef|desc|clear_mods|cln|boolean}} |
− | + | ||
:Clears the counts of all mods for the item. The does not undo the affects of the mods nor does it change any flags (including IF_MODIFIED). | :Clears the counts of all mods for the item. The does not undo the affects of the mods nor does it change any flags (including IF_MODIFIED). | ||
---- | ---- | ||
− | {{ | + | {{moddef|desc|is_damaged|cln|boolean}} |
− | + | ||
:This determines if the item's durability is less than its maxdurability. For items with IF_NOREPAIR, this function always returns false. (So, in effect this function determines if the item needs to be repaired.) | :This determines if the item's durability is less than its maxdurability. For items with IF_NOREPAIR, this function always returns false. (So, in effect this function determines if the item needs to be repaired.) | ||
---- | ---- | ||
− | {{ | + | {{moddef|desc|fix|cln|boolean|integer|amount}} |
− | + | ||
:This will increase the item's durability by amount, respecting maxdurability. It returns true is the item is no longer is_damaged. ''amount'' is optional; by default the item is completely repaired. | :This will increase the item's durability by amount, respecting maxdurability. It returns true is the item is no longer is_damaged. ''amount'' is optional; by default the item is completely repaired. | ||
---- | ---- | ||
− | {{ | + | {{moddef|desc|get_mods|cln|table}} |
− | + | ||
:This will return a table that maps single character mod letters to the corresponding amount of mods that have been applied to the item. Mod letters that have not been applied are not included as keys. | :This will return a table that maps single character mod letters to the corresponding amount of mods that have been applied to the item. Mod letters that have not been applied are not included as keys. | ||
---- | ---- | ||
− | {{ | + | {{moddef|list|get_mod|ids|cln|table}} |
− | + | :As get_mods, but the table returned gives all mods in terms of their sID. | |
+ | ---- | ||
+ | {{moddef|desc|can_overcharge|cln|boolean}} | ||
:This will determine if the item can be overcharged. To be overcharged, an item can't already by overcharged (IF_DESTROY), and must be fully loaded. The ui part of overcharging is included. On success, IF_DESTROY and IF_NOUNLOAD are set, but other affects must be applied by the caller. | :This will determine if the item can be overcharged. To be overcharged, an item can't already by overcharged (IF_DESTROY), and must be fully loaded. The ui part of overcharging is included. On success, IF_DESTROY and IF_NOUNLOAD are set, but other affects must be applied by the caller. | ||
---- | ---- | ||
− | {{ | + | {{moddef|desc|check_mod_array|cln|boolean|string|nextmod|integer|techbonus}} |
− | + | ||
:This will check if the mod indicated by ''nextmod'' (the single uppercase character representing the mod) could form an assembly (given the provided techbonus). If so, the assembly is created on the item (if the player confirms the ui message) with all associated side effects. Returns true only if the assembly is actually created. | :This will check if the mod indicated by ''nextmod'' (the single uppercase character representing the mod) could form an assembly (given the provided techbonus). If so, the assembly is created on the item (if the player confirms the ui message) with all associated side effects. Returns true only if the assembly is actually created. |
Revision as of 19:39, 2 February 2012
DoomRL has many kinds of items. Weapons, powerups, levers, and other things are all items. Items inherit from the Thing class which handles some basic properties in common with beings.
Contents |
Prototype
New items are created from item prototypes. Think of an item prototype as a recipe for creating new items. There can be multiple pistols, but they all came from the same prototype. Prototypes are declared by passing a table with the desired properties to the Items function. The available properties depend on the item type. Engine hooks may also be included in the prototype. Mostly, the prototype's properties just describe items' initial properties (occasionally with different names). Items' properties can also mostly be changed after they are instantiated. Required fields are underlined. Sometimes required fields can safely be omitted, but this will generate a message in the log file. All item prototypes are stored in a global table called items. This table can be indexed by id or nid.
Item Prototype | ||
string | name | This is the item's name. |
string | id | This is the item's sid. It must be distinct from other string ids. (The numeric id is automatically generated and stored in the nid field of the prototype.) It defaults to the first word of the name in all lowercase. |
value list | overlay | This describes of color transformation of the item's sprite. It is only used in the graphical version. This will create overlay_red, overlay_blue, overlay_green, and overlay_alpha attributes for the prototype. |
Color | color | This is the item's color. The default is LIGHTGRAY. |
string | color_id | For the purpose of custom color bindings, this id will be used for the item. Multiple items (like levers) can have the same color_id to prevent them from being distinguished. |
integer | level | This is an item generation parameter. The default is 0. |
integer | weight | This is an item generation parameter. |
integer | sprite | This is the item's sprite. This field is only relevant to the graphical version; use 0 for no sprite. |
value list | coscolor | Some sprites (such as armor and boots) are color-neutral to begin: coscolor determines the color of the sprite in these cases. The list must be written in this form: {red,green,blue,alpha}, where all of these values range from 0.0 to 1.0. |
value list | glow | Creates a customized "glow" effect around the sprite. See coscolor for table specifications. |
Item Flag List | flags | The flags in this list will automatically be included in the item's flag set. The default is an empty list. Some flags may be added automatically. The prototype will automatically be given a flagSet property containing the flags in set format. |
ItemSet ID | set | If included, this item will belong to the given item set. This will modify the item's OnEquip and OnRemove hooks. |
string | firstmsg | If included, this message will be displayed when the an item with this prototype is picked up for the first time. This will modify the item's OnFirstPickup hook. |
integer | res_bullet | This is the item's res_bullet. The default is 0. |
integer | res_melee | This is the item's res_melee. The default is 0. |
integer | res_shrapnel | This is the item's res_shrapnel. The default is 0. |
integer | res_acid | This is the item's res_acid. The default is 0. |
integer | res_fire | This is the item's res_fire. The default is 0. |
integer | res_plasma | This is the item's res_plasma. The default is 0. |
ItemType | type | This is the item's itype. It also determines which other properties can be used in the prototype. |
Armor or Boots
These are the fields used by ITEMTYPE_ARMOR and ITEMTYPE_BOOTS.
Armor or Boots Prototype | ||
string | desc | This is the armor's description that is displayed in the inventory screen. |
integer | armor | This is the armor's armor property. |
integer | durability | This is the armor's maxdurability as well as its initial durability. The default is 100. (This should still be 100 for armors with no durability, as no durability is achieved by a flag.) |
integer | knockmod | This is the armor's knockmod. The default is 0. |
integer | movemod | This is the armor's movemod. The default is 0. |
string | ascii | This is the armor's picture. It should be a length one string. The default is "[" for body armor and ";" for boots. |
Consumable
These are the fields used by ITEMTYPE_PACK. This includes mods and relics.
Consumable Prototype | ||
string | desc | This is the pack's description that is displayed in the inventory screen. |
string | mod_letter | This is the shorthand letter by which the pack will be recognized as a mod. Do not fill this value unless this item is meant to be a mod pack. |
function | OnUse | Packs must provide an OnUse hook. |
string | ascii | This is the pack's picture. It should be a length one string. The default is "+". |
Powerup
These are the fields used by ITEMTYPE_POWER.
Powerup Prototype | ||
function | OnPickup | Powerups must provide an OnPickup hook. |
string | ascii | This is the powerup's picture. It should be a length one string. The default is "^". |
Ammo
These are the fields used by ITEMTYPE_AMMO.
Ammo Prototype | ||
string | desc | This is the ammo's description that is displayed in the inventory screen. |
integer | ammo | This is the ammo's initial ammo property. |
integer | ammomax | This is the ammo's ammomax property. |
string | ascii | This is the ammo's picture. It should be a length one string. The default is "|". |
Ammo Pack
These are the fields used by ITEMTYPE_AMMOPACK.
Ammo Pack Prototype | ||
string | desc | This is the ammo pack's description that is displayed in the inventory screen. |
integer | ammo | This is the ammo pack's initial ammo property. |
integer | ammomax | This is the ammo pack's ammomax property. |
string | ammo_id | This is the ammo pack's ammoid property. |
string | ascii | This is the ammo pack's picture. It should be a length one string. The default is "!". |
Ranged Weapon
These fields are used by ITEMTYPE_RANGED.
Ranged Weapon Prototype | ||
string | desc | This is the weapon's description that is displayed in the inventory screen. |
string | damage | This should be a string like "2d4"; the weapon's damage_dice and damage_sides will be parsed from this. |
DamageType | damagetype | This is the weapon's damagetype. |
string | psprite | This is the projectile sprite used with the weapon. It is only relevant in the graphical version. |
string | group | This is the weapon's group for purposes of kill counting. The used weapon groups are "weapon-melee", "weapon-pistol", "weapon-shotgun", "weapon-chain", "weapon-rocket", "weapon-plasma", and "weapon-bfg". The default is "weapon-other". |
string | ammo_id | This is the weapon's ammoID. |
integer | fire | This is the weapon's usetime. The default is 10. |
integer | acc | This is the weapon's acc. The default is 0. |
integer | ammomax | This is the weapon's ammomax and the weapon's initial ammo. |
integer | radius | This is the weapon's blastradius. The default is 0. |
integer | shots | This is the weapon's shots. The default is 0 (which will still give one shot). |
integer | shotcost | This is the weapon's shotcost. The default is 0 (which will still require one ammo). |
AltFire | altfire | This is the weapon's altfire. The default is ALT_NONE. |
AltReload | altreload | This is the weapon's altreload. The default is RELOAD_NONE. |
string | altfirename | This is the name the game uses for the weapon's alternate fire mode. Most of the AltFire constants provide defaults. |
string | altreloadname | This is the name the game uses for the weapon's alternate reload mode. Most of the AltReload constants provide defaults. |
string | sound_id | The sound_id will be used to look up sounds if there are no sounds defined for the weapon's actual id. By convention, this is set as the usual wielder's id when applicable. |
Missile ID | overcharge | This field is currently unused. |
Missile ID or Missile Prototype | missile | This is the weapon's missile. (It will be translated into an nid. To use a shotgun missile, the weapon must have the IF_SHOTGUN flag.) If this property is a table, it will be used to declare a new missile with the same id as the weapon. |
string | ascii | This is the weapon's picture. It should be a length one string. The default is "}". |
Natural Ranged Weapon
These fields are used by ITEMTYPE_NRANGED. Natural ranged weapons are usually defined inline in a Being definition.
Natural Ranged Weapon Prototype | ||
string | damage | This should be a string like "2d4"; the weapon's damage_dice and damage_sides will be parsed from this. |
DamageType | damagetype | This is the weapon's damagetype. |
string | group | This is the weapon's group for purposes of kill counting. The used weapon groups are "weapon-melee", "weapon-pistol", "weapon-shotgun", "weapon-chain", "weapon-rocket", "weapon-plasma", and "weapon-bfg". The default is "weapon-other". |
integer | fire | This is the weapon's usetime. The default is 10. |
integer | acc | This is the weapon's acc. The default is 0. |
integer | radius | This is the weapon's blastradius. The default is 0. |
integer | shots | This is the weapon's shots. The default is 0 (which will still give one shot). |
string | sound_id | The sound_id will be used to look up sounds if there are no sounds defined for the weapon's actual id. By convention, a natural weapon's soundID is the usual wielder's id. |
Missile ID or Missile Prototype | missile | This is the weapon's missile. (It will be translated into an nid. To use a shotgun missile, the weapon must have the IF_SHOTGUN flag.) If this property is a table, it will be used to declare a new missile with the same id as the weapon. |
string | ascii | This is the weapon's picture. It should be a length one string. The default is "?". |
Melee Weapon
These fields are used by ITEMTYPE_MELEE.
Melee Weapon Prototype | ||
string | desc | This is the weapon's description that is displayed in the inventory screen. |
string | damage | This should be a string like "2d4"; the weapon's damage_dice and damage_sides will be parsed from this. |
DamageType | damagetype | This is the weapon's damagetype. |
string | psprite | This is the projectile sprite used with the weapon. It is only relevant in the graphical version. |
string | group | This is the weapon's group for purposes of kill counting. The used weapon groups are "weapon-melee", "weapon-pistol", "weapon-shotgun", "weapon-chain", "weapon-rocket", "weapon-plasma", and "weapon-bfg". The default is "weapon-other". |
integer | fire | This is the weapon's usetime. The default is 10. |
integer | acc | This is the weapon's acc. The default is 0. |
integer | shotcost | This is the weapon's shotcost. The default is 0 (which will still require one ammo). |
AltFire | altfire | This is the weapon's altfire. The default is ALT_NONE. |
string | altfirename | This is the name the game uses for the weapon's alternate fire mode. Most of the AltFire constants provide defaults. |
Missile ID or Missile Prototype | missile | This is the missile used if for the throw alternate fire mode. |
Item ID | throw_id | In the case where the melee weapon can be thrown, this is the item that appears after the item is thrown. It defaults to the item itself. |
string | ascii | This is the weapon's picture. It should be a length one string. The default is "\". |
Lever
These fields are used by ITEMTYPE_LEVER. DoomRL levers usually also have a target_area custom property.
Lever Prototype | ||
string | desc | This is the full description of the lever used if the player has BF_LEVERSENSE2. |
string | good | This is the qualitative description of the lever used if the player has BF_LEVERSENSE1. By convention, this should be "beneficial", "neutral", or "dangerous". |
integer | fullchance | The level generation code will set the lever's target_area to the full map fullchance percent of the time. The default is 0. (To be fair, the level generation code won't generate custom levers.) |
string | warning | This message will be displayed by the level generation code if the fullchance roll succeeds. |
null | color_id | This field is required for levers. By convention, it is set to "lever". |
null | sound_id | If the particular lever doesn't have sound bindings, the game will use the sound ID to look for sound bindings. By default, this is "lever". |
string | ascii | This is the lever's picture. It should be a length one string. The default is "&". |
Teleporter
These fields are used by ITEMTYPE_TELE. The built-in teleport item has a custom target property. This can be set to any coord to control the destination.
Teleporter Prototype | ||
function | OnEnter | This hook is required for teleporters. |
string | ascii | This is the teleporter's picture. It should be a length one string. The default is "*". |
Flags
Item Flags | |
IF_CHAMBEREMPTY | For IF_PUMPACTION weapons, this flag indicates whether ammo is in the chamber or not. |
IF_UNIQUE | This flag is set for unique items. Unique items add a player history message when picked up as well as doing a screen blink. Unique items are also not destroyable. |
IF_EXOTIC | This flag is set for exotic items. This is used by the game to compile the special items list. |
IF_MODIFIED | This flag is automatically set for items that have been modded. |
IF_HALFKNOCK | If a weapon with this flag is wielded, all knockback against the wielder will be halved. |
IF_GLOBE | This is a marker flag for items that are disallowed in Angel of Masochism. |
IF_CURSED | Items with this flag cannot be unequipped. |
IF_RECHARGE | Items with this flag regenerate ammo or durability as with a Nano Pack. |
IF_CLEAVE | Items with this flag give the wielder the benefits of the Blademaster trait (as Butcher's Cleaver). |
IF_NOAMMO | Items with this flag don't consume ammo when fired. For the player, a weapon still must have ammo loaded to be fired. |
IF_NECROCHARGE | Items with this flag recharge as with IF_RECHARGE, but reduce the weilder's health by 1 for each point of recharge (as with Necroarmor). |
IF_PUMPACTION | Ranged weapons with this flag must be pumped after each shot as with the combat shotgun. |
IF_SINGLERELOAD | Ranged weapons with this flag only reload one ammo at a time (as with the missile launcher) instead of all at once. |
IF_PISTOL | This flag indicates whether the weapon counts as a pistol for the purposes of the Son of a Gun and Dualgunner traits. (For kill counting, the weapon group is used instead.) |
IF_SHOTGUN | This flag causes a weapon's missile to be treated as a shotgun id rather than a missile id. Also, this flag is used to decide if the Shottyman trait should count the weapon as a shotgun. (For kill counting, the weapon group is used instead.) |
IF_SPREAD | Ranged weapons with this flag fire three shots at once (as the tristar blaster and mancubus natural weapon). In 0.9.9.4, this flag is a bit buggy. |
IF_SCATTER | For ranged weapons with this flag, each shot is aimed at a different cell near the real target (as with the BFG 10K). |
IF_MODABLE | Allows a unique item to be fully modded. |
IF_SINGLEMOD | Restricts the number of allowed mods on the item to one. (For unique items, this must be used along with IF_MODABLE.) |
IF_DUALSHOTGUN | For multi-shot weapons, this flag eliminates all delay between shots and causes the firing sound to play only once. |
IF_AIHEALPACK | This flag allows the default AI to pick up and use the item. |
IF_NOUNLOAD | Ranged weapons with this flag cannot be unloaded. |
IF_NUKERESIST | Items with this flag will not be destroyed by nuking. |
IF_NODROP | Items with this flag will not be dropped when the carrier/wearer dies. |
IF_AUTOHIT | Weapons with this flag never miss (as with items modified by a sniper weapon pack). |
IF_SETITEM | This flag is automatically set for items that specify a set. |
IF_NODURABILITY | Armors and boots with this flag have no durability (as with items modified by an Onyx Armor Pack). |
IF_NODESTROY | Armors with this flag cannot be destroyed by damage. Also, items on the ground with this flag will not be destroyed by explosions. |
IF_NONMODABLE | Items with this flag cannot be modded. |
IF_NOREPAIR | Armors and boots with this flag cannot be repaired by normal methods (ie item:fix). Directly setting item.durability bypasses this prohibition. |
IF_ASSEMBLED | This flag is automatically set on assemblies. Items with this flag cannot be used for the base of any other assembly. |
IF_DESTROY | Weapons with this flag will be destroyed after firing (with a default message). The flag is used for overcharged weapons. |
IF_BLADE | Weapons with this flag are considered blades for the purpose of activating the flags used for Malicious Blades. |
IF_DESTRUCTIVE | Weapons with this flag deal double damage to cells (if they can hurt cells, see CF_FRAGILE.) |
Engine Hooks
These hooks can give greater flexibility for how items work. For some item types, a hook provides the primary function. Sometimes, the engine will add to explicitly defined hooks, but this shouldn't interfere with a modder's use of the hooks. However, modders should be careful when changing hooks.
Item Hooks | |
---|---|
boolean | OnCreate(Item self) |
boolean | OnPickup(Item self, Being getter) |
boolean | OnFirstPickup(Item self, Being getter) |
boolean | OnPickupCheck(Item self, Being getter) |
boolean | OnUse(Item self, Being user) |
boolean | OnUseCheck(Item self, Being user) |
boolean | OnReload(Item self, Being reloader) |
boolean | OnAltFire(Item self, Being firer) |
boolean | OnAltReload(Item self, Being reloader) |
boolean | OnEquip(Item self, Being equipper) |
boolean | OnEquipTick(Item self, Being wearer) |
boolean | OnEquipCheck(Item self, Being equipper) |
boolean | OnRemove(Item self, Being wearer) |
boolean | OnKill(Item self, Being dier, Being wearer) |
boolean | OnHitBeing(Item self, Being attacker, Being target) |
boolean | OnEnter(Item self, Being enterer) |
boolean | OnFire(Item self, Being firer) |
boolean | OnFired(Item self, Being firer) |
- OnCreate(Item self)
- This hook is called when the item is created. For ammo, beware: the game creates and destroys ammo items liberally as a normal part of ammo management.
- OnPickup(Item self, Being getter)
- When an item is picked up, this hook is called with the being that is picking the item up. This is most commonly used to implement powerups.
- OnFirstPickup(Item self, Being getter)
- When an item with a given id is picked up for the first time, the function is called. This only works for items that go into the inventory.
- OnPickupCheck(Item self, Being getter) → boolean
- When a being tries to pick up an item, this function is called with the being that is trying to pick it up. If the return value is true, then the being is allowed to pick the item up, otherwise the being can't. For the player, both cases include the item in the player's previously found items. (This can affect OnFirstPickup.)
- OnUse(Item self, Being user) → boolean
- This hook is called when levers are used and when packs are used with the being that it using the item. For packs, if the return value is true, the item is consumed, otherwise it is left in the inventory. For levers, the return value is ignored and it is safe not to have a return value.
- OnUseCheck(Item self, Being user) → boolean
- This hook is called called before OnUse for levers and packs. If the return value is false, then the being can't use the item, otherwise it can. For levers, this can control whether the lever statistic is increased.
- OnReload(Item self, Being reloader) → boolean
- If it is declared, this hook is called when a weapon is reloaded. If the return value is false, then the normal reload procedure is aborted. This can be used to prevent reloading or to implement a custom reloading mechanism (like for the Acid Spitter). If true is returned, the weapon is reloaded normally afterwards.
- OnAltFire(Item self, Being firer) → boolean
- This hook works exactly like the OnFire hook, except it is called when the weapon's alternate fire mode is used for weapons with ALT_SCRIPT altfire.
- OnAltReload(Item self, Being reloader)
- If the weapon's altreload is RELOAD_SCRIPT, then this hook is called with when the weapon's alternate reload mode is used.
- OnEquip(Item self, Being equipper)
- This hook is called when the item is equipped in any equipment slot. Due to a bug, equipper is the active being. This is always correct during normal play, but modders must be careful when manually equipping items with this hook.
- OnEquipTick(Item self, Being wearer)
- While this item is equipped in any slot (including the prepared slot), this function is called on each of the being's actions. (Despite the name, it probably won't be called on every tick; it depends on the being's speed.)
- OnEquipCheck(Item self, Being equipper) → boolean
- This function is called (before OnEquip) when the player tries to equip an item. If the return value is true, then the player is allowed to equip the item; otherwise the player isn't allowed to equip the item.
- OnRemove(Item self, Being wearer)
- This hook is called when a being unequips the item, or when the item is otherwise removed from the being's equipment. This includes armor being destroyed by damage. Like OnEquip, this is called with the active being which can cause problems especially if this hook is called for armor destruction.
- OnKill(Item self, Being dier, Being wearer)
- When a being dies, this hook is called on all of the active being's equipment. This includes the prepared slot. (Weapons can check what slot they are in inside of this hook.)
- OnHitBeing(Item self, Being attacker, Being target) → boolean
- For weapons with no blastradius, this hook is called whenever a being is hit with the weapon. This hook is called before applying damage. If the return value is true, damage is applied as usual. Otherwise, the damage phase is skipped.
- OnEnter(Item self, Being enterer)
- This function is called whenever a being enters a cell that has the item lying on the floor. For the player, this supresses the usual "There is an item lying here" message. This is used in DoomRL to implement teleports.
- OnFire(Item self, Being firer) → boolean
- This hook is called when a weapon is fired. This only works for normal firing, not alternative firing (see OnAltFire). This hook is called before a target is selected. If the return value is true, then the rest of the normal firing operation is aborted. If the return value is false, then it continues as usual.
- OnFired(Item self, Being firer)
- This hook is called after a weapon is fired. This is after the entire usual firing procedure including damage, etc. Currently, this only works for the player.
Properties
Items also have all the Thing properties in addition to those listed below. For items, the meaning of the resistance fields vary depending on the item type. For armor and boots, the resistances are applied only to attacks to the corresponding target. For other equipment, the resistance applies to all attacks. For non-equipment, the resistances aren't used. Also, some properties are only valid for armor, and some are only valid for weapons. For these purposes, armor are items with itype ITEMTYPE_ARMOR and ITEMTYPE_BOOTS and weapons are items with itype ITEMTYPE_AMMO, ITEMTYPE_MELEE, ITEMTYPE_NRANGED, ITEMTYPE_RANGED, and ITEMTYPE_AMMOPACK. Properties of the incorrect type are always indexable, but they may share a memory address with properties of the opposite type, so modders should only use this feature very carefully. The type of such properties is noted. Also, the meaning of many fields is slightly different depending on the itype; these differences are also described.
Item | ||
ItemType | itype | This determines the basic features of the item. ITEMTYPE_NONE has no features; it can't be picked up or used. ITEMTYPE_RANGED can be picked up and wielded as a ranged weapon. ITEMTYPE_NRANGED is like ITEMTYPE_RANGED, but it isn't designed to exist on the map. ITEMTYPE_ARMOR can be picked up and equipped as armor. ITEMTYPE_MELEE can be picked up and wielded as a melee weapon. ITEMTYPE_AMMO is always a new ammo type that can be picked up and stacked. ITEMTYPE_PACK items can be picked up and used. ITEMTYPE_POWER items are consumed when they are picked up. ITEMTYPE_BOOTS can be picked up and worn as boots. ITEMTYPE_TELE have no special features, but by convention they interact with OnEnter. ITEMTYPE_LEVER have special description routines, and they can be used while on the floor. ITEMTYPE_AMMOPACK can be picked up and wielded in the prepared slot. They provide reloading benefits. While it is possible to change an item's itype, this should almost never be done. If it is done, care must be taken to account for overlapping weapon and armor properties. |
byte | armor | For armor and boots, this is the amount of protection provided at full durability. Weapons in the main slot may also provide a (universal) protection bonus with this field. |
word | durability | For armor and boots, this is the current amount of durability of the item. This property is armor-specific. |
word | maxdurability | For armor and boots, this is the maximum amount of durability. Most effects won't raise the durability above maxdurability. This property is armor-specific. |
integer | movemod | For armor and boots, this percentage movement speed modifier is applied while the item is equipped. This property is armor-specific. |
integer | knockmod | For armor and boots, this percentage knockback modifier is applied while the item is equipped. This property is armor-specific. |
Item ID | ammoid | This must always be a number id. For ranged weapons, this is the item id of the kind of ammo the weapon uses. For ammo packs, this is the kind of ammo provided by the pack. This property is weapon-specific. |
word | ammo | For ranged weapons, this is the amount of currently-loaded ammo. For ammo packs and ammo stacks, this is the amount of ammo inside. This property is weapon-specific. |
word | ammomax | For ranged weapons, this is the size of the magazine. For ammo stacks, this is the maximum stack size (unaffected by BF_BACKPACK). For ammo packs, this is the initial amount of ammo. This property is weapon-specific. |
word | acc | For ranged and melee weapons, this is an accuracy modifier applied to attacks with the weapon. This property is weapon-specific. |
word | damage_sides | For weapons, this is the number of dice rolled for damage (e.g. the X of XdY). This property is weapon-specific. |
word | damage_dice | For weapons, this is the number of sides on each die rolled for damage (e.g. the Y of XdY). This property is weapon-specific. |
integer | damage_add | For weapons, this is a flat bonus added to all damage rolls. This property is weapon-specific. |
Missile ID | missile | This must always be a number id. For ranged weapons, this is the missile used by the weapon. For melee weapons, this is the missile used by the throw alternate fire mode (if any). This property is weapon-specific. |
byte | blastradius | This is the radius of the explosion caused by a ranged weapon. This should be 0 for weapons with no explosion. This property is weapon-specific. |
byte | shots | This is the number of shots fired by a rapid-fire ranged weapon. This should be 0 (not 1) for single-shot weapons. This property is weapon-specific. |
byte | shotcost | This is the amount of ammo consumed by each shot with a ranged weapon. This should be 0 (not 1) for weapons that take only one ammo per shot. This property is weapon-specific. |
byte | reloadtime | This is the number of 0.1s intervals it takes (without modifiers) to reload a ranged weapon. This property is weapon-specific. |
byte | usetime | This is the number of 0.1s intervals it takes (without modifiers) to fire/use a weapon. This property is weapon-specific. |
DamageType | damagetype | This is the type of the damage caused by a weapon. This property is weapon-specific. |
AltFire | altfire | This is the alternate fire mode of a weapon. For ALT_SCRIPT, the details depend on the OnAltFire hook. This property is weapon-specific. |
AltReload | altreload | This is the alternate reload mode of a ranged weapon. For RELOAD_SCRIPT, the details depend on the OnAltReload hook. This property is weapon-specific. |
string | desc | This is the string used to describe the item in the inventory list. For the description in the inventory sidebar, use .proto.desc. This property is read-only. |
Item Prototype | __proto | This is the item's prototype. You can access item prototype fields using this (e.g., item.__proto.color). |
API
The Thing API can also be used with items.
Item Interface | |
---|---|
Item | new(Item ID iid) |
boolean | add_mod(string modletter) |
boolean | can_mod(string modletter) |
integer | get_mod(string modletter) |
boolean | clear_mods() |
boolean | is_damaged() |
boolean | fix(integer amount) |
table | get_mods() |
table | get_mod() → cln |
boolean | can_overcharge() |
boolean | check_mod_array(string nextmod, integer techbonus) |
- new(Item ID iid) → Item
- This returns a newly allocated item create from the specified prototype. This item doesn't exist in the game yet; it must be dropped on the level, added to an inventory, or equipped.
- add_mod(string modletter) → boolean
- Adds a mod to the item's mod list and sets the IF_MODIFIED flag. This does not apply any affects of the mod, it is only a primitive operation for accessing the mod list. modletter should be a single uppercase letter representing the mod. This will check modding restrictions (as can_mod) and return true on success, false on failure.
- can_mod(string modletter) → boolean
- Determines if the given mod can be added to the item. modletter should be a single uppercase letter representing the mod. This will always use the player's techbonus. It also accounts for limits on the number of mods of a given type and various modability item flags.
- get_mod(string modletter) → integer
- Counts the number of the given mod that have already been added to the item. modletter should be a single uppercase letter representing the mod.
- clear_mods() → boolean
- Clears the counts of all mods for the item. The does not undo the affects of the mods nor does it change any flags (including IF_MODIFIED).
- is_damaged() → boolean
- This determines if the item's durability is less than its maxdurability. For items with IF_NOREPAIR, this function always returns false. (So, in effect this function determines if the item needs to be repaired.)
- fix(integer amount) → boolean
- This will increase the item's durability by amount, respecting maxdurability. It returns true is the item is no longer is_damaged. amount is optional; by default the item is completely repaired.
- get_mods() → table
- This will return a table that maps single character mod letters to the corresponding amount of mods that have been applied to the item. Mod letters that have not been applied are not included as keys.
get_mod() → cln
- As get_mods, but the table returned gives all mods in terms of their sID.
- can_overcharge() → boolean
- This will determine if the item can be overcharged. To be overcharged, an item can't already by overcharged (IF_DESTROY), and must be fully loaded. The ui part of overcharging is included. On success, IF_DESTROY and IF_NOUNLOAD are set, but other affects must be applied by the caller.
- check_mod_array(string nextmod, integer techbonus) → boolean
- This will check if the mod indicated by nextmod (the single uppercase character representing the mod) could form an assembly (given the provided techbonus). If so, the assembly is created on the item (if the player confirms the ui message) with all associated side effects. Returns true only if the assembly is actually created.