TeraNUI

TeraNUI (Terasology's New UI Framework) is a canvas based UI framework.

Its major features are:

• Canvas providing primitive draw operations for UI, including "drawing" interaction regions.
• Skins providing display information, handled through the canvas operations.
• UIWidget system for encapsulating drawing logic into objects
• Skin asset providing the ability to define skins
• UI asset providing the ability to define widget layouts
• Data binding support

Learn more about TeraNUI and how to use it here:

👉 JavaDoc ▪ Guide ▪ Tutorial 👈

🤓 Development

We welcome contributions to this UI library, be it bug fixes or new features. Feel free to fork this project and open a PR with your changes. You can start right away by using the Gitpod online workspace:

In Terasology, you can test easily locally until you're ready for a snapshot or release. To do so, you'll need to re-embed TeraNUI into Terasology as source which has priority over any binary version. You can get the TeraNUI library as source into your local Terasology workspace as follows:

groovyw lib get TeraNUI

This will place the TeraNUI source code into /libs/TeraNUI. Please note, that you may need to reload/refresh your gradle workspace in Intellij IDEA.

🤖 Maintenance

The main development of TeraNUI happens on the master branch, a strong main branch that always has the latest version of the code. However, we maintain two versions of TeraNUI for gestalt v5 and v7, respectively. As the two code lines are nearly identical most changes to either version should be ported back 🔗 to the other.

Porting changes from one branch to the other should be possible by cherry picking the respective commits as there are no differences in the code (yet). Make sure to adjust the version number to the respective branch when porting a change.

🚀 Release Management

A release denotes that an artifact for the associated commit is available for consumption. Our Jenkins CI/CD pipeline automatically builds and publishes releases for the main master branch and release branches prefixed with release/v{{major-version}}.x. The artifact is published to our Artifactory under the version specified in build.gradle.

⚠ Note: Whether an artifact should be published as release or snapshot is determined by whether or not there is a -SNAPSHOT in the version. Publishing will fail in case publishing the same non-snapshot version is attempted again.

The exact build steps for this library are defined in the Jenkinsfile.

🗄 Snapshots ▪ Releases

🚧 TODO: how to consume TeraNUI from the Terasology Artifactory (e.g., gradle dependency snippet)

Release Process

As releases are automatically triggered from master and release/v{{major-version}}.x the required steps to make a non-snapshot release for any version is as follows:

1. Decide on release version ▪ Which branch to publish, under which version?

   The version number MUST be a higher SemVer than the current version of the branch to release. The version bump SHOULD follow SemVer specifications, e.g., increase the major version for breaking changes, or do a patch release for bug fixes.

2. Make the release commit ▪ Trigger a release via Jenkins

   Update the version in build.gradle and remove the -SNAPSHOT suffix. Commit the change with the following message:

   release: version {{version}}

   Until we have automatic tagging or a tag-based release process it is recommended to manually create and push an annotated tag for the respective version on master. For a library release v1.2.3 the tag process is:

   git tag -a v1.2.3 -m "Release version 1.2.3"
   git push --tags

3. Prepare for next release ▪ Bump to next snapshot version

   Finally, we have to increase the version number to be able to get pre-release -SNAPSHOT builds for subsequent commits. Therefore, the version number MUST be a higher SemVer than the version just released. This will typically be a minor version bump. To do this, just update the version in build.gradle and commit the change with the following message:

   chore: prepare next snapshot for {{version}}

💚 We try to keep v1 and v2 in sync, thus this relase process should usually be executed for both branches, respectively.

License

This library is licensed under the Apache 2.0 License.