Adds BUILDIN(equipidx); BUILDIN(equip) now returns 0 or 1.

doc/script_commands.txt

@@ -5603,6 +5603,9 @@ item in his/her inventory, while the autoequip function will equip the
 given item ID when this is looted. The option parameter of the autoequip
 is 1 or 0, 1 to turn it on, and 0 to turn it off.
 
+equip() returns 1 if the item was successfully equipped and 0 if the
+item failed to equip.
+
 Examples:
 
 //This will equip a 1104 (falchion) on the character if this is in the
@@ -5622,6 +5625,30 @@ Examples:
 
 ---------------------------------------
 
+*equipidx(<index>)
+
+The equipidx function will attempt to equip the item at the given inventory
+inventory index. This feature is only really useful when multiple instances
+of an Item ID exist in the player's inventory.
+
+Returns 1 if the item was successfully equipped.
+Returns 0 if the item failed to equip.
+
+See getinventorylist() for an explanation on retrieving an inventory index.
+
+Examples:
+
+//	This will prioritize equip a rental Knife
+	getinventorylist();
+	for (.@i = 0; .@i < @inventorylist_count; ++.@i) {
+		if (@inventorylist_id[.@i] == Knife && @inventorylist_expire[.@i]) {
+			equipidx(.@i);
+			break;
+		}
+	}
+
+---------------------------------------
+
 *buyingstore(<slots>)
 
 Invokes buying store preparation window like the skill 'Open Buying

src/map/script.c

@@ -16473,21 +16473,28 @@ static BUILDIN(unequip)
 
 static BUILDIN(equip)
 {
-	int nameid=0,i;
+	int nameid = 0, i;
 	struct item_data *item_data;
 	struct map_session_data *sd = script->rid2sd(st);
-	if (sd == NULL)
-		return false;
 
-	nameid=script_getnum(st,2);
-	if((item_data = itemdb->exists(nameid)) == NULL)
-	{
-		ShowError("wrong item ID : equipitem(%d)\n",nameid);
+	if (sd == NULL) {
+		script_pushint(st, 0);
+		return true;
+	}
+
+	nameid = script_getnum(st, 2);
+	if ((item_data = itemdb->exists(nameid)) == NULL) {
+		ShowError("buildin_equip: Invalid Item ID (%d).\n", nameid);
+		script_pushint(st, 0);
 		return false;
 	}
+
 	ARR_FIND(0, sd->status.inventorySize, i, sd->status.inventory[i].nameid == nameid && sd->status.inventory[i].equip == 0);
+
 	if (i < sd->status.inventorySize)
-		pc->equipitem(sd, i, item_data->equip);
+		script_pushint(st, pc->equipitem(sd, i, item_data->equip));
+	else
+		script_pushint(st, 0);
 
 	return true;
 }
@@ -16515,6 +16522,48 @@ static BUILDIN(autoequip)
 	return true;
 }
 
+/**
+ * equipidx(<index>)
+ */
+static BUILDIN(equipidx)
+{
+	struct map_session_data *sd = script->rid2sd(st);
+
+	if (sd == NULL) {
+		script_pushint(st, 0);
+		return true;
+	}
+
+	int i = script_getnum(st, 2);
+	if (i < 0 || i >= sd->status.inventorySize) {
+		ShowError("buildin_equipidx: Index (%d) should be from 0-%d.\n", i, sd->status.inventorySize - 1);
+		script_pushint(st, 0);
+		return false;
+	}
+
+	if (sd->status.inventory[i].equip != 0) { // item already equipped, run silently
+		script_pushint(st, 1);
+		return true;
+	}
+
+	int nameid = sd->status.inventory[i].nameid;
+	struct item_data *item_data = itemdb->exists(nameid);
+	if (item_data == NULL) {
+		ShowError("buildin_equipidx: Invalid Item ID (%d).\n", nameid);
+		script_pushint(st, 0);
+		return false;
+	}
+
+	if (pc->equipitem(sd, i, item_data->equip) == 0) {
+		ShowWarning("buildin_equipidx: Item ID (%d) at index (%d) cannot be equipped.\n", nameid, i);
+		script_pushint(st, 0);
+		return false;
+	}
+
+	script_pushint(st, 1);
+	return true;
+}
+
 /*=======================================================
  * Equip2
  * equip2 <item id>,<refine>,<attribute>,<card1>,<card2>,<card3>,<card4>;
@@ -25491,6 +25540,7 @@ static void script_parse_builtin(void)
 		BUILDIN_DEF(equip,"i"),
 		BUILDIN_DEF(autoequip,"ii"),
 		BUILDIN_DEF(equip2,"iiiiiii"),
+		BUILDIN_DEF(equipidx, "i?"),
 		BUILDIN_DEF(setbattleflag,"si"),
 		BUILDIN_DEF(getbattleflag,"s"),
 		BUILDIN_DEF(setitemscript,"is?"), //Set NEW item bonus script. Lupus