orefinder-estimate 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 241ee2fe99c357eb6a52fe274ab907fb5ddf48379eee6bf0a7f572ca6b795a30
+  data.tar.gz: '095401a530362c9a0ac3c58d271a3886fe514db5a2554df68b89344abb8eba63'
+SHA512:
+  metadata.gz: 170e51a5dea283bfe8c1321cfd793436d5c8f04fc9cb7c17ef4ee1b08a60f073d730b7f02957f0c0bcb85334c0a06118bfcbb75cf44c106dce7e9acf3f2b5672
+  data.tar.gz: 8b79f27cee69fbf594702fc3f6f6fa3cf8a1bf2630c474cca13ae775601a2f0d44ad2f03bf483c31efa063263c0d16583854680425a8a4b9fd7a77bf0d9543a8

data/DISCLAIMER.md

@@ -0,0 +1,19 @@
+# About these estimates
+
+These packages give you a fast, offline **estimate** of where an ore is most
+likely to concentrate in Minecraft - the best mining Y level and the nearby
+areas worth digging - using published Y-level distribution ranges and
+statistical weighting.
+
+Think of it as a smart heads-up for planning your next mining trip: quick to
+run, no world load, no network calls, and easy to build on in your own projects.
+
+For pinpoint, seed-exact block coordinates (Java and Bedrock), pair it with the
+full tool at:
+
+**https://orefinder.io**
+
+As with any planning tool, treat the results as guidance and confirm important
+spots in-game. Minecraft, the Minecraft name, and associated assets are property
+of Mojang/Microsoft. These packages are an unofficial, fan-made utility and are
+not affiliated with or endorsed by Mojang.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ore Finder (https://orefinder.io)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,52 @@
+# orefinder-estimate (RubyGems)
+
+A fast, offline, dependency-free Minecraft ore **estimator** gem. Feed it a
+seed label, version, and player position; get likely ore coordinates and the
+best mining Y for Java or Bedrock.
+
+> Fast, offline estimates of the best mining Y and where an ore is likely to
+> concentrate. For pinpoint, seed-exact coordinates (Java & Bedrock), pair it with
+> **[Ore Finder](https://orefinder.io)**.
+
+## Install
+
+```bash
+gem install orefinder-estimate
+```
+
+## Ruby
+
+```ruby
+require 'orefinder_estimate'
+
+result = OrefinderEstimate.estimate(
+  'seed' => '42',
+  'version' => 'java_1_21',
+  'ore' => 'diamond',
+  'x' => 0, 'y' => 64, 'z' => 0,
+  'biome' => 'plains',
+  'searchRadius' => 220
+)
+
+puts result['metadata']['miningPeakY']
+p result['bestCluster'].first
+```
+
+## CLI
+
+```bash
+orefinder-estimate --version java_1_21 --ore diamond -x 0 -y 64 -z 0
+orefinder-estimate --ore ancient_debris --version java_1_21 --biome crimson_forest --json
+```
+
+## Supported ores
+
+diamond, iron, gold, coal, copper, emerald, redstone, lapis, ancient_debris
+(plus netherite aliases), nether_gold, nether_quartz, gilded_blackstone,
+blackstone.
+
+Deterministic and parity-tested against the sibling packages. No world-gen
+simulation, no structures, no network calls. Seed-accurate placement lives at
+[orefinder.io](https://orefinder.io).
+
+MIT (c) [Ore Finder](https://orefinder.io).

data/exe/orefinder-estimate

@@ -0,0 +1,104 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Ore Finder Estimate CLI. Approximate distribution estimate; NOT seed-accurate.
+# For exact, seed-based results use https://orefinder.io
+require 'json'
+
+begin
+  require 'orefinder_estimate'
+rescue LoadError
+  $LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+  require 'orefinder_estimate'
+end
+
+HELP = <<~TXT
+  orefinder-estimate - approximate Minecraft ore locator (offline)
+
+  USAGE:
+    orefinder-estimate --version <ver> --ore <ore> [options]
+
+  OPTIONS:
+    --seed <s>     World seed label. Default: 42
+    --version <v>  e.g. java_1_21, 1.20.1  (required)
+    --ore <o>      e.g. diamond, ancient_debris  (required)
+    -x -y -z <n>   Player position. Default: 0 64 0
+    --biome <b>    Biome bonus. Default: plains
+    --radius <n>   Search radius 32-512. Default: 220
+    --json         Print raw JSON
+    --ores         List supported ores
+    -h, --help     Show this help
+
+  Approximate estimate, not seed-accurate. For exact coords use https://orefinder.io
+TXT
+
+opts = {}
+flags = []
+i = 0
+while i < ARGV.length
+  a = ARGV[i]
+  case a
+  when '-h', '--help' then flags << 'help'
+  when '--json' then flags << 'json'
+  when '--ores' then flags << 'ores'
+  else
+    if a.start_with?('-') && i + 1 < ARGV.length
+      opts[a] = ARGV[i + 1]
+      i += 1
+    end
+  end
+  i += 1
+end
+
+if flags.include?('help') || ARGV.empty?
+  puts HELP
+  exit 0
+end
+if flags.include?('ores')
+  puts OrefinderEstimate::Data.known_ore_keys.sort.join("\n")
+  exit 0
+end
+
+version = opts['--version']
+ore = opts['--ore']
+if version.nil? || ore.nil?
+  warn 'Error: --version and --ore are required. Use --help.'
+  exit 2
+end
+
+res = OrefinderEstimate.estimate(
+  'seed' => opts['--seed'] || '42',
+  'version' => version,
+  'ore' => ore,
+  'x' => (opts['-x'] || '0').to_f,
+  'y' => (opts['-y'] || '64').to_f,
+  'z' => (opts['-z'] || '0').to_f,
+  'biome' => opts['--biome'] || 'plains',
+  'searchRadius' => (opts['--radius'] || '220').to_f
+)
+
+unless res['success']
+  warn "Error (#{res['error']}): #{res['message']}"
+  exit 1
+end
+
+if flags.include?('json')
+  puts JSON.pretty_generate(res)
+  exit 0
+end
+
+m = res['metadata']
+puts 'Ore Finder Estimate (approximate - verify at https://orefinder.io)'
+puts "#{m['ore']}  #{m['versionLabel']} [#{m['edition']}/#{m['era']}]  best Y ~ #{m['miningPeakY']}"
+puts "biome #{m['biomeEffective']} (x#{m['biomeEffect']})  dimension #{m['dimension']}"
+puts ''
+puts 'Best mining area:'
+res['bestCluster'].each do |p|
+  puts "  X #{p['x']}  Y #{p['y']}  Z #{p['z']}   #{p['distance']}m   #{p['probabilityPct']}%  (conf #{p['confidence']})"
+end
+res['secondaryClusters'].each_with_index do |group, gi|
+  puts "Nearby area #{gi + 1}:"
+  group.each do |p|
+    puts "  X #{p['x']}  Y #{p['y']}  Z #{p['z']}   #{p['distance']}m   #{p['probabilityPct']}%"
+  end
+end

data/lib/orefinder_estimate/cluster.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require_relative 'rng'
+require_relative 'probability'
+
+# Cluster-based coordinate generator (statistical, not chunk-exact). See ../../../SPEC.md section 6.
+module OrefinderEstimate
+  module Cluster
+    SECONDARY_XZ_MIN = 10
+    SECONDARY_XZ_MAX = 30
+    PRIMARY_XZ_MIN = 8
+    PRIMARY_XZ_MAX = 15
+    SECONDARY_Y_MAX = 3
+    PRIMARY_Y_MAX = 2
+
+    module_function
+
+    def num_str(v)
+      v == v.to_i ? v.to_i.to_s : v.to_s
+    end
+
+    def dist2(x1, z1, x2, z2)
+      dx = x1 - x2
+      dz = z1 - z2
+      Math.sqrt(dx * dx + dz * dz)
+    end
+
+    def adaptive_center_band(cfg, search_radius)
+      f = cfg['frequency'].to_s
+      lo = 50
+      hi = 150
+      if %w[very_rare rare].include?(f)
+        lo = 40
+        hi = 90
+      elsif %w[very_common common].include?(f)
+        lo = 60
+        hi = 140
+      end
+      band_hi = [hi, search_radius].min
+      band_lo = [lo, band_hi].min
+      [band_lo, band_hi]
+    end
+
+    def norm_distance(d, search_radius)
+      cap = [search_radius, 1].max
+      Probability.clamp(d / cap.to_f, 0, 1)
+    end
+
+    def point_ux_score(prob_pct, distance, search_radius)
+      (prob_pct / 100.0) * 0.8 - norm_distance(distance, search_radius) * 0.2
+    end
+
+    def cluster_rank_score(max_prob, mean_prob, mean_norm_dist)
+      (max_prob * 0.7 + mean_prob * 0.3) - mean_norm_dist * 12
+    end
+
+    def generate_clusters(seed:, ore:, era:, cfg:, px:, pz:, biome:, search_radius: 220)
+      peak_y = Probability.optimal_y_for_mining(cfg)
+      band_lo, band_hi = adaptive_center_band(cfg, search_radius)
+      num_centers = search_radius < 48 ? 2 : 3
+      points_per_cluster = [4, 3, 3]
+      min_y = cfg['minY']
+      max_y = cfg['maxY']
+
+      expand = lambda do |cx, cz, n, rng, confidence_bonus, primary|
+        xz_min = primary ? PRIMARY_XZ_MIN : SECONDARY_XZ_MIN
+        xz_max = primary ? PRIMARY_XZ_MAX : SECONDARY_XZ_MAX
+        y_max = primary ? PRIMARY_Y_MAX : SECONDARY_Y_MAX
+        pts = []
+
+        push = lambda do |x, y, z|
+          prob = Probability.calculate_ore_probability(cfg, y, biome)
+          d = dist2(x, z, px, pz)
+          conf = Probability.clamp(Probability.calculate_confidence(prob, d, y, peak_y) + confidence_bonus, 0, 100)
+          pts << {
+            'x' => x, 'y' => y, 'z' => z,
+            'confidence' => Rng.round_to_tenth(conf),
+            'probabilityPct' => Rng.round_half_up(prob * 1000) / 10.0,
+            'distance' => Rng.round_to_tenth(d)
+          }
+        end
+
+        if primary && n > 0
+          center_y = Probability.clamp(Rng.round_half_up(peak_y + (rng.call - 0.5) * 2), min_y, max_y)
+          push.call(Rng.round_half_up(cx), center_y, Rng.round_half_up(cz))
+        end
+
+        start_i = (primary && n > 0) ? 1 : 0
+        (start_i...n).each do
+          mag_x = xz_min + rng.call * (xz_max - xz_min)
+          mag_z = xz_min + rng.call * (xz_max - xz_min)
+          sx = rng.call < 0.5 ? -1 : 1
+          sz = rng.call < 0.5 ? -1 : 1
+          x = Rng.round_half_up(cx + sx * mag_x)
+          z = Rng.round_half_up(cz + sz * mag_z)
+          dy = if primary
+                 Probability.clamp(Rng.round_half_up((rng.call + rng.call - 1) * y_max), -y_max, y_max)
+               else
+                 Probability.clamp(Rng.round_half_up((rng.call + rng.call + rng.call - 1.5) * 2), -y_max, y_max)
+               end
+          y = Probability.clamp(Rng.round_half_up(peak_y + dy), min_y, max_y)
+          push.call(x, y, z)
+        end
+
+        if primary && !pts.empty?
+          max_probs = pts.map { |p| p['probabilityPct'] }
+          max_p = max_probs.max
+          if max_p < 75
+            k = max_probs.index(max_p)
+            y_best = Probability.clamp(Rng.round_half_up(peak_y), min_y, max_y)
+            p0 = pts[k]
+            prob = Probability.calculate_ore_probability(cfg, y_best, biome)
+            d = dist2(p0['x'], p0['z'], px, pz)
+            conf = Probability.clamp(Probability.calculate_confidence(prob, d, y_best, peak_y) + confidence_bonus, 0, 100)
+            pts[k] = {
+              'x' => p0['x'], 'y' => y_best, 'z' => p0['z'],
+              'confidence' => Rng.round_to_tenth(conf),
+              'probabilityPct' => Rng.round_half_up(prob * 1000) / 10.0,
+              'distance' => Rng.round_to_tenth(d)
+            }
+          end
+        end
+
+        # Stable sort: pointUxScore desc, then confidence desc.
+        pts.each_with_index.sort_by do |p, i|
+          [-point_ux_score(p['probabilityPct'], p['distance'], search_radius), -p['confidence'], i]
+        end.map(&:first)
+      end
+
+      base_rng = Rng.make_rng([seed.to_s, ore, era, 'centers', num_str(Rng.round_half_up(px)), num_str(Rng.round_half_up(pz))])
+      base_angle = base_rng.call * Math::PI * 2
+
+      built = []
+      (0...num_centers).each do |c|
+        r = Rng.make_rng([seed.to_s, ore, era, 'c', c.to_s, num_str(band_lo), num_str(band_hi)])
+        angle = base_angle + c * ((2 * Math::PI) / num_centers) + (r.call - 0.5) * 0.45
+        rad = band_lo + r.call * (band_hi - band_lo)
+        cx = px + Math.cos(angle) * rad
+        cz = pz + Math.sin(angle) * rad
+
+        n = points_per_cluster[c] || 3
+        primary = c.zero?
+        bonus = primary ? 5 : 0
+        pts = expand.call(cx, cz, n, r, bonus, primary)
+
+        if pts.empty?
+          max_prob = 0
+          mean_prob = 0
+          mean_norm_dist = 1
+        else
+          max_prob = pts.map { |p| p['probabilityPct'] }.max
+          mean_prob = pts.sum { |p| p['probabilityPct'] } / pts.length.to_f
+          mean_norm_dist = pts.sum { |p| norm_distance(p['distance'], search_radius) } / pts.length.to_f
+        end
+        rank = cluster_rank_score(max_prob, mean_prob, mean_norm_dist)
+        rank += 22 if c.zero?
+        built << { 'pts' => pts, 'rank' => rank }
+      end
+
+      sorted = built.each_with_index.sort_by { |b, i| [-b['rank'], i] }.map(&:first)
+      best = sorted.empty? ? [] : sorted[0]['pts']
+      secondary = sorted[1..].map { |b| b['pts'] }
+      { 'bestCluster' => best, 'secondaryClusters' => secondary }
+    end
+  end
+end

data/lib/orefinder_estimate/data.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'set'
+
+# Loads the embedded ore-distribution tables. Fully offline; no network.
+module OrefinderEstimate
+  module Data
+    ORE_DATA = JSON.parse(File.read(File.join(__dir__, 'ore-data.json'))).freeze
+    NETHER_BIOMES = ORE_DATA['netherBiomes'].to_set
+    ORE_ALIASES = ORE_DATA['oreAliases']
+
+    module_function
+
+    def known_ore_keys
+      ORE_DATA['ores'].keys + ORE_ALIASES.keys
+    end
+
+    def resolve_ore_keys(raw)
+      display_label = raw.to_s.strip.downcase
+      compute_key = ORE_ALIASES[display_label] || display_label
+      [compute_key, display_label]
+    end
+
+    def known_ore?(ore_key)
+      k = ore_key.to_s.strip.downcase
+      ORE_ALIASES.key?(k) || ORE_DATA['ores'].key?(k)
+    end
+
+    def era_config(era, compute_key)
+      entry = ORE_DATA['ores'][compute_key]
+      return nil unless entry
+
+      entry[era]
+    end
+  end
+end

data/lib/orefinder_estimate/estimate.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative 'data'
+require_relative 'version'
+require_relative 'probability'
+require_relative 'cluster'
+require_relative 'rng'
+
+# Public estimate API. See ../../../SPEC.md section 7. Offline only; never calls a network.
+module OrefinderEstimate
+  module_function
+
+  def error(error, message, extra = {})
+    { 'success' => false, 'error' => error, 'message' => message }.merge(extra)
+  end
+
+  def estimate(input)
+    return error('invalid_body', 'Input must be a hash.') unless input.is_a?(Hash)
+
+    ore_in = input['ore'].is_a?(String) ? input['ore'].strip.downcase : ''
+    compute_key, display_label = Data.resolve_ore_keys(ore_in)
+    return error('invalid_ore', 'Unknown ore for estimator.') if ore_in.empty? || !Data.known_ore?(ore_in)
+
+    px = to_num(input['x'])
+    pz = to_num(input['z'])
+    py = input['y'].nil? ? 64.0 : to_num(input['y'])
+    if px.nil? || pz.nil? || py.nil? || !px.finite? || !pz.finite? || !py.finite?
+      return error('invalid_position', 'x, y and z must be finite numbers.')
+    end
+
+    version_field = input['version'] || input['platform'] || ''
+    parsed = Version.parse_version(version_field.to_s)
+    return error('invalid_version', 'Pass a version like "java_1_21" or "1.20.1".') if parsed.nil?
+
+    cfg = Data.era_config(parsed['era'], compute_key)
+    if cfg.nil?
+      msg = compute_key == 'copper' && parsed['era'] == 'legacy' ? 'Copper is modern-only (1.18+).' : 'This ore/version combination has no dataset row.'
+      return error('ore_not_in_era', msg)
+    end
+
+    need_mc = cfg['specialRules'] ? cfg['specialRules']['minMcMinor'] : nil
+    if need_mc.is_a?(Integer) && parsed['mcMinor'] < need_mc
+      return error('version_too_old_for_ore',
+                   "This target needs Minecraft 1.#{need_mc}+ (you selected 1.#{parsed['mcMinor']}).",
+                   'minMcMinor' => need_mc, 'selectedMcMinor' => parsed['mcMinor'])
+    end
+
+    biome = input['biome']
+    raw_biome = biome.is_a?(String) && !biome.strip.empty? ? biome.strip.downcase.gsub(/\s+/, '_') : 'plains'
+    biome_effective = Probability.normalize_biome(cfg, raw_biome)
+
+    radius_val = input['searchRadius'].nil? ? 220.0 : to_num(input['searchRadius'])
+    search_radius = [[radius_val, 32].max, 512].min.to_i
+    seed = input['seed'].nil? ? 'numeric' : input['seed']
+
+    clusters = Cluster.generate_clusters(
+      seed: seed, ore: compute_key, era: parsed['era'], cfg: cfg,
+      px: px, pz: pz, biome: raw_biome, search_radius: search_radius
+    )
+
+    peak_y = Probability.optimal_y_for_mining(cfg)
+    effect = Probability.biome_multiplier(cfg, biome_effective)
+
+    {
+      'success' => true,
+      'ore' => display_label,
+      'computeKey' => compute_key,
+      'bestCluster' => clusters['bestCluster'],
+      'secondaryClusters' => clusters['secondaryClusters'],
+      'metadata' => {
+        'ore' => display_label,
+        'computeKey' => compute_key,
+        'edition' => parsed['edition'],
+        'era' => parsed['era'],
+        'mcMinor' => parsed['mcMinor'],
+        'versionLabel' => parsed['raw'],
+        'optimalY' => cfg['optimalY'],
+        'practicalY' => cfg['practicalY'],
+        'actualPeakY' => cfg['actualPeakY'],
+        'yRange' => [cfg['minY'], cfg['maxY']],
+        'biomeRequested' => raw_biome,
+        'biomeEffective' => biome_effective,
+        'dimension' => cfg['dimension'] || 'overworld',
+        'biomeEffect' => Rng.round_half_up(effect * 1000) / 1000.0,
+        'miningPeakY' => peak_y,
+        'generation' => 'distribution_cluster_estimate',
+        'approximate' => true
+      }
+    }
+  end
+
+  def to_num(v)
+    return nil if v.nil?
+
+    Float(v)
+  rescue ArgumentError, TypeError
+    nil
+  end
+end

data/lib/orefinder_estimate/ore-data.json

@@ -0,0 +1,316 @@
+{
+  "version": 1,
+  "note": "Approximate Minecraft ore Y-distribution tables. Not seed-accurate. See https://orefinder.io",
+  "netherBiomes": [
+    "nether_wastes",
+    "crimson_forest",
+    "warped_forest",
+    "soul_sand_valley",
+    "basalt_deltas"
+  ],
+  "oreAliases": {
+    "netherite_block": "ancient_debris",
+    "netherite_scrap": "ancient_debris",
+    "netherite_ingot": "ancient_debris"
+  },
+  "ores": {
+    "coal": {
+      "modern": {
+        "minY": 0, "maxY": 256, "optimalY": 96, "practicalY": null, "actualPeakY": null,
+        "frequency": "very_common", "dimension": "overworld",
+        "distributions": [
+          { "type": "uniform", "minY": 136, "maxY": 256, "peakY": null, "weight": 0.5 },
+          { "type": "triangular", "minY": 0, "maxY": 192, "peakY": 96, "weight": 0.5 }
+        ],
+        "biomeModifiers": { "stony_peaks": 1.5, "windswept_hills": 1.3 },
+        "specialRules": {}
+      },
+      "legacy": {
+        "minY": 0, "maxY": 127, "optimalY": 64, "practicalY": null, "actualPeakY": null,
+        "frequency": "very_common", "dimension": "overworld",
+        "distributions": [
+          { "type": "uniform", "minY": 0, "maxY": 127, "peakY": null, "weight": 1.0 }
+        ],
+        "biomeModifiers": {},
+        "specialRules": {}
+      }
+    },
+    "iron": {
+      "modern": {
+        "minY": -64, "maxY": 256, "optimalY": 16, "practicalY": null, "actualPeakY": null,
+        "frequency": "very_common", "dimension": "overworld",
+        "distributions": [
+          { "type": "uniform", "minY": -64, "maxY": 72, "peakY": null, "weight": 0.33 },
+          { "type": "triangular", "minY": -24, "maxY": 56, "peakY": 16, "weight": 0.33 },
+          { "type": "triangular", "minY": 80, "maxY": 256, "peakY": 232, "weight": 0.34 }
+        ],
+        "biomeModifiers": { "jagged_peaks": 2.0, "snowy_slopes": 1.8, "stony_peaks": 1.7 },
+        "specialRules": {}
+      },
+      "legacy": {
+        "minY": 0, "maxY": 63, "optimalY": 32, "practicalY": null, "actualPeakY": null,
+        "frequency": "very_common", "dimension": "overworld",
+        "distributions": [
+          { "type": "uniform", "minY": 0, "maxY": 63, "peakY": null, "weight": 1.0 }
+        ],
+        "biomeModifiers": {},
+        "specialRules": {}
+      }
+    },
+    "copper": {
+      "modern": {
+        "minY": -16, "maxY": 112, "optimalY": 48, "practicalY": null, "actualPeakY": null,
+        "frequency": "common", "dimension": "overworld",
+        "distributions": [
+          { "type": "triangular", "minY": -16, "maxY": 112, "peakY": 48, "weight": 1.0 }
+        ],
+        "biomeModifiers": { "dripstone_caves": 3.0 },
+        "specialRules": {}
+      },
+      "legacy": null
+    },
+    "gold": {
+      "modern": {
+        "minY": -64, "maxY": 32, "optimalY": -16, "practicalY": null, "actualPeakY": null,
+        "frequency": "rare", "dimension": "overworld",
+        "distributions": [
+          { "type": "triangular", "minY": -64, "maxY": 32, "peakY": -16, "weight": 0.5 },
+          { "type": "uniform", "minY": -64, "maxY": -48, "peakY": null, "weight": 0.5 }
+        ],
+        "biomeModifiers": { "badlands": 5.0, "eroded_badlands": 5.0, "wooded_badlands": 5.0 },
+        "specialRules": {}
+      },
+      "legacy": {
+        "minY": 0, "maxY": 31, "optimalY": 16, "practicalY": null, "actualPeakY": null,
+        "frequency": "rare", "dimension": "overworld",
+        "distributions": [
+          { "type": "uniform", "minY": 0, "maxY": 31, "peakY": null, "weight": 1.0 }
+        ],
+        "biomeModifiers": {},
+        "specialRules": {}
+      }
+    },
+    "diamond": {
+      "modern": {
+        "minY": -64, "maxY": 16, "optimalY": -59, "practicalY": -53, "actualPeakY": null,
+        "frequency": "very_rare", "dimension": "overworld",
+        "distributions": [
+          { "type": "triangular", "minY": -64, "maxY": 16, "peakY": -59, "weight": 1.0 }
+        ],
+        "biomeModifiers": {},
+        "specialRules": {}
+      },
+      "legacy": {
+        "minY": 1, "maxY": 15, "optimalY": 11, "practicalY": null, "actualPeakY": null,
+        "frequency": "very_rare", "dimension": "overworld",
+        "distributions": [
+          { "type": "uniform", "minY": 1, "maxY": 15, "peakY": null, "weight": 1.0 }
+        ],
+        "biomeModifiers": {},
+        "specialRules": {}
+      }
+    },
+    "lapis": {
+      "modern": {
+        "minY": -64, "maxY": 64, "optimalY": 0, "practicalY": null, "actualPeakY": null,
+        "frequency": "uncommon", "dimension": "overworld",
+        "distributions": [
+          { "type": "triangular", "minY": -32, "maxY": 32, "peakY": 0, "weight": 0.5 },
+          { "type": "uniform", "minY": -64, "maxY": 64, "peakY": null, "weight": 0.5 }
+        ],
+        "biomeModifiers": {},
+        "specialRules": {}
+      },
+      "legacy": {
+        "minY": 0, "maxY": 30, "optimalY": 15, "practicalY": null, "actualPeakY": null,
+        "frequency": "uncommon", "dimension": "overworld",
+        "distributions": [
+          { "type": "triangular", "minY": 0, "maxY": 30, "peakY": 15, "weight": 1.0 }
+        ],
+        "biomeModifiers": {},
+        "specialRules": {}
+      }
+    },
+    "redstone": {
+      "modern": {
+        "minY": -64, "maxY": 16, "optimalY": -59, "practicalY": -53, "actualPeakY": null,
+        "frequency": "common", "dimension": "overworld",
+        "distributions": [
+          { "type": "uniform", "minY": -64, "maxY": 16, "peakY": null, "weight": 0.5 },
+          { "type": "triangular", "minY": -64, "maxY": -32, "peakY": -59, "weight": 0.5 }
+        ],
+        "biomeModifiers": {},
+        "specialRules": {}
+      },
+      "legacy": {
+        "minY": 0, "maxY": 15, "optimalY": 8, "practicalY": null, "actualPeakY": null,
+        "frequency": "common", "dimension": "overworld",
+        "distributions": [
+          { "type": "uniform", "minY": 0, "maxY": 15, "peakY": null, "weight": 1.0 }
+        ],
+        "biomeModifiers": {},
+        "specialRules": {}
+      }
+    },
+    "emerald": {
+      "modern": {
+        "minY": -16, "maxY": 320, "optimalY": 232, "practicalY": null, "actualPeakY": 90,
+        "frequency": "very_rare", "dimension": "overworld",
+        "distributions": [
+          { "type": "triangular", "minY": -16, "maxY": 320, "peakY": 232, "weight": 1.0 }
+        ],
+        "biomeModifiers": {
+          "stony_peaks": 1.0, "jagged_peaks": 1.0, "frozen_peaks": 1.0, "meadow": 1.0,
+          "grove": 1.0, "cherry_grove": 1.0, "snowy_slopes": 1.0, "windswept_hills": 1.0,
+          "windswept_forest": 1.0, "windswept_gravelly_hills": 1.0
+        },
+        "specialRules": { "biomeExclusive": true }
+      },
+      "legacy": {
+        "minY": 4, "maxY": 32, "optimalY": 18, "practicalY": null, "actualPeakY": null,
+        "frequency": "very_rare", "dimension": "overworld",
+        "distributions": [
+          { "type": "uniform", "minY": 4, "maxY": 32, "peakY": null, "weight": 1.0 }
+        ],
+        "biomeModifiers": { "extreme_hills": 1.0 },
+        "specialRules": { "biomeExclusive": true }
+      }
+    },
+    "ancient_debris": {
+      "modern": {
+        "minY": 8, "maxY": 119, "optimalY": 15, "practicalY": 14, "actualPeakY": null,
+        "frequency": "very_rare", "dimension": "nether",
+        "distributions": [
+          { "type": "triangular", "minY": 8, "maxY": 24, "peakY": 16, "weight": 0.45 },
+          { "type": "uniform", "minY": 8, "maxY": 119, "peakY": null, "weight": 0.55 }
+        ],
+        "biomeModifiers": {
+          "nether_wastes": 1.0, "crimson_forest": 1.02, "warped_forest": 1.02,
+          "soul_sand_valley": 1.0, "basalt_deltas": 0.94
+        },
+        "specialRules": { "minMcMinor": 16 }
+      },
+      "legacy": {
+        "minY": 8, "maxY": 119, "optimalY": 15, "practicalY": 14, "actualPeakY": null,
+        "frequency": "very_rare", "dimension": "nether",
+        "distributions": [
+          { "type": "triangular", "minY": 8, "maxY": 24, "peakY": 16, "weight": 0.45 },
+          { "type": "uniform", "minY": 8, "maxY": 119, "peakY": null, "weight": 0.55 }
+        ],
+        "biomeModifiers": {
+          "nether_wastes": 1.0, "crimson_forest": 1.02, "warped_forest": 1.02,
+          "soul_sand_valley": 1.0, "basalt_deltas": 0.94
+        },
+        "specialRules": { "minMcMinor": 16 }
+      }
+    },
+    "nether_gold": {
+      "modern": {
+        "minY": 10, "maxY": 114, "optimalY": 48, "practicalY": 45, "actualPeakY": null,
+        "frequency": "uncommon", "dimension": "nether",
+        "distributions": [
+          { "type": "triangular", "minY": 20, "maxY": 96, "peakY": 48, "weight": 0.55 },
+          { "type": "uniform", "minY": 10, "maxY": 114, "peakY": null, "weight": 0.45 }
+        ],
+        "biomeModifiers": {
+          "nether_wastes": 1.0, "crimson_forest": 1.05, "warped_forest": 1.05,
+          "soul_sand_valley": 0.98, "basalt_deltas": 1.04
+        },
+        "specialRules": { "minMcMinor": 16 }
+      },
+      "legacy": {
+        "minY": 10, "maxY": 114, "optimalY": 48, "practicalY": 45, "actualPeakY": null,
+        "frequency": "uncommon", "dimension": "nether",
+        "distributions": [
+          { "type": "triangular", "minY": 20, "maxY": 96, "peakY": 48, "weight": 0.55 },
+          { "type": "uniform", "minY": 10, "maxY": 114, "peakY": null, "weight": 0.45 }
+        ],
+        "biomeModifiers": {
+          "nether_wastes": 1.0, "crimson_forest": 1.05, "warped_forest": 1.05,
+          "soul_sand_valley": 0.98, "basalt_deltas": 1.04
+        },
+        "specialRules": { "minMcMinor": 16 }
+      }
+    },
+    "nether_quartz": {
+      "modern": {
+        "minY": 10, "maxY": 114, "optimalY": 42, "practicalY": null, "actualPeakY": null,
+        "frequency": "common", "dimension": "nether",
+        "distributions": [
+          { "type": "triangular", "minY": 10, "maxY": 114, "peakY": 42, "weight": 1.0 }
+        ],
+        "biomeModifiers": {
+          "nether_wastes": 1.0, "crimson_forest": 1.0, "warped_forest": 1.0,
+          "soul_sand_valley": 1.0, "basalt_deltas": 1.0
+        },
+        "specialRules": { "minMcMinor": 8 }
+      },
+      "legacy": {
+        "minY": 10, "maxY": 114, "optimalY": 42, "practicalY": null, "actualPeakY": null,
+        "frequency": "common", "dimension": "nether",
+        "distributions": [
+          { "type": "triangular", "minY": 10, "maxY": 114, "peakY": 42, "weight": 1.0 }
+        ],
+        "biomeModifiers": {
+          "nether_wastes": 1.0, "crimson_forest": 1.0, "warped_forest": 1.0,
+          "soul_sand_valley": 1.0, "basalt_deltas": 1.0
+        },
+        "specialRules": { "minMcMinor": 8 }
+      }
+    },
+    "gilded_blackstone": {
+      "modern": {
+        "minY": 62, "maxY": 88, "optimalY": 75, "practicalY": null, "actualPeakY": null,
+        "frequency": "rare", "dimension": "nether",
+        "distributions": [
+          { "type": "uniform", "minY": 62, "maxY": 88, "peakY": null, "weight": 1.0 }
+        ],
+        "biomeModifiers": {
+          "nether_wastes": 0.85, "crimson_forest": 0.9, "warped_forest": 0.9,
+          "soul_sand_valley": 0.95, "basalt_deltas": 1.1
+        },
+        "specialRules": { "minMcMinor": 16 }
+      },
+      "legacy": {
+        "minY": 62, "maxY": 88, "optimalY": 75, "practicalY": null, "actualPeakY": null,
+        "frequency": "rare", "dimension": "nether",
+        "distributions": [
+          { "type": "uniform", "minY": 62, "maxY": 88, "peakY": null, "weight": 1.0 }
+        ],
+        "biomeModifiers": {
+          "nether_wastes": 0.85, "crimson_forest": 0.9, "warped_forest": 0.9,
+          "soul_sand_valley": 0.95, "basalt_deltas": 1.1
+        },
+        "specialRules": { "minMcMinor": 16 }
+      }
+    },
+    "blackstone": {
+      "modern": {
+        "minY": 58, "maxY": 92, "optimalY": 74, "practicalY": null, "actualPeakY": null,
+        "frequency": "uncommon", "dimension": "nether",
+        "distributions": [
+          { "type": "uniform", "minY": 58, "maxY": 92, "peakY": null, "weight": 0.55 },
+          { "type": "triangular", "minY": 62, "maxY": 85, "peakY": 74, "weight": 0.45 }
+        ],
+        "biomeModifiers": {
+          "nether_wastes": 0.88, "crimson_forest": 0.92, "warped_forest": 0.92,
+          "soul_sand_valley": 0.96, "basalt_deltas": 1.12
+        },
+        "specialRules": { "minMcMinor": 16 }
+      },
+      "legacy": {
+        "minY": 58, "maxY": 92, "optimalY": 74, "practicalY": null, "actualPeakY": null,
+        "frequency": "uncommon", "dimension": "nether",
+        "distributions": [
+          { "type": "uniform", "minY": 58, "maxY": 92, "peakY": null, "weight": 0.55 },
+          { "type": "triangular", "minY": 62, "maxY": 85, "peakY": 74, "weight": 0.45 }
+        ],
+        "biomeModifiers": {
+          "nether_wastes": 0.88, "crimson_forest": 0.92, "warped_forest": 0.92,
+          "soul_sand_valley": 0.96, "basalt_deltas": 1.12
+        },
+        "specialRules": { "minMcMinor": 16 }
+      }
+    }
+  }
+}

data/lib/orefinder_estimate/probability.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative 'data'
+require_relative 'rng'
+
+# Distribution + confidence model. See ../../../SPEC.md sections 4-5.
+module OrefinderEstimate
+  module Probability
+    module_function
+
+    def clamp(n, lo, hi)
+      [[n, lo].max, hi].min
+    end
+
+    def triangular_probability(y, min_y, max_y, peak_y)
+      return 0.0 if y < min_y || y > max_y
+
+      range = max_y - min_y
+      return 0.0 if range <= 0
+
+      peak = [[peak_y, min_y].max, max_y].min
+      peak_offset = peak - min_y
+      fall_len = max_y - peak
+      return 0.0 if peak_offset <= 0 && fall_len <= 0
+
+      if y <= peak
+        return (y == min_y ? 1.0 : 0.0) if peak_offset <= 0
+
+        return (y - min_y).to_f / peak_offset
+      end
+      return 0.0 if fall_len <= 0
+
+      (max_y - y).to_f / fall_len
+    end
+
+    def uniform_probability(y, min_y, max_y)
+      y >= min_y && y <= max_y ? 1.0 : 0.0
+    end
+
+    def normalize_biome(cfg, biome)
+      dimension = cfg['dimension'] || 'overworld'
+      b = biome.to_s.strip.downcase.gsub(/\s+/, '_')
+      if dimension == 'nether'
+        return Data::NETHER_BIOMES.include?(b) ? b : 'nether_wastes'
+      end
+      return 'plains' if Data::NETHER_BIOMES.include?(b)
+
+      b
+    end
+
+    def biome_multiplier(cfg, normalized_biome)
+      m = cfg['biomeModifiers'][normalized_biome]
+      return m unless m.nil?
+      return 0.12 if cfg['specialRules'] && cfg['specialRules']['biomeExclusive']
+
+      1.0
+    end
+
+    def calculate_ore_probability(cfg, y, raw_biome)
+      nb = normalize_biome(cfg, raw_biome)
+      total = 0.0
+      cfg['distributions'].each do |dist|
+        prob = if dist['type'] == 'triangular' && !dist['peakY'].nil?
+                 triangular_probability(y, dist['minY'], dist['maxY'], dist['peakY'])
+               elsif dist['type'] == 'uniform'
+                 uniform_probability(y, dist['minY'], dist['maxY'])
+               else
+                 0.0
+               end
+        total += prob * dist['weight']
+      end
+      total *= biome_multiplier(cfg, nb)
+      [total, 1.0].min
+    end
+
+    def optimal_y_for_mining(cfg)
+      return cfg['practicalY'] unless cfg['practicalY'].nil?
+      return cfg['actualPeakY'] unless cfg['actualPeakY'].nil?
+
+      cfg['optimalY']
+    end
+
+    def calculate_confidence(probability, distance, y_level, optimal_y)
+      confidence = probability * 100
+      confidence -= [(y_level - optimal_y).abs * 2, 30].min
+      confidence -= [distance / 100.0, 20].min
+      clamp(Rng.round_to_tenth(confidence), 0, 100)
+    end
+  end
+end

data/lib/orefinder_estimate/rng.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Deterministic RNG shared by every Ore Finder Estimate port. See ../../../SPEC.md section 2.
+module OrefinderEstimate
+  module Rng
+    MASK = 0xFFFFFFFF
+
+    module_function
+
+    # floor(x + 0.5); matches JS Math.round (not banker's rounding).
+    def round_half_up(x)
+      (x + 0.5).floor
+    end
+
+    def round_to_tenth(x)
+      round_half_up(x * 10) / 10.0
+    end
+
+    def imul(a, b)
+      ((a & MASK) * (b & MASK)) & MASK
+    end
+
+    # Returns a lambda producing doubles in [0, 1).
+    def mulberry32(seed)
+      state = seed & MASK
+      lambda do
+        state = (state + 0x6D2B79F5) & MASK
+        t = state
+        t = imul(t ^ (t >> 15), t | 1)
+        t = (t ^ ((t + imul(t ^ (t >> 7), t | 61)) & MASK)) & MASK
+        (t ^ (t >> 14)) / 4_294_967_296.0
+      end
+    end
+
+    # FNV-1a hash of parts.join('|') -> mulberry32 generator (ASCII inputs).
+    def make_rng(parts)
+      h = 2_166_136_261
+      s = parts.join('|')
+      s.each_char do |ch|
+        h ^= ch.ord
+        h = imul(h, 16_777_619)
+      end
+      mulberry32(h & MASK)
+    end
+  end
+end

data/lib/orefinder_estimate/version.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Minecraft version string -> era (modern >= 1.18, else legacy). See ../../../SPEC.md section 3.
+module OrefinderEstimate
+  module Version
+    UNDERSCORE = /\A(?:java|bedrock)_(\d+)_(\d+)(?:_(\d+))?\z/.freeze
+    DOTTED = /(\d+)\.(\d+)(?:\.(\d+))?/.freeze
+    LOOSE = /(\d{1,2})[^0-9]+(\d{1,2})/.freeze
+
+    module_function
+
+    def era(mc_minor)
+      mc_minor >= 18 ? 'modern' : 'legacy'
+    end
+
+    def parse_version(raw)
+      return nil unless raw.is_a?(String)
+
+      trimmed = raw.strip
+      return nil if trimmed.empty?
+
+      s = trimmed.downcase
+      edition = s.include?('bedrock') ? 'bedrock' : 'java'
+
+      if (m = UNDERSCORE.match(s))
+        mc_minor = m[2].to_i
+        patch = m[3] ? m[3].to_i : 0
+        return { 'edition' => edition, 'era' => era(mc_minor), 'mcMinor' => mc_minor, 'patch' => patch, 'raw' => trimmed }
+      end
+      if (m = DOTTED.match(s))
+        mc_minor = m[2].to_i
+        patch = m[3] ? m[3].to_i : 0
+        return { 'edition' => edition, 'era' => era(mc_minor), 'mcMinor' => mc_minor, 'patch' => patch, 'raw' => trimmed }
+      end
+      if (m = LOOSE.match(s))
+        mc_minor = m[2].to_i
+        return { 'edition' => edition, 'era' => era(mc_minor), 'mcMinor' => mc_minor, 'patch' => 0, 'raw' => trimmed }
+      end
+
+      nil
+    end
+  end
+end

data/lib/orefinder_estimate.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Ore Finder Estimate - offline, approximate Minecraft ore-distribution estimator.
+# Approximate only; for seed-accurate results use https://orefinder.io
+require_relative 'orefinder_estimate/version'
+require_relative 'orefinder_estimate/data'
+require_relative 'orefinder_estimate/probability'
+require_relative 'orefinder_estimate/cluster'
+require_relative 'orefinder_estimate/estimate'
+
+module OrefinderEstimate
+  VERSION = '1.0.0'
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: orefinder-estimate
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Ore Finder
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A fast, dependency-free, offline estimator for the best mining Y and
+  the areas where ores are most likely to concentrate across Java and Bedrock. Pairs
+  with orefinder.io for seed-exact coordinates.
+email:
+- hello@orefinder.io
+executables:
+- orefinder-estimate
+extensions: []
+extra_rdoc_files: []
+files:
+- DISCLAIMER.md
+- LICENSE
+- README.md
+- exe/orefinder-estimate
+- lib/orefinder_estimate.rb
+- lib/orefinder_estimate/cluster.rb
+- lib/orefinder_estimate/data.rb
+- lib/orefinder_estimate/estimate.rb
+- lib/orefinder_estimate/ore-data.json
+- lib/orefinder_estimate/probability.rb
+- lib/orefinder_estimate/rng.rb
+- lib/orefinder_estimate/version.rb
+homepage: https://orefinder.io
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://orefinder.io
+  source_code_uri: https://github.com/nazzal5448/ore-finder-pkgs
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Fast offline Minecraft ore estimator (best mining Y and likely ore areas).
+test_files: []