The SkyControl Project provides a sky-simulation library for
the jMonkeyEngine (JME) game engine.
It contains 3 subprojects:
- SkyLibrary: the SkyControl runtime library and its automated tests
- SkyExamples: example applications
- 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:
- Add SkyControl and its dependencies to the classpath.
- Disable any existing sky which might interfere with SkyControl.
- Add a
SkyControl
instance to some node in the scene graph.
- Configure the
SkyControl
instance.
- Enable the
SkyControl
instance.
- 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.0.5")
}
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.0.5</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):
- Right-click on the project (not its assets) in the "Projects" window.
- Select "Properties" to open the "Project Properties" dialog.
- Under "Categories:" select "Libraries".
- Click on the "Compile" tab.
- 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.
- (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.
- Similarly, add the SkyControl jar(s).
- Click on the "OK" button to exit the "Project Properties" dialog.
Jump to the table of contents
How to build SkyControl from source
- Install a Java Development Kit (JDK),
if you don't already have one.
- 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 '
- 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.0.5
- 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
- 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: [email protected]
Jump to the table of contents