物品与容器¶

abi.h 里的分节说明

§E 物品（SNBT 值对象）与容器（§E items (SNBT value objects) & containers）

物品：附魔、匹配、NBT（专用函数）（Item: enchants, matching, NBT (dedicated fns)）

让客户端重新同步容器（Client-side container resync）

container_set_item、_clear、_add_item 都经 Container::setItem 写入，它只修改服务器上的副本，不发送任何东西。客户端继续显示它最后收到的内容，所以批量重写（比如跨维度传送时换掉玩家的物品栏）看起来像什么都没发生，直到玩家点一下某个格子，强制重新同步。

在一批写入之后调用一次这个槽位。要成批调用：它推送的是整个容器，在循环里每改一格调一次，只会发出大量数据包，没有任何好处。

追加：批量读写方块（Appended: bulk block reads and writes）

槽位¶

`item_get_num`¶

C
bool (*item_get_num)(PierStr item_snbt, int32_t prop, double* out);

调用形式：api->item_get_num(item_snbt, prop, out)
参数：
- item_snbt : PierStr
- prop : int32_t
- out : double*
返回值类型：bool
所在分节：§E 物品（SNBT 值对象）与容器（§E items (SNBT value objects) & containers）
表内序号：第 43 个槽位（从 0 数起）
各绑定里的调用方：
- Rust：ItemStack::num、ItemStack::count、ItemStack::max_stack_size、ItemStack::aux_value、ItemStack::id、ItemStack::damage 等，共 29 个
- Go：Item.Count、Item.MaxStackSize、Item.AuxValue、Item.Id、Item.Damage、Item.IsNull 等，共 29 个
- Zig：Item.count、Item.maxStackSize、Item.auxValue、Item.id、Item.damage、Item.isNull 等，共 28 个

`item_get_str`¶

C
bool (*item_get_str)(PierStr item_snbt, int32_t prop, void* ctx, PierStrSink sink);

调用形式：api->item_get_str(item_snbt, prop, ctx, sink)
参数：
- item_snbt : PierStr
- prop : int32_t
- ctx : void*
- sink : PierStrSink
返回值类型：bool
所在分节：§E 物品（SNBT 值对象）与容器（§E items (SNBT value objects) & containers）
表内序号：第 44 个槽位（从 0 数起）
各绑定里的调用方：
- Rust：ItemStack::text、ItemStack::type_name、ItemStack::name、ItemStack::custom_name、ItemStack::hover_name、ItemStack::raw_name_id 等，共 11 个
- Go：Item.TypeName、Item.Name、Item.CustomName、Item.RawNameId、Item.Lore、Item.CanDestroy 等，共 12 个
- Zig：Item.typeName、Item.name、Item.customName、Item.rawNameId、Item.lore、Item.canDestroy 等，共 11 个

`item_transform`¶

C
bool (*item_transform)(PierStr item_snbt, int32_t op, PierStr sarg, double narg, void* ctx, PierStrSink out);

先重建物品，再修改，最后序列化；out 收到的是新的物品 SNBT。

调用形式：api->item_transform(item_snbt, op, sarg, narg, ctx, out)
参数：
- item_snbt : PierStr
- op : int32_t
- sarg : PierStr
- narg : double
- ctx : void*
- out : PierStrSink
返回值类型：bool
所在分节：§E 物品（SNBT 值对象）与容器（§E items (SNBT value objects) & containers）
表内序号：第 45 个槽位（从 0 数起）
各绑定里的调用方：
- Rust：ItemStack::transform、ItemStack::set_custom_name、ItemStack::reset_name、ItemStack::set_damage、ItemStack::set_count、ItemStack::set_unbreakable 等，共 14 个
- Go：Item.Transform、Raw.ItemTransform

`container_size`¶

C
bool (*container_size)(PierContainerRef ref, int32_t* out);

调用形式：api->container_size(ref, out)
参数：
- ref : PierContainerRef
- out : int32_t*
返回值类型：bool
所在分节：§E 物品（SNBT 值对象）与容器（§E items (SNBT value objects) & containers）
表内序号：第 46 个槽位（从 0 数起）
各绑定里的调用方：
- Rust：Container::size、Container::items
- Go：Container.Size、Raw.ContainerSize

`container_get_item`¶

C
bool (*container_get_item)(PierContainerRef ref, int32_t slot, void* ctx, PierStrSink sink);

这一格的内容，以物品 SNBT 给出（空格子给出空气物品的 SNBT）。

调用形式：api->container_get_item(ref, slot, ctx, sink)
参数：
- ref : PierContainerRef
- slot : int32_t
- ctx : void*
- sink : PierStrSink
返回值类型：bool
所在分节：§E 物品（SNBT 值对象）与容器（§E items (SNBT value objects) & containers）
表内序号：第 47 个槽位（从 0 数起）
各绑定里的调用方：
- Rust：Container::item、Container::items
- Go：Container.Item、Raw.ContainerGetItem

`container_set_item`¶

C
bool (*container_set_item)(PierContainerRef ref, int32_t slot, PierStr item_snbt);

调用形式：api->container_set_item(ref, slot, item_snbt)
参数：
- ref : PierContainerRef
- slot : int32_t
- item_snbt : PierStr
返回值类型：bool
所在分节：§E 物品（SNBT 值对象）与容器（§E items (SNBT value objects) & containers）
表内序号：第 48 个槽位（从 0 数起）
各绑定里的调用方：
- Rust：Container::set_item
- Go：Container.SetItem、Raw.ContainerSetItem

`container_add_item`¶

C
bool (*container_add_item)(PierContainerRef ref, PierStr item_snbt);

调用形式：api->container_add_item(ref, item_snbt)
参数：
- ref : PierContainerRef
- item_snbt : PierStr
返回值类型：bool
所在分节：§E 物品（SNBT 值对象）与容器（§E items (SNBT value objects) & containers）
表内序号：第 49 个槽位（从 0 数起）
各绑定里的调用方：
- Rust：Container::add_item
- Go：Container.AddItem、Raw.ContainerAddItem

`container_remove_item`¶

C
bool (*container_remove_item)(PierContainerRef ref, int32_t slot, int32_t count);

调用形式：api->container_remove_item(ref, slot, count)
参数：
- ref : PierContainerRef
- slot : int32_t
- count : int32_t
返回值类型：bool
所在分节：§E 物品（SNBT 值对象）与容器（§E items (SNBT value objects) & containers）
表内序号：第 50 个槽位（从 0 数起）
各绑定里的调用方：
- Rust：Container::remove_item
- Go：Container.RemoveItem、Raw.ContainerRemoveItem

`container_clear`¶

C
bool (*container_clear)(PierContainerRef ref);

调用形式：api->container_clear(ref)
参数：
- ref : PierContainerRef
返回值类型：bool
所在分节：§E 物品（SNBT 值对象）与容器（§E items (SNBT value objects) & containers）
表内序号：第 51 个槽位（从 0 数起）
各绑定里的调用方：
- Rust：Container::clear
- Go：Container.Clear、Raw.ContainerClear

`item_get_enchants`¶

C
bool (*item_get_enchants)(PierStr item_snbt, void* ctx, PierStrSink sink);

SNBT [{id, level},…]

调用形式：api->item_get_enchants(item_snbt, ctx, sink)
参数：
- item_snbt : PierStr
- ctx : void*
- sink : PierStrSink
返回值类型：bool
所在分节：物品：附魔、匹配、NBT（专用函数）（Item: enchants, matching, NBT (dedicated fns)）
表内序号：第 125 个槽位（从 0 数起）
各绑定里的调用方：
- Rust：ItemStack::enchants
- Go：Item.Enchants、Raw.ItemGetEnchants

`item_set_enchants`¶

C
bool (*item_set_enchants)(PierStr item_snbt, PierStr enchants_snbt, void* ctx, PierStrSink out);

enchants_snbt 形如 [{id, level},…]；out 收到新的物品 SNBT。当前所有宿主上这个槽位都是 NULL：写附魔还没有实现，读取一侧是 item_get_enchants。

调用形式：api->item_set_enchants(item_snbt, enchants_snbt, ctx, out)
参数：
- item_snbt : PierStr
- enchants_snbt : PierStr
- ctx : void*
- out : PierStrSink
返回值类型：bool
所在分节：物品：附魔、匹配、NBT（专用函数）（Item: enchants, matching, NBT (dedicated fns)）
表内序号：第 126 个槽位（从 0 数起）
各绑定里的调用方：
- Rust：ItemStack::with_enchants
- Go：Raw.ItemSetEnchants

`item_matches`¶

C
bool (*item_matches)(PierStr a, PierStr b);

调用形式：api->item_matches(a, b)
参数：
- a : PierStr
- b : PierStr
返回值类型：bool
所在分节：物品：附魔、匹配、NBT（专用函数）（Item: enchants, matching, NBT (dedicated fns)）
表内序号：第 127 个槽位（从 0 数起）
各绑定里的调用方：
- Rust：ItemStack::matches
- Go：Item.Matches、Raw.ItemMatches

`item_get_user_data`¶

C
bool (*item_get_user_data)(PierStr item_snbt, void* ctx, PierStrSink sink);

调用形式：api->item_get_user_data(item_snbt, ctx, sink)
参数：
- item_snbt : PierStr
- ctx : void*
- sink : PierStrSink
返回值类型：bool
所在分节：物品：附魔、匹配、NBT（专用函数）（Item: enchants, matching, NBT (dedicated fns)）
表内序号：第 128 个槽位（从 0 数起）
各绑定里的调用方：
- Rust：ItemStack::user_data
- Go：Raw.ItemGetUserData

`container_refresh`¶

C
bool (*container_refresh)(PierContainerRef ref);

把玩家自己的容器（which 为 0 到 3）重新发给它的主人。方块容器（which == 4）返回 false：箱子没有唯一的主人可以重发，正在看它的玩家由引擎自己的容器事务流程刷新。

调用形式：api->container_refresh(ref)
参数：
- ref : PierContainerRef
返回值类型：bool
所在分节：让客户端重新同步容器（Client-side container resync）
表内序号：第 155 个槽位（从 0 数起）
各绑定里的调用方：
- Rust：Container::refresh
- Go：Raw.ContainerRefresh

`container_get_items`¶

C
bool (*container_get_items)(PierContainerRef ref, void* ctx, PierSlotSink sink);

一次调用读出容器的每一格：输出回调按顺序对每一格收到 (槽位, 物品 SNBT)，空格子也在内，给的是空物品的快照。解析一次容器、跨一次 FFI，代替原来每一格各一次。容器解析不出来时返回 false。只能在服务器线程调用。

调用形式：api->container_get_items(ref, ctx, sink)
参数：
- ref : PierContainerRef
- ctx : void*
- sink : PierSlotSink
返回值类型：bool
所在分节：追加：批量读写方块（Appended: bulk block reads and writes）
表内序号：第 192 个槽位（从 0 数起）
各绑定里的调用方：
- Rust：Container::items
- Go：ContainerItems、Container.Items

`PierItemNumProp`¶

item_get_num 的键（查询的是从 SNBT 临时重建的 ItemStack）。

名称	值	说明
`PIER_IPROP_COUNT`	`0`	取自 `ItemStackBase::mCount`
`PIER_IPROP_MAX_STACK_SIZE`	`1`	取自 `ItemStackBase::getMaxStackSize`
`PIER_IPROP_AUX_VALUE`	`2`	取自 `ItemStackBase::getAuxValue`
`PIER_IPROP_ID`	`3`	取自 `ItemStackBase::getId`
`PIER_IPROP_DAMAGE`	`4`	取自 `ItemStackBase::getDamageValue`
`PIER_IPROP_IS_NULL`	`5`	取自 `ItemStackBase::isNull`
`PIER_IPROP_IS_BLOCK`	`6`	取自 `ItemStackBase::isBlock`
`PIER_IPROP_IS_ENCHANTED`	`7`	取自 `ItemStackBase::isEnchanted`
`PIER_IPROP_IS_ARMOR`	`8`	取自 `ItemStackBase::isArmorItem`
`PIER_IPROP_IS_DAMAGEABLE`	`9`	取自 `ItemStackBase::isDamageableItem`
`PIER_IPROP_IS_DAMAGED`	`10`	取自 `ItemStackBase::isDamaged`
`PIER_IPROP_MAX_DAMAGE`	`11`	取自 `ItemStackBase::getMaxDamage`
`PIER_IPROP_IS_UNBREAKABLE`	`12`	取自 `ItemStackBase::isUnbreakable`
`PIER_IPROP_HAS_DURABILITY`	`13`	取自 `ItemStackBase::hasDurability`
`PIER_IPROP_IS_POTION`	`14`	取自 `ItemStackBase::isPotionItem`
`PIER_IPROP_IS_THROWABLE`	`15`	取自 `ItemStackBase::isThrowable`
`PIER_IPROP_IS_FIRE_RESISTANT`	`16`	取自 `ItemStackBase::isFireResistant`
`PIER_IPROP_ATTACK_DAMAGE`	`17`	取自 `ItemStackBase::getAttackDamage`
`PIER_IPROP_REPAIR_COST`	`18`	取自 `ItemStackBase::getBaseRepairCost`
`PIER_IPROP_ENCHANT_VALUE`	`19`	取自 `ItemStackBase::getEnchantValue`
`PIER_IPROP_IS_STACKABLE`	`20`	取自 `ItemStackBase::isStackable`
`PIER_IPROP_IS_MUSIC_DISC`	`21`	取自 `ItemStackBase::isMusicDiscItem`
`PIER_IPROP_IS_OFFHAND`	`22`	取自 `ItemStackBase::isOffhandItem`
`PIER_IPROP_USE_DURATION`	`23`	取自 `ItemStackBase::getMaxUseDuration`
`PIER_IPROP_IS_GLINT`	`24`	取自 `ItemStackBase::isGlint`
`PIER_IPROP_IS_BUNDLE`	`25`	取自 `ItemStackBase::isBundle`
`PIER_IPROP_HAS_USER_DATA`	`26`	取自 `ItemStackBase::hasUserData`
`PIER_IPROP_HAS_CUSTOM_NAME`	`27`	取自 `ItemStackBase::hasCustomHoverName`

`PierItemStrProp`¶

item_get_str 的键。

名称	值	说明
`PIER_ISTR_TYPE_NAME`	`0`	取自 `ItemStackBase::getTypeName`（形如 `"minecraft:apple"`）
`PIER_ISTR_NAME`	`1`	取自 `ItemStackBase::getName`（显示名）
`PIER_ISTR_CUSTOM_NAME`	`2`	取自 `ItemStackBase::getCustomName`
`PIER_ISTR_RAW_NAME_ID`	`3`	取自 `ItemStackBase::getRawNameId`
`PIER_ISTR_LORE`	`4`	SNBT 列表 `["l1","l2"]`，取自 `ItemStackBase::getCustomLore`
`PIER_ISTR_CAN_DESTROY`	`5`	SNBT 列表 `["minecraft:stone",…]`
`PIER_ISTR_CAN_PLACE_ON`	`6`	SNBT 列表
`PIER_ISTR_USER_DATA`	`7`	完整的 NBT 用户数据，以 SNBT 表示
`PIER_ISTR_HOVER_NAME`	`8`	取自 `ItemStackBase::getHoverName`
`PIER_ISTR_EFFECT_NAME`	`9`	取自 `ItemStackBase::getEffectName`
`PIER_ISTR_COLOR`	`10`	SNBT `{r,g,b}`，取自 `ItemStackBase::getColor`

`PierItemOp`¶

item_transform 的操作：重建，修改，再序列化回去（out 收到新的 SNBT）。

名称	值	说明
`PIER_IOP_SET_CUSTOM_NAME`	`0`	`sarg` 为名字，调用 `ItemStackBase::setCustomName`
`PIER_IOP_SET_DAMAGE`	`1`	`narg` 为损耗值，调用 `ItemStackBase::setDamageValue`
`PIER_IOP_SET_COUNT`	`2`	`narg` 为数量，写入 `ItemStackBase::mCount`
`PIER_IOP_SET_LORE`	`3`	`sarg` 为 SNBT 列表 `["l1","l2"]`，调用 `ItemStackBase::setCustomLore`
`PIER_IOP_SET_UNBREAKABLE`	`4`	`narg` 为 0 或 1，调用 `ItemStackBase::setUnbreakable`
`PIER_IOP_HURT_AND_BREAK`	`5`	`narg` 为伤害值，调用 `ItemStackBase::hurtAndBreak`
`PIER_IOP_SET_REPAIR_COST`	`6`	`narg` 为修复花费，调用 `ItemStackBase::setRepairCost`
`PIER_IOP_ADD_ENCHANT`	`7`	`sarg` 为 `"name:level"`，经 `saveEnchantsToUserData` 写入
`PIER_IOP_REMOVE_ENCHANTS`	`8`	调用 `ItemStackBase::removeEnchants`
`PIER_IOP_CLEAR_LORE`	`9`	调用 `ItemStackBase::clearCustomLore`
`PIER_IOP_RESET_NAME`	`10`	调用 `ItemStackBase::resetHoverName`
`PIER_IOP_SET_CAN_DESTROY`	`11`	`sarg` 为 SNBT 列表，调用 `ItemStackBase::setCanDestroy`
`PIER_IOP_SET_CAN_PLACE_ON`	`12`	`sarg` 为 SNBT 列表，调用 `ItemStackBase::setCanPlaceOn`

物品与容器¶

槽位¶

item_get_num¶

item_get_str¶

item_transform¶

container_size¶

container_get_item¶

container_set_item¶

container_add_item¶

container_remove_item¶

container_clear¶

item_get_enchants¶

item_set_enchants¶

item_matches¶

item_get_user_data¶

container_refresh¶

container_get_items¶

PierItemNumProp¶

PierItemStrProp¶

PierItemOp¶