Standardized script-queue related commands

- The commands queueadd, queueremove, queueopt, queuedel and qiclear
  now all return true (success) or false (failure). - Taken/extended
  from AnnieRuru's PR #847.
- The constants HQO_OnDeath, HQO_OnLogOut, HQO_OnMapChange were renamed
  to QUEUEOPT_DEATH, QUEUEOPT_LOGOUT, QUEUEOPT_MAPCHANGE respectively.
- The name of the variable @QMapChangeTo$ used during the
  QUEUEOPT_MAPCHANGE event has been renamed to @Queue_Destination_Map$.

Signed-off-by: Haru <haru@dotalux.com>

5 files changed, 53 insertions, 44 deletions

diff --git a/db/const.txt b/db/const.txt
index ca78c223d..7b0b7c076 100644
--- a/db/const.txt
+++ b/db/const.txt
@@ -3356,9 +3356,9 @@ IT_AMMO	10
 IT_DELAYCONSUME	11
 IT_CASH	18
 
-HQO_OnLogout	1
-HQO_OnDeath	2
-HQO_OnMapChange	3
+QUEUEOPT_LOGOUT	1
+QUEUEOPT_DEATH	2
+QUEUEOPT_MAPCHANGE	3
 
 IOT_NONE	0
 IOT_CHAR	1
diff --git a/doc/script_commands.txt b/doc/script_commands.txt
index 6e2b92417..5219eed47 100644
--- a/doc/script_commands.txt
+++ b/doc/script_commands.txt
@@ -8964,17 +8964,21 @@ Returns the amount of entries in the queue instance of <queue_id>.
 
 ---------------------------------------
 
-*queueadd(<queue_id>,<var_id>);
+*queueadd(<queue_id>, <var_id>);
 
-Adds <var_id> to queue of <queue_id>, returning 1 if <var_id> is already
-present in the queue, otherwise returning 0.
+Adds <var_id> to queue of <queue_id>.
+
+Returns false if <var_id> couldn't be added (was already present in the queue),
+true otherwise.
 
 ---------------------------------------
 
-*queueremove(<queue_id>,<var_id>);
+*queueremove(<queue_id>, <var_id>);
+
+Removes <var_id> from queue of <queue_id>.
 
-Removes <var_id> from queue of <queue_id>, returning 1 if <var_id> is not
-present in the queue, otherwise returning 0.
+Returns false if <var_id> couldn't be removed (wasn't present in the queue),
+true otherwise.
 
 ---------------------------------------
 
@@ -8984,23 +8988,26 @@ Modifies <queue_id>'s <optionType>. When <option val> is not present
 <optionType> is removed from <queue_id>. When present it modifies
 <queue_id>'s <optionType> with the new <option val> value.
 
-Currently 3 options are available:
-HQO_OnDeath (1), HQO_OnLogout (2), HQO_OnMapChange (3)
+Returns true on success, false on failure.
 
-When HQO_OnMapChange event is triggered, it sets a temp char var
-@QMapChangeTo$ with the destination map name.
+Currently 3 options are available:
+- QUEUEOPT_DEATH (1)
+- QUEUEOPT_LOGOUT (2)
+- QUEUEOPT_MAPCHANGE (3)
 
-Note: The constant names are not final.
+When the QUEUEOPT_MAPCHANGE event is triggered, it sets a temp char var
+@Queue_Destination_Map$ with the destination map name.
 
 Example:
-	queueopt(.@queue_id,0,"MyNPC::MyOnQueueMemberDeathEventName");
+	queueopt(.@queue_id, QUEUEOPT_DEATH, "MyNPC::MyOnQueueMemberDeathEventName");
 	
 ---------------------------------------
 
 *queuedel(<queue_id>);
 
-Deletes <queue_id> and returns 1 when <queue_id> is not found, otherwise
-0 is returned.
+Deletes the queue <queue_id>.
+
+Returns false if the queue wasn't found, true otherwise.
 
 ---------------------------------------
 
@@ -9035,8 +9042,9 @@ Example:
 
 *qiclear(<queue_iterator_id>);
 
-Deletes a queue iterator from memory and returns 1 when it fails,
-otherwise 0 is returned.
+Deletes a queue iterator from memory.
+
+Returns false when it fails, otherwise 1 is returned.
 
 ---------------------------------------
 //=====================================
diff --git a/npc/custom/bgqueue/flavius.txt b/npc/custom/bgqueue/flavius.txt
index f93821264..99a4d5e0a 100644
--- a/npc/custom/bgqueue/flavius.txt
+++ b/npc/custom/bgqueue/flavius.txt
@@ -33,8 +33,8 @@ OnPlayerListReady:
 	set $@Croix_QueueBG1, queue();
 	set $@Guill_QueueBG1, queue();
 
-	queueopt($@Guill_QueueBG1,HQO_OnLogout,"start#bat_b01::OnGuillaumeQuit");
-	queueopt($@Croix_QueueBG1,HQO_OnLogout,"start#bat_b01::OnCroixQuit");
+	queueopt($@Guill_QueueBG1, QUEUEOPT_LOGOUT, "start#bat_b01::OnGuillaumeQuit");
+	queueopt($@Croix_QueueBG1, QUEUEOPT_LOGOUT, "start#bat_b01::OnCroixQuit");
 
 	set .@i, 0;
 
@@ -143,8 +143,8 @@ OnPlayerListReady:
 	bg_warp $@FlaviusBG1_id2,"bat_b01",311,224;
 
 	/* after warp */
-	queueopt($@Guill_QueueBG1,HQO_OnMapChange,"start#bat_b01::OnGuillaumeQuit");
-	queueopt($@Croix_QueueBG1,HQO_OnMapChange,"start#bat_b01::OnCroixQuit");
+	queueopt($@Guill_QueueBG1, QUEUEOPT_MAPCHANGE, "start#bat_b01::OnGuillaumeQuit");
+	queueopt($@Croix_QueueBG1, QUEUEOPT_MAPCHANGE, "start#bat_b01::OnCroixQuit");
 
 	donpcevent "countdown#bat_b01::OnEnable";
 	end;
diff --git a/src/map/pc.c b/src/map/pc.c
index d3b5498cc..1b7fcd610 100644
--- a/src/map/pc.c
+++ b/src/map/pc.c
@@ -5529,7 +5529,7 @@ int pc_setpos(struct map_session_data* sd, unsigned short map_index, int x, int
 		for( i = 0; i < sd->queues_count; i++ ) {
 			struct script_queue *queue = script->queue(sd->queues[i]);
 			if (queue && queue->event_mapchange[0] != '\0') {
-				pc->setregstr(sd, script->add_str("@QMapChangeTo$"), map->list[m].name);
+				pc->setregstr(sd, script->add_str("@Queue_Destination_Map$"), map->list[m].name);
 				npc->event(sd, queue->event_mapchange, 0);
 			}
 		}
diff --git a/src/map/script.c b/src/map/script.c
index f6de7041d..768677d12 100644
--- a/src/map/script.c
+++ b/src/map/script.c
@@ -18918,7 +18918,8 @@ bool script_hqueue_add(int idx, int var)
 /**
  * Script command queueadd: Adds a new entry to the given queue.
  *
- * Returns 1 if already in queue or in case of error, 0 otherwise.
+ * Returns 0 (false) if already in queue or in case of error, 1 (true)
+ * otherwise.
  *
  * @code{.herc}
  *    .@size = queuesize(.@queue_id);
@@ -18930,9 +18931,9 @@ BUILDIN(queueadd)
 	int var = script_getnum(st, 3);
 
 	if (script->queue_add(idx, var))
-		script_pushint(st, 0);
-	else
 		script_pushint(st, 1);
+	else
+		script_pushint(st, 0);
 
 	return true;
 }
@@ -18978,7 +18979,7 @@ bool script_hqueue_remove(int idx, int var)
 /**
  * Script command queueremove: Removes an entry from a queue.
  *
- * Returns 0 on success, 1 if the item wasn't in queue.
+ * Returns 1 (true) on success, 0 (false) if the item wasn't in queue.
  *
  * @code{.herc}
  *    queueremove(.@queue_id, .@value);
@@ -18990,9 +18991,9 @@ BUILDIN(queueremove)
 	int var = script_getnum(st, 3);
 
 	if (script->queue_remove(idx,var))
-		script_pushint(st, 0);
-	else
 		script_pushint(st, 1);
+	else
+		script_pushint(st, 0);
 
 	return true;
 }
@@ -19002,15 +19003,15 @@ BUILDIN(queueremove)
  *
  * When the option value isn't provided, the option is removed.
  *
- * Returns 0 on success, 1 on failure.
+ * Returns 1 (true) on success, 0 (false) on failure.
  *
  * The optionType is one of:
- * - HQO_OnDeath
- * - HQO_OnLogOut
- * - HQO_OnMapChange
+ * - QUEUEOPT_DEATH
+ * - QUEUEOPT_LOGOUT
+ * - QUEUEOPT_MAPCHANGE
  *
- * When the OnMapChange event is triggered, it sets a temporary character
- * variable \c @QMapChangeTo with the destination map name.
+ * When the QUEUEOPT_MAPCHANGE event is triggered, it sets a temporary
+ * character variable \c @Queue_Destination_Map$ with the destination map name.
  *
  * @code{.herc}
  *    queueopt(.@queue_id, optionType, <optional val>);
@@ -19024,7 +19025,7 @@ BUILDIN(queueopt)
 
 	if (idx < 0 || idx >= VECTOR_LENGTH(script->hq) || VECTOR_INDEX(script->hq, idx).size == -1) {
 		ShowWarning("buildin_queueopt: unknown queue id %d\n",idx);
-		script_pushint(st, 1);
+		script_pushint(st, 0);
 		return true;
 	}
 
@@ -19051,7 +19052,7 @@ BUILDIN(queueopt)
 			break;
 		default:
 			ShowWarning("buildin_queueopt: unsupported optionType %d\n",var);
-			script_pushint(st, 1);
+			script_pushint(st, 0);
 			return true;
 	}
 	script_pushint(st, 1);
@@ -19098,7 +19099,7 @@ bool script_hqueue_del(int idx)
 /**
  * Script command queuedel: Deletes a queue.
  *
- * Returns 0 on success, 1 if the queue doesn't exist.
+ * Returns 1 (true) on success, 0 (false) if the queue doesn't exist.
  *
  * @code{.herc}
  *    queuedel(.@queue_id);
@@ -19109,9 +19110,9 @@ BUILDIN(queuedel)
 	int idx = script_getnum(st, 2);
 
 	if (script->queue_del(idx))
-		script_pushint(st, 0);
-	else
 		script_pushint(st, 1);
+	else
+		script_pushint(st, 0);
 
 	return true;
 }
@@ -19270,7 +19271,7 @@ BUILDIN(qicheck)
 /**
  * Script command qiclear: Destroys a queue iterator.
  *
- * Returns 0 on success, 1 on failure.
+ * Returns true (1) on success, false (0) on failure.
  *
  * @code{.herc}
  *    qiclear(.@iter);
@@ -19282,12 +19283,12 @@ BUILDIN(qiclear)
 
 	if (idx < 0 || idx >= VECTOR_LENGTH(script->hqi)) {
 		ShowWarning("buildin_qiclear: unknown queue iterator id %d\n",idx);
-		script_pushint(st, 1);
+		script_pushint(st, 0);
 		return true;
 	}
 
 	VECTOR_INDEX(script->hqi, idx).items = -1;
-	script_pushint(st, 0);
+	script_pushint(st, 1);
 	return true;
 }