Content

General

The bot is the essential part of a pickup channel. It helps organise the games,
gives certain information about users and manages the channel. It basically does
everything to run pickup games.

In the following we will explain how our bot works, how you can control it and
what you can expect from it in certain situations.

This will help to ensure that a particular behaviour of the bot isn't considered
a bug and that our users will understand how the system actually works.

Features and Commands

The bot offers several features and commands which will be explained in the following
in detail.
The structure will be like: the command and its aliases, brief introduction, messages,
you may receive and actions by the bot.

NOTE:

Each topic update is delayed on purpose and should not be considerd lag.
Commands which can cause a topic update are aggregated within that time.
This is done to reduce the amount of topic changes within the channel.
Notices and private messages are sent immediately though.

!add [<gamemode>] [<gametype>] (aliases: !a)

Brief Introduction:

The most used command is probably !add. This command will add you to the current
pickup as long as you're not locked or already added.
The bot will send you a notice about your add.

Without any options !add will add you to the default gamemode. If the optional gamemode parameter is given you'll
be added to the specified gamemode if available.
The gametype is also optional and only necessary for cross-channel-adds. (?)

Messages:

If a server hasn't been added yet and you're not locked:
Notice: "You have been added to CTF pickup. Your QLAcc is: .... If this is wrong, contact an admin.
The game will only start if a server was added. Feel free to add one with !server <url>"

If you are already added and a server isn't yet:
Notice: "You are already added. However, you may want to add a server with !server"

If you are already added and a server is as well:
Notice: "You are already added."

If you are locked:
Notice: "I am sorry, but you are still locked for ... Reason: ..."

Action:

If !add is executed successfully:
The topic will be updated if the user was added to the pickup.

If the necessary amount of players are added:
The game will be ready. That leads to resetting the topic and sending
messages to each player and final public messages. For more details
see Game ready.

!remove (aliases: !r)

Brief Introduction:

This command will simply remove you completly from the current pickup as long
as you're added.

The server which was added by a user who is being removed will be removed as well.

Messages: -

Actions:

The topic will be updated if the user was removed from the pickup.

!who [<gamemode>](aliases: !w)

Brief Introduction:

This will send a public messages to the channel with a list of players currently being added.
If a gamemode is specified the list for the corresponding mode will be shown, otherwise the default mode is used.
People who are in that list are not getting highlighted since we've added a
zero-width space in the middle of each nick.

Messages:

Public: "CTF pickup: Added players [ 3 / 8 ] Tin​kuuu (52m), qwert​yman1 (36m)<- [???], pa​w_ (12m)"

Actions:

Sending a public message.

!promote (aliases: !p)

Brief Introduction:

This will do a promotion for the current pickup to get more people involved.
If more than 60% are added to the topic, the bot will send a promotion message accross
all channels it is idling in.
It will also send a message via XMPP to everybody who's got the 'playquake' account added
to his friendlist in QuakeLive.

Messages:

Within the actual channel
Public: "CTF Pickup: 1 more player(s) needed in #ctfpickup - type '!add' now!"

Cross channel message
Public: "CTF Pickup: 1 more player(s) needed in #ctfpickup - type '!add CTF' here if you're in the chan or join there!"

Actions:

Sending a public message and messages via XMPP to QuakeLive.

!sub <player> [<sub>]

Brief Introduction:

Sometimes it happens that a player needs a substitute for whatever reason.
With this command it is possible to substitute that particular player for another one.
The bot will search for the player to be substituted within the most 3 recent games and
within the last 20 minutes.
Once the player could be found the bot will create new teams and inform each player involved
about certain changes.

There are 2 possible ways to use this command. If !sub <player> is executed, the one who is executing
the command will be replacing <player>. If !sub <player> <sub> is executed, <sub> will be replacing
<player>.

If the old map picker is being replaced, a new one is picked.

Also, the sub doesn't bother to remove if he was actually added. The bot will remove him
automatically if necessary.

In order to have this command work properly one has to make sure that the names are spelled correctly.
This command is case sensitive.

Messages:

If the bot was just started:
Public: "Sorry. Last match was before bot restart."

If <sub> is not in the channel:
Public: "<sub> is not here."

If <player> could not be found in one the recent games:
Public: "<player> was not added or has already been subbed."

If <sub> is not known by nick (in QL):
Public: "<sub> is not known in QL (by nick)"

If <sub> is already playing a game.
Public: "<sub> is already in that game. (#<gID>)"

If everything worked out well, new teams are generated and public message is sent:
Public: "--- UPDATED TEAMS ---"
Public: "Team Red: alexxys, corvu, kirson, FisHBone Team Blue: Tinkuuu, paw, _rage_q3, bandit-- Map picker: FisHBone"

If !sub is executed successfully:
The one who is substitute:
Private: "Thanks for helping out. Please connect to: <server> <password> You are on team <team>."
Everyone else:
Private: "<player> is substituted for <sub>. New teams were generated. You're on team Blue now. Map picker: <mappicker>"

Actions:

If !sub is executed successfully:
Generating new teams and sending messages respectively.
Removing <sub> from the current topic if necessary.

!server [<gamemode>] <serverlink> [<password>] (aliases: !s, !sv)

Brief Introduction:

Each pickup game needs to be played on a server. This command is used to add such a server to the next game.
Since a server is absolutley necessary to play, a game won't be ready before a server is added.

If a game is _almost_ ready, that is 8/8 player are added but no server is yet, the bot will ignore any
!add command. An appropriate message is sent (See messages).

If no server is added, brackets and a few other indicators are colored yellow. Once a server is added
they are colored green. Only server indicators are colored yellow or green.
Depending on your IRC client and the theme used the colours may differ. Since
the bot makes use of default IRC color codes, it is recommended to do so on client side as well.

To be able to add a server to the game you'll have to be either admin, granted voice status or being
added to the next game. Normal player can only add server to modes they are added to, voiced players and admins can add servers to any mode
at any time even without being added.

You can specify the gamemode to which the server should be added to.

If a server is added, it can be updated by either an admin or the server owner. Server owner is the one
who added the server rather than the one who actually spawned the server.

If !server is executed without any arguments, either the currently added server is posted via notice
or an appropiate message is sent. Again, this affects only admins, voiced and added player.

Two type of a serverlink can be passed to the !server command. A short one with 6 digits being the
match id at the end like http://www.quakelive.com/#!join/516452. This is considered a matchlink.
Or a long one with 32 signs (hex) at the end like http://www.quakelive.com/#!join/7d2625da-f32b-47fa-bdc8-f60647a46299
which is considered a invitelink.
If an invitelink is used, the bot will parse the link and then uses the parsed password instead of the one passed to
the command.

Determine the correct mode

If no gamemode is specified the bot will always pick the mode you're added to over anything else no matter if you're an admin or
a normal user. If you want to add a server to a different mode while being added to another one already, you'll have to specify the gamemode.
The order goes like: mode you're added to > default mode > specified mode

Messages:

If no server is added and !server without arguments is executed:
Notice: "No Server added yet. To add a server use: !server <url> [<pw>]"

If a server is added and !server without arguments is executed:
Notice: "Server: <serverlink>"
Notice: "Password: <password>" (only if one was added)
Notice: "Added by <serverowner>"

If a server was added and is updated:
Notice: "Thank you for updating the gameserver."

If someone apart from admin or serverowner is trying to update the server:
Notice: "You are not allowed to update the server."

If the server was added successfully:
Notice: "Thank you for adding a gameserver."

Actions:

If the server was added successfully:
The topic is being updated and the colour of the indicator, that is the brackets, is updated.

If a game was _almost_ ready and a server is then added:
The game will be ready. That leads to resetting the topic and sending
messages to each player and final public messages. For more details
see Game ready.

!changesv [<gameid>] <serverlink> [<password>] (aliases: !chgsv, !csv, !cs)

Brief Introduction:

Changing the server is different to updating the current server with !server.
This command is used to provide the abillity for changing a server after a
game has been ready or started already.
This may be necessary if the server is used for another game and was added on accident
or if it turns out afterwards that the server is down.

Once the command is executed the bot will search for the most recent 3 games within the
last 20 minutes where the player who executed the command was involved.

Admins are able to specify a gameid to change the server respectively.

Messages:

If the bot was just started:
Public: "Sorry. Last match was before bot restart."

If a non-admin is trying to change the server using a gameid:
Notice: "You can't specified an ID if you want to change the server."

If no corresponding game was found using a gameid:
Notice: "You can't change the server. Game is either to old or does not exist."

If no corresponding game was found:
Notice: "You can't change the server. You haven't been part of any recent pickup games."

If the command was executed successfully:
Public: "Server for game #22 has been changed. Please connect to: http://www.quakelive.com/#!join/512983 Password: zxcvz"
Private: "The server for your pickup game has been changed. Please connect to: http://www.quakelive.com/#!join/512983 Password: zxcvz"

Actions:

If the command was executed successfully:
Public and private messages are sent respectively.

!rmserver (aliases: !rs, !rsv)

Brief Introduction:

This command simply removes the server from the current topic.
Only the serverowner or admins can remove the server.

Messages:

If the server doesn't belong to the commad executer:
Notice: "Cannot remove server, you are either not added or it is not your server."

If the command was executed successfully:
Notice: "The server has been removed."

Actions:

If the command was executed successfully:
The topic is being updated and the indicators are colored yellow.

!lastgame (aliases: !l, !last)

Brief Introduction:

This command gives quick information about the recent game.
When did who play on which server.

Messages:

Public: "Last CTF Pickup (#playquake) started 28mins 52secs ago. Players: re4​lity, ska​thi, ri​ne, gar​bol, X​er, kil​l^^, vi​tya, ph0​en|X."
Public: "Server: http://www.quakelive.com/#!join/2439ca68-b858-49ed-96f6-4df2b0c343bc Password: pq"

Actions:

Sending a public message.

!iam <qlnickname>

Brief Introduction:

To ensure teams are generated properly the bot needs to know each IRC user by QL nick.
This command is used by users to become known to the bot.

In order to have this work properly one has to have played at least one pickup game
and this game has to be stored in our database already. Played games are parsed
every 20 minutes. See Further Details for more details on that.

If an unknown player was added to a recently starting game and used !iam afterwards, teams will be
updated.

Messages:

If the QL nick is already known:
Public: "I know <nickname> as <qlnickname>. If this is not correct message an admin."

If a player is not known or hasn't played for a long time:
Public: "I'm sorry, but <qlnickname> has not played a game in the last year"

If the command was executed successfully:
Public: "Ok. <nickname> plays QL as <qlnickname>"

If !iam caused a team update:
Public: "--- UPDATED TEAMS ---"
Public: "Team Red: alexxys, corvu, kirson, FisHBone Team Blue: Tinkuuu, paw, _rage_q3, bandit-- Map picker: FisHBone"

Actions:

Sending public messages.
Storing certain information about the player.
Updating teams if necessary.

!stat

Brief Introduction:

This command will display a few player stats about the player who issues the command.

Meaning of */30/7:
* = overall games played
30 = games played the last 30 days
7 = games played the last 7 days

Messages:

Public: "vsm: Games (*/30/7): 550/12/0 30-Day-Stats: Winratio: 0.6667 AvgScore: 507 Rating: 493.0"

Actions:

Sending public message.

!top15[w,m]

Brief Introduction:

As the name implicit you'll be shown the top 15 of played pickup games.
There are 3 types of top 15 lists. Overall (!top15), the last 30 days (!top15m)
and the last 7 days (!top15w) played games.

As for !who, players are not getting highlighted by the message because of the zero-width space
within the names.

Messages:

Overall output:
Public: "0​3 (1428), bandi​t1111 (993), ph0​enX (989), C3n​oB1t (968), Pet​tern (966), h​T (930), Di​mmo (894), ek​i22 (867), rai​den (843), Ra​ist (834),
ab​so (800), Ke​rsi (797), Rees​eend (787), n3​mo (786), riddl​er618 (781)"

Last 30 days:
Public: "Tin​kuuu (76), p​aw (74), 0​3 (56), spe​nzer (52), Pet​tern (44), Maste​rmind (44), socke​rpappa (44), tolst​yitrol (44), rai​den (41), h​T (38),
R​TB (36), Ra​ist (34), Mop​b14 (33), kub​s0n (31), ph0​enX (30)"

Last 7 days:
Public: "p​aw (32), Tin​kuuu (27), socke​rpappa (18), bandi​t1111 (14), R​TB (13), Ma​xtt (12), PY​TON (12), kub​s0n (10), 0​3 (10), rai​den (9), Pet​tern
(9), he​adz (8), ni​x0n (8), Maste​rmind (8), wo​lf (7)"

Actions:

Sending public message.

!game (aliases: !g)

Brief Introduction:

By executing this command the bot will list all currently active games.
Thus it is easy to find out if a game might end soon and whether it is worth adding. (In fact, its always worth it!)
The list includes the game id of each game.
Adding the gameID to it, the command can then provide further information about a particular game.

Detailed information are status of the game, score, map, actual time still to play and the teams.

Messages:

If no game is running:
Public: "No games active at the moment."

If active games available:
Public: "5 active Games: #9c started 23mins 22secs ago. #0d started 7mins 56secs ago. Detailed infos with !gameinfo <gameid>"

Actions:

Sending public messages.

Messages:

If the game couldn't be found:
Public: "Couldn't find any games with ID <gameid>"

If a game has not yet started:
Public: "Match has not yet started..."
Public: "Players: Team Red: paw, dcr, aka03, majinz Team Blue: khan____, Deimo, Raist, PYTON"

If a game is running and the teams are tied:
Public: "Teams are tied with a score of 2:2 on Ironworks with 2mins to go."
Public: "Players: Team Red: paw, dcr, aka03, majinz Team Blue: khan____, Deimo, Raist, PYTON"

If a game is running and team red leads:
Public: "Team Red leads with 3:2 over Blue on Ironworks with 2mins to go."
Public: "Players: Team Red: paw, dcr, aka03, majinz Team Blue: khan____, Deimo, Raist, PYTON"

If a game is running and team blue leads:
Public: "Team Blue leads with 4:3 over Red on Ironworks with 15sec to go."
Public: "Players: Team Red: paw, dcr, aka03, majinz Team Blue: khan____, Deimo, Raist, PYTON"

Actions:

Sending public messages.

!mappool

Brief Introduction:

This command will get you to the current mappool.

Messages:

Public: "CTF map pool: Japanese Castles (p1), Troubled Waters (c2), Ironworks (c7), Spider Crossings (p9), Infinity,
Camper Crossing (p14), Shining Forces (p5), Courtyard (c10), Pillbox(new)"

Actions:

Sending a public message.

!help (aliases: !h)

Brief Introduction:

This command will get you to the help page.

Messages:

Public: "A list of commands and information can be found at: http://ctfpickup.eu/help"

Actions:

Sending a public message.

!rules

This command will get you to the rules page.

Messages:

Public: "Rules are written down at: http://ctfpickup.eu/rules"

Actions:

Sending a public message.

Further Details

The bot is doing a few things in the background to be of assistence
with certain things.

It takes track of added player and will remove them automatically if they
are added more than 2h and no games became ready during that time.

Played games are parsed every 20minutes in the background. Therefore you
can't expect stats (called by !stat) to be updated right after you played a game.

Multimode Support

The pickup system is capable of supporting multiple modes or sets per IRC channel.

Currently 4on4 (which is the default mode), 5on5 and Skilled (4on4) are the available modes.
Only the Skilled mode requires you to have a rating of 400 to be able to add to it. You can look up your rating with !stat.

Mode Aliases

There are aliases which can be used for specifing a mode when using !add, !who or !server commands to shorten things a little.
The default mode (which is 4on4) doesn't need to be specified at any time and can be left out (there is only one exception to it, see !server).
It'll just work as if there was only one mode.

ModeAliases
4on44, 4v4
5on55, 5v5
Skilleds

Game Ready

If a game is _almost_ ready, that is the necessary amount of player is added but a server is not,
the bot will post the following public message which will highlight each involved player.
Public: "CTF Pickup is almost ready! Please add a server with !server <url> [<pw>] to get started. sockerpappa, nix0n, tee3, raiden_, tr1x0, dan5, ntEE, Increas"

If a game has finally become ready the following messages are sent:
Public: "CTF Pickup is ready! Please connect to: http://www.quakelive.com/#!join/81f5a008-8845-4006-9832-de459d56fdbf Password: ctf"
Public: "Team Red: tee3, ntEE, tr1x0, raiden_ Team Blue: nix0n, sockerpappa, dan5, QLPrism-User-4 Map picker: ntEE"

Private: "Your CTF Pickup started in #ctfpickup! You are on team Red. Map picker: vsm_"
Private: "Please connect to: http://www.quakelive.com/#!join/511257 Password: ctf"