kts.AddItem – add randomly generated item(s) to the dungeon


kts.AddItem(item_type, number, weights)


This generates the given number of items, of the given type, and adds them at random locations within the dungeon.

The table weights determines how the locations are decided. This must be a list of alternating tile category names, and numbers representing the weight given to that tile category. Higher weights indicate that the item will be more likely to be placed within a tile of that category. A weight of zero means that tile category will only be used if no tiles of the other categories are available.

(The tile category names correspond to the "items" field of the Tile, see kts.Tile for details.)

See below for an example.

Return Value

Nothing is returned.


Errors will be generated if parameters are missing or have the wrong types, if the weights table has an odd number of entries, if any weight is negative, or if all weights in the table are zero (at least one non-zero weight is required).


This function is intended to be used during initial dungeon generation. To add items to the dungeon during gameplay, use kts.PlaceItem.


The following command:

kts.AddItem( i_gem,
             { "chest",       3,
               "small_table", 1,
               "table",       1,
               "floor",       0  } )

will place four gems into the dungeon at random locations.

Each gem has a 60% chance (3 out of 5) of being placed in a "chest", 20% (1 out of 5) on a "small table", and 20% on a "table". If no tiles of those types exist in the dungeon (or if they all already have items on them) then the gem(s) will be placed on floor tiles instead.

This example assumes that i_gem was previously created by a call to kts.ItemType. It also assumes that suitable tiles have previously been created by calls to kts.Tile, and that the "items" property of at least some of the tiles was set to either "chest", "small_table", "table" or "floor".

See Also