How to add Acorus to an existing project

This is the start page of a web tutorial about the Acorus library.

If you’re creating a JMonkeyEngine desktop application from scratch, the BasicGame-on-Gradle project provides a good starting point.

Adding Acorus to an existing JMonkeyEngine project is a 3-step process:

  • Add libraries to the classpath.

  • Convert the application to an ActionApplication or AcorusDemo.

  • Test and tune as necessary.

Add libraries to the classpath

Acorus comes pre-built as a JVM library that depends on:

For projects built using Gradle or Maven, it’s usually sufficient to specify the dependency on the Acorus Library. Build tools 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:Acorus:2.0.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>Acorus</artifactId>
  <version>2.0.0</version>
</dependency>

Ant-built projects

Ant doesn’t know about transitive dependencies, so you’ll need to resolve them manually.

Download the Acorus library and its dependencies from GitHub and/or Maven Central:

You’ll definitely want the 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:", click on Libraries.

  4. Click on the Compile tab.

  5. Add the Acorus class JAR:

    1. Click on the Add JAR/Folder button.

    2. Navigate to the download directory.

    3. Select the "Acorus-2.0.0.jar" file.

    4. Click on the Open button.

  6. (optional) Add JARs for javadoc and sources:

    1. Click on the Edit button.

    2. Click on the Browse…​ button to the right of "Javadoc:"

    3. Select the "Acorus-2.0.0-javadoc.jar" file.

    4. Click on the Open button.

    5. Click on the Browse…​ button to the right of "Sources:"

    6. Select the "Acorus-2.0.0-sources.jar" file.

    7. Click on the Open button button again.

    8. Click on the OK button to close the "Edit Jar Reference" dialog.

  7. Add the other JVM libraries in a similar manner.

  8. Click on the OK button to exit the "Project Properties" dialog.

Convert to an ActionApplication

JMonkeyEngine applications typically extend the SimpleApplication class. To use Acorus, an application should instead extend ActionApplication or one of its subclasses, typically AcorusDemo.

  • ActionApplication and AcorusDemo are both abstract classes.

  • ActionApplication is simpler and easier to understand.

  • AcorusDemo extends ActionApplication with features intended for demo apps.

ActionApplication directly extends SimpleApplication and has a similar interface (API). The key difference is that startup code goes in a acorusInit() method instead of simpleInitApp().

AcorusDemo implements acorusInit(). If your application extends AcorusDemo, it should should always invoke super.acorusInit().

Summary

  • Acorus is available as a pre-built library.

  • Apps should extend AcorusDemo or maybe ActionApplication.

  • Startup code goes in acorusInit(), not simpleInitApp().