stephengold/Heart

A general-purpose add-on library for jMonkeyEngine (code has New BSD license)

The Heart Project provides a general-purpose add-on library for the jMonkeyEngine (JME) game engine.

It contains 3 subprojects:

1. HeartLibrary: the Heart JVM runtime library and its automated tests
2. HeartExamples: demos, examples, and non-automated test software
3. J3oDump: a command-line utility to dump J3O assets

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

Many other libraries depend on the Heart Library, including Acorus, jme3-wireframe, JmePower, Minie, MonkeyWrench, SkyControl, and Wes.

Contents of this document

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

Important features

• debugging aids:
  • Dumper to concisely dump a scene graph or a subtree thereof, or to dump appstates or viewports
  • Validate to validate arguments passed to a library method
  • AxesVisualizer to visualize the coordinate axes of a Node
  • BoundsVisualizer to visualize the world bounds of a Spatial
  • PointVisualizer to visualize a particular location in the world
  • SkeletonVisualizer to visualize the bones/joints of an animated model
  • VectorVisualizer to visualize a vector
  • MyAsset.createDebugMaterial() to visualize mesh normals with or without gamma correction
  • MyMesh.boneWeightMaterial() to visualize bone weights in a Mesh
• Mesh subclasses:
  • Dodecahedron, Icosahedron, Octahedron, and Tetrahedron to generate meshes for Platonic solids
  • CapsuleMesh, Cone, DomeMesh, Icosphere, LoopMesh, Octasphere, PointMesh, Prism, and RectangleOutlineMesh to generate familiar 3-D shapes
  • RectangleMesh to generate custom quads
  • DiscMesh and RoundedRectangle to generate eye-pleasing backgrounds for user-interface text
• MyMesh utilities to analyze and manipulate JMonkeyEngine meshes:
  • compress a Mesh by introducing an index buffer
  • expand a Mesh to ensure no vertex data are re-used
  • generate normals for an outward-facing sphere, a faceted mesh, or a smooth mesh
  • translate, rotate, or uniformly scale a Mesh
  • merge 2 meshes into one
  • flip mesh normals and/or triangle windings
  • subdivide all elements of a mesh
  • enumerate all vertices in a scene-graph subtree
  • convert mesh triangles to lines
• JME-oriented math:
  • generate pseudo-random quaternions and vectors
  • interpolate and cardinalize quaternions and vectors
  • other useful operations on scalars, quaternions, vectors, arrays, buffers, and sets of vectors
  • generate 2-D Perlin noise
• loaders for Properties and String assets
• ContrastAdjustmentFilter
• an AppState to manage ViewPort updating
• and much, much more!

Jump to the table of contents

How to add Heart to an existing project

Heart comes pre-built as a single library that depends on the standard "jme3-core" library from jMonkeyEngine. Adding Heart to an existing jMonkeyEngine project should be a simple matter of adding this library to the classpath.

For projects built using Maven or Gradle, it is sufficient to add a dependency on the Heart Library. The build tool should automatically resolve the remaining dependencies.

Gradle-built projects

Add to the project’s "build.gradle" file:

repositories {
    mavenCentral()
}
dependencies {
    implementation("com.github.stephengold:Heart:9.1.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>Heart</artifactId>
  <version>9.1.0</version>
</dependency>

Ant-built projects

For projects built using Ant, download the library from GitHub:

• https://github.com/stephengold/Heart/releases/latest

You'll definitely want the class jar 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:" select "Libraries".
4. Click on the "Compile" tab.
5. Add the Heart class jar:

• Click on the "Add JAR/Folder" button.
• Navigate to the download folder.
• Select the "Heart-9.1.0.jar" file.
• Click on the "Open" button.

6. (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-9.1.0-javadoc.jar" file.
• Click on the "Open" button.
• Click on the "Browse..." button to the right of "Sources:"
• Select the "Heart-9.1.0-sources.jar" file.
• Click on the "Open" button again.
• Click on the "OK" button to close the "Edit Jar Reference" dialog.

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

Jump to the table of contents

How to build Heart from source

1. Install a Java Development Kit (JDK), if you don't already have one.
2. 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 '

3. Download and extract the Heart source code from GitHub:

• using Git:
  • git clone https://github.com/stephengold/Heart.git
  • cd Heart
  • git checkout -b latest 9.1.0
• 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

4. 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 "HeartLibrary/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 v4.5.0) can be downloaded from GitHub.

Older releases (v0.9.5 through v4.4.0) can be downloaded from the Jme3-utilities Project.

Newer Maven artifacts (since v6.3.0) are available from MavenCentral.

Old Maven artifacts (v5.0.0 through v6.4.0) are available from JCenter.

Jump to the table of contents

Conventions

Package names begin with jme3utilities.

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 test and demonstrate certain features of Heart.

These can be run from the menu-driven AppChooser app:

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

You can also run specific apps from a command prompt:

• using Bash or Fish or PowerShell or Zsh: ./gradlew :HeartExamples:LoopMeshTest
• using Windows Command Prompt: .\gradlew :HeartExamples:LoopMeshTest

LoopMeshTest

This app demonstrates constructing a regular polygon using the LoopMesh class.

TestBoundsVisualizer

This app demonstrates visualizing the bounding volume of a geometry using a BoundsVisualizer.

Pressing the "B" key toggles the bounding volume between a sphere and an axis-aligned box.

TestContrast

This app demonstrates changing the contrast of a rendered scene using a ContrastAdjustmentFilter.

• Pressing the NUMPAD4 key reduces the exponent of the filter.
• Pressing the NUMPAD6 key increases the exponent.

TestGenerator

This app demonstrates generating pseudo-random vectors and rotations using a Generator.

TestMergeMeshes

This app demonstrates translating, indexing, and merging meshes using the MyMesh utility class.

TestMulticolor

This app demonstrates visualizing a mesh with vertex colors using the "multicolor.j3md" material definitions.

TestPas

This app demonstrates monitoring the maximum time per frame using a PerformanceAppState.

TestRotate

This app demonstrates rotation of mesh vertices using the MyMesh.rotate() utility method.

Pressing the Enter key rotates both meshes to a new, pseudo-randomly chosen orientation.

TestSkeletonVisualizer

This app demonstrates visualizing the skeleton of an animated model using SkeletonVisualizer.

Pressing the "." key toggles the animation between paused and running.

TestSolidMeshes

This app demonstrates procedurally generating meshes using the Cone, Dodecahedron, DomeMesh, Icosahedron, Icosphere, Octahedron, Octasphere, Prism, and Tetrahedron classes.

Pressing the "N" key cycles through 6 different test materials.

TestSubdivide

This app demonstration subdividing a mesh using the MyMesh.subdivideTriangles() utility method.

• Pressing the Tab key toggles between textured and wireframe materials.
• Pressing the NUMPAD4 key reduces the number of subdivisions.
• Pressing the NUMPAD6 key increases the number of subdivisions.

TestWireframe

This app demonstrates visualizing a mesh as a wireframe using the MyAsset.createWireframeMaterial() utility method.

TrianglesToLines

This app demonstrates converting a triangle mesh to a line mesh using the MyMesh.trianglesToLines() utility method.

Jump to the table of contents

External links

• the Heart page in the JmonkeyEngine Library

Jump to the table of contents

History

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

The oldest parts of the Heart Library were originally included in SkyControl.

From May 2017 to February 2020, Heart was a subproject of the Jme3-utilities Project.

Since February 2020, Heart has been a separate project, hosted at GitHub.

Jump to the table of contents

Acknowledgments

Like most projects, the Heart Project builds on the work of many who have gone before. I therefore acknowledge the following software developers:

• "jayfella", for creating and sharing the original Icosphere.java
• Paul Speed, for helpful insights
• "rvandoosselaer", for reporting and fixing issue #2.
• plus the creators of (and contributors to) the following software:
  • the Blender 3-D animation suite
  • the Checkstyle tool
  • the FindBugs source-code analyzer
  • the Firefox and Google Chrome web browsers
  • the Git revision-control system and GitK commit viewer
  • 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 PMD source-code analyzer
  • the WinMerge differencing and merging tool

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