ObsidianMaterial

ObsidianMaterial is a comprehensive material abstraction library for Minecraft/Bukkit plugins. It provides a unified API for handling items, blocks, and materials across different Minecraft versions and custom item plugins.

---

Features

• Cross-Version Compatibility: Works with Minecraft 1.13+ using unified material names
• Custom Item Plugin Support: Native integration with popular custom item plugins
  • Oraxen 1.171.0+
  • ItemsAdder 3.0.0+
  • Nexo 1.0.0+ (via reflection for Java 8 compatibility)
  • Slimefun4 RC-37+
  • Skript 2.6.1+
• Async Loading Support: Properly handles asynchronous plugin initialization with event listeners
• XSeries Integration: Support for all XSeries materials
• Player Heads: Direct support for player head items
• Custom Adapters: Extensible architecture for adding your own material providers
• JSON & Legacy Format: Support for both modern JSON and legacy string formats

---

Installation

Maven Repository

Add the repository to your pom.xml:

<repository>
    <id>obsidianmakerdevelopment</id>
    <url>https://moyskleytech.com/debian/m2</url>
</repository>

Add the dependency:

<dependency>
    <groupId>com.moyskleytech</groupId>
    <artifactId>ObsidianMaterialAPI</artifactId>
    <version>1.0.10</version>
</dependency>

Gradle

Add the repository to your build.gradle or build.gradle.kts:

repositories {
    maven("https://moyskleytech.com/debian/m2")
}

Add the dependency:

dependencies {
    implementation("com.moyskleytech:ObsidianMaterialAPI:1.0.10")
}

Using as a Plugin Dependency

If you want to use ObsidianMaterial as a plugin (with XSeries and Jackson bundled), add it as a dependency in your plugin.yml:

depend: [ObsidianMaterial]
# Or as soft dependency if optional
softdepend: [ObsidianMaterial, Skript, ItemsAdder, Slimefun, Oraxen, Nexo]

Then use it as a compileOnly dependency:

dependencies {
    compileOnly("com.moyskleytech:ObsidianMaterial:1.0.10")
}

Additional Dependencies

Some features require additional libraries (marked in JavaDoc):

dependencies {
    implementation("com.github.cryptomorin:XSeries:13.6.0")
    implementation("com.fasterxml.jackson.core:jackson-databind:2.13.1")
    implementation("com.fasterxml.jackson.core:jackson-core:2.20.1")
}

---

Usage

Basic Material Parsing

import com.moyskleytech.obsidian.material.ObsidianMaterial;

// Parse any material (vanilla, custom items, etc.)
ObsidianMaterial material = ObsidianMaterial.valueOf("RED_BED");
ObsidianMaterial oraxenItem = ObsidianMaterial.valueOf("oraxen:custom_sword");
ObsidianMaterial itemsAdderItem = ObsidianMaterial.valueOf("itemsadder:custom_item");

Item Template Parsing

import com.moyskleytech.obsidian.material.ObsidianItemTemplate;
import com.moyskleytech.obsidian.material.ItemParser;

// Parse from string
ObsidianItemTemplate template = ItemParser.deserialize("RED_BED");

// Clone existing item
ObsidianItemTemplate template = new ObsidianItemTemplate(itemStack);

// Parse legacy format
ObsidianItemTemplate template = ItemParser.deserialize(
    "DIAMOND_SWORD_OF_MENDING_5_NAMED_Destroyer of universe"
);

// Parse JSON format
String json = """
{
    "name": "Destroyer of universe",
    "material": "DIAMOND_SWORD",
    "enchants": {
        "MENDING": 5
    }
}
""";
ObsidianItemTemplate template = ItemParser.deserialize(json);

Converting to Bukkit Types

// Material to Bukkit Material
ObsidianMaterial material = ObsidianMaterial.valueOf("DIAMOND_SWORD");
org.bukkit.Material bukkitMaterial = material.toMaterial();

// Material to ItemStack
org.bukkit.inventory.ItemStack itemStack = material.toItem();

// Template to ItemStack
ObsidianItemTemplate template = ItemParser.deserialize("DIAMOND_SWORD");
org.bukkit.inventory.ItemStack itemStack = template.toItem();

// Set block in world
ObsidianMaterial material = ObsidianMaterial.valueOf("oraxen:custom_block");
material.setBlock(block);

---

Supported Material Formats

ObsidianMaterial supports a wide variety of material string formats:

Format	Example	Description
Vanilla Materials	DIAMOND_SWORD	All org.bukkit.Material values
XSeries Materials	RED_BED	All com.cryptomorin.xseries.XMaterial values
Player Heads	Notch_HEAD	Player head items by username
Spawners	PIG_SPAWNER	Spawner with entity type
Enchanted Books	MENDING_BOOK	Single enchantment book
	MENDING_5_BOOK	Enchantment with level
	MENDING_5_AND_UNBREAKING_3_BOOK	Multiple enchantments (infinite chain)
Potions	SPEED_POTION	Basic potion
	SPEED_SPLASH_POTION	Splash potion
	SPEED_2_POTION	Level 2 potion
	EXTENDED_SPEED_POTION	Extended duration
Custom Items	oraxen:custom_sword	Oraxen items
	itemsadder:custom_item	ItemsAdder items
	nexo:custom_block	Nexo items
	slimefun:REINFORCED_ALLOY	Slimefun items

---

Custom Adapters

You can extend ObsidianMaterial to support additional item providers:

Creating an Adapter

import com.moyskleytech.obsidian.material.implementations.adapters.Adapter;
import com.moyskleytech.obsidian.material.ObsidianMaterial;
import org.bukkit.inventory.ItemStack;
import org.bukkit.block.Block;
import org.bukkit.block.data.BlockData;
import java.util.Optional;

public class MyCustomAdapter implements Adapter {
    
    @Override
    public Optional<ObsidianMaterial> tryParse(String materialString) {
        // Parse string format like "mycustom:item_id"
        if (materialString.startsWith("mycustom:")) {
            String itemId = materialString.substring(9);
            // Create and return your custom material
            return Optional.of(new MyCustomMaterial(itemId));
        }
        return Optional.empty();
    }
    
    @Override
    public Optional<ObsidianMaterial> tryMatch(ItemStack stack) {
        // Check if ItemStack is one of your custom items
        return Optional.empty();
    }
    
    @Override
    public Optional<ObsidianMaterial> tryMatch(Block block) {
        // Check if Block is one of your custom blocks
        return Optional.empty();
    }
    
    @Override
    public Optional<ObsidianMaterial> tryMatch(BlockData blockData) {
        // Check if BlockData matches your custom blocks
        return Optional.empty();
    }
}

Registering an Adapter

import com.moyskleytech.obsidian.material.ObsidianMaterial;

// Register your adapter
ObsidianMaterial.registerAdapter(MyCustomAdapter.class, plugin);

---

Documentation

• JavaDoc: https://obsidianmakerdevelopment.github.io/ObsidianMaterial
• Issues: GitHub Issues

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Support

For support, questions, or feature requests:

• Open an issue on GitHub
• Join our Discord community (if applicable)

---

Acknowledgments

• XSeries for cross-version material compatibility
• Oraxen for custom item support
• ItemsAdder for custom item support
• Nexo for custom item support
• Slimefun4 for custom item support
• The Bukkit/Spigot community