Q2Java v0.5 -  Quake II Game programming in Java

    Author:   Barry Pederson <bpederson@geocities.com>
    Homepage: http://www.openquake.org/jquake/q2java
    Date:     May 5th, 1998

    Description: A DLL and Java classes that allow a QuakeII game
                 to be written in Java.

    Requirements: Win95, WinNT 4.0, or Solaris for SPARC
                  Quake II v 3.14 for Win32/Intel or Solaris/SPARC
                  Sun Java JDK or JRE 1.1.4 or higher
                  
    (Beta versions of JDK 1.2 and Win98 seem to be flakey or non-functional 
     when running Q2Java - that's why they're considered "beta")

-------------------------------------


INSTALLING

    First, you need a working, registered copy of Quake II v3.14

    Secondly, Sun's Java JDK or JRE 1.1.4 or higher.  If you downloaded the 
    JDK, you can test to see if it's installed properly by typing "java -version" 
    at a command prompt.  If it's installed correctly, you'll see a usage message.
    If you installed the JRE, test it by typing "jre -version".  
    
    ====================
    IMPORTANT NOTE FOR WINDOWS USERS
    --------------------    
    The JDK or JRE should have added its "bin" directory to your system's PATH
    (that's the regular path, in Win95 it's set in the Autoexec.bat, in WinNT it's
    under the properties of the "My Computer" icon in the "Environment" tab).  If
    the directory that contains "javai.dll" is not listed in the path - the system
    won't be able to find it when you try to run Q2Java and you'll get an error
    message.
    
    Unfortunately, it sounds like the JRE install may not be adding the necessary
    directory to the path, so be sure to check that if you have problems.
    ====================
      

    Make sure the contents of this zip file are extracted into a subdirectory
    of your Quake II directory (usually c:\quake2).
    I'd recommend c:\quake2\q2java

    Assuming you unzipped this file into a game subdirectory named "q2java",
    you can start the sample Q2Java game and bring up the first map
    with this command:

        quake2 +set game q2java +map base1

OPTIONS

    Here are some options you can specify to the Q2Java DLL

        +set q2java_security 0
            Turn security features off

        +set q2java_security 1
            Allow read/write access to a subdirectory of the
            game directory named "sandbox" (usually c:\quake2\q2java\sandbox),
            and access to IP ports numbered >1023

        +set q2java_security 2
            (DEFAULT) Turn on full security..no file or IP access is
            allowed at all. Hopefully all the game can do is execute
            game functions.

        (Use security levels 1 and 2 at your own risk)

        +set q2jgame_packages <package-list>
            The default value of this option is "baseq2", you can
            specify a list of packages to be loaded at startup
            by separating the package names with one of these
            characters: + , ; / \

            So if you want to run the barryp.rocketmania plugin, you
            can say something like:

                 +set q2jgame_packages barryp.rocketmania+baseq2


    The Telnet Server

        To enable the telnet server you'll have to set the game
        to run at either security level 0 or 1, the default level
        of 2 will prevent the Telnet server from running.

        You can load the Telnet server package at the command line
        with a statement such as:

            +set q2jgame_packages barryp.telnet+baseq2

        To actually start a server session, set the port you want to 
        run the server on (for example: 1200) at the command line with 
        the option:

            +set telnet_port 1200

        where <n> is a port number (greater than 1023 if in security level 1)

        You can password-protect (for example, the password: foobar) the 
        Telnet server with the option:

            +set telnet_password foobar

        You can also load the Telnet server package and start a session
        after the game has started, by typing on the console:

            sv addpackage barryp.telnet
            sv telnet_start 1200 -pass foobar
       
        The Telnet server will relay all Game output to any number of
        connected telnet clients, and allow the client to send chat
        messages or issue commands to the game.

        Unfortunately, the Telnet server has no way to intercept
        output from the Quake2.exe itself, so it's not -quite-
        a perfect remote console..but it's still useful, especially
        for debugging.  MUD clients work well with the server, since
        they usually have large scrollback buffers, and separate
        input and output windows.

        If you're using a stock Telnet client, turn the "local-echo"
        feature on to see what you're typing. MUD clients usually operate
        this way by default.


MODIFYING THE JAVA CODE

    If you want to modify and recompile the sample game code, here's what I'd
    recommend:

        update your classpath environment variable to include the classes
        subdirectory, for example:

            set classpath=c:\jdk\lib\classes.zip;c:\quake2\q2java\classes;

    At this point, you should be able to run the development tools in the
    JDK to compile any changes to the classes.  As a first test, try
    modifying the class "baseq2.WelcomeMessage" and recompiling: to do this
    use a text editor to modify

        c:\quake2\q2java\classes\baseq2\WelcomeMessage.java

    Once you've saved your changes, recompile with the command:

        javac WelcomeMessage.java

    Run the game and see if your modification worked.

    Don't make changes to the classes in the q2java package, since the DLL
    expects things laid out in a certain way.  

    I have noticed that for some reason the JDK javac compiler complains
    when compiling the baseq2.spawn.func_train class about accessing
    a protected field that as far as I can tell it should be able to access.
    If anyone can tell me why this is, I'd appreciate it (it compiles fine
    with IBM's VisualAge for Java compiler)


---------------------------

Knock yourselves out

    Barry <bpederson@geocities.com>
