We took the 'Java' out of Minecraft Java Edition. Same mods. Same worlds. Different FPS.
Rewrite Minecraft Java Edition's performance-critical cores — world generation (and eventually entity AI / pathfinding) — in native code, while keeping the full Java mod ecosystem intact. Same seed. Same world. Same mods. The native core goes underneath.
Why: Java Edition's performance has been a meme for two decades. Every existing fix has a fatal flaw:
| Approach | Flaw |
|---|---|
| Paper & optimization plugins | Still Java — treats symptoms, not causes |
| Cuberite (full C++ rewrite) | Fast, but the mod ecosystem dies |
| Switch to Bedrock | Ecosystem gone, version drift forever |
CoreSwap walks the path nobody has walked: native performance core + Java mod layer (JNI bridge) — the mod API stays Java and untouched; everything below it is free to go native.
The worldgen core has migrated from C++ to Rust. One worldgen.dll now ships everything — the JNI bridge (Java_wg_CppWorldgen_*) and the engine (wg_* C ABI) in a single Rust cdylib. The C++ line is archived (historical reference only); all active development happens in WorldgenRust/.
Why Rust: one language for bridge + engine (no second toolchain), memory safety in a hot multi-threaded path, and a build-time density-function transpiler (vanilla JSON → specialized native code) that doubles as a correctness oracle — the transpiled pipeline is proven equivalent to the runtime interpreter to floating-point residual (<5e-7), catching semantic bugs invisible to production sampling.
- ✅ Overworld fully native: density → aquifer → ore veins → surface rules → carvers → features. End-to-end save-path block match ≈ 99.0% vs vanilla (3-sample avg 99.01%, large-region sweeps; residual is an isolated floating-point edge band around the density zero-crossing, not terrain structure); density fields aligned to floating-point residual (<5e-7). Verified in-game (server + client)
- ✅ Nether fully native: end-to-end block match 99.9992% (two 4×4 regions, 16 mismatched blocks total, all traced to a closed density-edge mechanism); extreme coordinates verified (±30M corners, 98.85–99.85%)
- ✅ Worldgen performance — faster than vanilla Java: large-sample end-to-end benchmark (256 chunks, fresh world, stable medians) puts the Rust pipeline at ~28 ms/chunk vs vanilla Java's ~32–33 ms/chunk — and after the aquifer-estimation rewrite (-63.5% on that stage) real-world chunk loading is player-verified noticeably faster than vanilla, on top of full parallelism (adaptive worker pool, shared-column caches). No approximation anywhere — all gains are lossless
- ✅ Self-contained jar: the mod jar bundles the complete worldgen dataset (849 files) + the native dll — drop it into
mods/, no configuration, no external data folder; extraction is version-hashed and self-updating - ✅ Startup safety net: every noise sampler the surface engine can query is validated against the preload table at startup — a missing key fails fast at boot with an exact diagnostic instead of crashing mid-gameplay in a rare biome
- ✅ Dual loader support — Fabric + Forge: one jar for both. Fabric native; Forge via Sinytra Connector (400+ modpacks tested there)
- ✅ Pairs with Sodium/Iris: Sodium owns rendering (FPS), CoreSwap owns generation (chunk loading) — complementary, no conflict
- 📦 Download: Releases —
1.0.23 - 🔭 Roadmap: End engine, LIGHT stage, entity AI (Brain / Goal / Pathfinding) in Rust
- Minecraft 1.20.1 (Java Edition)
- Fabric Loader 0.15.x — if you don't have Fabric yet, install it with the Fabric installer (select MC 1.20.1, click Install)
- Java 17 — Fabric Loader 0.15 requires Java 17+
- Download the latest
coreswap-1.20.1-*.jarfrom Releases - Install Fabric (skip if already installed): run the Fabric installer, pick Minecraft 1.20.1, Install. It creates a "fabric-loader-…" profile in the launcher
- Open the mods folder: in the Fabric launcher profile click Open Mods Folder, or navigate manually to:
- Windows:
%appdata%\.minecraft\mods - macOS:
~/Library/Application Support/minecraft/mods - Linux:
~/.minecraft/mods
- Windows:
- Drop the CoreSwap jar into
mods/— done - (Recommended) Add Sodium + Iris (from Modrinth) — Sodium owns rendering (FPS), CoreSwap owns generation (chunk loading) — they complement each other, no conflict.
- Launch the Fabric profile. Verify it's active in
logs/latest.log:[BenchMod] CoreSwap replace mode: C++ worldgen active [CppBridge] init seed=... enabled=true [CppBridge] initNether seed=... enabled=true
- Server: works on dedicated Fabric servers too — put the same jar in the server's
mods/folder - Forge: supported via Sinytra Connector
- The log line still says "C++ worldgen" for historical reasons — since 1.0.19 the native core is Rust
- Overworld + Nether are engine-generated; other dimensions fall through to vanilla (End is protected from misrouting)
The repo is organized by Minecraft Java version number. Each version lives in its own directory:
CoreSwap/
├── README.md
├── WorldgenRust/ # ← the Rust worldgen core (active)
│ ├── src/ # engine: density / aquifer / surface / carver / features / JNI bridge
│ ├── build/ # build-time transpiler (vanilla JSON → native code)
│ └── rust-dll/ # legacy artifacts (unused)
└── versions/
├── 1.20.1/ # ← current
│ ├── cpp/ # archived C++ core (historical reference)
│ ├── data/ # worldgen JSON + reference block data (for verification)
│ └── docs/ # engineering knowledge base (01-11 topic docs)
└── <future versions>/
The Fabric mod project lives in runtime/1.20.1/java (fabric-loom). Its build syncs the freshly compiled Rust dll into the mod jar automatically.
Toolchain (Windows x64):
- Rust (stable,
cargo) — builds the native core - JDK 17 — JNI headers + Fabric/loom builds
- Gradle 8.x — mod packaging (fabric-loom 1.10)
:: 1. build the Rust core (emits WorldgenRust.dll; also regenerates the
:: transpiled density code from vanilla JSON via build.rs)
cd WorldgenRust
cargo build --release
:: 2. build the Fabric mod (syncs the dll into the jar automatically)
cd ..\runtime\1.20.1\java
gradle build
:: jar lands in build\libs\coreswap-1.20.1-*.jarThe transpiler inside build.rs reads versions/1.20.1/data/worldgen (vanilla's worldgen JSON tree) at build time. Verification probes (WorldgenRust/src/bin/*) additionally need blocks.json + reference .blocks dumps — exported from a vanilla 1.20.1 server; intentionally kept out of the repo.
The Rust core reconstructs the density field following vanilla's exact semantics:
- Noise primitives: Xoroshiro128PlusPlus RNG, MD5-based seed derivation, Perlin / octave / double-perlin samplers — matching Mojang's implementation
- Density function tree: loaded at runtime from vanilla's
worldgenJSON (noise_settings/<dim>.json+density_function/<dim>/*.json), mirroringNoiseConfig's visitor semantics — data-driven, no per-dimension code (multi-world ready) - Build-time transpiler (
build.rs): compiles the same JSON into specialized native functions (splines inlined, caches resolved, CSE'd) — a second, independent evaluation path used as a correctness oracle and wired into production behind an env gate - Block pipeline: density → aquifer → ore veins → surface rules → carvers → features, mirroring vanilla stage semantics (including dual noise/world heights for the Nether)
- ✅ JNI bridge: bulk chunk data exchange (now in Rust)
- ✅ Block layer: density → block states (surface rules + chunk fill)
- ✅ Integration: installable Fabric mod / server plugin
- ✅ Multi-world: Nether engine + in-game dimension dispatch (End next)
- ✅ Nether polish: conversion-surface drift, basalt/blackstone conversion bands and lava-ocean interface closed (99.9992% end-to-end)
- Entity AI / pathfinding: second core to nativify
- dustinmoon78 — Forge + Sinytra Connector compatibility: multi-level mod jar resolution (
CoreSwapFixHelper) + directJarFileextraction, tested on 400+ mod packs. See #3.
MIT