Core Concepts

Core Concepts

To effectively use and extend MultiBlockEngine (MBE), you need to understand its five fundamental pillars. These concepts apply whether you are writing YAML configurations or developing Java Addons.

---

1. The Controller

Every multiblock has exactly one Controller block. This is the "brain" and the physical anchor of the structure in the world.

• Anchor Point: It serves as the coordinate origin (0, 0, 0) for the entire pattern. All other blocks are defined as offsets from this controller.
• Interaction Hub: It is the primary block players interact with (e.g., using a Wrench) to trigger events or assemble the structure.
• Structural Integrity: If the controller is broken, the entire multiblock instance is destroyed and its data is cleaned up.

---

2. Patterns & Rotation

Structures are defined using relative coordinates around the Controller.

• Automatic Rotation: You only need to design your pattern facing one direction (typically NORTH). The engine's mathematical matrix automatically calculates the offsets for EAST, SOUTH, and WEST.
• Smart Detection: The engine analyzes the direction the player is looking, or the orientation of directional blocks (like stairs or pistons), to determine the correct rotation upon assembly.

---

3. Instances (MultiblockInstance)

When a pattern is successfully assembled in the world, it transitions from being a mere collection of blocks to a living entity called a MultiblockInstance.

• Persistent: Instances are saved securely to the database (SQLite/MySQL). If the server restarts, the machine remembers what it was doing.
• Stateful: Each instance holds its own unique State (e.g., ACTIVE, INACTIVE) and localized Variables (e.g., energy_stored, mana).

---

4. ECA System (Event-Condition-Action)

The reactive logic of the engine is driven by an ECA architecture, heavily utilized in the YAML configurations:

1. Event (Trigger): Something happens in the game world (e.g., on_interact, on_tick, on_break).
2. Condition: A set of rules that must be met (e.g., Is the player sneaking? Is the machine ACTIVE? Does it have enough energy?).
3. Action: The output logic executed if conditions are met (e.g., Send a message, consume an item, spawn particles, change state).

---

5. Services & Addons (The Platform)

Unlike traditional plugins where all features are baked into one massive core, MultiBlockEngine is a Service-Oriented Platform.

• Services First: Advanced features like Energy, Wiring, or UI are not part of the core engine. They are isolated Services injected dynamically at runtime.
• Addons as First-Class Citizens: Addons in MBE can expose their own services to the ecosystem. For example, the mbe-energy addon provides an EnergyService that any other addon or multiblock can interact with.
• If you understand that MBE is just the orchestrator and everything else is a decoupled service, you will master the engine's true potential.