
// Readme template for jk3files
//
// Gamall Wednesday Ida

\style{FILEFRONT}
\output{README.txt}

\header
	JEDI KNIGHT: Jedi Academy & Outcast
\end

\modinfos
	TITLE   : Command-line Quake3 Server Commander		\line
	TYPE    : Server Utility					\line
	VERSION : 0.1					\line
	AUTHOR  : Gamall Wednesday Ida		\line
	E-MAIL  : gamall.ida@gmail.com		\line
	WEBSITE : http://gamall-ida.com		\line
	\line

	FILESIZE          : ~150 Ko			\line
	OS : Windows & Linux \line
	RELEASE DATE      : September 2007		\line
\end



\section
	WHAT IS THAT ?
\end
\body
     There is (as far as I know) no easy way to send an order to a server from a simple
	bash script under Windows or Linux, for instance a cronjob changing maps or adding passwords
	at specific times. In order to do something as trivial as that in a script, one needs PERL socket 
	programming or some ugly unix pipes hack. I have no idea if this is even doable under Windows.
\end

\body
	This program is a very simple tool, written in C++, allowing anybody to send
	any command to any server using the Quake3 protocol, which is the case of Jedi Knight servers,
	without any unnecessary hassle.
\end

\section
	HOW DO I USE IT ?
\end
\body
	Running the executable without any argument displays some help text:
\end
\verb
** Quake3 Commander v. 0.1
** by Gamall Wednesday Ida
** email : gamall.ida@gmail.com
** web   : gamall-ida.com


Usage: ./qcmd -ip 127.0.0.1 -p 21000 -c rcon MyPass map mp/ffa3

Other options :
-format : clean display for query 'getinfo' or 'getstatus'
-timeout: seconds before timeout                [def=2]
-retries: if timeout, how many times do I try ? [def=2]
\end{verb}

\body
	Note that depending on your system and where you put the executable,
	you might not need the "./" before the command name. And never under Windows.
	This is not specific to this program anyway :P \line

	\line Let us see some example of commands and the corresponding output of the 
	program. Here the RCon password of my server is set to "MyPass". Note that
	the script need not be run on the same system than the server. If it is, however,
	you can use the IP "127.0.0.1" or "localhost".
\end
\verb
./qcmd -ip 213.251.186.99 -p 29070 
                          -c rcon MyPass say Hello there !

Time      'Sun Sep 30 18:06:19 2007'
To server '213.251.186.99:29070'
Command   'rcon MyPass say Hello there !'
Answer    [    print
broadcast: print "server: Hello there !\n"
]
\end{verb}

\body
	You can also use non-RCon commands such as getstatus or getinfo:
\end

\verb
./qcmd -ip 213.251.186.99 -p 29070 -c getinfo

Time      'Sun Sep 30 18:13:34 2007'
To server '213.251.186.99:29070'
Command   'getinfo'
Answer    [    infoResponse
\game\japlus\fdisable\163837\wdisable\524279\truejedi\0
\needpass\1\gametype\0\sv_maxclients\24\clients\0\mapname
\the_academy_v3\hostname\^1Dragon's Lair\protocol\26]
\end{verb}

\body
	As you can see, the server's answer is, in that case, quite illegible. Use the -format
	option to get a more readable answer:
\end
\verb
./qcmd -ip 213.251.186.99 -p 29070 -c getinfo -format

Time      'Sun Sep 30 18:17:25 2007'
To server '213.251.186.99:29070'
Command   'getinfo'
Answer    [    infoResponse

       -> game : japlus
       -> fdisable : 163837
       -> wdisable : 524279
       -> truejedi : 0
       -> needpass : 1
       -> gametype : 0
       -> sv_maxclients : 24
       -> clients : 0
       -> mapname : the_academy_v3
       -> hostname : ^1Dragon's Lair
       -> protocol : 26]
\end{verb}

\body
	Of course, since you will use this program inside a script, you won't be there to read
	anything... but you can easily redirect the output to a log file: the command
\end
\verb
./qcmd -ip 213.251.186.99 -p 29070 -c getinfo -format >> mylog.txt
\end{verb}
\body
	Will append the output to the file "mylog.txt", and create the file if it didn't already exist, so
	you can easily keep logs of every command that is sent by your script/cronjob/etc.
	And for once, it works the same way under both Windows and Linux :-)
\end

\body
	There is no need to speak about -timeout and -retries, as the default values should be perfect
	in most cases.
\end
\body
	If the server doesn't answer, be it because you are targeting the wrong IP:Port or
	sending an incorrect command, you can expect a timeout error message:
\end
\verb
qcmd -ip 213.251.186.99 -p 29071 -c getstatus -format

Time      'Sun Sep 30 18:39:22 2007'
To server '213.251.186.99:29071'
Command   'getstatus'
Answer    [
ERROR: Socket timeout, no reply received.
]
\end{verb}

\section
	CONTACT
\end
\body
	If you need help, or have suggestions, comments, insults, praise or in general,
	anything to say about this program you expect me to read and answer to, please
	post on the program's topic on my website:
\end
\verb
http://gamall-ida.com/f/viewtopic.php?f=3&t=342
\end{verb}

\section
	END OF FILE
\end
