========================= Quake Servers Info v1.1.1 ========================= designed by Matt Haffner -- haffner@uwast.astro.wisc.edu What's new in 1.1.1 =================== * Added workaround for MRJ 2.0 Datagram bug that prevents any queries from working. What's new in 1.1 ================= * Filtering!!!! A very powerful filtering system has been added to QSI. I went for flexibility and sacrificed a little simplicity, so please read the Filtering section below for a quick tutorial on how filters work. * 'Update All Servers'. Since filtering causes servers to become 'invisible' if they are filtered out, this button was added to update all the servers that you have loaded. * Preferences. You can now edit several key QSI variables that affect speed and memory usage. I have also added the option for a persistent command line string. * You can now stop getting new servers from a URL by clicking the 'Stop' button. This will avoid QSI hanging when a host is not available. * QSI will now tell Quake the proper commands to connect to a server not on port 26000. I mistakenly though the syntax #.#.#.#:# was accepted by Quake. In fact 'port #; connect #.#.#.#' must be used. Known bugs & limitations ======================== * Mac active scrolling memory chomp (see below). * Changing filters during active server queries may produce harmless (I think) error messages. It's not recommended quite yet. Description =========== QSI is a Java application that manages lists of Quake Internet servers. QSI features many of the traditional server-query-tool features such as a sortable multi-column list, queries for current player information and server rules, list filtering, ping-time coloring, and the ability to save and load local lists of favorite servers. QSI can launch Quake and connect to the selected server. I wrote QSI because, at the time, there appeared to be no movements to port any of the popular query tools to the Mac. There are a few alternatives developing now, but QSI is the most mature of these tools right now. Why Java? Well, first of all, I wanted to try my hand at Java programming. More importantly, it's free :) , portable, and has networking built in. This allowed me to rip the initial versions out in about a week that convinced me this project was worth pursuing. Keep in mind that this is a Java application, not an applet. Java security in 1.0.2 does not allow applets to access network resources other than those from the serving host. QSI runs on a variety of platforms and was developed on a PowerComputing PowerBase 180 (with MacOS 7.5.5 and MacOS 8), a 9500/200 (7.5.5), and a SGI O2 running IRIX 6.3. However, Java Virtual Machines (JVMs) are not the most stable creatures yet. I cannot account for all platforms and JVM combinations. Please try a different JVM if you are having troubles before contacting me. See the JVM/QSI comments page (http://www.astro.wisc.edu/~haffner/QSI-JVM.html) for the latest information. Getting QSI to work =================== QSI is a Java application, not an applet. It does not run in a web browser! To use QSI, you need a Java Virtual Machine (JVM) capable of running applications. For Mac users, I recommend MRJ 1.5 (http://applejava.apple.com/), but you can try any JVM that can handle non-compressed zip archives. For SGI users, you'll need the latest JVM released by SGI. See my page on which JVMs work with QSI. Java "portability" is relative still, I guess. :) I'd like to hear of any other experiences with other JVMs. Special Mac Instructions ------------------------ * Make sure MRJ 1.5 or higher and OpenTransport 1.1.2 or greater are installed. MRJ 2.0 or higher makes QSI look much more like a true Mac application and will speed up queries since one major multi-threading bug was eliminated. * Download QSI, unstuff, double-click. :) QSI runs in a 512k memory partition, however, this is a bit misleading. MRJ uses System memory for almost all Java operations, so this is where you'll see the bite. In MacOS 8, this memory is grouped with QSI so you can see how much it's really taking. Typical usage is 2-4 MB in my experience. I know this takes a bunch away for Quaking, but it's the best I can do right now with Java. Giving the QSI application more memory does nothing, so don't bother. It might be possible to have QSI quit before Quake is launched, freeing up some memory. If folks are interested in this option, drop me a line. There is one memory bug apparently in MRJ 1.5 that I can't seem to get around. If you grab the thumb of the scroll bar and scroll the list up and down for a few seconds, QSI's memory partition, as reported in the Finder (MacOS 8), grows quite large for a few seconds and then drops back to normal. Java does not report this memory as being allocated, so I think it's something that MRJ is doing. I'm continuing to track this down, but it shouldn't affect things to much. This bug is apparently fixed in MRJ 2.0. Since MRJ does not yet include AppleScript support, an AppleScript helper application called 'QSI Launcher' is needed to launch and talk to Quake. As a result, make sure AppleScript is installed on your machine, even if you have a minimum extensions set for Quaking. QSI writes out an intermediate file called 'Quake Command' that gets passed to the launcher. The first time you connect to a server, you will be asked to locate the Quake executable on your drive. If you mess this up and select, say, Asteroids, you'll have to either edit the script yourself (change the lines that read 'tell application ""') or load a fresh version of the launcher from the Stuffit archive and try again. If you have the demo and upgrade to the commercial version, you'll also need to redo the script, hide (in an archive) or delete the demo, or get a fresh copy of the launcher script. As compensation for this run-around, Mac users can connect to a new server with QSI without quitting Quake! Simply switch back to the QSI process (hit ESC from Quake to get the menubar back) and select another server and hit 'Connect'. This may not work with the 3Dfx version unless you have two monitors. Keep in mind that the resolution switching that Quake does will also be present when you switch back. Thus, you might want to start QSI up at the resolution that Quake uses to avoid having half the window off the screen. Also, Quake messes with the color palette so don't be surprised if the colors in QSI are different. Special Unix Instructions ------------------------- * Download and untar. * Edit the QSI script to specify the location of your Java JVM, if necessary. Do not change the CLASSPATH line, unless you know what you're doing. * Type 'QSI'. Let me know what works and doesn't since I don't have access to many other Unix platforms. Special DOS/Windows Instructions -------------------------------- * Download the Win32 executable and unzip it. (This version is quite behind the current release and many new features are missing) * Get the Microsoft SDK installation (you'll need to have IE 3.01 or greater installed first) at http://www.microsoft.com/java/download/dl_vmsp2-f.htm * Run the resulting EXE. - or - * Download the class zip file. * Run a JVM with the zip file as your CLASSPATH and access the QSI class. (Probably just 'java QSI'.) Thanks to Josh Straub (mailto:tookycat@nconnect.net) for help with testing and for making the executable. See the QSI-JVM page (http://www.astro.wisc.edu/~haffner/QSI-JVM.html) for current success stories from Windows users. Documentation ============= Buttons ------- Get Servers: Grabs a list of Quake servers from one of the popular Quake server list web pages. Only IP numbers and ports in the format #.#.#.#:# are extracted. You can enter your own URL in the text box. You can stop the process by clicking the 'Stop' button. Select All Rows: Selects every visible row in the server list. Update All Servers: Queries all servers (filtered and unfiltered) for general server information and gathers ping times. This button changes to 'Stop Update' after queries start. Update Selected Servers: Queries only the selected servers. This button changes to 'Stop Update' after queries start. Get Player Info: Queries a server (only the first server if multiple ones are selected) for information about current players. An attempt is made to 'translate' some of the more popularly used extended Quake characters in player names. Characters that are not translated yet appear as '?'. If your favorite special character is not translated yet, mail me. The Player panel sports three useful buttons. 'Refresh' updates the player information. 'Rules' brings up the Rules Info panel for this server. 'Close' removes the Player panel. For now, the ping time in the Player panel will not agree with that in the main listing--they are from two separate servers queries. Get Rules Info: Queries a server (only the first server if multiple ones are selected) for information about variable settings on the server. Connect: Launches Quake and attempts to connect to the selected server (the first server if multiple ones are selected). The Mac version can also tell a running Quake process to connect to a new server. Quit: Brings you back to reality. Menus ----- File ==== Load Servers...: Load a list of servers from a text file. This file should contain a list of Quake servers (names or IP numbers in the format #.#.#.#:#), one per line. Formatting is fairly free otherwise. Blank space is ignored and three comment characters are recognized when used as the first non-blank character on a line: ';', '/', and '!'. Comments on the line immediately above a name or IP number are inserted into the name field of the list box until the first update is executed. If a file named 'Servers' exists in the current directory, QSI will load the file on startup. Save Selected Servers...: Save the currently selected servers to a text file. If a file named 'Servers' exists in the current directory, QSI will load the file on startup. Connect: Fire up Quake. Same as the button. Preferences: Brings up the Preferences panel. You can edit these variables: * Quake Path & Executable name. (Non-Mac platforms only.) Use the 'Find' button to bring up a standard file box. * Extra Connect Parameters. You can add additional Quake command line parameters here that you want always included on a Quake launch. This string will appear in the Connect box every time. * Maximum Number of Query Threads. This variable controls the number of simultaneous query operations. Increasing this number will speed up querying a large list of servers at the cost of using more memory. The default is 8. I have tried up to 32 on a Unix machine but don't recommend setting it much higher than that. * Query Timeout. The time in milliseconds (1/1000 second) that QSI waits for a server response. Lowering this number will speed up queries, but may leave more servers as unreachable. The default is 5000 (5 seconds). * Ping Time Coloring. These two numbers control the coloring of lines in the main list box based on the ping time. Servers with times less than the first number are colored green, those in between the two numbers are yellow, and those greater than the second number are red. These values are saved in a text file called 'QSI.prop' that can be hand edited. Show Memory Usage: Bring up JVM memory statistics. Quit: Leave QSI. Servers ======= Get Servers: Same as the button. Add Servers...: Manually enter a server. The dialog box takes names or IP numbers. Delete Servers: Delete the selected servers from the list. Update All Servers: Update Selected Servers: Get Player Info: Get Rules Info: Same as the buttons. Filters ======= Edit Filters: Brings up the Filter editing box (see below). None: List all servers. ...: The Filters you add will be listed at the end of the menu. Select one to apply the filter to your list. Changing filters while servers queries are running is not recommended yet. Listboxes --------- The listboxes in QSI have several common features. They employ active scrolling if you grab the scroll thumb (although see the note above about a small Mac bug). All lists are sorted. The column that is the sort key is in bold in the heading row of the listbox. The arrow in front of the caption reflects the sort order (ascending or descending). Clicking on a column heading selects that heading as the sort key. Clicking again toggles the sorting order. Columns can be resized by clicking on the separating line in the heading row and dragging. The main servers listbox allows multiple selections using the traditional modifier keys. Hold SHIFT down when clicking to select contiguous regions. Hold CONTROL down to select non-contiguous regions. This feature allows you to query or mark multiple servers at once. The main servers listbox also has row coloring according to the last queried ping time. The default thresholds are: ping <= 400 Green 400 < ping <= 600 Yellow 600 < ping < 9999 Red ping >= 9999 Gray You can edit these values in the Preferences dialog box. Filtering --------- The filtering system in QSI is very flexible and will allow you to create arbitrarily complex filters. The interface is definitely non-standard and requires a little explanation. The key point for QSI filters is that complex filters are built on the simpler ones. In the examples below I show how to make a filter that operates like this: if (name contains ctf or map contains ctf) and (ping < 500) In QSI, filters are constructed from a list of rules. Rules can be previously existing filters or one of the built-in rules and are joined by a single logical connector: * 'and': all rules must be true for a server to pass * 'or': any rule must be true for a server to pass There are 5 built-in rules, which each have a settable VALUE: * ping: passes servers with ping times less than VALUE. * name: passes servers with names containing VALUE. * map: passes servers with maps containing VALUE. * current players: passes servers with current players greater than VALUE. * open players: passes servers with at least VALUE open player slots. String comparisons are case insensitive. For our example, we will create 3 filters: * Low Ping: [Ping] < 500 * CTF: [Name] = ctf OR [MAP] = ctf * Low Ping CTF: Low Ping AND CTF Including a filter as a rule creates a real link, not a copy of the filter. Changes to either Low Ping or CTF will affect the Low Ping CTF filter. As a result, you now can't delete Low Ping or CTF until you delete Low Ping CTF since it uses the other two. You also can't create cyclical filters (e.g. by adding Low Ping CTF to the CTF filter). You could skip the creation of the Low Ping filter and just do this: * CTF: [Name] = ctf OR [MAP] = ctf * Low Ping CTF: [Ping] < 500 AND CTF but it's nice to have one Low Ping filter you can use in many other complex filters. Then you just change the value of the Low Ping filters and all the descendants use the new value. The Edit Dialog box has these controls: Edit Filter: The currently selected filter that is being edited. It's name is put into the name box and it's rules are listed in the right hand list box. New Filter: Creates a new, empty filter called Untitled. Delete Filter: Deletes the selected filter. A filter cannot be deleted (the button will be disabled) if other filters currently use it. Name Box: (below the 'Rules for' label) Type a new name in this box and hit return or click the 'Change' button to apply the change. Rules Toolbox: To add rules to the currently selected filter, click on a rule in the box and click 'Add Rule'. You cannot add rules that would produce cyclical filters (e.g. you can't add the Low Ping CTF filter as a rule to the CTF filter in the example above). Rules List: To change the value of a built-in rule, select it in the Rules List and edit the value in the box below the list. Hit return or click change to apply the value. To remove a rule, select it and click the 'Remove Rule' button under the Rule Toolbox list. Logical Connector Click to choose which connector will be used for this filter. AND requires all of the rules to be true for a filter to pass and OR requires only one of the rules to be true. Close: Saves any changes you made into a file called 'Filters'. This file is loaded when QSI launches. Here's how to make the 3 example filters: * Click 'New Filter' * Change the name to 'Low Ping' and click 'Change' * Select the [Ping] rule from the toolbox and click 'Add Rule' * Select the [Ping] < 500 in Low Ping's rule list and edit the value below the list if you want. Click 'Change' to apply the value. * Click 'New Filter' * Change the name to 'CTF' and click 'Change' * Select the [Name] rule from the toolbox and click 'Add Rule' * Select the [Name] = Quake in CTF's rule list and change the value to ctf. Click 'Change' to apply the value. * Select the [Map] rule from the toolbox and click 'Add Rule' * Select the [Map] = e1 in CTF's rule list and change the value to ctf. Click 'Change' to apply the value. * Choose the OR connector * Click 'New Filter' * Change the name to 'Low Ping CTF' and click 'Change' * Select the Low Ping rule from the toolbox and click 'Add Rule' * Select the CTF rule from the toolbox and click 'Add Rule' That's it! After closing the dialog box, three filters will appear at the end of the Filter menu. Selecting one applies the filter to the list. Acknowledgments =============== Thanks to Jerry Acord for testing and frequent use of QSI :) QSI uses the (life-saving) Perl regular expression package (OROMatcher) from ORO (http://www.oroinc.com/). QSI also uses the MultiColumnListbox widget from Taligent (http://www.taligent.com/Products/products.html), modified slightly by me to fix a few bugs and add row coloring. Copyright and Permission Notice for MultiColumnListbox (only) Permission is granted to copy, use, modify, and merge this software into your applications and to permit others to do any of the foregoing for non-commercial use only. You must include this permission and copyright notice in all copies and modified versions of this software, and include attribution to Taligent in all splash screens included in any application using this software. You must require others to whom you distribute this software to do likewise. To obtain an unrestricted commercial license to the software source and/or binaries, please contact Taligent at widgets@taligent.com THE SOFTWARE IS PROVIDED IN ITS 'AS IS' CONDITION FOR NON-COMMERCIAL USE ONLY. TALIGENT DISCLAIMS ANY LIABILITY OF ANY KIND FOR DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE. (C) Copyright Taligent, Inc. 1996,1997-All Rights Reserved. (C) Copyright IBM Corporation 1996,1997 Contact ======= You can reach me at haffner@uwast.astro.wisc.edu or visit the QSI webpage at http://www.astro.wisc.edu/~haffner/QSI.html. You also might find me stomping around QClan.CAE.wisc.edu or breese.doit.wisc.edu as Charon.RS. of the Rocket Scientists. Copyright ========= This software and included documentation are Copyright (C) L. Matthew Haffner, 1997. Please include attribution in all redistributions. You may not include this program in any distribution or collection of software that is not free without prior written agreement from me.