This is the Stellarium for Java FAQ, which contains answers to the most Frequently Asked Questions about the Stellarium for Java 3D planetarium simulator.


General questions

Java questions

Installing Stellarium for Java

Using Stellarium for Java




General questions

What is Stellarium for Java?

Stellarium is an open source desktop planetarium for Java platforms, including Linux/Unix, Windows and MacOSX. It renders the skies in realtime using OpenGL, which means the skies will look exactly like what you see with your eyes, binoculars, or a small telescope. Stellarium is very simple to use, which is one of its biggest advantages: it can easily be used by beginners.
The original Stellarium project was started by Fabien Chéreau during the summer of 2001 and uses Sourceforge intensively.

Stellarium for Java (S4J) is the Java version of Stellarium. Access the Sourceforge project page here.

How Stellarium and Stellarium for Java will be sync?

Currently Stellarium for Java is sync with Stellarium 0.8.2. Once that version released as non-beta, the project may check for improvements and new features from the original Stellarium, and integrate them as needed.

Is Stellarium for Java free?

Yes. Stellarium is free software in both meanings of the term. That is, available for free and open source : anyone has the right to download, use, distribute and even modify it provided that the terms of its GNU Public License (GPL) are respected.

Where can I download Stellarium?

Currently Stellarium is available as a Java Web Start application (to be installed first, if you don't have any Java runtime on your host) from Sourceforge or from Java.net.

Further releases will be available from the download page of the Sourceforge servers.

Where can I provide feedback?

Your ideas and comments are invaluable to Stellarium. Have a look at the feedback page to see where you can get personal support, ask for new features, report bugs and even submit your own patches.


Java questions

What is Java?

Java is a software plaftorm that allows a sofware to run on many lower-level platforms such as Windows, Linux, MacOS and many others. Java software is run by a JVM (Java Virtual Machine) software that runs on your host.

Why a Java version?

There is a number of reasons for providing a Java version of Stellarium. Among these are :

Isn't Java too slow?

This argument was valid when the first releases of Java appeared (around 1996), but has become increasingly false with each new release. Some figures put JDK 1.0 at 20 to 40 times slower than C++. J2SE 1.4.2 is typically 1.1-1.3 times slower, and J2SE 1.5 (a.k.a. Java 5) is meant to be 1.2 to 1.5 times faster than its predecessor. S4J now runs on Java 1.6 (a.k.a Java 6).

Note that these numbers depend greatly on the code quality. Java programmers must be good programmers in order to utilise Java efficiently, but that’s true of any language. Jack Shirazi's Java Performance Tuning site is a good source for performance tips, and links to tools and other resources.

A benchmarking of Java vs C++ by Keith Lea caused quite a stir. He found that Java may sometimes be faster than C++.

The speed-up in Java is mostly due to improvements in compiler design. The Hotspot technology introduced in J2SE 1.3 enables the run-time system to identify crucial areas of code that are utilised many times, and these are aggressively compiled. Hotspot technology has the unfortunate side-effect that program execution is often slow at the beginning until the code has been analyzed and compiled.

Swing often comes under attack for being slow. Swing GUI components are created and controlled from Java, with little OS support: this increases their portability and makes them more controllable from within a Java program. Speed is supposedly compromised because Java imposes an extra layer of processing above the OS. This is one reason why some games applications still utilise the original Abstract Windowing Toolkit (AWT) – it's mostly just simple wrapper methods around OS calls.

A crucial point about speed is knowing what to blame when a program runs slowly. Typically, a large part of the graphics rendering of a game is handled by hardware or software outside of Java. For example, Java 3D passes its rendering tasks down to OpenGL or Direct3X, which may emulate hardware capabilities such as bump mapping. Often the performance bottleneck in network games is the network.

Hasn't Java memory leaks?

When C/C++ programmers refer to memory leaks in Java, it may mean that they don't understand how Java works. Java doesn't offer pointer arithmetic, and typical C-style memory leaks such as out-of-bounds array accesses are caught by the Java compiler. However, they may mean that objects which are no longer needed by the program are not being garbage collected. This becomes an issue if the program keeps creating new objects, requiring more memory, and eventually crashes when the maximum allocation is exceeded.

This kind of problem is a consequence of bad programming style, since the garbage collector can only do its job when an object is completely dereferenced (i.e. the program no longer refers to it). A good profiling tool, such as JProfiler, can be a great help in identifying code using excessive amounts of memory. JProfiler is a commercial product; many open source profilers are available.

Another memory related complaint is that the garbage collector is executing at poorly timed intervals, causing the application to halt for seconds while the collector sweeps and cleans.

The JVM comes with several different garbage collectors, which collect in various ways, and can be selected and fine-tuned from the command line. Information on the performance of the chosen collector can be gathered and analysed. A good hands-on explanation of this topic, centered around the JTune visualization tool.

Isn't Java too high level?

This complaint is the age old one of abstraction versus speed and control. The details of the argument often include the following statements:

1. Java’s use of classes, objects and, inheritance add too much overhead without enough coding benefit;
2. Java’s machine independence means that low-level, fast operations, such as direct Video RAM I/O, are impossible.

Statement (1) ignores the obvious benefits of reusing and extending Java’s very large class library, which includes high-speed I/O, advanced 2D and 3D graphics, and an enormous range of networking techniques, from lowly sockets to distributed agents. Also forgotten are the advantages of object oriented design, typified by UML, which makes complex, large real-world systems more manageable during development, implementation, and maintenance.

Statement (2) impacts gaming when we consider high-speed graphics, but it's been addressed in recent versions of Java. J2SE 1.4 introduced a full-screen exclusive mode (FSEM), which suspends the normal windowing environment, and allows an application to more directly access the underlying graphics hardware. It permits techniques such as page flipping, and provides control over the screen's resolution and image depth. The principal aim of FSEM is to speed up graphics-intensive applications, such as games. Statement (2) also comes into play for game perpherals, such as joysticks and gamepads; machine independence seems to suggest that 'non-standard' I/O devices won't be useable. Java games requiring these types of devices can utilize JNI, the Java Native Interface, to link to C or C++ and so to the hardware. There's even JInput, a new game controller API, due to be finalised early in 2005.

An interesting historical observation is that the gaming community use to think that C and C++ were too high-level for fast, efficient games programming, when compared to assembly language. Opinions started to change only after the obvious success of games written in C, such as Doom and Dungeon Master, in the mid 1980s. Also important was the appearance of cross-platform development tools that supported C, such as Renderware.

Is anyone using Java to write graphics-intensive or 3D software?

An good example is Java games, some of which are commercial. The number of commercial Java games is small compared to ones coded in C++ or C, but the number is growing, and many have garnered awards and become bestsellers:

Puzzle Pirates by Three Rings, a multiplayer pirate game that includes Tetris- or Columns-like puzzles at various points. Both the client and server are written in Java. It won several awards during 2004, including the Technical Excellence and Audience Choice prizes at the Game Developers Conference.

Chrome by Techland. A futuristic multiplayer FPS made up of 14 different missions, in an amazing variety of landscapes. It received a Duke's Choice Award from Sun Microsystems in 2004 for the most innovative product using Java technology.

Law and Order II, by Legacy Interactive. A detective game written in Java, Java 3D, and Quicktime for Java. The first Law and Order sold over 100,000 units.

Kingdom of Wars, set in the fantasy world of Jairon, by Abandoned Castle Studios

Alien Flux
, an exciting arcade shoot-em-up from Puppy Games

War! Age of Imperialism, a computer version of the award-winning board game from Eagle Games.

Runescape by Jagex is a massive 3D multiplayer fantasy adventure game. Clients can use a Java applet to play, or download a Windows-based client application.

Star Wars Galaxies from LucasArts has its game logic coded in Java.

IL-2 Sturmovikand the new version IL2-Forgotten Battles by Ubi-Soft. Award winning WW I aerial combat using Java and C++.

Pernica by Starfire Research. An online fantasy role-playing game first implemented in Java 3D, recently ported to Xith3D.

Cosm from Navtools, Inc. Another fun online fantasy-based role-playing game.

C&C Attack Copter. A free online action game based on the Command & Conquer series from Electronic Arts.

Roboforge by Liquid Edge Games. Train a 3D robot to fight in online tounaments. It was given an "Excellent 87%” by PC Gamer Magazine.

Galactic Village by Galactic Village Games, a massively multiplayer strategy game, written entirely in Java. Not yet finished, although alpha versions have been appearing.

Wurm Online by Mojang Specifications. Another massively multiplayer fantasy game, written in Java. Still at the alpha stages of development, but the screenshots look great.

Jellyvision used a mix of Java and C++ in their popular Who wants to be a Millionaire (2000) and You don't know Jack (1995) games. They employed Java for the game logic, an approach also used in Majestic (2001) by Electronic Arts.

Java was utilized as a scripting language in the acclaimed Vampire - the Masquerade: Redemption (2000) from Nihilistic software.

Tom Clancy's Politika (1997) from Red Storm Entertainment was written in almost pure Java. Both Shadow Watch (2000) and Tom Clancy’s ruthless.com (1998) mixed Java and C/C++.

A good source for non-technical lists of Java games, both commercial and freeware/shareware, can be found on the Java games pages at java.com. It divides games into several categories: action, adventure, strategy, puzzle, cards, sports, and so on.

There are many, many Java games out on the Web, but finding a game that's well written requires a careful search. Many applets date from the late 1990’s, and were
designed using the outdated JDK 1.0 and 1.1 with their feeble media APIs (graphics, sounds, etc). The initial Java euphoria produced some less than exciting games, more concerned with technical trickery. This large pool of useless applets got Java labelled as a toy language.

Recent versions of Java are quite different: speed is vastly improved, and APIs crucial to gaming, such as graphics and audio, are of a high quality. There's been a move away from applets towards the downloading of client-side applications using Java Web Start.

Java’s backwards compatibility allows the applets from 1996-8 to be executed, and they'll often run quicker than originally. However, it’s probably best to steer clear of these Java dinosaurs, and look for more modern code.

There are numerous Web sites with free/shareware Java games. The emphasis of the following list is on applications/applets for playing:

Java Games Factory (JGF). There aren’t many games at this site (about 50), but they're all high quality. The aim is to show off the variety of modern Java game technologies.
ArcadePod.com, Over 750 Java games, nicely categorized.
Java 4 Fun, Similar in style to ArcadePod, and a good set of links to other sites.
jars.com, A general Java site with a ratings scheme. There are many games, but a lot of them are old applets.
Java Shareware, Another general site: look under the categories: applications/games/ and applets/games.
Java Games Central, A personal Web site which lists games with ratings and links. It was last updated in 2001.

Some good freeware/shareware games at the moment:

• Super Elvis (also known as Hallucinogenesis) by puppygames.net, which won the Sun Microsystems 2004 Technology Game Development Contest. Super Elvis can be downloaded using Java Web Start
FlyingGuns, a 3D multiplayer WW1 fighter plane game/simulator.
Cosmic Trip, an arcade style 3D game with striking graphics.
Squareheads a multiplayer FPS (it came third in the developer contest).
Escape, a Doom-like FPS.
CazaPool3D, a pool game that allows online (single/multiplayer) play in an applet or as a standalone application.

Programmers looking for source code should start at one of the following sites:

SourceForge, SourceForge acts as a repository, and management tool, for software projects, many with source code. A recent search for (java + game) returned over 70 projects that had 40% or greater activity. One of the drawbacks of SourceForge is that it can be quite difficult to decide whether a project is vaporware or not. Good projects, which have been completed, will show low activity after a time, dropping down the list of search results.
FreshMeat.com, Freshmeat maintains thousands of applications, most released under open source licenses. The search facilities are excellent, and can be guided by game category terms. The results include rating, vitality, and popularity figures for each piece of software. A recent search for Java in the Games/Entertainment category returned nearly 70 hits. Many applications turn up at both SourceForge and FreshMeat.
The "Your Games Here" Java Games Forum, Implementors can post links to their games, and (perhaps more importantly) users can post their opinions as follow-ups.
Code Beach, CodeBeach has a searchable subsection for Java games that currently contains nearly 90 example.
Programmers Heaven, It has a ‘Java zone’ containing some games.

Why choosing JOGL?

The original Stellarium software has been written using a C OpenGL API. JOGL is a Java version of the latest OpenGL API 2.0, including vendor extension, which conforms to the expected Java standard support for JOGL (JSR 231). Furthermore, contrary on other APIs, it allows mixing both OpenGL and Swing.


Installing Stellarium

What are Stellarium's system requirements?

A graphics card capable of rendering OpenGL. A Riva TNT2, released in 1999 or 2000, should do. Stellarium is also fairly processor intensive, so you will get higher framerates with faster processors. Any reasonably recent computer should be able to run Stellarium. Furthermore your computer should be running a Linux, Windows or MacOSX operating system.

How do I install Stellarium?

For Windows users, run the downloaded file "setup.exe" and follow the instructions.
For Linux users, the easiest is to find a pre-compiled package for your distribution.
But it is also possible to compile the program yourself: detailed compilation instructions for Linux, Posix, Cygwin and MacOSX are available in the "install" file.

How do I uninstall Stellarium?

For Windows users, uninstall Stellarium using the "Add or Remove Programs" applet in the Windows control panel.
For Linux users, use your packet manager if you installed a pre-compiled version.
If you compiled yourself you can uninstall by typing "make uninstall" in the compilation directory.


Using Stellarium

How do I start using Stellarium?