I hit an interesting problem today, and while I think I've figured out how to work around it, it still makes sense to post it here. These little issues often pepper the development process, and it's interesting to see what sort of shapes they can take.
Something I want to implement on the interface is to have not only the current verb button highlighted, but if an item is selected for use, to have the item's icon highlighted. This shouldn't be too hard - it's simply a matter of finding the right function to change an item's graphic, and then knowing how to use it. A search through the documentation led me to the function SetInvItemPic (int inv, int sprite_slot) - perfect. This is designed to change the inventory item "inv"'s graphic to the graphic in the sprite slot represented by "sprite_slot".
I added two inventory items and put in the code necessary to change their images to the highlighted images when they're selected, and back when they're not. It's extremely straightforward logic to put in place - and I'll probably be explaining how it all works later - so I didn't even bother testing the function to make sure it works (honestly, what can go wrong with such a simple function?)
When I compiled the game to test the functionality, I got an odd error. It claimed I had specified an invalid inventory item. I figured that maybe instead of calling items 1 and 2, it might start at index 0, and therefore need me to call items 0 and 1, but checking this proved this wasn't the case. How odd.
I tried substituting the direct values with a check which gets the current active inventory item number, rather than relying on preset integers. This also threw me an error. How could it claim that the item number was invalid when it was pulling the item number directly from the selected item? It makes no sense.
Frustrated, I went and tidied up a script module for work, figuring a break from the problem might help. That done, I came back to the code and tried clearing out all instances of the function, this time simply calling it once on game start, just changing item 1's graphic, to see if I could get it working by itself. It crashed again. I changed it to item number 2, and tried again.
It worked. Confused, I went back and changed it to item 1. Again, a crash. I then created a new item, item number 3, and tried changing the graphic of both 2 and 3 on game start. It worked perfectly.
I went back through and re-implemented the functions to change the items upon mouse selection/deselection - however this time using items 2 and 3, rather than 1 and 2. Tested the game and it worked perfectly.
The issue, then, seems to be that for whatever reason, this function cannot work with item #1. I have no idea how this could happen, but AGS was build by one chap, and this is an obscure function in an old version of the engine/editor. Perhaps there's some bug that snuck in here that was fixed at a later date.
Whatever the case, it shouldn't be too hard to work around. All I need to do, seemingly, is to have item 1 be a dummy item that can never be collected by the player. This means I'll never have to change its graphic, and hopefully will never have an issue with this again. As frustrating as it is to lose time while stuck on problems like this, it's nice to find a workaround. Hopefully I don't find too many more bugs like this down the path.