jMonkeyEngine Native Image Gradle Plugin

The org.jmonkeyengine.nativeimage plugin generates GraalVM Native Image reachability metadata for jMonkeyEngine applications and prepares the native runtime library layout used by native-image executables.

Use it together with the official GraalVM Build Tools plugin:

plugins {
    id 'application'
    id 'org.graalvm.buildtools.native' version '1.1.0'
    id 'org.jmonkeyengine.nativeimage'
}

application {
    mainClass = 'com.example.MyGame'
}

graalvmNative {
    binaries {
        named('main') {
            imageName = 'my-game'
            mainClass = 'com.example.MyGame'
        }
    }
}

jmeNativeImage {
    useDefaultResourceSettings()
}

Build the native executable with:

./gradlew nativeCompile

Reflection Metadata

The plugin automatically preserves common jME runtime types, such as Savable, AssetLoader, Control, Filter, networking serializers, and other engine extension points.

For application classes, use the jmeNativeImage DSL:

jmeNativeImage {
    targetType 'com.example.MyNiftyController'
    targetType 'com.example.MyCustomAssetLoader'
}

targetType accepts either a concrete class or a type used as a match target. If the configured type is an interface or superclass, the generator preserves matching classes found on the scan classpath.

You can also preserve all classes marked with an annotation:

jmeNativeImage {
    targetAnnotation 'com.example.ReflectiveEntryPoint'
}

jME also provides a built-in annotation for this:

import com.jme3.util.PreserveReflection;

@PreserveReflection
public class MyNiftyController {
    public void startGame() {
    }
}

Classes annotated with @PreserveReflection are included by default when this plugin generates metadata. They are also marked as unsafe-allocatable by default. Disable that when a reflected type must always be constructed normally:

@PreserveReflection(allowUnsafeAllocation = false)
public class ConstructorOnlyEntryPoint {
}

Default Resource Settings

jmeNativeImage {
    useDefaultResourceSettings()
}

adds broad default GraalVM resource settings, compatible with typical jME applications.

You can override those defaults through the DSL:

jmeNativeImage {
    includeResources 'Interface/.*|Textures/.*|Models/.*'
    excludeResources '(?i).*\\.(class|jar|dylib|so|dll|jnilib)$'
}

Runtime Initialization

Add application-specific classes or packages you want to be initialized at runtime instead of build time:

jmeNativeImage {
    runtimeInitialize 'com.example.RuntimeState'
    runtimeInitialize 'com.example.runtime'
}

Advanced Usage

The following additional options are available, but most applications should not need them. The plugin already scans the main source set resources, preserves common jME extension points, and supports @PreserveReflection for application classes.

Resource Globs

A resource glob is an optional path pattern for extra files that should be included as resources in the generated native image metadata.

It is not a Java class name. It is a resource path inside your application or dependency jars, using / separators.

You usually do not need to configure resource globs for ordinary files under the project's src/main/resources: the plugin scans the main source set resources and writes metadata for them automatically.

Use resourceGlob when a resource is outside the normal main resources scan, comes from a dependency, is generated by a separate task, or needs to be added as a broader pattern instead of as a discovered concrete file.

Examples of optional extra resource globs:

jmeNativeImage {
    resourceGlob 'Interface/**'
    resourceGlob 'Textures/**'
    resourceGlob 'Models/**/*.j3o'
    resourceGlob 'com/example/external-runtime-config.properties'
}

Unsafe Allocation

The plugin automatically detects direct construction of known unsafe allocation container types, such as SafeArrayList(SomeType.class), in compiled classes and adds unsafe allocation metadata for the corresponding SomeType[] array storage. By default, the container list contains com.jme3.util.SafeArrayList.

You can also add explicit unsafe allocation entries:

jmeNativeImage {
    unsafeAllocatedType 'org.example.Foo'
    unsafeAllocatedType 'org.example.Bar[]'
    unsafeAllocatedType '[Lorg.example.Baz;'
}

If a project has another container type with the same Class-first constructor pattern, add it to the detector:

jmeNativeImage {
    unsafeAllocationContainerType 'org.example.MyArrayStore'
}

Proxy Interfaces

If your application uses dynamic proxies, configure the interface set:

jmeNativeImage {
    proxyInterfaceSet([
        'com.example.Service',
        'com.example.ServiceEvents'
    ])
}

Each proxyInterfaceSet entry represents one proxy definition containing the interfaces implemented by that proxy.