add scripts/qstat.md

Signed-off-by: hwipl <33433250+hwipl@users.noreply.github.com>

scripts/qstat.md

@@ -0,0 +1,142 @@
+# qstat.tcl
+
+The script [qstat.tcl](qstat.tcl) stores game servers in a server list file and
+queries their status with the utility
+[qstat](https://github.com/multiplay/qstat) with the server commands below.
+
+## Setup
+
+The script requires the tool [qstat](https://github.com/multiplay/qstat). If it
+is not available on your system, you need to install it first.
+
+You can configure the names of the commands, the path to the `qstat` binary,
+and the `qstat` options for querying all or a single server in the following
+namespace variables. You can find them at the top of the script. The default
+options are for the game Quake 2:
+
+```tcl
+# command names
+variable addcommand "!addserver"
+variable delcommand "!delserver"
+variable showcommand "!serverlist"
+variable refreshcommand "!refresh"
+
+# path to your qstat binary
+variable qstat "/usr/local/bin/qstat"
+
+# qstat options for querying all servers
+variable optionsall "-nh -u -default q2s"
+
+# qstat options for querying single server
+variable optionssingle "-nh -P -sort F -u -q2s"
+```
+
+You can enable the script in a specific channel by setting the `qstat` flag for
+the channel in your Eggdrop. For example, enable the script in the channel
+`#test` with the following Eggdrop command:
+
+```
+.chanset #test +qstat
+```
+
+Accordingly, you can disable the script in a specific channel by removing the
+`qstat` flag from the channel in your Eggdrop. For example, disable the script
+in the channel `#test` with the following Eggdrop command:
+
+```
+.chanset #test -qstat
+```
+
+## Usage
+
+After enabling the script in a channel, you can use the commands in that
+channel as shown below.
+
+Add a server to the server list:
+
+```
+!addserver <server>
+```
+
+Remove a server from the server list:
+
+```
+!delserver <number>
+```
+
+Show the servers in the server list (without querying their status):
+
+```
+!serverlist
+```
+
+Query the status of all servers in the server list:
+
+```
+!refresh
+```
+
+Query the status of a single server in the server list and retrieve
+information about the current players on the server:
+
+```
+!refresh <number>
+```
+
+## Examples
+
+Example of adding Quake 2 servers to the server list:
+
+```
+17:59 <@hwipl> !addserver 212.42.38.88:27910
+17:59 <@hwipl> !addserver 23.227.170.222:27916
+17:59 <@hwipl> !addserver 50.209.196.145:27910
+```
+
+Example of showing the server list:
+
+```
+18:00 <FooBot> *** Server List ***:
+18:00 <FooBot> (1)  212.42.38.88:27910
+18:00 <FooBot> (2)  23.227.170.222:27916
+18:00 <FooBot> (3)  50.209.196.145:27910
+```
+
+Example of querying all servers in the list:
+
+```
+18:00 <@hwipl> !refresh
+18:00 < FooBot> (1) 212.42.38.88:27910    openffa PlayGround.ru - Deathmatch
+                (16/20) (q2dm1)
+18:00 < FooBot> (2) 23.227.170.222:27916  tastyspleen.net::dm
+                (4/17)  (q2dm2)
+18:00 < FooBot> (3) 50.209.196.145:27910  coop [HCI] Custom Coop - Vanilla,
+                Xatrix, and Rogue.  Votable maps! (3/8)   (jail1)
+```
+
+Example of querying a specific server in the list and getting player
+information (up to maximum message length). The player list was edited to hide
+the real player names on that server:
+
+```
+18:00 <@hwipl> !refresh 1
+18:00 < FooBot> (1) 212.42.38.88:27910    openffa PlayGround.ru - Deathmatch
+                (16/20) (q2dm1)
+18:00 < FooBot> Player1 (27 frags, 5ms), P2 (20 frags, 21ms), Player003 (17
+                frags, 46ms), Play4 (16 frags, 23ms), Player00005 (14 frags,
+                78ms), Player006 (13 frags, 25ms), Player7 (13 frags, 7ms),
+                Player000008 (6 frags, 83ms), Player00009 (4 frags, 44ms), P10
+                (4 frags, 109ms), Playe11 (1 frags, 61ms), Player000000012 (1
+                frags, 7
+```
+
+Example of deleting a server from the server list:
+
+```
+18:01 <@hwipl> !delserver 2
+18:01 <@hwipl> !refresh
+18:01 < FooBot> (1) 212.42.38.88:27910    openffa PlayGround.ru - Deathmatch
+                (16/20) (q2dm1)
+18:01 < FooBot> (2) 50.209.196.145:27910  coop [HCI] Custom Coop - Vanilla,
+                Xatrix, and Rogue.  Votable maps! (3/8)   (jail1)
+```