iPlugin | API Usage Guide

Overview

Zaphkiel provides a complete set of API interfaces, allowing other plugin developers to easily integrate and use Zaphkiel's item system. Through the API, you can create, manage, and manipulate custom items, as well as listen to related events.

Obtain API Instance

Main API Interface

Zaphkiel's core API is provided through the ZapAPI interface:

// Obtain Zaphkiel API instance
val api = Zaphkiel.api()
 
// Obtain various managers
val itemHandler = api.getItemHandler()
val itemManager = api.getItemManager()
val itemUpdater = api.getItemUpdater()
val itemLoader = api.getItemLoader()
val itemSerializer = api.getItemSerializer()

Legacy API (Deprecated)

// Legacy API (not recommended for use)
@Deprecated("Use ink.ptms.zaphkiel.Zaphkiel#api()")
object ZaphkielAPI

Core API Components

ItemHandler - Item Processor

Used to read and process Zaphkiel items:

val itemHandler = Zaphkiel.api().getItemHandler()
 
// Read item stream
val itemStream = itemHandler.read(itemStack)
 
// Obtain item instance
val item = itemHandler.getItem(itemStack)
 
// Obtain item ID
val itemId = itemHandler.getItemId(itemStack)
 
// Obtain item data
val itemData = itemHandler.getItemData(itemStack)
 
// Obtain unique data
val uniqueData = itemHandler.getItemUniqueData(itemStack)

ItemManager - Item Manager

Manages all registered items, display templates, groups, etc.:

val itemManager = Zaphkiel.api().getItemManager()
 
// Obtain registered items
val itemMap = itemManager.getItemMap()
val item = itemMap["item_id"]
 
// Obtain display templates
val displayMap = itemManager.getDisplayMap()
 
// Obtain groups
val groupMap = itemManager.getGroupMap()
 
// Obtain metadata types
val metaMap = itemManager.getMetaMap()
 
// Generate items
val itemStream = itemManager.generateItem("item_id", player)
val itemStack = itemManager.generateItemStack("item_id", player)

ItemUpdater - Item Updater

Handles item version updates and checks:

val itemUpdater = Zaphkiel.api().getItemUpdater()
 
// Check inventory for updates
itemUpdater.checkUpdate(player, inventory)
 
// Check single item for updates
val updatedStream = itemUpdater.checkUpdate(player, itemStack)

ItemLoader - Item Loader

Loads item definitions from files:

val itemLoader = Zaphkiel.api().getItemLoader()
 
// Load items from file
val items = itemLoader.loadItemFromFile(file)
items.forEach { itemManager.registerItem(it) }
 
// Load display templates
val displays = itemLoader.loadDisplayFromFile(file)
displays.forEach { itemManager.registerDisplay(it) }
 
// Load metadata
val metaList = itemLoader.loadMetaFromSection(configSection)

ItemSerializer - Item Serializer

Serializes and deserializes items:

val itemSerializer = Zaphkiel.api().getItemSerializer()
 
// Serialize item
val json = itemSerializer.serialize(itemStack)
val jsonFromStream = itemSerializer.serialize(itemStream)
 
// Deserialize item
val itemStream = itemSerializer.deserialize(jsonString)
val itemStreamFromJson = itemSerializer.deserialize(jsonObject)

Practical API Examples

Check and Manipulate Items

fun handlePlayerInteract(player: Player, itemStack: ItemStack) {
    val itemHandler = Zaphkiel.api().getItemHandler()
    
    // Check if it is a Zaphkiel item
    val itemId = itemHandler.getItemId(itemStack)
    if (itemId != null) {
        // Obtain item instance
        val item = itemHandler.getItem(itemStack)
        
        // Obtain item data
        val itemData = itemHandler.getItemData(itemStack)
        
        // Execute custom logic
        player.sendMessage("You used a Zaphkiel item: $itemId")
    }
}

Give Custom Items

fun giveCustomItem(player: Player, itemId: String, amount: Int) {
    val itemManager = Zaphkiel.api().getItemManager()
    
    // Generate item
    val itemStack = itemManager.generateItemStack(itemId, player)
    if (itemStack != null) {
        itemStack.amount = amount
        
        // Give to player
        val overflow = player.inventory.addItem(itemStack)
        
        // Handle overflow items
        overflow.values.forEach { item ->
            player.world.dropItem(player.location, item)
        }
    }
}

Check Item Updates

fun checkAndUpdateItems(player: Player) {
    val itemUpdater = Zaphkiel.api().getItemUpdater()
    
    // Check entire inventory
    itemUpdater.checkUpdate(player, player.inventory)
    
    // Or check specific item
    val mainHand = player.inventory.itemInMainHand
    if (!mainHand.type.isAir) {
        val updatedStream = itemUpdater.checkUpdate(player, mainHand)
        // The updated item stream can be further processed
    }
}

Serialize Item Data

fun saveItemToDatabase(itemStack: ItemStack): String? {
    val itemHandler = Zaphkiel.api().getItemHandler()
    val itemSerializer = Zaphkiel.api().getItemSerializer()
    
    // Check if it is a Zaphkiel item
    val itemId = itemHandler.getItemId(itemStack)
    if (itemId != null) {
        // Serialize to JSON
        val json = itemSerializer.serialize(itemStack)
        return json.toString()
    }
    return null
}
 
fun loadItemFromDatabase(jsonString: String): ItemStack? {
    val itemSerializer = Zaphkiel.api().getItemSerializer()
    
    return try {
        val itemStream = itemSerializer.deserialize(jsonString)
        itemStream.toItemStack()
    } catch (e: Exception) {
        null
    }
}

Advanced API Usage

Custom Item Operations

fun customItemOperations(player: Player, itemId: String) {
    val itemManager = Zaphkiel.api().getItemManager()
    val item = itemManager.getItemMap()[itemId] ?: return
    
    // Check if player has the item
    if (item.hasItem(player, 1)) {
        // Remove item
        if (item.takeItem(player, 1)) {
            player.sendMessage("Item removed")
        }
    }
    
    // Give item (handle overflow)
    item.giveItem(player, 1) { overflow ->
        overflow.forEach { item ->
            player.world.dropItem(player.location, item)
        }
    }
    
    // Give item or drop if inventory is full
    item.giveItemOrDrop(player, 1)
}

Item Similarity Check

fun checkItemSimilarity(itemStack1: ItemStack, itemStack2: ItemStack): Boolean {
    val itemHandler = Zaphkiel.api().getItemHandler()
    
    val item1 = itemHandler.getItem(itemStack1)
    val item2 = itemHandler.getItem(itemStack2)
    
    return if (item1 != null && item2 != null) {
        item1.isSimilar(itemStack2)
    } else {
        false
    }
}

Event Listening

Listen to Zaphkiel Events

@EventHandler
fun onItemBuild(event: ItemBuildEvent) {
    val item = event.item
    val player = event.player
    val itemStream = event.itemStream
    
    // Execute custom logic when item is built
    if (item.id == "special_item") {
        // Modify item stream
        itemStream.getZaphkielData().putDeep("custom.property", ItemTagData("value"))
    }
}
 
@EventHandler
fun onItemRelease(event: ItemReleaseEvent) {
    val itemStream = event.itemStream
    val player = event.player
    
    // Execute logic when item is released
    val itemId = itemStream.getZaphkielItem().id
    player.sendMessage("Released item: $itemId")
}

Dependency Configuration

Maven

<dependency>
    <groupId>ink.ptms.zaphkiel</groupId>
    <artifactId>zaphkiel-api</artifactId>
    <version>Latest Version</version>
    <scope>provided</scope>
</dependency>

Gradle

dependencies {
    compileOnly("ink.ptms.zaphkiel:zaphkiel-api:Latest Version")
}

Best Practices

1. Safety Checks

// Always check API availability
if (Bukkit.getPluginManager().isPluginEnabled("Zaphkiel")) {
    val api = Zaphkiel.api()
    // Use the API
}

2. Exception Handling

try {
    val itemStream = itemHandler.read(itemStack)
    // Process the item stream
} catch (e: Exception) {
    // Handle exceptions (may not be a Zaphkiel item)
}

3. Performance Considerations

// Cache frequently used item instances
private val cachedItems = mutableMapOf<String, Item>()
 
fun getCachedItem(itemId: String): Item? {
    return cachedItems.computeIfAbsent(itemId) {
        Zaphkiel.api().getItemManager().getItemMap()[it]
    }
}

API Usage Guide

On this page