Architecture Overview

Architecture Overview

MultiBlockEngine (MBE) is not just a structure detector; it is designed as a modular, service-oriented platform for building multi-block ecosystems in Minecraft.

To achieve maximum stability, extensibility, and cross-version compatibility, the architecture follows strict design principles that separate the API contract from the server implementation.

---

1. The Platform-Agnostic API

The biggest architectural shift in MBE is the complete purge of Bukkit/Spigot dependencies from the api module.

Why?

In traditional plugins, everything is heavily coupled to the Bukkit API (e.g., using org.bukkit.entity.Player or org.bukkit.inventory.ItemStack everywhere). This causes issues across versions and makes testing difficult.

How it works now

The api module defines pure Java contracts and domain logic. When an addon needs to interact with the game world, it does so through adapters and bridges provided by the core module.

• You won't find org.bukkit imports in the public API contracts.
• Reflection Safety: Because the API is abstracted, your addons are naturally insulated from internal Minecraft server changes between updates (1.20 - 1.21+).

(For more details on how to handle items and blocks, see Platform Bridges)

---

2. Service-Oriented Architecture (SOA)

MBE operates on a Service-Oriented Architecture. Instead of having monolithic manager classes, functionality is divided into highly decoupled, single-purpose Services.

The Unified Service Registry

At the heart of the engine is the UnifiedServiceRegistry (replacing the legacy MBEServiceRegistry). Every system—whether it's the PersistenceService, EnergyService, or BlueprintService—must be registered here.

Dependency Injection (@InjectService)

Services communicate with each other through a built-in Dependency Injection system. Addons and core components request services simply by annotating their fields, and the engine resolves them at runtime:

public class MyCustomLogic {
    @InjectService
    private MultiblockRuntimeService runtimeService;
}

---

3. The Modular Addon Ecosystem

MultiBlockEngine treats Addons as first-class citizens. Addons are not just secondary scripts; they are powerful modules that can define their own behaviors, states, and even expose their own services to the engine.

Addon Discovery, Lifecycle & I18n

The AddonLifecycleService manages the state of all installed addons. It handles loading, dependency resolution, initialization, and localization.

• Independence: Addons should never depend directly on the core module. They only interact with the api.
• Environment & Capabilities: Addon loading is strictly validated against environment constraints (Java and Minecraft versions) and declared capabilities in their addon.yml.
• Addon I18n System: Addons can bundle localization files under lang/. Each addon accesses its isolated AddonI18n instance via AddonContext#getI18n(), allowing seamless localized messages without core overhead.
• Lifecycle Integrity & Auditing: The AddonAuditService prevents duplicate addon loading and records lifecycle metrics across load/enable/disable transitions.
• Cross-Addon Communication: Since addons can register their own services, Addon A can inject a service provided by Addon B without needing hardcoded dependencies.
• Advanced Dependency Resolution: The lifecycle orchestrator handles complex load graphs including cyclic soft dependencies using load-before and load-after directives.

---

4. The core is just an Orchestrator

It is crucial to understand that the core plugin you put in your plugins/ folder is not the source of truth.

The api defines the rules, and the core is simply an implementation of those rules. The core acts as an orchestrator that:

1. Bootstraps the service registry.
2. Loads the addons.
3. Bridges the platform-agnostic API with the actual Bukkit server environment (handling Bukkit events, command execution, and entity manipulation).

By adhering to this structure, MultiBlockEngine remains a robust, future-proof platform ready for any custom extension you can imagine.