English | 日本語

JUEParse

JUEParse is an independent Kotlin/JVM library and CLI for reading Unreal Engine 4 and 5 cooked archives and metadata. It is not a Java wrapper around CUE4Parse: production parsing is implemented in Kotlin and runs without a .NET runtime, C# sidecar, or external parser process.

The current public alpha is v0.1.0-alpha.2. Maven coordinates are defined but are not yet published to Maven Central. Check the measured compatibility results before relying on a format or game build.

JUEParse does not bundle or download AES keys, mappings, Oodle binaries, game files, or credentials. It is not an official Epic Games, Fortnite, Riot Games, VALORANT, or CUE4Parse project.

Capabilities

• bounded loose-file, Pak, IoStore, legacy-package, and UE5 Zen package readers;
• Zlib, Gzip, LZ4, and Zstandard, plus an optional caller-supplied Oodle adapter;
• USMAP, unversioned and tagged properties, Generic UObject exports, and canonical JSON;
• selected texture and audio conversions; and
• a scriptable CLI for listing, inspection, package/object decoding, export, and offline comparison.

Unsupported versions and native serializers remain explicit partial or raw results instead of guessed data.

Install and use

Java 21 or newer is required. The library, sources, Javadoc, Oodle adapter, and CLI archives are attached to each release, with a SHA256SUMS file to check them against. Downloading those is the shortest path.

Because alpha.2 is not on Maven Central, resolving the coordinates below instead needs the three public artifacts built and staged in this checkout:

./gradlew :jueparse:publishMavenJavaPublicationToLocalStagingRepository \
  :jueparse-oodle:publishMavenJavaPublicationToLocalStagingRepository \
  :jueparse-cli:publishMavenJavaPublicationToLocalStagingRepository

Then add build/staging-deploy as a Maven repository and use these fixed coordinates:

dependencies {
    implementation("io.github.fnjpnews:jueparse:0.1.0-alpha.2")
    implementation("io.github.fnjpnews:jueparse-oodle:0.1.0-alpha.2")
    implementation("io.github.fnjpnews:jueparse-cli:0.1.0-alpha.2")
}

A minimal Kotlin provider setup is:

JueFileProvider.open(gameDirectory, FortniteGameProfile(EngineVersion.UE5_7)).use { provider ->
    provider.registerDefaultAesKey(aesKey) // supplied by the caller
    provider.registerMappings(usmapPath)  // supplied by the caller
    provider.initialize()
    println(JueJson.prettyPrint(provider.loadPackage("/Game/Example")))
}

The same lifecycle is available from Java:

try (JueFileProvider provider =
        JueFileProvider.open(gameDirectory, new FortniteGameProfile(EngineVersion.UE5_7))) {
    provider.registerDefaultAesKey(aesKey); // supplied by the caller
    provider.registerMappings(usmapPath);  // supplied by the caller
    provider.initialize();
    System.out.println(JueJson.prettyPrint(provider.loadPackage("/Game/Example")));
}

Runnable Kotlin and Java consumers show profile selection, mappings, optional codecs, package loading, and JSON output. They are verified against the locally staged artifacts with ./gradlew consumerExamplesTest --no-problems-report.

AES keys and mappings must be obtained and passed by the caller. If a container uses Oodle, the caller must also provide an authorized, trusted native Oodle library; JUEParse does not redistribute one.

CLI

Build the distribution and use the generated launcher:

./gradlew :jueparse-cli:installDist
modules/cli/build/install/jueparse-cli/bin/jueparse --version
modules/cli/build/install/jueparse-cli/bin/jueparse \
  --profile fortnite \
  --engine-version UE5_7 \
  --aes-key-file /secure/local/keys.txt \
  --mappings /secure/local/mappings.usmap \
  scan /authorized/CookedContent

On Windows, use gradlew.bat and modules\cli\build\install\jueparse-cli\bin\jueparse.bat. Keep secrets out of shell history where possible; --aes-key-file and --aes-key-map accept local caller-controlled files.

Validation and limitations

A deterministic local Fortnite 41.20 corpus of 50 packages was measured with caller-supplied inputs: 50 packages parsed with 0 package failures, 598 exports discovered, 566 Generic UObjects decoded, and 32 raw exports retained. The isolated CUE4Parse differential oracle is test-only; production JUEParse neither invokes nor depends on it. Full measurements and categories are in compatibility.md.

Container and schema reading is additionally checked against CUE4Parse on generated fixtures, comparing extracted bytes rather than metadata: Pak legacy and path-hash indexes, IoStore containers, and USMAP schemas, each in plaintext and AES-encrypted form where the format allows one. That comparison needs no game files, keys, or mappings, so anyone can reproduce it with ./gradlew referenceTest.

Known limitations include incomplete Pak and IoStore version coverage, remaining schema-index and native-serializer gaps, partial bulk texture/audio/mesh handling, and 23 partial differential objects in the measured corpus. VALORANT support is not currently measured. These results apply only to the stated inputs and are not blanket compatibility claims.

Build and test

Use the checked-in Gradle wrapper:

./gradlew clean build spotlessCheck releaseAudit --no-problems-report
./gradlew referenceTest --no-problems-report

The public reference test needs the CUE4Parse revision pinned by reference-lock.json checked out at .reference/CUE4Parse. Real-game tests are opt-in and require private caller-supplied inputs.

Project structure

Path	Role
modules/core/	Core Kotlin/JVM parser and public API
modules/cli/	Command-line application
modules/oodle/	Optional adapter for caller-supplied Oodle libraries
tooling/oracle/	Test-only CUE4Parse differential oracle
tooling/benchmarks/	JMH performance benchmarks
tooling/release-audit/	Repository and publication safety checks
examples/	Runnable Java and Kotlin examples

The logical Gradle projects and public coordinates remain :jueparse, :jueparse-cli, and :jueparse-oodle; the directory layout does not change package names or artifact IDs. Oracle and benchmarks are never publication candidates.

Implementation map

Stage	Main implementation
Provider and VFS	JueFileProvider, vfs
Pak	PakArchive
IoStore and Package Store	iostore
Legacy and Zen packages	packageformat
USMAP	mappings
UObject and properties	assets
Profiles	game
Canonical JSON	json
CLI	Main.kt

Contributing and security

See Contributing for fixtures, tests, benchmarks, support, and release checks, and follow the Code of Conduct. Use GitHub Issues for reproducible bugs and scoped features. Report vulnerabilities using the Security policy.

Treat cooked files as untrusted input. Do not upload game files, keys, mappings, native libraries, credentials, reports containing private paths, or proprietary decoded values.

License and provenance

JUEParse is licensed under Apache License 2.0. See LICENSE, NOTICE, THIRD_PARTY_NOTICES.md, and the source methodology.