物品与方块

本页收录 ItemBuiltins 和 BlockBuiltins，主要覆盖主手 / 槽位 / 背包 / NBT，以及周围方块环境读取。

物品附魔等级

• 用法：物品附魔等级(附魔名)
• 参数：附魔名
• 返回值：Number

赋值 sharp = 物品附魔等级("锋利")
发送消息("&f锋利等级: " + sharp)

物品包含Lore

• 用法：物品包含Lore(文本)
• 参数：要查找的文本
• 返回值：Boolean

判断 (物品包含Lore("&6任务物品")) {
  发送消息("&a已识别任务物品")
}

物品拥有NBT

• 用法：物品拥有NBT(NBT路径)
• 参数：NBT 路径
• 返回值：Boolean

判断 (物品拥有NBT("quest.id")) {
  发送消息("&b物品已带任务标签")
}

槽位物品类型

• 用法：槽位物品类型(槽位)
• 参数：槽位表达式
• 返回值：String
• 补充说明：支持 主手 / 副手 / 头盔 / 胸甲 / 护腿 / 靴子 及对应英文别名，也支持直接传库存索引；源码会先按原始数字槽位解析，所以数字字符串表示的是库存下标，不是单独的快捷栏序号别名。

赋值 type = 槽位物品类型("主手")
发送消息("&f主手类型: " + type)

槽位物品名称

• 用法：槽位物品名称(槽位)
• 参数：槽位表达式
• 返回值：String

赋值 name = 槽位物品名称("头盔")
发送消息("&f头盔名称: " + name)

槽位物品数量

• 用法：槽位物品数量(槽位)
• 参数：槽位表达式
• 返回值：Number

赋值 amount = 槽位物品数量("0")
发送消息("&7槽位数量: " + amount)

槽位物品附魔

• 用法：槽位物品附魔(槽位, 附魔名)
• 参数：槽位、附魔名
• 返回值：Number

赋值 level = 槽位物品附魔("主手", "锋利")
发送消息("&f主手锋利等级: " + level)

槽位有物品

• 用法：槽位有物品(槽位)
• 参数：槽位表达式
• 返回值：Boolean
• 补充说明：副手读取走 VersionCompat，因此在 1.7-1.8 没有副手 API 的版本会直接视为无物品。

判断 (槽位有物品("副手")) {
  发送消息("&a副手存在物品")
}

槽位物品Lore包含

• 用法：槽位物品Lore包含(槽位, 文本)
• 参数：槽位、文本
• 返回值：Boolean

判断 (槽位物品Lore包含("主手", "&d史诗")) {
  发送消息("&d检测到史诗 Lore")
}

背包包含物品

• 用法：背包包含物品(材料, 名称)
• 参数：材料、显示名或 "null"
• 返回值：Boolean

判断 (背包包含物品("DIAMOND", "null")) {
  发送消息("&b背包里有钻石")
}

获取物品数量

• 用法：获取物品数量(材料, 名称)
• 参数：材料、显示名或 "null"
• 返回值：Number

赋值 count = 获取物品数量("DIAMOND", "null")
发送消息("&f钻石数量: " + count)

存在未标记物品

• 用法：存在未标记物品(材料, 名称)
• 参数：材料、显示名或 "null"
• 返回值：Boolean

判断 (存在未标记物品("PAPER", "&6任务凭证")) {
  发送消息("&e检测到未标记任务物品")
}

获取物品NBT值

• 用法：获取物品NBT值(NBT路径)
• 参数：NBT 路径
• 返回值：Object

赋值 value = 获取物品NBT值("quest.id")
发送消息("&7NBT 值: " + value)

槽位物品NBT值

• 用法：槽位物品NBT值(槽位, NBT路径)
• 参数：槽位、NBT 路径
• 返回值：Object

赋值 value = 槽位物品NBT值("主手", "quest.id")
发送消息("&7槽位 NBT: " + value)

设置物品NBT值

• 用法：设置物品NBT值(NBT路径, 值)
• 参数：NBT 路径、字符串值
• 返回值：Boolean
• 补充说明：这组 NBT 写入函数只会修改当前主手物品，并通过兼容层把修改后的物品写回主手；源码没有“直接写回任意槽位 NBT”的对应函数。

设置物品NBT值("quest.id", "daily_001")
发送消息("&a已写入字符串 NBT")

设置物品数字NBT

• 用法：设置物品数字NBT(NBT路径, 值)
• 参数：NBT 路径、数字值
• 返回值：Boolean
• 补充说明：作用范围同样是当前主手物品；如果主手为空，函数会失败并返回 false。

设置物品数字NBT("quest.step", 3)
发送消息("&a已写入数字 NBT")

删除物品NBT

• 用法：删除物品NBT(NBT路径)
• 参数：NBT 路径
• 返回值：Boolean
• 补充说明：删除操作只针对当前主手物品执行。

删除物品NBT("quest.id")
发送消息("&c已删除指定 NBT")

增加物品数字NBT

• 用法：增加物品数字NBT(NBT路径, 增量)
• 参数：NBT 路径、增量
• 返回值：Number
• 补充说明：读取不到旧值时会按 0 起算，再把结果写回主手物品。

赋值 value = 增加物品数字NBT("quest.count", 1)
发送消息("&a新计数: " + value)

减少物品数字NBT

• 用法：减少物品数字NBT(NBT路径, 减量)
• 参数：NBT 路径、减量
• 返回值：Number
• 补充说明：和增加函数一样，只处理当前主手物品；旧值解析失败时按 0 处理。

赋值 value = 减少物品数字NBT("quest.count", 1)
发送消息("&e剩余计数: " + value)

获取手持物品类型

• 用法：获取手持物品类型()
• 参数：无
• 返回值：String
• 补充说明：读取的是主手物品；没有物品时返回 AIR。

赋值 type = 获取手持物品类型()
发送消息("&f手持类型: " + type)

获取手持物品名称

• 用法：获取手持物品名称()
• 参数：无
• 返回值：String

赋值 name = 获取手持物品名称()
发送消息("&f手持名称: " + name)

获取手持物品数量

• 用法：获取手持物品数量()
• 参数：无
• 返回值：Number
• 补充说明：读取的是主手物品；没有物品时返回 0。

赋值 amount = 获取手持物品数量()
发送消息("&7手持数量: " + amount)

手持物品是否为空

• 用法：手持物品是否为空()
• 参数：无
• 返回值：Boolean
• 补充说明：源码判空条件是“主手物品为 null 或材质为 AIR”。

判断 (手持物品是否为空()) {
  发送消息("&7当前主手为空")
}

获取脚下方块

• 用法：获取脚下方块()
• 参数：无
• 返回值：String

赋值 block = 获取脚下方块()
发送消息("&f脚下方块: " + block)

获取头顶方块

• 用法：获取头顶方块()
• 参数：无
• 返回值：String

赋值 block = 获取头顶方块()
发送消息("&f头顶方块: " + block)

获取当前方块

• 用法：获取当前方块()
• 参数：无
• 返回值：String

赋值 block = 获取当前方块()
发送消息("&f当前位置方块: " + block)

获取相邻方块

• 用法：获取相邻方块(方向)
• 参数：方向字符串
• 返回值：String

赋值 block = 获取相邻方块("北")
发送消息("&f北侧方块: " + block)

获取偏移方块

• 用法：获取偏移方块(X偏移, Y偏移, Z偏移)
• 参数：三个偏移量
• 返回值：String

赋值 block = 获取偏移方块(1, 0, 0)
发送消息("&f偏移方块: " + block)

获取方块类型

• 用法：获取方块类型(X, Y, Z)
• 参数：目标坐标
• 返回值：String

赋值 block = 获取方块类型(100, 64, 200)
发送消息("&f目标方块: " + block)

前方有墙

• 用法：前方有墙(距离)
• 参数：距离，可省略
• 返回值：Boolean

判断 (前方有墙(2)) {
  发送消息("&c前方两格内有固体方块")
}

脚下有方块

• 用法：脚下有方块()
• 参数：无
• 返回值：Boolean

判断 (脚下有方块()) {
  发送消息("&a脚下存在实体方块")
}

在水中

• 用法：在水中()
• 参数：无
• 返回值：Boolean

判断 (在水中()) {
  发送消息("&b当前位置是水")
}

在岩浆中

• 用法：在岩浆中()
• 参数：无
• 返回值：Boolean

判断 (在岩浆中()) {
  发送消息("&c当前位置是岩浆")
}

方块是

• 用法：方块是(方向, 类型)
• 参数：方向、材质名
• 返回值：Boolean

判断 (方块是("当前", "STONE")) {
  发送消息("&7你正站在石头上")
}

获取朝向方位

• 用法：获取朝向方位()
• 参数：无
• 返回值：String

赋值 facing = 获取朝向方位()
发送消息("&f当前朝向: " + facing)