MultiBlockEngine

MultiBlockEngine is a high-performance, extensible, and maintainable multi-block structure system designed for Minecraft servers (Paper/Spigot).

---

🎯 Key Objectives

• Event-Driven Detection: Detects structures based on events rather than periodic scans.
• YAML Definitions: Define multi-block structures using external YAML files.
• Immutable Models: Compiles definitions into an internal immutable model for thread safety and performance.
• Efficient Lifecycle: Creates live instances only when valid and maintains state with fast invalidation.
• Separation of Concerns: Strict separation between definition, instance, and behavior.

---

🧠 Design Philosophy

"The plugin does not search for structures; it recognizes them when they are born and maintains them while they exist."

Core Principles:

• Immutability: Definitions cannot be changed at runtime, ensuring stability.
• Early Validation: Fail fast during parsing to prevent runtime errors.
• Lightweight Runtime: Minimal overhead during gameplay.
• Extensibility: Designed to grow without breaking existing implementations.

---

🧱 Configuration (YAML)

Structures are defined in plugins/MultiBlockEngine/multiblocks/.

Basic Example

id: simple_core
version: 1.0

# The anchor block that triggers detection
controller: DIAMOND_BLOCK

pattern:
  # Relative offsets from the controller (x, y, z)
  - offset: [0, -1, 0]
    match: OBSIDIAN
  
  - offset: [1, 0, 0]
    match: "#logs"  # Minecraft Tag support

Matcher Types

The engine compiles YAML patterns into efficient BlockMatcher instances:

• Exact Material: Matches a specific Material.
• Tag Matcher: Matches a block tag (e.g., #logs, #wool).
• AnyOf: Matches any from a list of matchers.
• Air: Explicitly matches air blocks.

---

🏗️ Project Structure

The codebase follows a modular architecture:

src/main/java
└─ com.darkbladedev.engine
   ├─ api
   │  └─ event
   │     ├─ MultiblockFormEvent.java     # Cancellable creation event
   │     ├─ MultiblockBreakEvent.java    # Cancellable destruction event
   │     └─ MultiblockInteractEvent.java # Interaction handling
   ├─ command
   │  └─ MultiblockCommand.java          # /mb command (Inspect, Reload, Status)
   ├─ listener
   │  └─ MultiblockListener.java         # Core event handling (Place/Break/Interact)
   ├─ manager
   │  ├─ MultiblockManager.java          # State, Ticking & Logic controller
   │  └─ MetricsManager.java             # Performance tracking
   ├─ model
   │  ├─ MultiblockType.java             # Immutable definition
   │  ├─ MultiblockInstance.java         # Live structure instance
   │  ├─ MultiblockState.java            # Enum: ACTIVE, DISABLED, etc.
   │  ├─ PatternEntry.java               # Relative pattern rule
   │  ├─ action
   │  │  ├─ Action.java                  # Action interface
   │  │  ├─ SendMessageAction.java
   │  │  ├─ ConsoleCommandAction.java
   │  │  └─ SetStateAction.java
   │  └─ matcher
   │     ├─ BlockMatcher.java            # Functional interface
   │     ├─ ExactMaterialMatcher.java
   │     ├─ TagMatcher.java
   │     ├─ BlockDataMatcher.java        # State matching (stairs, slabs)
   │     └─ ...
   ├─ parser
   │  └─ MultiblockParser.java           # YAML to Object compiler
   └─ storage
      ├─ StorageManager.java             # Persistence interface
      └─ SqlStorage.java                 # SQLite implementation (w/ Migrations)

---

⚙️ Execution Flow

1. Startup:
   • Load YAML definitions.
   • Validate and compile into MultiblockType.
   • Restore persisted instances from database.
2. Runtime:
   • Listen for BlockPlaceEvent and PlayerInteractEvent.
   • Check if the block is a known Controller.
   • Validate the surrounding pattern candidates.
   • If valid, create and register a MultiblockInstance.
3. Invalidation:
   • Listen for BlockBreakEvent.
   • Check if the block belongs to an active instance (O(1) lookup).
   • Destroy the instance and clean up resources.

---

💾 Persistence

• State Management: Active instances are tracked in memory for fast access.
• Shutdown: Instances are serialized and saved to the database (SQLite via HikariCP).
• Startup: Instances are restored and lazily re-validated.

---

🚀 Future Development Plan

The following features are planned for future releases:

1. Phase 1: Advanced Matching

   • BlockState support (e.g., stairs, slabs).
   • NBT/Component data matching.

2. Phase 2: Condition & Action systems

   • Implement a flexible conditions system for multiblock behavior.
   • Add actions to be performed when a structure is valid (e.g., trigger events, run commands).

3. Phase 3: Rotation & Symmetry

   • Support for 4-direction horizontal rotation.
   • Automatic pattern adjustment based on controller facing.

4. Phase 4: Multiblock States

   • Multiblock states (e.g., ACTIVE, DAMAGED, DISABLED, OVERLOADED)

5. Phase 5: Dynamic topology (grow/shrink, mutation)

   • Dynamic structures (optional blocks).
   • Multi-chunk structure support (Chunk Safety).

6. Phase 6: Basic Debugging Tools

   • Add a debug command to inspect multiblock instances.
   • Add particle effects for validating patterns.

7. Phase 7: Advanced Runtime Scaling

   • Cache frequently accessed data (e.g., compiled matchers).
   • Batch processing for large-scale operations.
   • Memory-efficient data structures.
   • Adaptive ticking: priority by player distance, sleep when inactive

8. Phase 8: API & Integration

   • Developer API for custom behaviors.
   • Integration with protection plugins (WorldGuard, GriefPrevention) - Via Events.

9. Phase 9: Advanced Debugging & Monitoring

   • Add debug mode with verbose logging.
   • Implement a metrics system (e.g., Prometheus) for performance tracking.

10. Phase 10: Migration & Compatibility

    • Versioning of multiblock definitions.
    • Automated migrator for existing structures.
    • Clear warnings for incompatible changes.

---

📚 References

• PaperMC - High performance Minecraft server software.
• HikariCP - A "zero-overhead" production ready JDBC connection pool.
• PlaceholderAPI - Placeholder expansion for Bukkit plugins.