In this tutorial you will use telnet, a simple TCP client, to remotely command a quagent, and gain understanding of [[ProtocolZero]].

== Setting Up ==
You will need either an installation of or access to the Quagents program. See [[TutorialInstall]].

You will also need telnet. Telnet comes installed on most development platforms, but if you don't have it, check out http://www.telnet.org.

'''Start up Quagents''' by opening a command prompt and running the Quake executable. This tutorial will use the map "firstroom", so provide "+map firstroom" as an argument. (The whole command, for me, is: "~jpawlick/quagents/build/release-linux-i386/ioquake3.i386 +map firstroom".)

If this is your first time running it, you'll probably want to open up the options menu and switch it out of fullscreen mode and turn down the resolution (press ESC to bring up these menus).

Your cursor is probably trapped inside the Quake window. Press ` (backtick) to bring up the game console and free your mouse (on QWERTY keyboards, the key just left of the 1 key).

In another command prompt, start telnet and connect to the localhost on port 6000 by typing "telnet localhost 6000". If you use a different telnet program than BSD telnet, you might have a different command. Telnet should connect and await your input.

== Initial Phase ==
You are now in the initialization phase of a quagent. Here you can provide a variety of commands that will control how the bot appears when it spawns. Let's change the name of the bot from the default by typing "name Oscar" and pressing RETURN (Oscar is the name of the Wizard of Oz). Then, type "ready" and press RETURN to spawn the bot. Telnet usually operates in LINEMODE, which means that you can backspace if you make a mistake (but keys like DELETE or HOME may not act as you expect). Hopefully, the bot spawned and the server said to you, "id 1". The 1 is the unique identifier of the quagent, as well as its "entityid". The game will always refer to the quagent that you've now created as "1". You have now been moved into "live phase".

== Live Phase ==
The telnet connection that you've started is tied to this single quagent that has been created in the opposite corner of the room. If you wanted to create another one, you need to fire up another telnet window and repeat the process so far. But firstroom is kind of crowded with just two, so let's stick with just this one for now.

Click back in the Quake window and hide the console by pressing ` (backtick) again and walk around until you find your newly spawned bot. Get a good camera angle on it and then bring up the console again to free your mouse and go back to telnet.

Let's try moving! Type "n mi 1 0 0 1" and press RETURN. The bot should immediately start running forward until it hits the wall, then "cp mi 1 blocked" will show up in your telnet window.

The "n" in your command means "now". You can schedule any command as either "now", "then", or "replace". The meaning of "now" is obvious: "do this now". When the bot is done, it will resume doing whatever it was doing before (in this case, standing and patiently awaiting orders). When you say "t" instead of "n" you mean "then" and are telling the bot to do the command after it has finished doing everything you already told it to do. When you say "r" instead of "n" you are telling the bot to forget what it was just doing and start doing whatever you told it to do. This is similar to "now", except that it does not build up a list of actions for the bot to finish doing so it is sometimes more useful.

The "mi" in your command means "move indefinitely". This is the actual command and tells the bot to move until it can't move any more. A complete list of commands can be found on the ProtocolZero page.

The first "1" in your command is the command id number. This is a number you specify purely for your own convenience: when the command completes, it will say that number back to you: you can see, we provided an "mi 1", and the report was "cp mi 1 blocked".

The rest of the numbers are parameters to the "[[mi]]" command. The first 0 is an obstacle flag. In this map, it doesn't ever matter, so we'll leave it at 0. The second 0 is the direction of motion. 0 here means "straight ahead". Try doing the same command with a 180 instead of a 0 here, and your quagent will move backward! The final 1 is speed. Providing a "1" means "move at maximum speed", while a .5 is "half speed", and so on.

If you haven't already, try "n mi 2 0 180 .1". The quagent will slowly move backward. While it does, type "t mi 3 0 0 1". This is a then command, so it will run after the quagent completes the first movement you told him to do. He should slowly move backward until he strikes a wall, then run forward at full speed until he strikes a wall. The server will tell you, "cp mi 2 blocked" then "cp mi 3 blocked".

You can rotate a quagent with the [[ro]] command. As you can see from its wiki page, ro takes 2 parameters: yaw and pitch. Try "n ro 4 135 0". Over the course of a second or two, your quagent should turn, and you'll see the server say "cp ro 4 done". You're probably getting the hang of this by now: if you issue another [[mi]] command telling it to go straight forward, he'll start moving in the new direction that he is facing.

All commands send a '''report''', which tells you the status of the command when it finishes. [[mi]] reports "blocked" when it hits a wall, and [[ro]] reports "done". All reports start with "cp". Some commands also send one or more '''response''' messages. These commands are called queries. All responses start with "rs".

The simplest query is for position. Send the command "n lc 5". The server will give you two lines back: first something like "rs lc 5 176.874466 -120.000000 40.125000" and then "cp lc 5 done". The response has the command instruction and the command id number that you provided (5), as well as three other numbers. These are the X, Y, and Z locations of the quagent in the room (think of it like GPS coordinates).

Every command is guaranteed to give a report unless the command never terminates. Additionally, the order of the reports is guaranteed to be in the order that the commands were on the command queue, and will come after any responses. So, if you ever see a "cp" for a command, you know that it's the last thing you'll ever hear from that command and you can stop waiting for additional responses.

== Next Steps ==

Good job, you have a solid understanding of how to order Quagents around using telnet. Of course, it's not fast and it's not that interesting, but understanding the format these messages is necessary if you choose to write your own controller at the ProtocolZero level. You should look at more ProtocolZero commands and experiment with them. Each of them are well-described by this wiki.