The Acorus Project provides a simple user-interface library for the jMonkeyEngine (JME) game engine.

It contains 2 subprojects:

1. AcorusLibrary: the Acorus JVM runtime library
2. AcorusExamples: demos, examples, and non-automated test software

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

Acorus is oriented toward keyboard-driven demo/test applications. Examples may be found in the Heart, Minie, MonkeyWrench, and Wes projects.

Contents of this document

• Important features
• How to add Acorus to an existing project
• How to build Acorus from source
• Downloads
• Conventions
• An overview of the example applications
• History
• Acknowledgments

Important features

Acorus is a user-interface library for JMonkeyEngine desktop applications that don't require graphical widgets such as checkboxes, radio buttons, and sliders.

Acorus provides simple mechanisms to:

• bind keyboard keys, mouse buttons, and joystick buttons (hotkeys) to names that are meaningful to the application (actions)
• determine which hotkeys are active (signals)
• detect input combinations such as "Ctrl+C" (combos)
• use different hotkey bindings in different contexts (input modes)
• display on-screen UI help for the active input mode, localized for the system's keyboard layout (help nodes)

Input modes can be configured dynamically and/or loaded from files.

Help nodes make Acorus-based user interfaces (somewhat) self-documenting.

The Acorus library also includes:

• 2 implementations of the Application interface, tailored for demos (ActionApplication and AcorusDemo)
• an input mode for emulating a SimpleApplication (DefaultInputMode)
• a camera controller for orbiting the world's Y axis (CameraOrbitAppState)
• a display-settings editor (DsEditInputMode and DsEditOverlay)
• a class to simplify the management of asset locators (for asset editors)

Jump to the table of contents

How to add Acorus to an existing project

How to add Acorus to an existing project

How to build Acorus from source

How to build Acorus from source

Downloads

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

Old releases (through v0.9.6) can be downloaded from the Jme3-utilities Project.

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

Old Maven artifacts (v0.9.2 through v0.9.6) are available from MavenCentral jme3-utilities-ui.

Jump to the table of contents

Conventions

Package names begin with jme3utilities.ui

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

Jump to the table of contents

An overview of the example applications

Applications have been created to illustrate key concepts of Acorus. They are found in the AcorusExamples subproject. Since they aren't distributed in binary form, you must build the project from source in order to run them.

To run them using the included AppChooser:

• using Bash or Fish or PowerShell or Zsh: ./gradlew --no-daemon AppChooser
• using Windows Command Prompt: .\gradlew --no-daemon AppChooser

To run a specific app:

• using Bash or Fish or PowerShell or Zsh: ./gradlew --no-daemon appName
• using Windows Command Prompt: .\gradlew --no-daemon appName

HelloAcorus

Getting started with Acorus

TestHotkeys and HelloBind

Binding hotkeys to actions

HelloSignals

Binding hotkeys to signals

HelloCombo

Binding combos to actions

HelloSimpleApplication

Mimicking a simple application

HelloToggleHelp

Toggling the help node

TestAcorusDemo

Additional features of AcorusDemo

HelloSandbox and HelloRecorder

The Sandbox

TestToggleFly and HelloCoas

Controlling 3-D cameras

TestTwoModes and TestCursors

Defining multiple input modes

TestDsEdit

Editing display settings

TestHeadless

Using Acorus in a headless context

Jump to the table of contents

History

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

Prior to January 2022, Acorus was a subproject of the Jme3-utilities Project named "jme3-utilities-ui".

Since January 2022, Acorus has been a separate project, hosted at GitHub.

Jump to the table of contents

Acknowledgments

Like most projects, Acorus builds on the work of many who have gone before. I therefore acknowledge the creators of (and contributors to) the following software:

• the Ant and Gradle build tools
• the Antora static website generator
• the Checkstyle tool
• the FindBugs source-code analyzer
• the Firefox and Google Chrome web browsers
• the Git and Subversion revision-control systems
• the GitKraken client
• the Gradle build tool
• the IntelliJ IDEA and NetBeans integrated development environments
• the Java compiler, standard doclet, and runtime environment
• 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 NetBeans integrated development environment
• the PMD source-code analyzer
• the RealWorld Cursor Editor
• the WinMerge differencing and merging tool

I am grateful to Juan Cruz Fandino for his pull request.

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

I'm also grateful to 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