Platform Bridges

Platform Bridges

Because the MultiBlockEngine api module is completely platform-agnostic (meaning it contains zero direct references to Bukkit, Spigot, or Paper classes), developing addons requires a slight mindset shift.

If your addon's logic lives in the api layer, how do you interact with Minecraft-specific concepts like item metadata, blocks, or players? This is where Platform Bridges come in.

---

🌉 What is a Bridge?

A Bridge is an abstraction layer provided by the engine. It defines an interface in the api module, which is then implemented by the core module using the actual Bukkit code.

When you use a bridge in your addon, you are interacting with the abstract interface, ensuring your code remains reflection-safe, cross-version compatible, and decoupled from the server implementation.

---

📦 PdcItemStackBridge (Persistent Data)

One of the most common tasks in an addon is reading or writing custom NBT data to an item (e.g., checking if a held item is a valid "Wrench"). In modern Bukkit, this is done via the PersistentDataContainer (PDC).

Since you cannot import org.bukkit.inventory.ItemStack or org.bukkit.persistence.PersistentDataContainer in the API, the engine provides the PdcItemStackBridge.

Usage Example

If your addon needs to check if an item has a specific tag, you inject or access the bridge:

// Inside your Addon Logic
public void handleItemInteraction(Object platformItem) {
    // We pass the raw platform item (ItemStack) as an Object
    // and let the bridge handle the Bukkit-specific logic
    
    boolean isWrench = pdcItemStackBridge.hasStringTag(platformItem, "mbe_item_type", "wrench");
    
    if (isWrench) {
        // Proceed with logic
    }
}

The bridge handles the heavy lifting of casting the object to a Bukkit ItemStack, extracting the ItemMeta, and interacting with the PersistentDataContainer safely.

---

🧱 Other Common Abstractions

While the PdcItemStackBridge is the most prominent, the engine uses abstraction in several other areas:

1. MBESender (Commands)

Instead of dealing with org.bukkit.command.CommandSender or Player, the new Incendo Cloud v2 architecture wraps command executors in an MBESender. This interface provides methods to send messages and check permissions without exposing the underlying Bukkit player object.

2. Location Vectors

Instead of passing org.bukkit.Location around your domain logic, rely on the abstract mathematical vectors and coordinate offsets provided by the API. Let the core handle the translation to physical world coordinates only when it's time to spawn particles or entities.

---

🚦 Best Practices

1. Keep Domain Logic Pure: Keep your addon's core logic completely free of Bukkit imports.
2. Use Object generic parameters: If you must pass an entity or item from an event down into your domain logic, pass it as a generic Object and use a Bridge to extract the primitive data (strings, numbers) you need.
3. Avoid casting: Do not cast an Object back to ItemStack inside your API logic. If you need to do that, your architecture might need adjusting. Let the bridges do the platform-specific work!