Adapter library

Items Utils for Minecraft plugins.

JavaDoc here

Index

• Introduction
• Setup
  • Maven
  • Gradle Groovy
  • Gradle Kotlin DSL
  • After Setup
• Usage
• Compatibilities
• More Examples
• Do you want to test the library?

Note

This library will still be updated and improved, so if you have any suggestions or find any bugs, please let me know.

Introduction

You are tired of using the api of each plugin to get the item?
You are tired of using the api of each plugin to get the item id of the item, block or entity?

This library is for you!

Simple format: adapter_plugin:item_id

This library is a simple and easy-to-use library that allows you to get the item, block or entity from the id of the adapter, and vice versa. Allows transforming string to itemstack and itemstack to string.
itemstack diamond -> mc:diamond
mc:diamond -> itemstack diamond

Setup

Maven (pom.xml) CLICK!

Add the repository to your pom.xml file:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-shade-plugin</artifactId>
            <version>3.6.0</version>
            <executions>
                <execution>
                    <id>shade</id>
                    <phase>package</phase>
                    <goals>
                        <goal>shade</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <minimizeJar>true</minimizeJar>
                <relocations>
                    <relocation>
                        <pattern>dev.wuason.adapter</pattern>
                        <!-- TODO: Change this to my own package name -->
                        <shadedPattern>my.project.libs.adapter</shadedPattern>
                    </relocation>
                </relocations>
            </configuration>
        </plugin>
    </plugins>
</build>

<repositories>
    <repository>
        <id>techmc-studios-releases</id>
        <name>TechMC Repository</name>
        <url>https://repo.techmc.es/releases</url>
    </repository>
</repositories>

<dependency>
    <groupId>dev.wuason</groupId>
    <artifactId>adapter</artifactId>
    <version>RELEASE</version>
    <scope>provided</scope>
</dependency>

Gradle (build.gradle) CLICK!

Add the repository to your build.gradle file:

plugins {
    id 'com.gradleup.shadow' version '8.3.5'
    id 'java'
}

repositories {
    maven {
        name "techmcStudiosReleases"
        url "https://repo.techmc.es/releases"
    }
}

dependencies {
    implementation "dev.wuason:adapter:RELEASE"
}

tasks {
    shadowJar {
        relocate("dev.wuason.adapter", "my.project.libs.adapter")
    }
}

Gradle Kotlin DSL (build.gradle.kts) CLICK!

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

plugins { 
    id("java")
    id("com.gradleup.shadow") version "8.3.5"
}

repositories {
    maven {
        name = "techmcStudiosReleases"
        url = uri("https://repo.techmc.es/releases")
    }
}

dependencies {
    implementation("dev.wuason:adapter:RELEASE")
}

tasks.shadowJar {
    relocate("dev.wuason.adapter", "my.project.libs.adapter")
}

After Setup

Important

If you do not this step, the library will not work.

You need to initialize the library in your plugin:

public class PluginExample extends JavaPlugin {
    @Override
    public void onEnable() {
        Adapter.init(this);
    }
}

Usage

Examples of how to use the library:

Get an ItemStack from an adapter id

public class PluginExample extends JavaPlugin {
    @Override
    public void onEnable() {
        Adapter.init(this);
        
        String adapterId = "mc:diamond_sword";
        ItemStack item = Adapter.getItemStack(adapterId);
        
        if (item != null) {
            getLogger().info("Item: " + item.getType()); // Item: DIAMOND_SWORD
        }
    }
}

Get an adapter id from ItemStack

public class PluginExample extends JavaPlugin {
    @Override
    public void onEnable() {
        Adapter.init(this);
        
        ItemStack item = new ItemStack(Material.DIAMOND_SWORD);
        String adapterId = Adapter.getAdapterId(item);
        
        if (adapterId != null) {
            getLogger().info("Adapter id: " + adapterId); // Adapter id: mc:diamond_sword
        }
    }
}

Get an adapter id from Block and Entity

public class PluginExample extends JavaPlugin {
    @Override
    public void onEnable() {
        Adapter.init(this);
        String adapterBlock = Adapter.getAdapterId(block);
        String adapterEntity = Adapter.getAdapterId(entity);
    }
}

Check if an adapter id exists

public class PluginExample extends JavaPlugin {
    @Override
    public void onEnable() {
        Adapter.init(this);
        
        String adapterId = "mc:diamond_sword";
        if (Adapter.exists(adapterId)) {
            getLogger().info("The adapter id exists");
        }
    }
}

Get all items from all adapters

public class PluginExample extends JavaPlugin {
    @Override
    public void onEnable() {
        Adapter.init(this);
        
        List<String> items = Adapter.getAllItems();
        for (String item : items) {
            getLogger().info("Item: " + item);
        }
    }
}

Compatibilities

Plugin	adapter	aliases	syntax	format example	extra info
Minecraft	mc	vanilla, minecraft	(mc, minecraft, vanilla):(material)	mc:stone or mc:diamond_pickaxe[custom_name='"mypickaxe"']	Support nbt/components /give command format
ItemsAdder	ia	itemsadder	(ia, itemsadder):[namespace](id)	ia:iasurvival:ruby_sword or ia:ruby_sword
Nexo	nx	nexo	(nx, nexo):(id)	nx:ruby_sword or nexo:ruby_sword
Oraxen	or	oraxen, oxn	(or, oraxen, oxn):(id)	or:ruby_sword or oraxen:ruby_sword
CustomItems	ci	customitems, cui	(ci, cui):(id)	ci:ruby_sword or cui:ruby_sword
MMOItems	mmoi	mmoitems	(mmoi, mmoitems):(type):(id)[:level:tier]	mmoi:sword:ruby_sword or mmoitems:sword:ruby_sword:1:rare
ExecutableBlocks	eb	executableblocks	(eb, executableblocks):(id)	executableblocks:ruby_block or eb:ruby_block
ExecutableItems	ei	executableitems	(ei, executableitems):(id)	executableitems:ruby_sword or ei:ruby_sword
MythicCrucible	crucible	mythicc, mcrucible, mythiccrucible	(crucible, mythicc, mcrucible, mythiccrucible):(id)	crucible:ruby_sword or mcrucible:ruby_sword
MythicMobs	mythic	mythicmobs, mmobs, mythicm	(mythic, mythicmobs, mmobs, mythicm):(id)	mythic:ruby_sword or mythicmobs:ruby_sword
StorageMechanic	sm	storagem, smechanic, storagemechanic	(sm, storagem, smechanic, storagemechanic):(id)	sm:backpack or storagem:backpack
CraftEngine	ce	craftengine, craftE, cEngine	(ce, craftengine, craftE, cEngine):(id)	ce:ruby_sword or craftengine:ruby_sword

More Examples

Compare adapters

It Is Similar

public class PluginExample extends JavaPlugin {
    @Override
    public void onEnable() {
        Adapter.init(this);
        
        String adapterId = "mc:diamond";
        ItemStack item = new ItemStack(Material.DIAMOND);
        if (Adapter.isSimilar(adapterId, item)) { // The item is similar
            getLogger().info("The item is similar");
        }
        
        String adapterId2 = "mc:diamond_sword";
        String adapterId3 = "mc:diamond_sword[custom_name='\"weapon\"']";
        
        if (!Adapter.isSimilar(adapterId2, adapterId3)) { // The items aren't similar
            getLogger().info("The items aren't similar");
        }
    }
}

Any Similar

public class PluginExample extends JavaPlugin {
    @Override
    public void onEnable() {
        Adapter.init(this);

        List<String> list = List.of("mc:diamond", "mc:diamond_sword", "mc:gold_sword");
        ItemStack item = new ItemStack(Material.DIAMOND_SWORD);
        
        Optional<String> similar = Adapter.anySimilar(list, item);
        if (similar.isPresent()) {
            getLogger().info("The item is similar to " + similar.get()); // The item is similar to mc:diamond_sword
        }
    }
}

Do you want to test the library?

You can build and test the sample plugin included in the Gradle subproject named plugin to verify the adapter works with the supported compatibilities.

• Subproject: plugin
• Gradle task: shadowJar

You can use the minecraft commands to test the plugin:

• Base usage

  • /adapter <list|get|give|exist>
  • Quick example to get started: hold any item and run:
    • /adapter get hand

• /adapter list

  • Shows all available adapters with their type, name, and enabled state.
  • Example: /adapter list

• /adapter exist adapter:id

  • Checks whether a specific adapter id exists.
  • Example: /adapter exist mc:diamond_sword

• /adapter get hand

  • Players only. Prints the AdapterId and AdvancedId (if different) of the item in your main hand.
  • Example: /adapter get hand

• /adapter get block

  • Players only. Prints the AdapterId and AdvancedId (if different) of the block you are looking at (within 6 blocks).
  • Example: /adapter get block

• /adapter give adapter:id [amount]

  • Gives the specified adapter item to a player. Amount is optional (default 1) and will be split into valid stacks automatically.
  • Examples:
    • /adapter give Steve mc:diamond_sword
    • /adapter give Steve mc:diamond 32

Tab completion:

• 1st arg: list, get, give, exist
• 2nd arg:
  • get: hand, block
  • give: online player names
  • exist: placeholder adapter:id
• 3rd arg (for give): dynamic suggestions of available adapter ids
• 4th arg (for give): 1, 16, 32, 64