Chunkscope

A fast, local, open-source seed map and seed finder for Minecraft: Java Edition, written in Rust. Think of an offline tool that shows biomes, structures and slime chunks for any seed, and can search millions of seeds for the features you care about.

Status: early. Biomes in the Overworld, the Nether and the End already match the game: the random number generators, seed handling, noise, climate sampling and biome lookup are all verified against the real JDK and the real game classes. Structure positions match too: where each structure set attempts to generate, and the biome and terrain checks that decide whether a structure really generates there (every structure in the three dimensions, mineshafts included).

Target: Minecraft 26.3 (Java 25).

Slime chunks, zoomed in	Strongholds, zoomed out

Goals

• Bit-exact parity with Java Edition. If the tool says there is a village at a position, there is one in the game. Every piece of logic is tested against an oracle (see docs/PARITY.md).
• Local and fast. No server, no uploads. Multi-threaded seed search.
• Pure Rust. No C dependencies.

Bedrock Edition is out of scope for now.

Workspace

Crate	Purpose
crates/java-compat	Bit-exact ports of the JDK behaviour Minecraft relies on: java.util.Random, StrictMath.log, Math.round, DoubleStream.sum, String.hashCode, String.trim, Long.parseLong
crates/mc-core	Minecraft logic: random sources (Xoroshiro, legacy, worldgen), noise (Perlin, normal noise, all vanilla noise parameters), overworld climate and biomes, overworld terrain (final_density, aquifers, heightmaps), structure placement, seed text → world seed, slime chunks
crates/chunkscope-app	The desktop app (chunkscope): an interactive biome and structure map, native Rust with egui
parity/oracle	JDK oracle: reference fixtures from a real JDK
parity/game-oracle	Game oracle: reference fixtures from the real game classes (downloads the official server jar)

Roadmap

• java.util.Random (including nextGaussian via an fdlibm port)
• Seed text parsing exactly as the game does it
• Slime chunks
• Xoroshiro128++, RandomSupport seeding and positional random factories
• WorldgenRandom decoration / feature / structure seeding
• Perlin noise and normal (double-Perlin) noise, with all vanilla noise parameters
• Smeared Perlin, blended and simplex noise (terrain, End islands)
• Overworld biomes (climate sampling, terrain offset spline, biome R-tree)
• Nether: biomes, terrain, fortresses, bastions, fossils; ruined portals in both dimensions (0.4)
• End: biomes, islands, end cities (0.5), and whether each end city has a ship (0.5.1)
• Mineshafts, no "possible" markers left, saved settings (0.6)
• Large-scale verification against the game (0.7)
• Stable command line and formats, signed builds (0.8)
• Large biomes and amplified presets
• Structure placement: candidate chunks, frequency rolls, exclusion zones (all vanilla structure sets)
• Strongholds (concentric rings with their biome search)
• Terrain height (needed to validate structures), in steps:
  • Volume-mode noise (NoiseStack.addToVolume)
  • Volume-mode density samplers, cell interpolation, smeared Perlin noise
  • Overworld final_density (the game's compiled sampler tree)
  • Aquifers
  • Heightmaps (getBaseHeight: WORLD_SURFACE_WG, OCEAN_FLOOR_WG) and base block columns
• Structure validation (biome and terrain height), every structure
• World spawn: the climate origin (exact) and the spawn block (estimate)
• Seed finder with filters (structures near the spawn, biome at the spawn), in the app and on the command line
• Map viewer GUI
  • Biome map (tiled, computed in parallel), structure layers, strongholds, slime chunks, grid, inspector
  • Structure markers validated by biome and terrain (0.2)
  • Release builds for Windows, macOS and Linux
  • Saved settings (0.6)
  • Signed builds

Download

Prebuilt binaries for Windows, macOS and Linux are on the releases page. Unpack the archive and run chunkscope (chunkscope.exe on Windows).

The binaries are not signed yet. On Windows, SmartScreen may ask for confirmation ("More info", then "Run anyway"). On macOS, remove the quarantine flag first: xattr -d com.apple.quarantine chunkscope.

Try it

The desktop app, from source:

cargo run --release -p chunkscope-app

Drag to pan, scroll to zoom, click a marker to select it, right-click the map to copy a position or a /tp command. The Finder tab searches seeds for structures near the spawn; click a result to open it on the map. Its query has a text form you can copy, paste or edit (the same the command line takes). Structures are checked against biome and terrain like the game does. The app remembers the seed, the view, the layers and the finder's query between runs. In the End, the void between the islands is drawn darker (the islands' shape comes from their density, so the edges are approximate). On Linux the app needs the usual X11 or Wayland libraries (for example libxkbcommon-x11-0 on X11).

Command-line examples:

cargo run --release -p mc-core --example biome -- <seed> <x> <z> [y]

cargo run --release -p mc-core --example structures -- <seed> <x> <z> [radius]

cargo run --release -p mc-core --example height -- <seed> <x> <z>

cargo run --release -p mc-core --example spawn -- <seed>

Search seeds: for example, a village within 300 blocks of the spawn and a pillager outpost within 500, among the first 100,000 seeds:

cargo run --release -p mc-core --example find -- --count 100000 villages:300 pillager_outposts:500

The query is the same text the app's finder shows:

• <structure>:<radius>[:<count>]: at least count (default 1) structures within radius blocks. Structures are named by layer id: villages, pillager_outposts, fortresses, bastions, end_cities... (an unknown name lists them all). Nether and End structures are measured from 0, 0 in their dimension.
• end_cities+ship:<radius>: only end cities with a ship (an elytra).
• center=spawn (default) or center=zero: where distances are measured from.
• biome=<biome>,...: the biome at the center, for example biome=plains,meadow.

Each match prints on one line, the same line the app's "copy all results" button copies.

Development

cargo test

To regenerate the reference fixtures (requires JDK 25):

java parity/oracle/Oracle.java

parity/game-oracle/run.sh

The large-scale check runs the real game on many random seeds and compares everything (biomes, heights, structures, end city ships, spawn, strongholds) in every dimension; it is too slow for every pull request and runs weekly and before each release:

parity/game-oracle/wide.sh 200

Versioning

Chunkscope uses semantic versioning, independent of Minecraft's version numbers. The game version a release matches is shown in the app and in the release notes.

• 0.x: the parity promise is not complete yet. Each minor version is a milestone: 0.1 the map viewer, 0.2 structures validated by biome and terrain, 0.3 world spawn and the seed finder, 0.4 the Nether and ruined portals, 0.5 the End, 0.6 mineshafts and saved settings, 0.7 large-scale verification, 0.8 a stable command line and formats, and signed builds. The full plan is in docs/ROADMAP.md.
• 1.0 comes when everything Chunkscope shows for the Overworld, the Nether and the End matches the game bit for bit and is verified by oracle tests: biomes, every structure (mineshafts and ruined portals included, with no "possible" markers left), strongholds, slime chunks, and the world spawn as far as the game itself is deterministic. The large-scale cross-check must be clean, settings are saved, the builds are signed, and the command line and saved formats are stable.
• After 1.0: patch versions fix bugs, minor versions add features or support for a new Minecraft version, and major versions break the command line or saved formats, or drop a Minecraft version.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

This project is not affiliated with Mojang Studios or Microsoft. "Minecraft" is a trademark of Mojang Synergies AB. No game code or assets are included.