ReadMe for Star Chess 2.0.4

ProgramStar Chess: Minimal 4X Game
Version2.0.4 (History)
Released01 May 2016
AuthorChristoph Nahr (Copyright)
Contactwebmaster@kynosarges.org
Websitekynosarges.org/StarChess.html

Table of Contents

  1. System Requirements
  2. Package Contents
  3. Usage Overview
  4. Source Package
  5. Known Issues
  6. Copyright Notice

1. System Requirements

Star Chess is a JavaFX GUI application that should work on any system with a current Java Runtime Environment (JRE). The precompiled JAR file requires Oracle Java SE 8 Update 66 with JavaFX 8 or later. Older JREs that only support Swing will not work.

Some hyperlink actions rely on Java’s multiplatform support for invoking default applications, such as web browsers and mail clients. These should work on all desktop platforms, assuming your applications are properly configured to handle the desired URLs or file types. If some action is entirely unsupported on your platform, the hyperlink’s tool tip will state that fact.

Microsoft Windows — Please see Oracle Java on Windows for information on how to avoid Oracle’s inferior default Windows JRE. For Star Chess in particular, the non-default Server VM runs computer players 50% faster than the default Client VM.

2. Package Contents

The directory to which the binary package was unpacked contains the following files:

ReadMe.htmlThis file
WhatsNew.htmlStar Chess version history
project.cssStyle sheet for ReadMe & WhatsNew
Diagrams.xmlProject file for overview diagrams
StarChess.jarStar Chess GUI executable (requires JavaFX)
help/*Star Chess help system (show with index.html)
lib/StarChess.Core.jarStar Chess core algorithms (requires Compact1 profile)

These files are all you need to run Star Chess. Java programmers may also want to download the source package which is available separately.

3. Usage Overview

Use the command line javaw -jar StarChess.jar to run Star Chess. Depending on your JVM, you may also be able to omit javaw -jar and simply execute StarChess.jar directly, or to simply double-click on StarChess.jar in your favorite file explorer.

Star Chess creates a folder called StarChess in the current user’s home directory to store saved games and user settings, as well as temporary files for the help system. If creation of that folder fails, Star Chess will attempt to store games and settings directly in the current user’s home directory.

For more information on how to play Star Chess, please see the integrated help system. An additional PDF document available as a separate download on the Star Chess home page describes the computer player algorithms and internals of the game engine.

Known JavaFX Issues

There are currently two known JavaFX issues that might affect your system. First, its hardware accelerated graphics may cause some display drivers to crash; and second, its automatic DPI scaling is disabled by default on Windows at 120 DPI (125%) which might cause layout errors. Should you experience these issues you can avoid them using Java startup switches, as described here.

4. Source Package

The source package is available as a separate download on the Star Chess home page. The expected environment is NetBeans 8.1 with Oracle JDK 8u92. This package contains all of the files in the binary package, except for the precompiled Java archive, plus the following:

build.xmlCustomized build steps
manifest.mfApplication manifest placeholder
nbproject/*NetBeans project configuration
src/*Source code and resources
dist/javadoc/*Javadoc class reference

NetBeans injects custom dependencies into its Ant build scripts, so you’ll need an actual NetBeans installation to rebuild the project. Note that rebuilding will produce a bunch of unnecessary Java Web Start files, but I don’t see a way to disable that.

Star Chess Core

The source package contains two NetBeans projects: the main project StarChess for the JavaFX-based GUI executable, and the library project StarChess.Core with the actual game engine and computer player algorithm. StarChess.Core requires only the smallest Compact1 profile introduced in Java 8, so you could use it on platforms that don’t support JavaFX or other features requires by the main project.

StarChess.Core contains an executable command-line runner that prints the current game situation as ASCII art. Start the runner with java -jar StarChess.Core.jar as usual. You’ll be asked to enter a starting distribution, then the game will play out with four computer players. When finished the runner will save the game, and reload and replay the saved game. I use this program for testing the game engine. Edit Runner.java to change the hard-coded settings or the executed actions.

The Javadoc class reference for the main project links into that for the core project, using relative file paths. For this to work you need to keep both projects side-by-side in the same parent directory. When rebuilding you must first generate Javadoc files for the core project, then for the main project.

Overview Diagrams

The computer player documentation includes a chapter on implementation that describes relevant classes in the Star Chess source code. Relationships between these classes are visualized in several overview diagrams, created from the included file Diagrams.xml which is a Class Diagrammer project.

To view or edit the project in Class Diagrammer, open Diagrams.xml in the same directory that holds StarChess.jar. Note that the diagrams in the computer player documentation were created with locally installed Adobe Myriad Pro fonts, so you may have to adjust the diagram layouts for wider fonts.

5. Known Issues

About Star Chess: The positions/second display is somewhat imprecise. It’s based on System.nanoTime which measures total JVM execution time, not per-thread execution time for the computer player background thread. The latter would require java.lang.management.ThreadMXBean from profile Compact3, and StarChess.Core otherwise only requires profile Compact1.

All files – individual files, multi-file packages, and individual files contained in multi-file packages – that constitute the original distribution of Star Chess are Copyright © 1999–2016 by Christoph Nahr, except where otherwise noted.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Exceptions

The text font is Share Regular by Ralph du Carrols, hosted on Font Squirrel and available under the SIL Open Font License. Icons are rendered from Font Awesome by Dave Gandy, also using the SIL Open Font License, and Ionicons by Ben Sperry, available under the MIT License. All fonts are embedded. The original font files can be found in directory src/resources of the source code package.

The map image is based on Galaxies in Hiding, a photograph of 200 galaxies in the Perseus-Pisces supercluster taken by NASA’s Spitzer Space Telescope. Courtesy NASA/JPL-Caltech as per Spitzer’s Image Use Policy.

The barren planet image is based on Mars and Elysium, taken by NASA’s Hubble Space Telescope. The terran planet image is based on Full Earth, taken by NASA’s Apollo 17 crew traveling toward the moon. Both images are covered by the NASA Copyright Notification.