ItemsAdder API 文档

概述

ItemsAdder 是一个 Minecraft 插件，用于添加自定义物品、方块、实体、HUD、GUI 等。本文档整理了其 API 用法，重点关注 Java API、Skript API 和 Denizen API。

包名和主要类

主包：dev.lone.itemsadder.api
主要类：
- CustomStack – 自定义物品操作
- CustomBlock – 自定义方块操作
- CustomEntity – 自定义实体操作
- ItemsAdder – 静态工具方法
- FontImageWrapper – 字体图像/表情符号
- TexturedInventoryWrapper – 自定义 GUI
- PlayerHudsHolderWrapper – HUD 持有者
- PlayerQuantityHudWrapper – 数值型 HUD

Java API 详细用法

1. 获取 API 实例

// 等待 ItemsAdder 加载完成
@EventHandler
public void onItemsAdderLoad(ItemsAdderLoadDataEvent event) {
    // ItemsAdder 已加载完成
}

2. 自定义物品操作

获取自定义物品

// 通过 ID 获取自定义物品
CustomStack stack = CustomStack.getInstance("your_item");
if (stack != null) {
    ItemStack itemStack = stack.getItemStack();
} else {
    // 未找到该自定义物品
}

// 检查自定义物品是否存在
boolean exists = CustomStack.isInRegistry("your_item");

// 从 Bukkit ItemStack 获取 CustomStack
CustomStack stack = CustomStack.byItemStack(myItemStack);
if (stack != null) {
    // 是自定义物品
    stack.setUsages(5); // 设置使用次数
}

3. 自定义方块操作

检查自定义方块

// 检查自定义方块是否存在
boolean exists = CustomBlock.isInRegistry("your_item");

// 检查世界中的方块是否为自定义方块
CustomBlock customBlock = CustomBlock.byAlreadyPlaced(block);
if (customBlock != null) {
    // 是自定义方块
} else {
    // 不是自定义方块
}

// 放置自定义方块
CustomBlock customBlock = CustomBlock.getInstance("ruby_ore");
if (customBlock != null) {
    customBlock.place(location);
}

4. 自定义实体操作

生成自定义实体

// 生成自定义实体
CustomEntity customEntity = CustomEntity.spawn("your_item", location);
if (customEntity != null) {
    System.out.println(customEntity.getNamespacedID());
}

// 从已生成的 Bukkit 实体获取 CustomEntity
CustomEntity customEntity = CustomEntity.byAlreadySpawned(entity);
if (customEntity != null) {
    // 是自定义实体
}

5. 液体 API

需要安装 IALiquids 插件

@EventHandler
void interact(PlayerInteractEvent e) {
    if (e.getAction() == Action.LEFT_CLICK_BLOCK) {
        ItemsAdder.setLiquid("ialiquids:red_water", e.getClickedBlock().getLocation());
    } else if (e.getAction() == Action.RIGHT_CLICK_BLOCK) {
        System.out.println(ItemsAdder.getLiquidName(e.getClickedBlock().getRelative(e.getBlockFace()).getLocation()));
    }
}

6. HUD 操作

设置 HUD 数值

PlayerHudsHolderWrapper playerHudsHolderWrapper = new PlayerHudsHolderWrapper(playerObject);
PlayerQuantityHudWrapper hud = new PlayerQuantityHudWrapper(playerHudsHolderWrapper, "namespace_name:hud_name");
hud.setFloatValue(1f);

显示/隐藏 HUD

PlayerHudsHolderWrapper playerHudsHolderWrapper = new PlayerHudsHolderWrapper(playerObject);
PlayerQuantityHudWrapper hud = new PlayerQuantityHudWrapper(playerHudsHolderWrapper, "namespace_name:hud_name");
hud.setVisible(true);

7. 获取表情符号/GUI 字符

String emoji = new FontImageWrapper("twitteremojis:confirm").getString();

8. API 工具方法（静态方法）

检查物品是否已加载

boolean loaded = ItemsAdder.areItemsLoaded();

检查是否为自定义物品

boolean isCustom = ItemsAdder.isCustomItem(itemStack);
boolean isCustom = ItemsAdder.isCustomItem("custom_item_name");

获取世界中的自定义方块

ItemStack blockItem = ItemsAdder.getCustomBlock(block);

检查是否为家具

boolean isFurniture = ItemsAdder.isFurniture(entity);

匹配特定自定义物品

boolean matches = ItemsAdder.matchCustomItemName(itemStack, "amethyst_pickaxe");

9. 旧 API 方法（仍可用）

获取自定义物品

ItemStack item = ItemsAdder.getCustomItem("nameInConfig");

放置自定义方块

ItemsAdder.placeCustomBlock(location, customBlock);
ItemsAdder.placeCustomBlock(location, customBlock, lightweight);

获取自定义方块掉落物

List<ItemStack> loot = ItemsAdder.getCustomBlockLoot(block, tool, includeSelfBlock);

检查是否为自定义方块

boolean isCustom = ItemsAdder.isCustomBlock(block);

种植自定义作物

ItemsAdder.placeCustomCrop(location, seed);

检查是否为自定义作物

boolean isCustomCrop = ItemsAdder.isCustomCrop(block);

获取自定义种子名称

String seedName = ItemsAdder.getCustomSeedNameFromCrop(block);

获取物品配置名称

String itemName = ItemsAdder.getCustomItemName(itemStack);
String fileName = ItemsAdder.getCustomItemFileName(itemStack);

物品耐久度操作

int usages = ItemsAdder.getCustomItemUsages(itemStack);
ItemStack newItem = ItemsAdder.setCustomItemDurability(item, durability);
int durability = ItemsAdder.getCustomItemDurability(itemStack);
int maxDurability = ItemsAdder.getCustomItemMaxDurability(itemStack);

事件

ItemsAdderLoadDataEvent

package dev.lone.itemsadder.api.Events;
public class ItemsAdderLoadDataEvent extends Event

当 ItemsAdder 正确加载所有内容时触发（在 /iareload 时也会触发）。

ResourcePackSendEvent

当服务器向客户端发送资源包时触发。包含 URL、哈希值，以及是否是 ItemsAdder 资源包的信息。

Skript API

简单用法

给予自定义物品

command /iaskriptgetitem <text> [<number=1>]:
    trigger:
        set {%player%.item} to null
        set {%player%.item} to customitem arg 1
        if {%player%.item} is null:
            message "Custom item %arg 1% not found"
        else:
            give player arg 2 of {%player%.item}
            message "Obtained custom item %arg 1%"

检查手持物品是否为自定义物品

command /iaskriptiscustomitem:
    trigger:
        if player's tool is a customitem:
            message "it's a custom item"
        else:
            message "it's not a custom item"

使用表情符号

command /emojitest:
    trigger:
        set {iconConfirm} to fontimage "twitteremojis:confirm"
        message "Good: %{iconConfirm}%"

高级用法（需要 skript-reflect）

获取自定义物品

import: dev.lone.itemsadder.api.ItemsAdder

command /iaskript:
    trigger:
        set {testItem} to ItemsAdder.getCustomItem("itemsadder:ruby")
        sender.getInventory().addItem({testItem})

检查点击的方块是否为自定义方块

import: dev.lone.itemsadder.api.ItemsAdder
import: org.bukkit.event.player.PlayerInteractEvent
import: org.bukkit.inventory.EquipmentSlot as EquipmentSlot

on PlayerInteractEvent:
    if event.getHand() is EquipmentSlot.OFF_HAND:
        stop
    set {_clickedBlock} to event.getClickedBlock()
    set {_isCustomBlock} to ItemsAdder.isCustomBlock({_clickedBlock})
    event.getPlayer().sendMessage("Is custom block: %{_isCustomBlock}%")
    if {_isCustomBlock} is true:
        set {_tmp} to ItemsAdder.getCustomBlock({_clickedBlock})
        set {_name} to {_tmp}.getItemMeta().getDisplayName()
        event.getPlayer().sendMessage("%{_name}%")

自定义 GUI

import: dev.lone.itemsadder.api.ItemsAdder
import: dev.lone.itemsadder.api.FontImages.TexturedInventoryWrapper
import: dev.lone.itemsadder.api.FontImages.FontImageWrapper
import: org.bukkit.entity.Player

command /iaguitest:
    trigger:
        set {_customTexture} to new FontImageWrapper("mcguis:blank_menu")
        set {_gui} to new TexturedInventoryWrapper(null, 54, "&0Test" and {_customTexture})
        set {_icon} to ItemsAdder.getCustomItem("mcicons:icon_confirm")
        add player to {players::*}
        set slot 12 of {_gui}.getInternal() to {_icon}
        {_gui}.showInventory(player)

on inventory click:
    if {players::*} contain player:
        if index of event-slot = 12:
            cancel event
            send "Confirmed!"

on inventory close:
    remove player from {players::*}

更改 HUD 值

import: dev.lone.itemsadder.api.FontImages.PlayerQuantityHudWrapper
import: dev.lone.itemsadder.api.FontImages.PlayerHudsHolderWrapper

command /healme:
    trigger:
        set {_player} to new PlayerHudsHolderWrapper(player)
        set {_hud} to new PlayerQuantityHudWrapper({_player}, "realcraft:thirst_bar")
        {_hud}.setFloatValue(10.0)
        heal the player
        set the player's food level to 10

Denizen API

功能特性

# 检查物品是否为自定义物品
player.item_in_hand.is_ia_item

# 检查物品是否为自定义方块
player.item_in_hand.is_ia_block

# 获取物品命名空间 ID
player.item_in_hand.ia_namespaced_id

# 放置自定义方块
# 语法: set_custom_block [<location>|...] [<namespaced_id>]
set_custom_block <context.location> ruby_block

# 检查方块是否为自定义方块
context.location.is_ia_block

# 获取方块命名空间 ID
context.location.ia_namespaced_id

示例脚本

my_world_script:
  type: world
  events:
    after player left clicks block:
      - narrate " "
      - if <player.item_in_hand.is_ia_block>:
        - narrate "Left click item is a custom block! <&6><player.item_in_hand.ia_namespaced_id>"
      - else:
        - narrate "Left click item is NOT a custom block! <&7><player.item_in_hand.material>"
      - narrate " "
    
    after player right clicks block:
      - if <player.is_sneaking>:
        - set_custom_block <context.location> ruby_block
      - else:
        - narrate " "
        - if <player.item_in_hand.is_ia_item>:
          - narrate "Right click item is a custom item! <&6><player.item_in_hand.ia_namespaced_id>"
        - else:
          - narrate "Right click item is NOT a custom item! <&7><player.item_in_hand.material>"
        - if <context.location.is_ia_block>:
          - narrate "Interacted block is a custom block! <&6><context.location.ia_namespaced_id>"
        - else:
          - narrate "Interacted block is NOT a custom block!"
        - narrate " "

变量占位符

ItemsAdder 支持以下变量占位符（在配置文件中使用）：

玩家相关变量

%player_name% – 玩家名称
%player_displayname% – 玩家显示名称
%player_uuid% – 玩家 UUID
%player_world% – 玩家所在世界
%player_x%, %player_y%, %player_z% – 玩家坐标
%player_health% – 玩家生命值
%player_max_health% – 玩家最大生命值
%player_food% – 玩家饥饿值
%player_level% – 玩家等级
%player_exp% – 玩家经验值
%player_gamemode% – 玩家游戏模式

服务器相关变量

%server_name% – 服务器名称
%server_ip% – 服务器 IP
%server_port% – 服务器端口
%server_version% – 服务器版本
%server_online% – 在线玩家数量
%server_max_players% – 最大玩家数量
%server_motd% – 服务器 MOTD

时间相关变量

%time_hour% – 当前小时 (24小时制)
%time_minute% – 当前分钟
%time_second% – 当前秒
%time_day% – 当前日期
%time_month% – 当前月份
%time_year% – 当前年份
%time_full% – 完整时间

物品相关变量

%item_name% – 物品名称
%item_displayname% – 物品显示名称
%item_lore% – 物品描述
%item_amount% – 物品数量
%item_durability% – 物品耐久度
%item_max_durability% – 物品最大耐久度
%item_usages% – 物品使用次数

经济相关变量（需要 Vault）

%player_balance% – 玩家余额
%player_currency% – 玩家货币

权限相关变量（需要 Vault）

%player_prefix% – 玩家前缀
%player_suffix% – 玩家后缀
%player_group% – 玩家组

占位符API变量（需要 PlaceholderAPI）

%placeholderapi_<placeholder>% – 任何 PlaceholderAPI 占位符

注意事项

权限检查：使用 HUD API 时，确保玩家没有 ia.user.hud.bypass.api.* 权限，否则 setFloatValue 等方法将无效。
加载顺序：使用 ItemsAdderLoadDataEvent 确保 ItemsAdder 已加载完成后再访问其 API。
资源包：自定义物品需要客户端加载资源包才能正确显示。
版本兼容性：某些功能可能仅适用于特定版本的 ItemsAdder 或 Minecraft。
依赖关系：
- Skript API 需要安装 skript 和 skript-reflect
- Denizen API 需要 ItemsAdder 3.2.4+
- 液体 API 需要 IALiquids 插件

常见问题

1. 如何检查自定义物品是否存在？

boolean exists = CustomStack.isInRegistry("your_item");

2. 如何获取玩家手中的自定义物品？

CustomStack stack = CustomStack.byItemStack(player.getInventory().getItemInMainHand());
if (stack != null) {
    // 是自定义物品
}

3. 如何生成自定义实体？

CustomEntity entity = CustomEntity.spawn("your_entity", location);

4. 如何设置 HUD 值？

PlayerHudsHolderWrapper holder = new PlayerHudsHolderWrapper(player);
PlayerQuantityHudWrapper hud = new PlayerQuantityHudWrapper(holder, "namespace:hud_name");
hud.setFloatValue(50.0f);

5. 如何获取表情符号字符串？

String emoji = new FontImageWrapper("twitteremojis:confirm").getString();

资源链接

GitHub API 仓库: https://github.com/LoneDev6/API-ItemsAdder
GUI 示例: https://github.com/LoneDev6/API-ItemsAdder-Example-GUI
HUD 示例: https://github.com/LoneDev6/API-ItemsAdder-Example-ServerMonitor
RPG HUDs: https://github.com/LoneDev6/RPGhuds

文档最后更新：基于 ItemsAdder Wiki 内容整理
注意：本文档仅包含 API 用法，不包含 Maven/Gradle 依赖配置信息

Overview

ItemsAdder API 文档

概述

包名和主要类

Java API 详细用法

1. 获取 API 实例

2. 自定义物品操作

获取自定义物品

3. 自定义方块操作

检查自定义方块

4. 自定义实体操作

生成自定义实体

5. 液体 API

6. HUD 操作

设置 HUD 数值

显示/隐藏 HUD

7. 获取表情符号/GUI 字符

8. API 工具方法（静态方法）

检查物品是否已加载

检查是否为自定义物品

获取世界中的自定义方块

检查是否为家具

匹配特定自定义物品

9. 旧 API 方法（仍可用）

获取自定义物品

放置自定义方块

获取自定义方块掉落物

检查是否为自定义方块

种植自定义作物

检查是否为自定义作物

获取自定义种子名称

获取物品配置名称

物品耐久度操作

事件

ItemsAdderLoadDataEvent

ResourcePackSendEvent

Skript API

简单用法

给予自定义物品

检查手持物品是否为自定义物品

使用表情符号

高级用法（需要 skript-reflect）

获取自定义物品

检查点击的方块是否为自定义方块

自定义 GUI

更改 HUD 值

Denizen API

功能特性

示例脚本

变量占位符

玩家相关变量

服务器相关变量

时间相关变量

物品相关变量

经济相关变量（需要 Vault）

权限相关变量（需要 Vault）

占位符API变量（需要 PlaceholderAPI）

注意事项

常见问题

1. 如何检查自定义物品是否存在？

2. 如何获取玩家手中的自定义物品？

3. 如何生成自定义实体？

4. 如何设置 HUD 值？

5. 如何获取表情符号字符串？

资源链接