stephengold / heart Goto Github PK

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

It contains 3 sub-projects:

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.

• 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

• 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
  • Cone, DomeMesh, Icosphere, Octasphere, and Prism 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

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.

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

repositories {
    mavenCentral()
}
dependencies {
    implementation 'com.github.stephengold:Heart:9.0.0'
}

For some older versions of Gradle, it's necessary to replace implementation with compile.

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.0.0</version>
</dependency>

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.0.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.0.0-javadoc.jar" file.
• Click on the "Open" button.
• Click on the "Browse..." button to the right of "Sources:"
• Select the "Heart-9.0.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

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.0.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

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

Package names begin with jme3utilities.

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

Jump to the table of contents

(This section is under construction.)

Applications have been created to test and demonstrate certain features of Heart. The following apps are found in the HeartExamples sub-project:

This app demonstrates conversion of a triangle mesh to a line mesh.

Jump to the table of contents

• the Heart page in the JmonkeyEngine Library

Jump to the table of contents

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 sub-project of the Jme3-utilities Project.

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

Jump to the table of contents

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: [email protected]

Jump to the table of contents