Queue System - Scripting knowledge required

[plankt]

Queue System

The code is commented all the way through to ease the reading and understanding of it.

Updates

25/12: Redownload queue.txt, forgot silly quotation of a query at the bottom during testing.

25/12: Updated example at the bottom of the post to keep pulling if it gets an error.

27/12: Fixed a bug and optimized a variable, thanks KeyWorld. New version 1.01

14/06: Did some minor optimizations and commented better for linked lists. New version 1.02. I decided to stick with getgmlevel since it's a better way to sort influential people out then groupid.

If your server do not have table creation permission, please execute the query on line 29 separately.

Please do not use or redistribute this script without giving proper credits. Report all bugs you notice!

Files

queue.txt - Version 1.02

queue.txt - Version 1.01

queue.txt - Version 1.00

queuetest.txt - The script I used to bug test, good to check if unsure how to use the functions

speedtest.txt - Please run this and reply with the values

Prologue

When you create a script involving more than one player at a time, you usually have to limit the script or access in an ugly kind of way, or build a kind of waiting hall where the players have to sit until it’s their turn. You never find the time to make a sleek waiting system for every script you make.

You then remember playing another RPG where you could sign up, even sign up with friends, and you would be paired up with other people who signed up for the same event, battleground or PvP fight.

Look no further; this Queue system is what you’re looking for!

What is it?

This is a system that you embed in to your own script. It’s simple in its function but also powerful to let you customize it exactly to match what you need for the moment.

It lets you store players, parties or guilds in a queue. You can then retrieve them from that queue. Both actions have their own simple function call; “push” and “pull”.

You only need the player attached when “pushing” them to the queue and you will receive a list of Account IDs when you “pull” players from the queue.

Why would you, a mighty coder, use this system when you could just make it yourself? What makes it special enough to actually bother to include?

This system lets you put players and parties in the same queue. You can then tell it to retrieve, say, 20 players for you. For the current event, you do not care if people join with friends or by themselves so it will put together 20 people within your customizations and makes sure to keep the parties unbroken. It will also make sure that the players, who have waited the most, get picked first.

Features

Are there any more awesome features? Yes!

Full feature list:

General:

· Can support infinite amount of queues

· The list uses MySQL so no queue is lost when restarting the server

· Supports priority system (will be explained below)

· Custom error codes so you will know exactly what went wrong

· Supports linking events together (will be explained below)

Push:

· Supports single players, parties and guilds

· Can set level required for the queue

Pull:

· Can return mixed players/parties

· Can return only players

· Can return parties only until X players are found

· Can return a single party of a certain size

· You can choose how many players to pull from the queue

· If X players aren’t found, you can set it to return the IDs found or an error

Priority system:

If you want to make donators have a perk, if your event requires a champion to join fast or for any reasons don’t want players to wait, the priority system is something to use!

If you set priority to a player, they will be put first in the queue, bypassing those who have been waiting. This can ONLY be used when pulling players or players and parties. You cannot give parties priority.

Linked events:

If you have some events that you want people to be able to queue for at the same time, linking events is for you!

Say you have two events:

1. Event 1
   
2. Event 2
   

You can put a link together in 2 possible ways.

1) $@queue3[0], 1, 2; This will get players from queue 1 and 2 when asking for event 3.

2) $@queue1[0], 3; $@queue2[0], 3; This will get players from queue 3 when asking for 1 or 2.

What can I use it for?

Say you are making any kind if event, battleground, PvP room or if you just like to put people in to a queue to then announce the time for them.

All you have to worry about is (1) putting them in the queue and what should I do with the account IDs I’ve received when asking who was next in line. The rest just works.

How can I use it?

If you want a simple queue, you can just include the code and then copy/paste one of the examples below. If you want to make it fit perfectly in your script, then you should read up on the two functions described below.

First of all, there’s a NPC at the top of the script file. If you want to link events (see information about linking above) then you should edit that NPC. The main two functions you will be interacting with are “push” and “pull”.

The push function

callfunc("push", arg(0), arg(1), arg(2), arg(3));

• Type of input
  0. Player
  1. Party
  2. Guild
  

• Event number; 0 means all events
  

• Level required for the event
  

• Should the member get priority?
  0. No
  1. If GM level is above 0
  2. Yes
  

Function return values:

0. Successful

1. No player attached

2. Base level too low

3. Player is missing a party

4. Party size is too small ( < 2 )

5. A party member was offline

6. A party member was too low level

7. A player/guild was already in the queue

8. Player is missing a guild

9. Player is not guild leader

The pull function

This function sets two temporary, global variables. Make sure to copy them before the script gets another queue!

• $@queue[] – Contains all the IDs wanted
  
• $@queue_size – Contains the amount of IDs recieved
  

callfunc("pull", arg(0), arg(1), arg(2), arg(3));

• How you would like to search for players
  0. Both players and parties
  1. Only players
  2. Only parties
  3. Only guilds
  

• Event number; 0 means all events
  

• Amount of players wanted
  

• Required to fill the group
  0. Returns the ones found, even if it couldn’t find the amount wanted
  1. Returns an error if it couldn’t find the amount wanted (If you’re searching for parties only, this will search for a party at exactly the size specified)
  

Function return values:

0. Successful

1. Size wanted was 0

2. Didn't get the required amount of players from the DB

3. Didn't get the required amount of players after filtering

Example:

// Put the player in to the queue for event 1, lvl 5 is required
callfunc("push", 0, 1, 5, 0);
...
...
...
// Now I want to get 5 players for my event 1, I want to make sure I get all 5
while(callfunc("pull", 0, 1, 5, 1)) sleep 100; // Keep pulling untill we don't have an error
set .@queue_size, $@queue_size;
copyarray .@queue[0], $@queue[0], .@queue_size;
// Here I have all the account IDs in '.@queue' and I can use them as I want!

I have included the NPC I used to bug test the script. It will show how you use the functions described above. It can also erase the content of the table and fill it with dummy data for testing.

Edited June 14, 2012 by plankt

[Olrox]

Hi plankt. I remember when I asked for your help with some scripts... that was like a year ago, maybe 2.

I'm glad to know that you are active. Nice work btw... I would try it, however, I dont have a server anymore.

[Mercurial]

awesome , I'm definitely going to be using this when theres a need to do so

[Emistry]

Wow..a Queue System ~ This is nice ~ Great Idea ^^

[plankt]

@Olrox

Thanks, yeah, I've been off for a while but now I've got some free time to mess around, glad you like my script

@Mercurial

Would be glad to let it be of any use, it just popped in to my head the other day

@Emistry

Thanks, glad to see you liked it

@On topic: Please do run the test script so I can see the latency of some other servers then mine

[Diconfrost VaNz]

i dnt get it. what is this?xD

[Mercurial]

thats why the topic says you need to have scripting knowledge to understand

[Diconfrost VaNz]

i have scripting knowledge, but i can't just get it LOL even i'll try to turn the world upside down xD but i have a clue how this scripts works, but i need a confirmation for that xD

[plankt]

It's a script that handles any kind of queue for your script. I will soon release another project using it, until then the example, queuetest and speedtest should show how to use it.

If you have any questions, try to throw together something and reply with the code so I can take a look to see how you tried to use it

[manabeast]

ahhhh~~ complicated -.-" no understand zzzz. gg.com xD!

[KeyWorld]

Good idea, but some things have to be change, I didn't test the code so maybe I miss some things:

	set .@said, getcharid(3);
set .@pre, 0;

// Do not continue if a player is not attached
set .@id, playerattached();
if(!.@id) return 1;

The getcharid() part should be used after the playerattached() check.

It need "set $@pull_lock, 0;" just before the "return 2;"

		if(.@type == 3){
		if(!.@rn){
			return 2;
		}
		set $@queue, .@aid;
		set $@queue_size, 1;
	} else {

About the $@pull_lock, I don't see the point, the table should never be accessed by multiple instances at same time, rathena isn't multi-thread, so this should never happened.

	query_sql("CREATE TABLE IF NOT EXISTS `queue` (`id` int(6) NOT NULL AUTO_INCREMENT, `event` int(11) NOT NULL, `name` varchar(30) NOT NULL, `level` smallint(6) NOT NULL, `type` smallint(1) NOT NULL, `aid` int(11) NOT NULL, `size` smallint(4) NOT NULL, `pid` int(11) NOT NULL, `pre` smallint(1) NOT NULL, PRIMARY KEY (`id`))");

Be aware, my old server (and i hope some actuals servers) don't have privileges to create table.

		set .@query$, .@query$+",('"+.@event+"', '"+.@names$[.@i]+"', '"+.@level+"', '"+.@type+"', '"+.@aid[.@i]+"', '"+.@size+"', '"+.@party+"', '"+.@pre+"')";

Be aware with all your input, there is no check (escape the .@name$, be sure there is no overflow with your table size (smallint(1), etc.)).

			copyarray .@aid[0], $@partymemberaid[0], .@size;
	// For every partymember, check online, name and blvl
		for(set .@i, 0; .@i < .@size; set .@i, .@i+1){
			if(!attachrid(.@aid[.@i])){

You should check for account_id + char_id. Here you just check for the account, so if members are connect with another character in their account there is no error.

Maybe use constant instead of return 1,2,3,4,5,6,7,8,... should be great for the style.

Keep it up

[plankt]

Thanks for the input KeyWorld

The getcharid(3) was a later input to make sure I re-attached the right player after checking party members, guess I missed that I had the ID already, bad habit when coding at night ^^

The '$@pull_lock' is there to make sure the '$@vars' aren't overwritten until the scripter has been able to save them locally in their script. As for the '$@pull_lock, 0;' before the return, it should definitely be there. I think I accidentally removed it in an attempt to make the code section within the lock smaller.

As for input checking, seeing this function wants as little code executed as possibly for speed, not that it's been though optimization yet, but I chose to rely on the scripters ability of giving input. I'll probably add some kind of input check in the next release.

The user is automatically removed from the queue when logging off so there's no chance to switch characters unless they can bypass the log off event.

Edited December 27, 2011 by plankt

[plankt]

New version 1.02!

Did some minor optimizations and commented better for linked lists.

I decided to stick with getgmlevel since it's a better way to sort influential people out then groupid.

[kotsumu]

I have a question about the queue...

Lets say I have 3 events, players queue on all 3 events.

If the a player gets pulled from 1 event, does it remove that player from the other event's queue?

[plankt]

Currently, the player can only queue for 1 event at a time.

You can however link those 3 events together and let the player sign for all 3 at the same time.

When a player is pulled, he is removed from all queues.

Working on an update which will let the user be queued for several different events at the same time.

He will still be removed from all queues when pulled, this is to not mess up the scripts which holds the AID. Imagine two of them going bananas when a missing player is warped here and there. So it will be first come, first served.

[solid2005]

Reupload pls.

[plankt]

The link at the top works fine for me, it's hosted by the board.

[brunoshp]

1 example for registre w8 2 players and warp ! pls!

[plankt]

@brunoshp

You must check if the party has a size of 2.

Register a party for event #4:

callfunc("push", 1, 4, 1, 0);

Then you can get the next waiting party members' AID:

callfunc("pull", 2, 4, 2, 1);

Edited January 16, 2013 by plankt

[ossi0110]

pretty confused now , but whith this somone should be able too make a nice PVP script whit random groups. like a 4 vs 4

Edited January 16, 2013 by ossi0110

[brunoshp]

prontera,152,186,4 script SpeedTest 123,{
mes" hi";
callfunc("push", 1, 4, 1, 0); // for regist
next;
callfunc("pull", 2, 4, 2, 1); // fopr warp?
close;

Pls send me 1 exemple for player registre and warp for izlude.

[plankt]

Please download and have a look at "queuetest.txt" to get an idea on how you can use the Queue System.

The parts related to your script would summarized be:

For putting players in the queue, lets say we pick event #1

prontera,155,189,4 script<tab>Queue<tab>123,{
 // Check party size
 getpartymember(getcharid(1));
 if($@partymembercount != 2){ // If the party is not of size 2
close;
 }
 // Put them in the queue
 set @result, callfunc("push", 1, 1, 0, 0);
 if(@result == 0){
mes "Your party has entered the queue";
 }
 close;
}

For getting people from the queue, still event #1

while(true){
 while(callfunc("pull", 1, 1, 2, 1)) sleep 100; // Keep pulling untill we don't have an error
 set .@queue_size, $@queue_size;
 copyarray .@queue[0], $@queue[0], .@queue_size;

 // We now have AID of 2 people who are in the same party
 // in the array .@queue (.@queue[0] and .@queue[1])
 // Now we could warp them
 for(set .@i, 0; .@i < .@queue_size; set .@i, .@i + 1){
if(attachrid(.@queue[.@i])){
  warp "Izlude", 0, 0;
}
 }
}

Edited January 18, 2013 by plankt

[005]

GOOD JOB