search

stephengold / MonkeyWrench

A versatile library for loading 3-D assets into JMonkeyEngine (code has New BSD license)
Other
12 stars 0 forks source link
3d-models asset-loader assimp importer java jme3 jmonkeyengine jmonkeyengine3 jvm-library lwjgl3 open-source

readme

MonkeyWrench Project logo

The MonkeyWrench Project is developing a software library to load 3-D assets into JMonkeyEngine.

It contains 2 subprojects:

  1. lib: the MonkeyWrench JVM runtime library based on lwjgl-assimp
  2. apps: related applications, including examples and non-automated test software

MonkeyWrench attempts to load 3-D models and animations in a wide variety of formats, including:

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

Contents of this document

How to add MonkeyWrench to an existing project

MonkeyWrench comes pre-built as a single library that depends on:

(Since MonkeyWrench depends on LWJGL version 3 (jme3-lwjgl3), it isn't compatible with LWJGL version 2 (jme3-lwjgl), nor will it run on mobile platforms such as Android.)

Adding MonkeyWrench to an existing jMonkeyEngine project begins with ensuring that these libraries are on the classpath.

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

Gradle-built projects

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

repositories {
    mavenCentral()
}
dependencies {
    implementation("com.github.stephengold:MonkeyWrench:0.6.1")
}

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>MonkeyWrench</artifactId>
  <version>0.6.1</version>
</dependency>

Configuring the asset manager

The MonkeyWrench loader class is named LwjglAssetLoader.

Once the classpath is configured, the next step is to configure the application's AssetManager to use LwjglAssetLoader in place of its default loaders. In Java:

import com.github.stephengold.wrench.LwjglAssetLoader;
// ...
assetManager.registerLoader(LwjglAssetLoader.class,
        "3ds", "3mf", "blend", "bvh", "dae", "fbx", "glb", "gltf",
        "lwo", "meshxml", "mesh.xml", "obj", "ply", "stl");

Further considerations

Verbose logging

For more diagnostic information while loading assets, invoke loadModel() on an LwjglAssetKey with verbose logging enabled. In Java:

LwjglAssetKey key = new LwjglAssetKey("Models/m/m.mesh.xml");
key.setVerboseLogging(true);
Spatial m = assetManager.loadModel(key);

Choice of file format

If the asset to be loaded is available in multiple file formats, the best choice would be glTF version 2.0 (either .glb or .gltf format). For best results, convert assets in .blend or .fbx format to glTF before loading them using MonkeyWrench.

The next-best choice would be Collada (.dae) format.

The most efficient format for loading model assets into JMonkeyEngine is ".j3o". Best practice is to convert assets to .j3o at build time, not during gameplay.

Structure of loaded assets

An asset loaded using MonkeyWrench might be structured differently from the same asset loaded using jme3-core or jme3-plugins. In particular:

JMonkeyEngine applications should minimize their assumptions about asset structure.

Finding external textures

Many 3-D models rely on textures stored in separate files and referenced by name. If the files get moved around or converted to different formats, the filenames stored in the main asset may become outdated. Even though the textures are available, the asset manager doesn't find them, so it replaces them with placeholders.

To address this issue, MonkeyWrench embeds a configurable TextureLoader in each LwjglAssetKey. The TextureLoader manipulates texture filenames to help MonkeyWrench find textures.

A TextureLoader consists of 2 parts:

Before the preliminary transformation is applied, the texture filename is URL encoded (converting each blank to "%20", for instance).

The preliminary transformation is either:

After the preliminary transformation is applied, the filename is split into 2 parts:

Finally, the TextureLoader attempts to load the texture using the filenames generated by each format string in its search path.

In this context, format strings have the following semantics:

For example, if the main asset was loaded using

TextureLoader textureLoader
        = new TextureLoader(PathEdit.LastComponent,
                "%s%s%s",
                "%stextures/%s.JPG",
                "Textures/%2$s%3$s");
LwjglAssetKey key = new LwjglAssetKey("source/diorama.fbx", textureLoader);

and the stored filename is "C:\My Documents\UV_Barn_Assets.psd", then

MonkeyWrench will try the following filenames, in sequence:

  1. "source/UV_Barn_Assets.psd"
  2. "source/textures/UV_Barn_Assets.JPG"
  3. "Textures/UV_Barn_Assets.psd"

MonkeyWrench will generate a placeholder only if no texture is found at any of those filenames.

Jump to the table of contents

How to build MonkeyWrench 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 MonkeyWrench source code from GitHub:
    • using Git:
    • git clone https://github.com/stephengold/MonkeyWrench.git
    • cd MonkeyWrench
    • git checkout -b latest 0.6.1
    • 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 "lib/build/libs".

You can install the artifacts to your local Maven repository:

You can restore the project to a pristine state:

Jump to the table of contents

Related applications

The following desktop applications are found in the "apps" subproject:

ImportMixamo

A console application to import characters and animations from Mixamo, for use with JMonkeyEngine.

Before running it, download a single character (and any desired animations for that character) to the "downloads/Mixamo/dae/" directory.

All assets should be downloaded in Collada (.dae) format. Mixamo automatically archives each downloaded asset using "zip".

ImportMixamo expects each zip archive to contain a .dae file with the same name. If any downloaded assets get renamed (due to filename conflicts) you'll need to unzip them, rename the .dae files, and re-zip them. Other than that, it shouldn't be necessary to modify downloaded assets.

The character should be downloaded in "T-pose". Each animation should be downloaded "in place" (if possible) and without skin.

You can run the application from the command line:

Afterwards, the imported assets should be in the "apps/Written Assets" directory.

CompareLoaders

A graphical tool for comparing MonkeyWrench to the asset loaders built into JMonkeyEngine.

You can run it from the command line:

Test data

The first time CompareLoaders is run, the buildscript downloads about 230 MBytes of test data from maven.org . On subsequent runs, startup should go more quickly.

The application also looks for (optional) test data in "../ext/assimp-mdb/model-db" relative to the project root. These data (about 10 MBytes) can be installed using Bash and Git:

The application also looks for (optional) test data in "../ext/glTF-Sample-Assets" relative to the project root. These data (about 1.9 GBytes) can be installed using Bash and Git:

The application also looks for (optional) test data in "../ext/glTF-Sample-Models" relative to the project root. These data (about 3.7 GBytes) can be installed using Bash and Git:

You can also install (optional) test data (about 890 MBytes) from the Amazon Lumberyard:

Test status

The application opens a window and displays status using 8 lines of text in its upper left corner.

<img height="400" src="https://i.imgur.com/Xl1luE4.png" alt="Rectangular window with a light blue background showing 2 green-skinned humanoids, 3 axis arrows, and 8 lines of text (7 on the left and one on the right)">

At any given time, one text line is selected, indicated by a yellow arrow. Lines that can be selected are hereafter referred to as fields.

The status lines indicate:

User controls

The CompareLoaders application is designed for use with a keyboard and mouse.

The documentation below assumes a keyboard with the "US" (QWERTY) layout. On keyboards with other layouts, some keys may be labeled differently. Refer to the help overlay (F1) for localized key labels.

Selecting fields and values
Running tests
Controlling the camera (viewpoint)

To rotate the camera, drag with the left mouse button (LMB).

To zoom the camera, turn the scroll wheel.

Other useful keys

TestIssue5232

A console app to reproduce Assimp issue 5232.

TestIssue5253

A console app to reproduce Assimp issue 5253.

TestIssue5289

A console app to reproduce Assimp issue 5289.

TestIssue5303

A console app to test for Assimp issue 5303.

Jump to the table of contents

Acknowledgments

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

I am grateful to GitHub, Sonatype, 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