GameFrame for Java 0.9.4 Class Library
Users Documentation - Readme


Version 0.9    04. Jul  1999 by Pasi Keränen, javanerd@geocities.com
Version 0.9.1 02. Nov 1999 by Pasi Keränen, javanerd@geocities.com
Version 0.9.2 19. Dec 1999 by Pasi Keränen, javanerd@geocities.com
Version 0.9.3 02. Apr 2000 by Pasi Keränen, javanerd@geocities.com
Version 0.9.4 16. Jul 2000 by Pasi Keränen, javanerd@geocities.com



INDEX

1. HOW TO INSTALL

2. ABOUT THE CURRENT RELEASE

2.1. General

2.2. How to upgrade your game from previous version

2.3. Known problems

3. SUPPORTED FEATURES

3.1. Java Development Kit 1.1.x based Java runtimes

3.2. Java Development Kit 1.2.x based Java runtimes

3.3. Java Development Kit 1.3.x based Java runtimes

3.4. Microsoft Java 3.x based Java runtimes

3.5. Microsoft Java 4.x based Java runtimes

4. ABOUT THE PACKAGE STRUCTURE

4.1. Files

4.2. Directories

5. ABOUT THE AUTHOR

6. CONTRIBUTORS


1. HOW TO INSTALL

Unpack the GameFrame0_9_4.zip file (preserving subdirectories!) to the directory of your choice (e.g. C:\GameFrame or /GameFrame).

Set or add to your CLASSPATH environment variable the directory where you unpacked the ZIP file (e.g. C:\GameFrame or /GameFrame).

If you don't want to touch your CLASSPATH you can just copy the gameframe subdirectory (the one that contains lots of *.class files and subdirectories) with its subdirectories under the directory of your project. When using the GF4J library with Applets, the gameframe subdirectory must reside as an unpacked subdirectory of the HTML page that loads the Applet that uses the library.


2. ABOUT THE CURRENT RELEASE

2.1. General

GameFrame for Java (GF4J) release 0.9.4 is the newest release of the easy to use Java game programmers class library. The main thing in this release is the implementation of an component graphics engine that is now used in windowed modes and emulated full screen modes. This component graphics engine can also be gotten from the library and used as a component in e.g. a level editor. Many of the interfaces have become more robust and useful e.g. the BitmapEffect interface is now more flexible and the BitmapData object is more generally usable. Also there are quite a lot of bug fixes and a brand new (and thus pretty unstable) preliminary support for Applets. There are quite a lot of obstacles to plow through before the Applet support is even close to being ready, but I included it still as many people have requested this feature and maybe this will give someone a base to work upon. Also I'd love if someone more knowing in the ways of Applet programming would take up this development aspect...

Examples are still included and the new examples for Applet use are included with HTML files. Hopefully this will help new users to grasp how to use GF4J to make games (or other interactive graphical programs).

This release is starting to point to the direction I'm trying to push with this thing. There still are bugs in the library, but at least I believe I've eradicated most of them. The library is starting to look logical (at least to me) and easy to use. The community involvement in this project has been nonexistent I'm sad to say, but it hasn't stopped me as I'm still eager to get my own game project up to speed and to do that I'm refining this library constantly.

I'm still encouraging any users to look into the library source code and try to add enhancements to it. Remember though that the Lesser GNU license requires you to release the source code of the GF4J library variant you have made based on this library, but you are NOT required to release the source code of your game itself. Also if you include this library with your game you are required to distribute the source code with it or at least provide a pointer to a website where the source code can be downloaded from. For exact details see the included license.html file.

I've lightly tested the release in the computers that I've access to that run Microsoft Windows 95/98/2000 and it seems to run without any major problems with pure Java 1.1, Java 2 and Microsoft Java 4.x (Microsoft Java 3.x is still an open issue, if you have this Java SDK in your computer, could you please try to run the examples and report back to me how it went). This doesn't mean there aren't any bugs or even serious errors contained in this library, the library is provided as is, but it does mean that I've tried to make sure the library is usable under these runtimes. If you use the library under other platforms (Linux, Mac etc.) or Java runtimes, please eMail me any experiences you have so I can keep a list of "tested" environments. A good "test suite" should be running all the examples provided with the library in sequence and taking notes on how they work.

As a side note: I don't think Windows is THE operating system to use, but I just don't have access to a Linux or Macintosh computers at the moment so I could test the library. Also the Microsoft Java specific versions of the library engines are there just because I had most of the needed code lying around from previous projects. I've tried NOT to favor DirectX engines in any way over the default windowed pure Java 1.1 version of the engines. Comments from users of different operating systems are welcome and remember that if you have the know how, why don't you make THE best implementation of the engines for your favorite operating system!

 

2.2. How to upgrade your game from previous version

The following 1 step procedure should upgrade your game source code from the previous library release 0.9.3. to compile and work with the 0.9.4. release. For new additions to the API see the included versions.html file:

  1. Where you previously invoked the setTitle( String ) method in GraphicsEngine, you now must remove this as the title is now set in the GameFrameSettings object.
  2. If you have implemented custom BitmapEffect's you are now required to return the BitmapData in processData( BitmapData ).

 

2.3. Known problems

Windows 2000 has some problems with some JavaSoft Java (JDK 1.3 used in testing) runtimes:

These problems are specific to Windows 2000 only and are hopefully rectified by JavaSoft in the near future.


3. SUPPORTED FEATURES

GF4J 0.9.4 supports the following features under the following runtimes.

 

3.1. Java Development Kit 1.1.x based Java runtimes:


Graphics Java AWT based graphics in windowed modes, no full screen support.
Sound Unofficial sound hack available via com.sun.audio package classes.
Might not work on all systems (known to work on JavaSoft based Java VM's).
No MIDI music support at the moment.
Input Mouse and keyboard input via normal java.awt.event event listener interfaces.
Timer System.currentTimeMillis().
Known Issues Sound hack doesn't work on all runtimes.

 

3.2. Java Development Kit 1.2.x based Java runtimes:
 


Graphics Java AWT based graphics in windowed modes, no full screen support.
Sound Official sound support via Java 2's java.applet.Applet.newAudioClip() method.
Supports MIDI music through the same official sound interface.
Input Mouse and keyboard input via default system event queue replacement class.
Timer System.currentTimeMillis().
Known Issues Very slow blitting of bitmaps. Sound playing is a bit lagged. Setting of sound volume and pan don't work.
 

 

3.3. Java Development Kit 1.3.x based Java runtimes:
 


Graphics Java AWT based graphics in windowed modes, no full screen support.
Sound Official sound support via Java 2's java.applet.Applet.newAudioClip() method.
Supports MIDI music through the same official sound interface.
Input Mouse and keyboard input via default system event queue replacement class.
Timer System.currentTimeMillis().
Known Issues Sound playing is still a bit lagged. Setting of sound volume and pan don't work.
 

3.4. Microsoft Java 3.x based Java runtimes:

Untested, if you are still using Microsoft Java SDK 3.x I'd like to hear from you and your experiences. The library will probably just need recompiling from the Java SDK 4.x sources, but still this might be a problem.

 

3.5. Microsoft Java 4.x based Java runtimes:
 

 

Graphics Java AWT based graphics in windowed modes,
DirectDraw based graphics in full screen modes through DirectX 3.
Sound DirectSound sample support with DirectX 3. MIDI music support using Win32 MCI interface through Direct/J.
Input Mouse and keyboard input via normal java.awt.event event listener interfaces.
Timer Uses Win32 system timer with Winmm.timeGetTime() function (available through Direct/J)
Known Issues DirectDraw limits the maximum Bitmap size to the current screen resolution, this has forced all other implementations to limit their maximum bitmap sizes the same way to keep all implementations consistent with each other.

4. ABOUT THE PACKAGE STRUCTURE

4.1. Files

In the directory where the ZIP file is unpacked you'll find the following files:

 

4.2. Directories

Also the following directories are created:


5. ABOUT THE AUTHOR

Pasi Keränen (the original author) can be contacted at: javanerd@geocities.com
The web pages for GF4J are currently located at: http://www.gamedev.net/hosted/javanerd


6. CONTRIBUTORS

Fredrik Glawe, glawe@framfab.se

Commented on the release 0.9.2. Comments implemented in release 0.9.3:

 

Donald Strong
Commented on the release 0.9.1. Comments implemented in release 0.9.2:

 

Donald Strong
Commented on the first public release 0.9. Comments implemented in release 0.9.1:


Copyright ©1999-2000 Pasi Keränen, javanerd@geocities.com
Re-use with the GameFrame for Java library builds
allowed if the history field in the beginning of the
document is left intact (only adding of entries
 is allowed, no removing).