kts.ItemType – create a new ItemType
result = kts.ItemType{
allow_strength = <boolean>,
ammo = <item type>,
backpack_graphic = <graphic>,
backpack_overdraw = <graphic>,
backpack_slot = <integer>,
can_throw = <boolean>,
control = <control>,
critical = <boolean or string>,
fragile = <boolean>,
graphic = <graphic>,
key = <integer>,
max_stack = <integer>,
melee_action = <function>,
melee_backswing_time = <integer>,
melee_damage = <function or integer>,
melee_downswing_time = <integer>,
melee_stun_time = <function or integer>,
melee_tile_damage = <function or integer>,
missile_access_chance = <number between 0 and 1>,
missile_anim = <anim>,
missile_backswing_time = <integer>,
missile_damage = <function or integer>,
missile_downswing_time = <integer>,
missile_hit_multiplier = <integer>,
missile_range = <integer>,
missile_speed = <integer>,
missile_stun_time = <function or integer>,
on_drop = <function>,
on_hit = <function>,
on_pick_up = <function>,
on_walk_over = <function>,
open_traps = <boolean>,
overlay = <overlay>,
parry_chance = <number between 0 and 1>,
reload_action = <function>,
reload_action_time = <integer>,
reload_time = <integer>,
stack_graphic = <graphic>,
tutorial_key = <integer>,
type = <"held", "backpack", "magic" or "nopickup">
}
Note: all fields are optional – reasonable default values will be used for any nil fields. Most items will need to specify at least type, however.
An "ItemType" represents a "template" for creating items. For example, "axe", "hammer", "gem", and "ancient book of knowledge" are ItemTypes.
The kts.ItemType function creates a new ItemType. The parameter is a table containing various properties that the ItemType should have, as follows:
allow_strength is usually true (and this is the default). If set to false, then the usual effect of the Strength or Super potion, to automatically destroy dungeon tiles, is suppressed with this item. (The Strength/Super will still have its usual effect when the item is used to attack creatures.) This is used specifically with the Wand of Open Ways; see also kts.OpenWays. ammo specifies another ItemType which is the "ammo" for this weapon. This is used with the crossbow, where the ammo is the i_bolts ItemType. backpack_graphic specifies the icon that will be used to represent this item when it is carried by a knight. backpack_overdraw gives an image that is used in the inventory when the knight carries more than one of this item type. (The image only includes the "top part" of the icon, i.e. the part that is not covered by the icon below it.) backpack_slot gives the position where this item will appear in the on-screen inventory display. Slots 11 to 19 are used for normal items (left to right), 20 to 22 for keys, 23 for the lock picks, and 30 for gems. can_throw is true if the item can be thrown (like an axe). control gives a kts.Control that is available while this item is held. Examples include setting traps, throwing daggers, or using the lockpicks. critical specifies whether the item is "quest-critical" (which means it will be automatically respawned if it is destroyed for any reason). Examples of quest-critical items include wands, books and gems. critical may be set to true or false, or it may be set to a string like "A gem". (The latter case is the same as setting critical to true, but also, a message like "A gem has been respawned at a random location" will be displayed at the appropriate time.) fragile indicates that the item will be destroyed if it is inside a chest that is destroyed, or on a table that is destroyed. (E.g. potions.) graphic is the image to use for the item within the Dungeon. key is an integer between 1 and 3 if this is one of the three key types, or -1 if this is the lock picks. max_stack is the maximum number of these items that can be in a single "stack" on the dungeon floor. melee_action is a function that is called when the item is used to attack a target in melee. For example this is used to implement the special effects of the various wands. melee_backswing_time is the time (in milliseconds) for the "backswing" part of a melee attack, for this item. melee_damage is the amount of damage inflicted by this item when used to hit creatures in melee. It can also be a function returning a number (useful for randomisation). See also: melee_tile_damage. melee_downswing_time is the time (in milliseconds) for the "downswing" part of a melee attack, for this item. melee_stun_time is the amount of time (in milliseconds) that a creature hit by this item (in melee) will be stunned for. It can also be a function returning a number. melee_tile_damage is the amount of damage inflicted by this item when used to hit dungeon tiles (chests, tables etc.) in melee. It can also be a function returning a number. See also: melee_damage. missile_access_chance is the probability of the item passing through gates etc., when fired or thrown as a missile weapon. (Specifically, this applies to tiles with "partial" or "approach" access at the "missiles" access level. See also kts.Tile.) missile_anim is a kts.Anim used for the item while it is flying through the dungeon as a missile weapon. missile_backswing_time is the time (in milliseconds) for the "backswing" when this item is thrown as a missile weapon. missile_damage is the amount of damage inflicted by this item when it is thrown as a missile weapon. (This can also be a function returning a number.) missile_downswing_time is the time (in milliseconds) for the "downswing" when this item is thrown as a missile weapon. missile_hit_multiplier controls the probability that a missile will hit something. Specifically, the probability to miss is equal to 1 / (1 + Amount of range left * Missile Hit Multiplier). Therefore, the higher the missile_hit_multiplier, the higher the probability to hit, but the probability of hit also falls off with range. missile_range is the maximum range (in squares) of a missile weapon. missile_speed gives the speed at which a missile weapon travels through the dungeon. Typical values include 250 for the axe, 350 for daggers and 440 for crossbow bolts. missile_stun_time is the amount of time (in milliseconds) for which a creature will be stunned after being hit by this missile weapon. This can also be a function returning a number (useful for randomisation). on_drop is a function called whenever this item is dropped into the dungeon. The function takes no arguments, but the cxt variable will be available. on_hit is a function called whenever this item is hit with a weapon. The function takes no arguments, but the cxt variable will be available. on_pick_up is a function called whenever this item is picked up by a knight. The function takes no arguments, but the cxt variable will be available. on_walk_over is a function called whenever a knight or other creature walks onto the item (while it is in the dungeon). For example, this is used to implement the effect of bear traps. The function takes no arguments, but the cxt variable will be available. open_traps should be set to true if a knight can open trapped chests or doors safely while holding this item. This is used for the staff. overlay is the kts.Overlay used to represent the item on-screen while it is being held by a knight (or other creature). parry_chance is the probability that this item will successfully parry a blow in melee combat. reload_action is a function that is called repeatedly while the item is being reloaded with ammo. This is used by the crossbow to play the "clicking" sound effect while the crossbow is being loaded. reload_action_time is the time (in milliseconds) between calls to reload_action. reload_time is the total time before the weapon is loaded. stack_graphic is the Graphic used to represent a stack of these items in the dungeon (as opposed to graphic which is used when there is a single item). (If stack_graphic is unset, then graphic is used for both single items and stacks.) tutorial_key is an integer indicating which tutorial message (if any) is associated with seeing this item. type determines the type of item: "held" means the knight holds the item in their hands (like a sword or axe); "backpack" means the item is carried in the inventory (like daggers or gems); "magic" means the item is consumed when picked up (like potions or scrolls); and "nopickup" means the item cannot be picked up at all (like open bear traps). The new ItemType (a Lua userdata object) will be returned.
There are several different errors that can be generated if any of the input parameters are incorrect.
Several examples of ItemTypes can be found in the file knights_data/server/classic/items.lua in the Knights distribution.