Skip to content

Latest commit

 

History

History
380 lines (292 loc) · 13.5 KB

README.md

File metadata and controls

380 lines (292 loc) · 13.5 KB
Raw

SkyControl logo

The SkyControl Project provides a sky-simulation library for the jMonkeyEngine (JME) game engine.

It contains 3 subprojects:

  1. SkyLibrary: the SkyControl runtime library and its automated tests
  2. SkyExamples: example applications
  3. SkyAssets: generate textures included in the library

Complete source code (in Java) is provided under a 3-clause BSD license.

Contents of this document

Important features

  • sun, moon, stars, horizon haze, and up to 6 cloud layers
  • compatible with static backgrounds such as cube maps
  • high resolution textures are provided -- or customize with your own textures
  • compatible with effects such as SimpleWater, shadows, bloom, and cartoon edges
  • continuous and reversible motion and blending of cloud layers
  • option to foreshorten clouds near the horizon
  • continuous and reversible motion of sun, moon, and stars based on time of day
  • updater to synchronize lighting and shadows with sun, moon, and clouds
  • continuous scaling of sun, moon, and clouds
  • option for continuously variable phase of the moon
  • demonstration apps and online tutorial provided
  • complete source code provided under FreeBSD license

Jump to the table of contents

How to add SkyControl to an existing project

Adding SkyControl to an existing jMonkeyEngine project should be a simple 6-step process:

  1. Add SkyControl and its dependencies to the classpath.
  2. Disable any existing sky which might interfere with SkyControl.
  3. Add a SkyControl instance to some node in the scene graph.
  4. Configure the SkyControl instance.
  5. Enable the SkyControl instance.
  6. Test and tune as necessary.

The SkyControl Library depends on the standard "jme3-effects" library from jMonkeyEngine and the Heart Library, which in turn depends on the standard "jme3-core" library.

For projects built using Maven or Gradle, it is sufficient to add a dependency on the SkyControl Library. The build tool should automatically resolve the remaining dependencies.

Gradle-built projects

Add to the project’s "build.gradle" or "build.gradle.kts" file:

repositories {
    mavenCentral()
}
dependencies {
    implementation("com.github.stephengold:SkyControl:1.1.0")
}

For some older versions of Gradle, it's necessary to replace implementation with compile.

Maven-built projects

Add to the project’s "pom.xml" file:

<repositories>
  <repository>
    <id>mvnrepository</id>
    <url>https://repo1.maven.org/maven2/</url>
  </repository>
</repositories>

<dependency>
  <groupId>com.github.stephengold</groupId>
  <artifactId>SkyControl</artifactId>
  <version>1.1.0</version>
</dependency>

Ant-built projects

For projects built using Ant, download the SkyControl and Heart libraries from GitHub:

You'll definitely want both class jars and probably the "-sources" and "-javadoc" jars as well.

Open the project's properties in the IDE (JME SDK or NetBeans):

  1. Right-click on the project (not its assets) in the "Projects" window.
  2. Select "Properties" to open the "Project Properties" dialog.
  3. Under "Categories:" select "Libraries".
  4. Click on the "Compile" tab.
  5. Add the Heart class jar:
  • Click on the "Add JAR/Folder" button.
  • Navigate to the download folder.
  • Select the "Heart-8.3.2.jar" file.
  • Click on the "Open" button.
  1. (optional) Add jars for javadoc and sources:
  • Click on the "Edit" button.
  • Click on the "Browse..." button to the right of "Javadoc:"
  • Select the "Heart-8.3.2-javadoc.jar" file.
  • Click on the "Open" button.
  • Click on the "Browse..." button to the right of "Sources:"
  • Select the "Heart-8.3.2-sources.jar" file.
  • Click on the "Open" button again.
  • Click on the "OK" button to close the "Edit Jar Reference" dialog.
  1. Similarly, add the SkyControl jar(s).
  2. Click on the "OK" button to exit the "Project Properties" dialog.

Jump to the table of contents

How to build SkyControl from source

  1. Install a Java Development Kit (JDK), if you don't already have one.
  2. Point the JAVA_HOME environment variable to your JDK installation: (In other words, set it to the path of a directory/folder containing a "bin" that contains a Java executable. That path might look something like "C:\Program Files\Eclipse Adoptium\jdk-17.0.3.7-hotspot" or "/usr/lib/jvm/java-17-openjdk-amd64/" or "/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home" .)
  • using Bash or Zsh: export JAVA_HOME=" path to installation "
  • using Fish: set -g JAVA_HOME " path to installation "
  • using Windows Command Prompt: set JAVA_HOME=" path to installation "
  • using PowerShell: $env:JAVA_HOME = ' path to installation '
  1. Download and extract the SkyControl source code from GitHub:
  • using Git:
    • git clone https://github.com/stephengold/SkyControl.git
    • cd SkyControl
    • git checkout -b latest 1.1.0
  • using a web browser:
    • browse to the latest release
    • follow the "Source code (zip)" link
    • save the ZIP file
    • extract the contents of the saved ZIP file
    • cd to the extracted directory/folder
  1. Run the Gradle wrapper:
  • using Bash or Fish or PowerShell or Zsh: ./gradlew build
  • using Windows Command Prompt: .\gradlew build

After a successful build, Maven artifacts will be found in "SkyLibrary/build/libs".

You can install the artifacts to your local Maven repository:

  • using Bash or Fish or PowerShell or Zsh: ./gradlew install
  • using Windows Command Prompt: .\gradlew install

You can restore the project to a pristine state:

  • using Bash or Fish or PowerShell or Zsh: ./gradlew clean
  • using Windows Command Prompt: .\gradlew clean

Jump to the table of contents

Downloads

Newer releases (since v0.9.27) can be downloaded from GitHub.

Older releases (v0.9.0 through v0.9.26) can be downloaded from the Jme3-utilities Project.

Newer Maven artifacts (since v0.9.30) are available from MavenCentral.

Old Maven artifacts (v0.9.25 through v0.9.29) are available from JCenter.

Jump to the table of contents

Conventions

Package names begin with jme3utilities.sky

Both the source code and the pre-built libraries are compatible with JDK 8.

In the default world coordinate system:

  • the +X axis points toward the northern horizon
  • the +Y axis points up (toward the zenith)
  • the +Z axis points toward the eastern horizon

However, these axis assignments can be overridden using SunAndStars.setAxes().

Jump to the table of contents

External links

Jump to the table of contents

History

The evolution of this project is chronicled in its release log.

SkyControl has its roots in SkyDome by Cris (aka "t0neg0d").

From November 2013 to September 2015, SkyControl was part of the Jme3-utilities Project at Google Code.

From September 2015 to August 2020, SkyControl was part of the Jme3-utilities Project at GitHub.

Since August 2020, SkyControl has been a separate project, hosted at GitHub.

Old (2014) versions of SkyControl can still be found in the jMonkeyEngine-Contributions Project.

Jump to the table of contents

Acknowledgments

Like most projects, the SkyControl Project builds on the work of many who have gone before. I therefore acknowledge the following artists and software developers:

  • Cris (aka "t0neg0d") for creating SkyDome (which provided both an inspiration and a starting point for SkyControl) and also for encouraging me to run with it ... thank you yet again!
  • Paul Speed, for helpful insights which got me unstuck during debugging
  • Rémy Bouquet (aka "nehon") for many helpful insights
  • Alexandr Brui (aka "javasabr") for a solving a problem with the de-serialization of SkyControl
  • the brave souls who volunteered to be alpha testers for SkyControl, including:
    • Davis Rollman
    • "Lockhead"
    • Jonatan Dahl
    • Mindaugas (aka "eraslt")
    • Thomas Kluge
    • "pixelapp"
    • Roger (aka "stenb")
  • the beta testers for SkyControl, including:
    • "madjack"
    • Benjamin D.
    • "Fissll"
    • Davis Rollman
  • users who found and reported bugs in later versions:
    • Rami Manaf
    • Anton Starastsin (aka "Antonystar")
  • the creators of (and contributors to) the following software:
    • Adobe Photoshop Elements
    • the Ant build tool
    • the Blender 3-D animation suite
    • the Checkstyle tool
    • the FindBugs source-code analyzer
    • the Firefox and Chrome web browsers
    • Gimp, the GNU Image Manipulation Program
    • the Git revision-control system and GitK commit viewer
    • the GitKraken client
    • the Gradle build tool
    • Guava core libraries for Java
    • the IntelliJ IDEA and NetBeans integrated development environments
    • the Java compiler, standard doclet, and runtime environment
    • the JCommander Java framework
    • jMonkeyEngine and the jME3 Software Development Kit
    • the Linux Mint operating system
    • LWJGL, the Lightweight Java Game Library
    • the Markdown document-conversion tool
    • the Meld visual merge tool
    • Microsoft Windows
    • the Nifty graphical user-interface library
    • Open Broadcaster Software Studio
    • the PMD source-code analyzer
    • Alex Peterson's Spacescape tool
    • the Subversion revision-control systems
    • the WinMerge differencing and merging tool

Many of SkyControl's assets were based on the works of others who licensed their works under liberal terms or contributed them to the public domain. For this I thank:

  • Cris (aka "t0neg0d")
  • Jacques Descloitres, MODIS Rapid Response Team, NASA/GSFC
  • Tom Ruen

I am grateful to GitHub, Sonatype, JFrog, YouTube, and Imgur for providing free hosting for this project and many other open-source projects.

I'm also grateful to Quinn (for lending me one of her microphones) and finally my dear Holly, for keeping me sane.

If I've misattributed anything or left anyone out, please let me know, so I can correct the situation: sgold@sonic.net

Jump to the table of contents