I encountered an issue while building my second module, which raised a concern about the GetObjectByTag function that I now bring to your attention. First I will give a brief overview and then a quick “flowchart” to see if it might affect you … Info believed to be correct at time of writing.
A) ITEMS ONLY: In my experience, the problem encountered only arises when using GetObjectByTag with ITEM objects. This appears to be mainly due to items either coming into a module (with imported PCs) or waiting to enter (on creature encounters) or having been destroyed (by builders removing unwanted items from entering PCs). I have not had an issue using the function with any other object type.
B) RESULTS VARY: Subject to steps taken, the issue the function has with items will range from negligible for some modules to potentially game-breaking for others. How much the problem affects you depends upon how you deal with items in general.
THREE POTENTIAL ISSUES
- REMOVING ITEMS FROM ENTERING PCS: This is the most likely means of you introducing the problem. If you are a builder who removes items from a PC upon them entering your module, or NEED to remove some items to avoid item duplication, then removing items will lead you to a problem …
THE PROBLEM: Assuming you strip all items from the PC at this stage, then any item you have removed (and destroyed), using GetObjectByTag will still return them as a valid object.
THE SOLUTION: Just before you destroy the items on the PC, change the item’s TAG to something you will not refer to. (Thanks to KevL for this quick solution.) This helps avoid the FALSE return of an item that is no longer actually present in the game, as it no longer responds to the original tag.
NB: There is another solution, which we will actually describe in a moment that requires saving and reloading the game. This has the affect of seeming to clear down the “FALSE” items.
- ITEMS LEFT WITH IMPORTED PCS: This is the second most likely reason you will encounter the problem. If you are a builder who leaves all or any items on a PC who enters your module …
THE PROBLEM: Assuming you remove only some (or no) items from the PC at this stage, then not only will you have the issue above for said items (unless you did the change tag trick), but you will also be left with the next issue, which is that any of those imported items left on the PC, when later used (and destroyed), will also still remain valid with GetObjectByTag. E.g. The PC imports with a Barkskin potion, which the builder allows to remain on the PC. The PC then uses the potion. If the player has not yet saved and reloaded their game since the initial start, then using GetObjectByTag will still return the Barkskin potion as a valid object even though it has been used. So if the builder is trying to check if the PC has a Barkskin it will return TRUE, even if it has been used! NB: This problem goes away if the player makes a SAVE and RELOAD prior to the function being used.
THE SOLUTION: This version of the problem is slightly more serious, as a builder may well make reference to items the PC has on them at some time using the GetObjectBytag function. The only solution I have found is to either recommend in your module notes for the player to SAVE and RELOAD after all PCs have entered the module (or whenever they import a PC into the module), or, as I have done, force the player to SAVE and RELOAD via scripting. This event only triggers when a player imports a PC that carries items with them. A gentle reminder GUI fires within a heartbeat requesting the player to save and reload their game. The save/load menu then persists until the action has been done by the player.
- ITEMS ON ENCOUNTER CREATURES: This is the least likely problem you will face, but is worth considering if you change item properties on a module wide scale. I have only two scripts in my campaign where I had to edit the code to accommodate this next problem …
THE PROBLEM: Items held in a creatures inventory (blueprint), which are then associated with an encounter trigger will return as valid objects, but do not return any valid location, nor any valid owner. E.g. A bugbear blueprint has a plot item with “PLOT_ITEM_A” in their inventory. This creature is then associated with an encounter trigger placed in the module. Even if this trigger is never triggered, doing a GetObjectByTag for “PLOT_ITEM_A” will return valid. With the caveat that neither a valid location nor valid creature ownership for said item will be returned. However, if you were just testing to see if this plot item was in the game using this function, you may be misled into believing the item is present, even though it is actually just hanging around on a creature that may be spawned from an encounter subject to the encounter settings.
THE SOLUTION: Double check your scripts where GetObjectByTag is used to ensure it is not looking for an item that may potentially be sitting on a pending encounter creature. You can do so by testing for both a valid location and valid ownership of said item.
FUNCTION CHECK FLOWCHART
This is just a quick flowchart test to see if you need to take any action … It makes the assumption that you do have some usage of GetObjectByTag somewhere in your scripting.
Start at Q1:
Q1: Do you allow imported PCs? YES>Goto Q2. NO>Goto Q3.
Q2: Do you strip all, some, or no items from them? ALL>Goto A1. SOME>Goto A2. NONE>Goto A2.
Q3: Do you use encounter triggers? YES>Goto Q4. NO>Goto Q5.
Q4: Do any spawned creatures carry any plot items? YES>Goto A3. NO>Goto Q5.
Q5: Did you say you allowed imported PCs? YES>Goto A5. NO>A4.
A1: You will need to change the TAG of all destroyed items at time of removal. (Goto Q3.)
A2: You will need to inform (or force) your players to save and reload after importing any PCs. (Goto Q3.)
A3: You need to decide if GetObjectByTag is supposed to reference the item potentially here too. (END)
A4: You do not need to take any action at all. (END)
A5: Deal with imported PCs as mentioned. Unlikely any further action with other scripting required. (END)
As far as I know, everything reported here is true, but welcome feedback that may conform or deny these results.
My thanks goes to @kevL_s for his continued patience and help in tracking down these issues.