Modding:Tutorial/Custom Items - Revision history

Epyon at 12:28, 11 August 2025

2025-08-11T12:28:06Z

Game Hunter: /* Weapon (_MELEE, _RANGED _NRANGED) */ syntax fix

2011-10-11T15:54:31Z

‎Weapon (_MELEE, _RANGED _NRANGED): syntax fix

Game Hunter: fixed engine hook syntax

2011-10-09T19:57:21Z

fixed engine hook syntax

Game Hunter: reorganization and minor details

2011-10-06T19:24:40Z

reorganization and minor details

Show changes

Game Hunter: split prototype/properties

2011-10-04T15:01:47Z

split prototype/properties

Game Hunter: added thing properties

2011-09-29T18:28:47Z

added thing properties

Game Hunter: /* Weapon: wrong default missile id

2011-09-29T14:17:47Z

/* Weapon: wrong default missile id

Game Hunter: fixes here and there

2011-09-26T13:35:02Z

fixes here and there

Game Hunter: quick fixes and added example for armor/boots (a bit incomplete)

2011-09-23T19:38:49Z

quick fixes and added example for armor/boots (a bit incomplete)

Game Hunter: added a bunch of other stuff, still need examples for some

2011-09-23T19:13:24Z

added a bunch of other stuff, still need examples for some

Show changes

@@ Line 33: / Line 33: @@
 *''id'' is the item identifier, to be used in lua whenever you want to call the item prototype.
 *''sprite'' is what will eventually be the graphical tile of the item.
-*''overlay'', like ''sprite'', is based on there being graphical tiles in DoomRL. You can ignore this key entirely for the time being.
+*''overlay'', like ''sprite'', is based on there being graphical tiles in DRL. You can ignore this key entirely for the time being.
 *''color'' is one of 16 (4-bit) [[Modding:Constants#Colors|colors]] that you can use to distinguish the item on the map. For items that can be picked up, this is also the color of the item's name in your inventory/equipment screens.
 *''level'' is the minimum level that the item can appear on, for random item generation purposes.
@@ Line 40: / Line 40: @@
 *''set'' defines what item set the item is in. For instance, the gothic armor/boots and phaseshift armor/boots are part of item sets. Item sets themselves are separate objects that must be defined before any item objects that use them.
 *''firstmsg'' is what will appear in the message area the very first time any item from this object prototype is picked up.
-*''color_id'' sets the id of the item for color-binding purposes. DoomRL levers, for instance, are all set to the same color_id, so that they cannot be disguished by a clever player manipulating color.lua carefully.
+*''color_id'' sets the id of the item for color-binding purposes. DRL levers, for instance, are all set to the same color_id, so that they cannot be disguished by a clever player manipulating color.lua carefully.
 *''res_[damage_type]'' sets the resistance for a particular damage type onto the item. This is only important for weapons, armor, and boots, as the resistance can only help if the item is equipped. (Note that DAMAGE_IGNOREARMOR has no resistance.)
 *''type'' is, quite possibly, the most important key for an item: it sets the item's type, which then determines what additional keys are required/allowed, what engine hooks it can use, and what properties it has. Each type will be explained over the course of the tutorial.
@@ Line 114: / Line 114: @@
 Teleporter items are almost identical to deadweight items, except that they must define an '''OnEnter()''' hook, since it is so pivotal in their function. Teleporters use '*' as their default ASCII character.
-In the case of DoomRL's base game, teleporter items are given an extra property using the '''OnCreate()''' hook that defines a particular coordinate on the map. This coordinate is then used during '''OnEnter()''' to teleport a being that enters the teleporter. Since we want the location to be different for every teleporter, this is why we don't have a location prototype key and, instead, have to alter its properties. A basic example is given below:
+In the case of DRL's base game, teleporter items are given an extra property using the '''OnCreate()''' hook that defines a particular coordinate on the map. This coordinate is then used during '''OnEnter()''' to teleport a being that enters the teleporter. Since we want the location to be different for every teleporter, this is why we don't have a location prototype key and, instead, have to alter its properties. A basic example is given below:
 <source lang="lua">
@@ Line 143: / Line 143: @@
 This example doesn't handle problems such as locations that exist in a cell that blocks movement, however, so it should be improved upon if you want a more useful random teleporter.
-Naturally, teleporter items don't need to be used as teleporters only: they are only named as such because of their unique use in the main game of DoomRL.
+Naturally, teleporter items don't need to be used as teleporters only: they are only named as such because of their unique use in the main game of DRL.
 ===Powerup (_POWER)===

@@ Line 455: / Line 455: @@
 *'''OnKill'''(''item'',''being'')
 *'''OnFire'''(''item'',''being'') triggers whenever ''being'' fires with ''item''. Its boolean return output determines whether or not ''item'' is fired.
-*'''OnAltFire'''(''item,''being'') triggers whenever ''being'' uses the alternate fire on ''item'' to attack. Its boolean return output determines whether or not ''item'' is fired.
+*'''OnAltFire'''(''item'',''being'') triggers whenever ''being'' uses the alternate fire on ''item'' to attack. Its boolean return output determines whether or not ''item'' is fired.
 *'''OnReload'''(''item'',''being'') triggers whenever ''being'' reloads ''item''. Its boolean return output determines whether or not ''item'' will be reloaded.
 *'''OnAltReload'''(''item'',''being'') triggers whenever ''being'' uses the alternate reload command with ''item''. Its boolean return output determines whether or not the alternate reload script on ''item'' is run.

@@ Line 103: / Line 103: @@
      type   = ITEMTYPE_NONE,
-     function OnEnter(_,being)
+     OnEnter = function(_,being)
          being.scount = being.scount - 100
      end,
@@ Line 126: / Line 126: @@
      type   = ITEMTYPE_TELE,
-     function OnCreate(self)
+     OnCreate = function(self)
          local location = coord.random(area.get(area.FULL))
          self:add_property("exit_pt",location)
      end,
-     function OnEnter(_,being)
+     OnEnter = function(_,being)
          being.displace(exit_pt)
      end
@@ Line 162: / Line 162: @@
      type = ITEMTYPE_POWER,
-     function OnPickup()
+     OnPickup = function()
          ui.msg("You feel protected!")
          player:set_affect(STATUSGREEN,100)
@@ Line 212: / Line 212: @@
      soundID    = "lever",
-     function OnCreate(self)
+     OnCreate = function(self)
          local location = area.around(self:get_position(),1)
          self:add_property(drop_pt,location)
@@ Line 219: / Line 219: @@
      end,
-     function OnUseCheck(self)
+     OnUseCheck = function(self)
          if self.times_used == self.total_use then
              ui.msg("Nothing happens.")
@@ Line 228: / Line 228: @@
      end,
-     function OnUse()
+     OnUse = function()
          ui.msg("An item materializes!")
          item = table.random_pick{"lmed","epack","pammo","pshell","procket","pcell"}
@@ Line 272: / Line 272: @@
      type = ITEMTYPE_PACK,
-     function OnPickupCheck()
+     OnPickupCheck = function()
          wpn_check  = player.eq[weapon] == "spear"
          armr_check = player.eq[torso] == "aarmor"
@@ Line 283: / Line 283: @@
      end,
-     function OnFirstPickup()
+     OnFirstPickup = function()
          ui.msg("You hear angels singing!"
          player.hp = player.hpmax * 2
@@ Line 289: / Line 289: @@
      end,
-     function OnUseCheck()
+     OnUseCheck function()
          if player.tired == false
              ui.msg("You are too tired to use this.")
@@ Line 298: / Line 298: @@
      end,
-     function OnUse()
+     OnUse function()
          ui.msg("You are flooded with holy energy!"
          player.hp = player.hpmax * 2

← Older revision		Revision as of 15:01, 4 October 2011
Line 45:		Line 45:
	Item types are always written as ITEMTYPE_[type], where [type] is the actual type of the item. A shorthand o this form (e.g., "_RANGED") will be used throughout the tutorial.		Item types are always written as ITEMTYPE_[type], where [type] is the actual type of the item. A shorthand o this form (e.g., "_RANGED") will be used throughout the tutorial.

		+	==Base Properties==
	Items only have two properties that coincide with all item types:		Items only have two properties that coincide with all item types:

@@ Line 44: / Line 44: @@
 Item types are always written as ITEMTYPE_[type], where [type] is the actual type of the item. A shorthand o this form (e.g., "_RANGED") will be used throughout the tutorial.
 Generally speaking, there are two practical groups by which item types can be categorized: inventory items and map items. Inventory items are anything that can be picked up and carried with you, while map items cannot. This categorization is used mostly for the convenience of this tutorial, as it is easier to find the item type you are looking for based on whether or not the item goes into your inventory.
@@ Line 49: / Line 77: @@
 ==Map Items==
-All items, both map and inventory, come with two properties and two engine hooks:
+All items, both map and inventory, come with two engine hooks:
-*Properties:
+*'''OnCreate()''' triggers whenever the item is created. Its primary function is to add properties to an item they may otherwise change from instance to instance.
-**''itype'' is the item type in property form. As _NONE, an item cannot be picked up or used.
+*'''OnEnter()''' triggers whenever a being enters the same tile as the item. Although technically it can be used with any item, it is most known for its use with the teleporter item type.
-**''proto'' is the prototype of the instantiated item.
-*Engine hooks:
-**'''OnCreate()''' triggers whenever the item is created. Its primary function is to add properties to an item they may otherwise change from instance to instance.
-**'''OnEnter()''' triggers whenever a being enters the same tile as the item. Although technically it can be used with any item, it is most known for its use with the teleporter item type.
 Map types have fewer properties and hooks associated with them, but they are by no means any less difficult to work with.

@@ Line 415: / Line 415: @@
      altreloadname = "full",          --default depends on altreload (_RANGED only)
      soundID       = "pistol",        --defaults to "id" (_RANGED and _NRANGED only)
-     missile       = "bullet",        --required field (optional for _MELEE)
+     missile       = "gun",           --required field (optional for _MELEE)
+}
 </source>

@@ Line 150: / Line 150: @@
      ....
      type       = ITEMTYPE_LEVER,                           --required type for a lever
-     good       = "neutral",                                --default is ""
+     good       = "neutral",                                --defaults to ""
-     desc       = "thermostat",                             --default is ""
+     desc       = "thermostat",                             --defaults to ""
-     soundID    = "lever",                                  --default is "lever"
+     soundID    = "lever",                                  --defaults to "lever"
-     fullchance = 10,                                       --default is 0
+     fullchance = 10,                                       --defaults to 0
-     warning    = "This place looks fully air-conditioned." --default is ""
+     warning    = "This place looks fully air-conditioned." --defaults to ""
+}
 </source>
@@ Line 312: / Line 312: @@
 </source>
-Ammo packs, on the other hand, can be customized a little bit if you want to be creative. Since they can be equipped, you can technically make use of the resistance prototype keys to grant extra resistance for equipping an ammo pack. In addition, the equipping hooks( OnEquip(), OnEquipCheck(), and OnEquipTick()) can also be used.
+Ammo packs, on the other hand, can be customized a little bit if you want to be creative. Since they can be equipped, you can technically make use of the resistance prototype keys to grant extra resistance for equipping an ammo pack. In addition, the equipping hooks( OnEquip(), OnEquipCheck(), and OnEquipTick() ) can also be used.
 ===Armor (_ARMOR) and Boots (_BOOTS)===
@@ Line 324: / Line 324: @@
      type  = ITEMTYPE_ARMOR, --use this for ITEMTYPE_BOOTS
      armor = 2,              --required field
-     durability = 100,       --default is 100
+     durability = 100,       --defaults to 100
-     knockmod = 25,          --default is 0
+     knockmod = 25,          --defaults to 0
-     movemod = -10,          --default is 0
+     movemod = -10,          --defaults to 0
+}
 </source>
@@ Line 399: / Line 399: @@
      ....
      type          = ITEMTYPE_RANGED, --use this, or ITEMTYPE_MELEE, or ITEMTYPE_NRANGED
-     damage        = "4d3",             --required field
+     damage        = "4d3",           --required field
      damagetype    = DAMAGE_BULLET,   --required field
-     group         = "weapon-pistol", --default is "weapon-other"
+     group         = "weapon-pistol", --defaults to "weapon-other"
-     fire          = 12,              --default is 10
+     fire          = 12,              --defaults to 10
-     acc           = 6,               --default is 0
+     acc           = 6,               --defaults to 0
-     radius        = 0,               --default is 0 (_RANGED and _NRANGED only)
+     radius        = 0,               --defaults to 0 (_RANGED and _NRANGED only)
-     shots         = 1,               --default is 0
+     shots         = 1,               --defaults to 0
      ammoID        = "ammo",          --required field (_RANGED only)
      ammomax       = 10,              --required field (_RANGED only)
-     reload        = 12,              --default is 10 (_RANGED only)
+     reload        = 12,              --defaults to 10 (_RANGED only)
-     shotcost      = 1,               --default is 0 (_RANGED only)
+     shotcost      = 1,               --defaults to 0 (_RANGED only)
-     altfire       = ALT_AIMED,       --default is ALT_NONE (_MELEE and _RANGED only)
+     altfire       = ALT_AIMED,       --defaults to ALT_NONE (_MELEE and _RANGED only)
-     altfirename   = "aimed shot",    --default based on altfire (_MELEE and _RANGED only)
+     altfirename   = "aimed shot",    --default depends on altfire (_MELEE and _RANGED only)
-     altreload     = RELOAD_FULL,     --default is RELOAD_NONE (_RANGED only)
+     altreload     = RELOAD_FULL,     --defaults to RELOAD_NONE (_RANGED only)
-     altreloadname = "full",          --default based on altreload (_RANGED only)
+     altreloadname = "full",          --default depends on altreload (_RANGED only)
-     soundID       = "pistol",        --default is id (_RANGED and _NRANGED only)
+     soundID       = "pistol",        --defaults to "id" (_RANGED and _NRANGED only)
      missile       = "bullet",        --required field (optional for _MELEE)
+}
@@ Line 420: / Line 420: @@
 *''damage'' is the weapon's damage, written in [[dice notation]].
-*''damagetype'' is the weapon's [[damage type]], one of seven possibilities. (See[[Modding:Constants#DamageType|DamageType]] for identifiers.)
+*''damagetype'' is the weapon's [[damage type]], one of seven possibilities. (See [[Modding:Constants#DamageType|DamageType]] for identifiers.)
 *''group'' is the group that the weapon belongs to, for statistical purposes. Note that setting this has no effect on weapon-specific traits like [[Son of a Gun]] or [[Shottyman]]: these are determined by the weapon's flags.
 *''fire'' is how long it takes to attack with the weapon, in game turns.
 *''acc'' is the [[accuracy]] of the weapon.
-*''radius'' is the [[explosion]] blast radius of the weapon's projectile. If radius is set to 0, no explosion occurs.
+*''radius'' is the [[explosions|explosion]] blast radius of the weapon's projectile. If radius is set to 0, no explosion occurs.
 *''shots'' is the number of times the weapon attacks or fires projectiles. The default, 0, still causes one attack to occur.
 *''ammoID'' is the identifer of the ammo that is to be used in this ranged weapon. This is what the weapon will look for in the player's inventory (or prepped slot in the case of ammo packs) when reloading.

@@ Line 56: / Line 56: @@
 *Engine hooks:
 **'''OnCreate()''' triggers whenever the item is created. Its primary function is to add properties to an item they may otherwise change from instance to instance.
-**'''OnEnter()''' triggers whenever a being enters the same tile as the item. Although technically it can be used for any item, it is most known for its coupling with the teleporter item type.
+**'''OnEnter()''' triggers whenever a being enters the same tile as the item. Although technically it can be used with any item, it is most known for its use with the teleporter item type.
-Map types have fewer properties and hooks associated with them, but they are by no means difficult to work with.
+Map types have fewer properties and hooks associated with them, but they are by no means any less difficult to work with.
 ===Deadweight (_NONE)===
@@ Line 342: / Line 342: @@
 *''movemod'' is the movespeed modifier of the item instance, as determined by the ''movemod'' prototype key.
 *''knockback'' is the knockback modifier of the item instance, as determined by the ''knockmod'' prototype key.
 === Weapon (_MELEE, _RANGED _NRANGED)===