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. With TeraNUI v3 we can support both versions of gestalt in a single release (v5 and v7, respectively).

We keep release branches for TeraNUI's major versions. Note that new features will only be implemented for the latest version on master. The following table shows release branches and known projects using them.

Branch	Version	gestalt	Projects
master	v3.x	*	Terasology 4.4+, DestinationSol
release/v2.x	v2.x	v7	DestinationSol
release/v1.x	v1.x	v5	Terasology prior to 4.4.0

We may port back changes made to the main line of the code to release branches by cherry picking them to the respective branches.

In addition to release branches we may prepare preview branches for upcoming and/or experimental features. Only -SNAPSHOT versions may be released from preview branches. It is the responsibility of the preview branch maintainers to keep the preview branches up-to-date with main development.

Branch	Version	gestalt	Projects
preview/v4.x	v4.x-SNAPSHOT	*	DestinationSol experimental branch

🚀 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

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 and push it:

   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, commit the change with the following message and push it:

   chore: prepare next snapshot for {{version}}

License

This library is licensed under the Apache 2.0 License.