A Better Way to Check for Existing Items Before Spawning

Many of you who have done my very first tutorial to create an item have been running into a problem.  When the script checks to see if you already have the item before creating a new one, it essentially only looks in your bags.  If the item isn’t in your bags, it can’t find it so creates a new one.

In this small tutorial we will look at a better way of checking for the item before spawning a new one.  A method that should accurately find the item even if it is no longer in your bags.

CountItemsByTag

int CountItemsByTag ( object oPossessor,
string sTag
)

Counts items with the given tag in the given container/inventory.

Parameters:
oPossessor – The placeable or creature to count items in.
sTag – The tag of the items to count.

In the original tutorial, we used the CountItemsByTag function to look and see if the player already had the item.  Essentially this function counts how many of items with the indicated tag are currently present in the specified objects inventory.  If the count was 0, then we figured the player did not have the item, so we created a new one.

This works, but it has several drawbacks.  It only checks the player’s bags.  If the player had the item, but it was somewhere else, the count would still come back as 0, so we would end up spawning a new one.  This most commonly happens when you equip the item on the player or a party member, or stick it in your storage chest.

Essentially, the problem with CountItemsByTag is its limited scope.  It only looks in one spot.  We need something that will have a wider scope, looking in more places for the item.

GetObjectByTag

object GetObjectByTag ( string sTag,
int nNth = 0
)

Returns the nth specified object with the appropriate tag, or OBJECT_INVALID on failure

Parameters:
sTag – The tag reference to get the object by
nNth – If there are multiple objects with the same tag, get the ‘nth’ specified object.

Returns:
the desired object or OBJECT_INVALID on failure

GetObjectByTag is a more generic object function, and is exactly what we need. This function has a much wider scope and will return any object, anywhere, that matches the specified tag as long as that object is currently loaded by the game.

You will notice though that this function works a bit different. Instead of the function returning to us the number of items with the specified tag, it instead returns the actual object itself.   By default it will return the first one it finds.  To make this do what we need we need to combine it with another function.

IsObjectValid

int IsObjectValid ( object oObject )

Returns TRUE if the object oObject exists and is a valid object, FALSE otherwise.

Parameters:
oObject – The object which may be valid.

Returns:
Returns TRUE if the object exists and is valid, FALSE otherwise.
Remarks:
This function is very similiar to checking whether an object is not equal to the OBJECT_INVALID constant, but this is a more robust check. An object that has been passed as a paramater in a delayed function call or has been stored as a local object will not equal the OBJECT_INVALID constant if the object has been destroyed since it was stored or passed. This function however will return FALSE in those circumstances. There is no instance where an object is equal to the OBJECT_INVALID constant and this function will return TRUE.

This function is very simple, and does exactly what it sounds like.  It tells us if the specified object is a valid object or not.

So how would we use these to check for an item before spawning a new one?  In pseudo-code:

Sword = GetObjectByTag("my_sword_tag")
If IsObjectValid(Sword) Then
     Do nothing - We already have the item
Else
     Spawn new Sword

Here is how this might fit into our original script

// All module events
#include "utility_h"
#include "wrappers_h"
#include "events_h"
void main()
{
    event ev   = GetCurrentEvent();
    int nEvent = GetEventType(ev);
    Log_Events("", ev);
    switch (nEvent)
    {
        case EVENT_TYPE_MODULE_LOAD:
        {
            // get the object which contains the player
            object oPlayer = GetHero();

            object oBow = GetObjectByTag("aga_bowofathena");
            if (!IsObjectValid(oBow))
                UT_AddItemToInventory(R"aga_bowofathena.uti",1);
            break;
        }
        default:
        {
            break;
        }
    }
}

Credits

This tutorial is based upon a writeup by Attono on DAMods