The Deimos Project

Java-based 3D space combat game

Version: 0.11.8 Beta
License: LGPL (license.txt)
Date of Writing: March 17, 2008
Overall API Docs: Can be found here
Overall Changelog: Can be found here

Short Description:
    I've always wanted to build a game and I love 3D first-person space shooters involving fighter combat, so this project is my attempt at such a game.

Long Description:
    The Deimos Project is intended to be a modular game system built from interconnecting libraries that are useable on their own. In some cases one or two others are needed; see below.
    This library collection will be the complete package; 3D sound and video, high-precision game timing, atomic data storage, math utilities, physics engine, etc.
    The goal is to be able to easily add new game components just by dropping a jar file in a directory. Everything the game uses will (hopefully) come from a jar file.

Notes on API Documentation
    Depending on what you download, you may get just the overall API docs or you may only have the individual documentation for a single library. For example, the main zip file containing all the libraries has the overall API documentation linked to on this page and the zip file containing Vertex Modeler only has it's individual API documetation. The website is the only source that has both the overall documentation and the documentation for individual libraries (else I'd get complaints about the site being broken).
    Each class in the API documentation has been stamped with stability comments. They've been placed there to help you know which APIs are permanent and which are most likely to change. Notes that are marked alpha are very likely to change. Beta means they're almost stable, but still subject to change. APIs marked stable won't change unless there's a major version switch, such as the change from version 1.x.y to 2.x.y.
    Pay very close attention to them when programming using these librarys, as they'll tell you which APIs to avoid. If a class has no stability comments, you should assume that it is pre-Alpha code and shouldn't be used unless you love refactoring your code every week.

Sub-Components:
    The Deimos Project is composed of several sub-projects. Each compiles to it's own jar file and some can be used on their own. Some require other libraries. Some require other libraries only under certain conditions, like during compilation. Read the notes below for more information. Each sub-component has it's own page, linked to at the top of the page and below.

Library	Version	Description	Jar File	Requires	Reccomended
Timer	1.3.1 Stable	Variable resolution stopwatch and timing system. Allows seamless useage of the millisecond timer or nanosecond timer, depending on what's available. It also gives you a manual stepping clock and the ability to plug in your own time sources.	timer.jar	Compile: Official Sun Java 1.5+ Runtime: Java 1.4.2+	Official Sun Java 1.4.2 or Java 1.5+
Hierarchy	1.3.0 Beta	Hierarchical persistable data storage. Allows storing hierarchical data in XML files.	hierarchy.jar	Java 1.4.2+
Audio	0.2.0 Alpha	OpenAL helper library. Includes classes for playing audio clips from memory and streaming from files. Capable of 3D sound.	audio.jar	Java 1.4.2+, JOAL	Surround Sound capable hardware; you're missing out if you've never tried surround sound with games
Video/Modeler	4.2.2 Stable	OpenGL helper library and modeler application. The net.jinx.video package simplifies using OpenGL. The net.jinx.video.model package allows programmatic creation and manipulation of 3D models. The Vertex Modeler application/library allows you to create and work with 3D models using Java source code. The modeler application itself allows you to display those models.	vmodeler.jar	Java 1.4.2+, JOGL, Janino (For the Modeler class only), Hierarchy, Timer, Math (VertexUtil only)	Decent video card; even something out-dated should work good; I'm using an ATI All-In-Wonder Radeon 7500
Action	0.6.5 Alpha	"Lights, Camera, Action!" Allows constructing a scene complete with actors, scenery and events, all based on a steppable clock, which can be backed by a real time clock, but doesn't have to be.	action.jar	Java 1.4.2+, Timer, Audio (for AudioRenderer), Modeler (for ActionGUI, VideoRenderer, ActorView and VisibleActor), Hierarchy (for ActionGUI)
Colorizer	0.1.1 Alpha	OpenGL based model painting application. Allows coloring 3D objects produced by Vertex Modeler.	colorizer.jar	Java 1.4.2+, Modeler
GUI	0.3.0 Alpha	GUI related classes for The Deimos Project.	gui.jar	Java 1.4.2+, Hierarchy
Math	0.5.2 Alpha	Math library for this project, including both a fast package suited for game physics and graphics, as well as a slower object-oriented package for seamless switching of numerical data types.	math.jar	Java 1.4.2+
Input	0.4.1 Beta	Input related library for use with the Action library.	input.jar	Java 1.4.2+, Timer, Action, JInput, JUtils	Input devices that don't suck ;-)
Asteroids	0.1.0 Alpha	3D first-person Asteroids clone.	asteroids.jar	Java 1.4.2+, Hierarchy, GUI
Plugin	0.1.0 Alpha	Deimos Modular Plugin Library. Allows dropping a jar file into a directory to add functionality to an already built system.	plugin.jar	Java 1.4.2+
Physics	0.4.3 Alpha	Deimos Physics Library.	physics.jar	Java 1.4.2+, Math, Action, Hierarchy, Modeler, Janino (For the Main class only)
Media	0.1.0 Alpha	Deimos Media Library. Plays video files in a platform independent fashion.	media.jar	Java 1.4.2+, MPlayer	Videos to play ;-)
Demo	0.1.1 Alpha	Deimos Demonstrator.	demo.jar	Java 1.4.2+, Varies by build target	Demos to run

External Libraries Used (Installation Notes):
    JOGL (http://jogl.dev.java.net) is required for video rendering to function. It is used for OpenGL rendering. I recently updated to using JOGL JSR-231 1.1.0; this is the version I reccomend, but JOGL JSR-231 1.0.0 should still work.
    JOAL (http://joal.dev.java.net) is required for audio rendering to function. It is used for OpenAL rendering. The only version I've tested with is 1.1b01. This version fixed all my gripes with JOAL (crappy debug output on the console and disabling ctrl+c for killing the JVM). I almost switched to using LWJGL for this part; thank goodness I found the newer file release! This is mainly why I did nothing with the Deimos Audio Library for so long (JOAL works real good now).
    JInput (http://jinput.dev.java.net) is required by the input library. JUtils (http://jutils.dev.java.net) is required by JInput.
    Janino (http://janino.net or http://janino.codehaus.org/) is required only by the Modeler (part of the Modeler application) and Main (part of the Physics library) classes. All of the others will function just fine without it. Janino is used to compile sources at runtime for model or scene construction. In your own projects, if you load all your models from exported xml files, you won't need Janino. Version 2.3.6 works fine.
    You will have to obtain copies of these libraries in order to use the applications and libraries from this collection. The jar files need to be in the same directory as the other jar files (vmodeler.jar, math.jar, gui.jar, etc.). Their names must be lower case and spelled as follows: "jogl.jar", "joal.jar", "jinput.jar", "jutils.jar" and "janino.jar"! You may have to figure out how to install the native libraries for JOGL, JOAL and JInput on your own. Under Windows, it should work by simply placing the .dll files in the same directory as the jars. Under Linux, put the .so files in a directory pointed at by your LD_LIBRARY_PATH.
    For JInput, follow the installation instructions in it's API documentation. Just placing the JInput jar in the directory with the other jars will work, but without the native bits, you'll have no controllers to use.
    Finally, the media library uses the command-line version of MPlayer (http://www.mplayerhq.hu/) to function. You'll have to install it and set the system property "Deimos.Media.MPlayer.Path" to the executable file. You can do this with with the following argument to the JVM (before the -jar switch):
    -DDeimos.Media.MPlayer.Path=PathToMPlayer
    Of course, you'll probably want to replace PathToMPlayer with the path to the MPlayer executable.
    Another option is to set the property in your Java code as follows, again replacing PathToMPlayer with the path to the executable:
    System.setProperty("Deimos.Media.MPlayer.Path", "PathToMPlayer");

Requirements:
    The Deimos Project was designed for Java 1.4.2, however, if you wish to compile it you will require the official Sun Java 1.5 or higher (you can still compile under 1.4.2 if you use the compile1.4 and jar1.4 ant tasks in the meta-build file; this precludes the timer functionality from being compiled). Only the net.jinx.time package requires 1.5. It has a package private class that handles nanosecond timing, but it is used only when this functionality is available. On Java 1.4.2, it will attempt to use sun.misc.Perf, then the standard millisecond system timer if that's not available.
    I would suggest that you use Java 1.5 or higher; nearly anything related to time will produce better results. Alternatively, you can install the official Sun version of Java 1.4.2; it has a performance profiling class (sun.misc.Perf) that works just as well.

Hosting for this project generously provided by: