API Usage Guide

// 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 (not recommended for use)
@Deprecated("Use ink.ptms.zaphkiel.Zaphkiel#api()")
object ZaphkielAPI

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)

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)

val itemUpdater = Zaphkiel.api().getItemUpdater()

// Check inventory for updates
itemUpdater.checkUpdate(player, inventory)

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

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)

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)

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")
    }
}

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)
        }
    }
}

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
    }
}

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
    }
}

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)
}

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
    }
}

@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>
    <groupId>ink.ptms.zaphkiel</groupId>
    <artifactId>zaphkiel-api</artifactId>
    <version>Latest Version</version>
    <scope>provided</scope>
</dependency>

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

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

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

// 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]
    }
}