From NWN Lexicon
Revision as of 00:53, 13 December 2019 by WilliamDraco (talk | contribs) (Remove confusing comments re: tag. sItemTemplate is always ResRef.)
Jump to: navigation, search

CreateItemOnObject(string, object, int, string)

Create a specific item in an objects inventory.

object CreateItemOnObject(
    string sItemTemplate,
    object oTarget = OBJECT_SELF,
    int nStackSize = 1,
    string sNewTag = ""



The blueprint ResRef string of the item to be created.


The inventory where you want the item created. (Default: OBJECT_SELF)


The number of items to be created. (Default: 1)


Sets the tag. If this string is empty (""), it be set to the default tag from the template. (Default: "")


This function creates an item with the ResRef sItemTemplate in oTarget's inventory.

Returns the object that has been created. On error, this returns OBJECT_INVALID. CreateItemOnObject will work on item containers.

Additional notes added for clarification in 1.64 include: If the item created was merged into an existing stack of similar items, the function will return the merged stack object. If the merged stack overflowed, the function will return the overflowed stack that was created.


The parameter nStackSize only applies to stackable items (eg. potions). If sItemTemplate refers to a non-stackable item (eg. armor) only 1 item will be created.

CreateItemOnObject has interesting behaviour when called to create a stackable item.

If the oTarget of the command has a stack already existing, the items created will be added to the existing stack, in which case two things can happen:

1. A new stack has to be created to hold some overflow. CreateItemOnObject returns a valid object, the overflowed stack of items (so, not the completly filled up stack)

2. The old stack object does not overflow past 99. No new stack object is created. CreateItemOnObject returns a value thats not equal to OBJECT_INVALID, but, if tested with GetIsObjectValid() will return FALSE.

Known Bugs

This bug will most likely be fixed in version 1.62, and thus only apply to 1.61 and possibly earlier versions as well:

Returns OBJECT_INVALID when the created object is added to an existing stack.




// The script below will create 5 ale potions in the inventory of
// the object to last use a placeable object.
object oTarget = GetLastUsedBy();
string sItemTemplate1 = "nw_it_mpotion021";  // The standard ale potion
int nStackSize = 5; // Create 5 items;
CreateItemOnObject(sItemTemplate1, oTarget, nStackSize);
// Now if we only change the item to create
string sItemTemplate2 = "nw_ashsw001"; // Standard small shield
// and run the command again
CreateItemOnObject(sItemTemplate2, oTarget, nStackSize);
// even tho nStackSize = 5 only 1 small shield will be created in
// oTargets inventory.

See Also



 author: Dave Withnall, editor: Jasperre, Mistress, additional contributor(s): Kirsten, Chris Becke, Andy Lange, Lilac Soul, Jasperre