OreOverlay

OreOverlay is a Fabric 1.21.11 client-only mod that renders translucent ore markers in-world from cached data.

The renderer still works from a local in-memory marker list. The new search flow only replaces how that list gets filled:

• manual import into ores.json
• in-game search UI that rewrites ores.json
• hidden/mined marker tracking in a separate state file
• reload without rebuilding the mod

The mod stays client-only. It does not talk to Minecraft servers, and it does not depend on any external ore website or helper process at runtime.

Features

• Client-only translucent ore overlay
• Per-ore colors
• Dimension filtering
• Chunk-grouped marker storage
• Max render distance culling (96 blocks in v1)
• O overlay toggle
• R reload ores.json
• G open the in-game ore search screen
• Search-state persistence
• Query-result cache under the config folder
• Hidden-marker persistence separate from imported/search result data

Runtime Files

Packaged Minecraft client:

• %APPDATA%\\.minecraft\\config\\oreoverlay\\ores.json
• %APPDATA%\\.minecraft\\config\\oreoverlay\\hidden-markers.json
• %APPDATA%\\.minecraft\\config\\oreoverlay\\search-state.json
• %APPDATA%\\.minecraft\\config\\oreoverlay\\query-cache\\

This repo's VS Code dev launch:

• run/config/oreoverlay/ores.json
• run/config/oreoverlay/hidden-markers.json
• run/config/oreoverlay/search-state.json
• run/config/oreoverlay/query-cache/

Controls

• O: toggle overlay
• R: reload ores.json
• G: open the in-game search screen

Reload success and failure are shown as client chat messages.

In-Game Search

Press G in-game to open the search screen.

The screen uses:

• seed text input
• ore selector
• cluster filter: All, Medium+, Big only
• the current player position as the search origin

Buttons:

• Fetch
• Reload
• Clear Results
• Reset Hidden
• Clear Cache
• Paste Seed when available in an OP-enabled local world

Current scope

The in-game search is intentionally limited in v1:

• Java Edition logic only
• 1.21.11 only
• overworld only
• single ore per fetch

Ancient debris remains supported for manual JSON import, but not for the in-game search screen because that search path is overworld-only in this first pass.

Local Exact Search

The in-game search is local and exact-only:

• it boots a local headless 1.21.11 overworld generation path in-process
• it generates fresh chunks for the requested seed
• it scans ore blocks
• it clusters neighboring ore blocks with 26-neighbor adjacency
• it never calls an external site or Python script

Exactness limits

The exact mode is only intended to be exact for:

• vanilla Minecraft Java Edition
• the correct seed
• fresh chunks first generated in 1.21.11
• the default normal world preset
• structures enabled
• bonus chest disabled
• the overworld

It is not claimed to be exact for:

• chunks generated in older versions first
• custom presets
• modded world generation
• datapacks that alter generation
• nether/end searches

Fetch output

A successful fetch:

1. writes a new ores.json
2. writes a per-query cached result under query-cache
3. rebuilds the in-memory marker store
4. shows a small client message with the marker count

The temporary runtime world used by the exact search path is deleted after each search. The cache keeps the normalized result JSON, not the generated world data.

Manual JSON Import

ores.json uses this shape:

{
  "dimension": "minecraft:overworld",
  "source": "manual",
  "seed": "123456789",
  "version": "1.21.11",
  "ores": [
    { "x": 100, "y": -54, "z": 100, "type": "diamond" },
    { "x": 104, "y": -53, "z": 101, "type": "diamond", "distance": 12.0, "clusterSize": 5 },
    { "x": 130, "y": -20, "z": 90, "type": "redstone" }
  ]
}

Supported ore ids in imported JSON:

• diamond
• redstone
• gold
• iron
• emerald
• lapis
• coal
• copper
• ancient_debris

Optional marker fields:

• distance
• clusterSize
• metadata

The loader is intentionally strict. Unknown fields, malformed coordinates, invalid ore ids, or malformed JSON fail reload and keep the previous valid in-memory dataset.

ores.json is treated as the current imported/generated result snapshot. When you mine a marked block, OreOverlay now stores that hidden state in hidden-markers.json instead of mutating ores.json. Hidden-marker state follows the current seed/dimension/version rather than a specific provider mode.

Windows + VS Code Run Instructions

1. Install a Windows JDK 21.
2. Open the repository in VS Code.
3. Make sure the VS Code Java extension is using that JDK.
4. Open Run and Debug.
5. Launch Minecraft Client using launch.json.
6. Join an overworld world.
7. Press G to open the search screen.
8. Enter the seed, choose an ore and cluster filter, and press Fetch.
9. Use Paste Seed in singleplayer if the button is enabled.
10. Use O to hide/show the overlay and R to reload the current ores.json snapshot manually.
11. Use Reset Hidden to restore boxes you already mined from view state.
12. Use Clear Query Cache if you want to drop cached search results.

If you want to skip the in-game search and import data manually, write to:

• run/config/oreoverlay/ores.json for the VS Code dev launch
• %APPDATA%\.minecraft\config\oreoverlay\ores.json for a normal Minecraft install

Notes

• The renderer no longer depends on hardcoded test boxes.
• The current renderer still only reads loaded markers; search/import logic stays separate.
• ores.json remains the active result snapshot, but mined-marker visibility is tracked separately in hidden-markers.json.
• Query cache entries can be safely deleted from the UI.
• The in-game search currently omits ancient debris because the v1 search path is overworld-only.
• The in-game search is fully local and does not depend on external services.