Java Kaser Interpreter Read Me

Introduction

This note describes how to install and run the Java version of the Kaser Interpreter, called jkint. This note is for v1.0 of the jkint.

Everett Kaser Software has a number of excellent Microsoft Windows-based puzzle games. The more recent of these games, namely Sherlock, Knarly Mazes and Latin Squares, have been written using the Kaser Interpreter. The Kaser Interpreter removes the direct dependency on the Microsoft Windows operating system, and allows these three puzzle games to run on other operating systems. jkint is a Java version of the Kaser Interpreter that allows these three puzzle games to be played on any system that has Java™2 Standard Edition (J2SE) 1.4, include, Linux and Solaris systems.


Installation

First of all, make sure that you have J2SE 1.4 available on your system. jkint will not work with 1.3 or before.

Secondly, jkint uses a fair bit of memory when compared to the Windows Kaser Interpreter. For example, one run of Knarly Mazes on Linux used nearly 100Mb of memory. Make sure your system has enough free memory.

Thirdly, jkint requires more processing power than the Windows Kaser Interpreter. Guidance here is limited at the moment as jkint has only had limited use. On one 400Mhz Linux system the games were just about playable, if a little on the slow side. On another 1.6Ghz Linux system they were fine. Please send in your experiences, so that this guide can be improved.

At the moment you need to first install a shareware, or licensed, version of Sherlock, Knarly Mazes or Latin Squares on a Windows platform. This is because, currently, these games only come as Windows-based installation programs. If you already have one of these games installed on a Windows system, then you can use that. Note that each individual game is copyrighted by Everett Kaser and may only be redistributed according to their specified licensing restrictions. This means you cannot use someone else's licensed version of the game in the following process.

Note: jkint requires Knarly Mazes revision 1.0a or later and Sherlock revision 5.0b or later. Earlier revisions of those games contain a couple of bugs which cause jkint to crash.

Once the game has been installed on Windows, you need to copy the game files to the system on which you wish to run jkint. For example, if you installed Latin Squares to c:\EKS, then you need to copy the complete contents of that directory to the other system. This would include the sub-directories MUSIC, LS, LS\UI and LS\IMAGES. So, if you were copying them to ~/EKS on the non-Windows system then you would have the directories ~/EKS/MUSIC, ~/EKS/LS, etc.

If you are doing two or all three of the games, then typically you would place them all in the same parent directory on the non-Windows system (i.e. that parent directory would hold the game directories KM, LS and SHERLOCK, as well as the MUSIC directory). This is up to you, but by using the same top-level directory they then share the same MUSIC/ directory. You need to make sure all directory names are in uppercase. Sometimes when copying from windows the directory MUSIC/, for example, gets copied as Music/.

You can see the amount of disk space you need from the disk space used on the Windows system. For Sherlock this is about 22Mb, for Knarly Mazes about 14Mb, and for Latin Squares about 14Mb. The music sub-directory is less that 1Mb. You will need more space for saved games, and for any additional game graphics and/or additional music files you might download.

Next you need to download jkint.jar from Everett Kaser Software. The easiest approach is to store this jar in each game directory (i.e. one in LS, one in KM, and one in SHERLOCK). You could instead place the jar in one place, and use some way to refer to that file as the program is run (e.g. by symbolic links). This note assumes that there is a copy of jkint.jar in each game directory.


Playing A Game

To play a game go into the game's sub-directory and execute the following Java command:

  java -jar jkint.jar 

For example to play Latin Squares you might do:

  cd ~/EKS/LS
  java -jar jkint.jar 

Alternatively you could download the (very simple) shell script jkint which does this, into the game directory. In this case you might run Latin Squares by:

  cd ~/EKS/LS
  jkint

Note, you would need to use ./jkint if the current directory is not on your execution path. Note also that you need execute permission to jkint as it is a shell script. This would be done, once, by the following:

  chmod u+x jkint

If you have a number of Java installations on your system, then you could edit jkint to set up JAVA_HOME and/or call the Java executable directly (e.g. by replacing "java" with "/usr/local/j2sdk141/bin/java", say).

If there is a serious problem, a Java exception will be written to standard output, and the game will stop. More details on the exception are written to a file called jkint.log. If you cannot work out how to fix the problem (e.g. by correcting your Java environment) then you should send

  • the jkint.log file,
  • details of your system, including your Java version,
  • the version of jkint you are using (this is printed as it starts),
  • the game you are attempting to play, and
  • an indication on how to reproduce the problem,
  • to Everett Kaser. Contact details are at the bottom of Everett Kaser Software. Alternatively here is his mailto link.

    Less serious problems are also written to the file jkint.log. You may want to check this file if things are not working as expected.

    Note also that the Java version does not support the "Make a copy" and "Make shareware copy" functions. It will give the error "Error, not all necessary files were found". This is because this initial release does not include its own installation program. If you wish to share this with your friends, then they will have to install it in the same way that you did.


    Frequently Asked Questions

    Question: Can I play on a system without a graphics head?
    No, jkint needs a graphics head and will not work without one. Often Unix-based systems use X-Windows for their graphics. In this case the graphics head can be on a separate machine to where the program is running, requiring that you set up the DISPLAY environment variable correctly. Please note that the game plays slower over a network, as the network introduces its own latency as it transfers the graphics. Sometimes this additional latency slows the game down to the point where it becomes unplayable.

    Question: Why do the colours look strange?
    Many Unix-based systems default to 8-bit graphics. jkint looks much better with 16-bit or more graphics. You should be able to change these defaults. Consult your UNIX manuals.

    Question: Why is jkint slow to start up?
    This is partly due to the Java system initialising, and partly because jkint has to convert the Windows bitmaps used by Everett's games into the graphics used by Java.

    Question: Why is the window size so large for the first run of a game?
    Sometimes the very first run of jkint, for a given game, selects a window size larger that the visible area of the screen. This is because the initial dimensions are based on typical Microsoft Window resolutions. You may need to resize the initial window size to something more suitable for your display. When a game exits, it saves the current window size and uses that size for the next run of the game, so subsequent runs of a game should be okay.

    Question: Why does the game pause for so long when I first use the printer?
    Not sure. On some systems printing is immediate, on others there is a very, very long pause for the first access to the print dialog. If this happens for you then you need to be patient (or forget about printing puzzles :-).

    Question: Why do the forward and backward mouse buttons not work?
    They have not been implemented yet.

    Question: Can I run two instances of the same game at the same time?
    No, you must not do this. There is no check in jkint to prevent this (as there is in the Windows version). You should not attempt this as the game's configuration file could be corrupted if the two game instances attempted an update at the same time.

    Question: Can two users use the same installed game?
    Yes, but as indicated by the previous question they cannot use the same installed game at the same time. Also note that you will have to get the directory and file permissions such that both users are able to write files to the game directory. This is because the game needs to save the configuration file, as well as saving partially finished games.

    Question: Why do I get the "Audio Device Unavailable" Java exception?
    Typically this is because your system does not have sound, or some other program has the audio device and it cannot be shared. If your system does not have sound then you should consider switching off all sound and music options in the game. This will stop the exception appearing.

    Question: Why do I get messages such as 'Warning: Cannot convert string "F1,_Key_Help" to type VirtualBinding' and 'Warning: Cannot convert string "-monotype-arial-regular-r-normal--*-140-*-*-p-*-iso8859-15" to type FontStruct'?
    These come from the Java system and are nothing to do with jkint.


    Version History

    Version Date Comments
    v1.0 21st January 2003 First release.

    Copyright Notice and Disclaimer

    Stephen M. Bennett holds the copyright on jkint.jar. You are free to use jkint.jar in order to play Everett Kaser games, so long as you do not break any game-specific license you have with him. You are not allowed to use jkint.jar for any other purpose, including the decompilation of the Java classes it contains.

    jkint.jar is based on technology that is copyrighted by Everett Kaser.

    jkint.jar is provided free of charge and as such is provided on an "AS IS" basis, without warranty of any kind. You use the software entirely at your own risk.


    Copyright © 2002 Stephen M. Bennett, All Rights Reserved. This file is $Revision: 1.7 $, $Date: 2003/01/21 16:10:15 $.