Mineseeker v1.1 - Initial Release 🎉

Minecraft Version: 1.20.1

📋 Overview

Mineseeker is a powerful Minecraft Forge mod that helps players efficiently locate structures and biomes using advanced search algorithms. Built with software design patterns and clean code principles as part of CPIT252 coursework at King Abdulaziz University.

---

✨ Features

🏗️ Structure Search

• Find any Minecraft structure with a simple command
• Supports all vanilla structures (villages, temples, strongholds, bastions, etc.)
• Smart duplicate filtering (avoids multiple results from same chunk)
• Adaptive sampling adjusts search speed based on radius
• Interactive click-to-teleport coordinates

🌍 Biome Search

• Locate specific biomes quickly
• Optimized ring-based search pattern
• Support for biome tags and direct biome IDs
• Distance-sorted results

🎯 Smart Search Algorithm

• Ring-based expansion: Searches in expanding circles from player position
• Adaptive sampling: Fewer samples for large radii (faster), more for small radii (accurate)
• Early termination: Stops after consecutive empty rings
• Safety limits: Prevents infinite loops with max iteration caps
• Candidate multiplier: Finds 3x requested structures, then returns closest

💡 User Experience

• Tab completion for structure and biome names
• Color-coded clickable coordinates (green)
• Hover-to-see "Click to teleport" tooltip
• Distance display in blocks
• Clear error messages for invalid inputs

---

🏛️ Design Patterns Implemented

1. Builder Pattern

• Location: MineseekerCommand.java
• Implementation: Uses Brigadier's LiteralArgumentBuilder to construct complex commands incrementally
• Benefit: Readable, maintainable command structure

2. Command Pattern

• Location: MineseekerCommand.java + MineseekerLogic.java
• Implementation: Separates command invocation from execution logic
• Benefit: Loose coupling between UI and business logic

3. Facade Pattern

• Location: MineseekerLogic.java
• Implementation: Provides simplified interface to complex search operations
• Benefit: Hides implementation complexity from command layer

4. Strategy Pattern

• Location: search/SearchStrategy.java and implementations
• Implementation: Pluggable search algorithms (Radial, Spiral)
• Benefit: Easy to add new search patterns without modifying existing code

---

📦 What's Included

Core Files

• Mineseeker.java - Main mod class and registration
• MineseekerCommand.java - Command registration (Builder + Command patterns)
• MineseekerLogic.java - Facade for search operations
• MineseekerSuggestions.java - Tab completion provider
• StructureSearchLogic.java - Structure search implementation
• BiomeSearchLogic.java - Biome search implementation

Design Pattern Implementation

• search/SearchStrategy.java - Strategy interface
• search/strategies/RadialSearchStrategy.java - Circular search pattern
• search/strategies/SpiralSearchStrategy.java - Spiral outward pattern

Utilities

• util/ComponentUtils.java - Reusable utilities for distance calculation and UI components

Configuration

• Config.java - Mod configuration handler

---

🎮 Usage

Structure Search

/mineseeker structure <structure_name> <count> [radius]

Examples:

/mineseeker structure village 5
/mineseeker structure stronghold 1 30000
/mineseeker structure desert_pyramid 3 15000
/mineseeker structure mansion 1 50000

Biome Search

/mineseeker biome <biome_name> <count> [radius]

Examples:

/mineseeker biome mushroom_fields 1
/mineseeker biome ice_spikes 2 20000
/mineseeker biome cherry_grove 3 15000

Parameters

• structure_name / biome_name: Use tab completion for valid options
• count: Number of locations to find (1-50)
• radius: Search radius in blocks (512-64,000, default: 12,000)

Permissions

• Requires permission level 2 (operator)

---

🔧 Technical Details

Performance Optimizations

• Adaptive Sampling:

  • Small radius (≤2000): 32 samples/ring (high accuracy)
  • Medium radius (≤10000): 24 samples/ring
  • Large radius (≤30000): 16 samples/ring
  • Very large radius (>30000): 12 samples/ring (prioritize speed)

• Early Termination: Stops after 3 consecutive empty rings

• Safety Limits: Max 200 iterations to prevent infinite loops

• Chunk-based Deduplication: Prevents duplicate structures from same chunk

Search Constants

STRUCTURE_RING_SIZE = 512 blocks
BIOME_RING_SIZE = 256 blocks
STRUCTURE_CANDIDATE_MULTIPLIER = 3x
MAX_EMPTY_RINGS = 3
MAX_TOTAL_ITERATIONS = 200

---

🧪 Testing

Test Coverage

• 38 comprehensive unit tests
• Test files: MineseekerAppTest.java, SearchStrategyTest.java

Test Categories

• ✅ Distance calculation tests (10 tests)
• ✅ Constant validation tests (12 tests)
• ✅ Strategy Pattern tests (12 tests)
• ✅ Private method logic tests (4 tests)

Testing Approaches

• Direct public method testing
• Reflection-based private method testing
• Edge case validation
• Pattern implementation verification

---

📚 Documentation

JavaDoc Coverage

• All public classes documented
• Design patterns clearly labeled
• Method parameters and return values explained
• Usage examples provided

Code Quality

• No code smells
• DRY principle: Eliminated duplicate code via ComponentUtils
• Single Responsibility: Each class has one clear purpose
• Consistent formatting: Professional code style throughout

---

🎓 Educational Value

Learning Outcomes Demonstrated

1. Design Patterns: Practical implementation of 4 different patterns
2. Clean Code: Professional-grade code organization and documentation
3. Testing: Comprehensive unit test coverage
4. Version Control: Meaningful commit history showing development progression
5. Software Engineering: Real-world application of SOLID principles

Pattern Relationships

User Input
    ↓
MineseekerCommand (Builder Pattern - constructs command)
    ↓
MineseekerLogic (Facade Pattern - simplifies interface)
    ↓
StructureSearchLogic (Command Pattern - executes search)
    ↓
SearchStrategy (Strategy Pattern - pluggable algorithm)
    ↓
ComponentUtils (Utilities - reusable helpers)

---

🛠️ Installation

1. Download mineseeker-1.0.0.jar
2. Place in your Minecraft mods/ folder
3. Launch Minecraft with Forge 47.x.x
4. Open a world and run /mineseeker to test

---

📝 Requirements

• Minecraft: 1.20.1
• Forge: 47.x.x or higher
• Java: 17 or higher
• Permission: Operator level (permission level 2)

---

LLM Usage Disclosure

AI assistance (ChatGPT/Claude) was used for:

• Search algorithm optimization and ring-based pattern design
• Design pattern implementation guidance and best practices
• Code refactoring suggestions for clean code principles
• Documentation and JavaDoc generation
• Testing strategy recommendations

All AI-generated content was thoroughly reviewed, modified, tested, and validated by team members to ensure correctness and understanding.

---

🐛 Known Issues

None at this time. Please report issues on our GitHub repository.

---

📄 License

[This project is licensed under the MIT License.]

---

Thank you for using Mineseeker! 🎮✨

For questions, suggestions, or contributions, please visit our GitHub repository or contact the development team.

---

Built with ❤️ for CPIT252 Final Project

Full Changelog: https://github.com/CPIT252-IT1-Fall25/course-project-mineseeker/compare/1.0...v1.1