GeoCompass adds a custom compass that turns mining into exploration gameplay.

• Right-click survey of nearby chunks
• Rare mineral directional tracking while holding the compass
• First-discovery server announcements with optional rewards
• Optimized with async scan + ChunkSnapshot + TTL cache

• Supported versions: 1.20.1 - 1.21.8
• Platform: Paper / Spigot-compatible servers
• API baseline: 1.20.1

1.Survey Mode (Right Click)

• Scans configured chunk radius around player
• Counts configured whitelist blocks (`survey.probe-blocks`)
• Display modes: CHAT / ACTIONBAR / real BOSSBAR
• Per-area cache with configurable TTL (`survey.cache-ttl-ms`)

2. Rare Mineral Tracking

• Passive detection every configured interval
• Direction + distance hint output
• Real BossBar tracking mode supported
• Independent "recent tracking valid window" (`tracking.recent-valid-seconds`)

3. First Discovery Broadcast

• Announces when a player mines tracked ore under valid tracking context
• Discovery records stored in SQLite (async writer)
• Optional reward commands via console execution

4. Customization

• Item visuals: `item.name`, `item.lore`, `item.custom-model-data`
• Language: fully configurable in `lang.yml`
• World-specific minerals: `worlds.world-minerals`
• Dimension defaults: `tracking.dimension-defaults` (overworld/nether/end)

• Target Mode GUI
  - Added `/gc gui`
  - Sneak + right-click compass opens target selection GUI
  - Players can switch between Auto mode and specific ore target
• Energy / Balance System
  - Compass now supports configurable energy
  - Survey consumes energy (`item.energy.survey-cost`)
  - Max energy configurable (`item.energy.max`)
• Tracking Performance Upgrade
  - ChunkSnapshot + sampled scan (instead of dense full-cube scan)
  - Frame budget: `tracking.players-per-tick`
  - Short-lived player grid cache: `tracking.scan-cache-ms`, `tracking.cache-grid-size`
• Discovery Storage Upgrade
  - Migrated to SQLite (`plugins/GeoCompass/discoveries.db`)
  - Async write queue to reduce main-thread I/O pressure
  - Indexed query fields for better scalability
• Quality Improvements
  - Survey radius supports wider configured range
  - Faster target lookup using material sets
  - Direction labels configurable (`tracking.direction-labels.*`)

Permission	Default	Description
geocompass.use	true	Use GeoCompass features
geocompass.craft	true	Craft GeoCompass recipe
geocompass.bypass.cooldown	op	Bypass survey cooldown
geocompass.admin.reload	op	Reload config/language
geocompass.admin.give	op	Give GeoCompass item

1. Put the plugin jar in your server `plugins/` folder.
2. Start the server once.
3. Edit `plugins/GeoCompass/config.yml` and `plugins/GeoCompass/lang.yml`.
4. Run `/gc reload` after edits.

• Survey scanning is asynchronous
• Uses ChunkSnapshot to avoid heavy sync block reads during counting
• Result caching reduces repeated scans in the same area

Discovery data is stored in SQLite:

• Server version and build​
• Plugin version​
• Relevant config sections​
• Console error logs (if any)​