Concepts of SAPI: Properties & DynamicProperties
本帖最后由 冥王大大 于 2025-10-13 20:14 编辑前言
在SAPI的脚本中，可以发现物品堆栈类（ItemStack Class）和实体类（Entity Class）都有.getDynamicProperty()和.setDynamicProperty()方法；而只有实体类有.getProperty()和.setProperty()方法。它们分别对应的是“自定义属性（DynamicProperties，有时也作CustomProperties）”和“属性（Properties）”的概念。注意，这里介绍的并不等同于JavaScript定义中的属性。
讲述
首先我们需要知道，属性和组件（Components）不同，组件可以与多种数据交互或储存，而属性只能储存一种类型的数据。让我们查看官方文档中的定义：
其中三维向量类是一种包含x、y、z三个属性的对象，我们知道一个属性只能对应一种类型的数值。自定义属性会以数据的形式储存在存档中的实体或物品NBT的标签组下。而属性在实体和方块中都有所体现，不过方块用的是一组属性的概念：序列（Permutation）。在实体类的文档中，我们可以看到：
这些属性通常要在相应的行为包文件中定义。我们拿狼举例：
其中某些属性会在驯服后改变，行为包事件也为属性增加了新关键字：“set_property”。不过，这里主讲的是SAPI中对属性的运用，感兴趣可以去官方github仓库查看原版的实体文件。
应用
我们知道定义文件中狼存在3个布尔值属性，1个枚举属性。它们分别用于决定是否可以给其装备狼铠、是否增加狼的最大生命值（在原版行为中驯服后就会增加狼的最大生命值）、狼的声音变体，以及标记是否已在1.21.100更新过该狼实体。
我们可以借助.setProperty()方法来使其变为使用“可爱”声音变体的狼：import { world, system } from "@minecraft/server"
system.runInterval(() => {
const wolf = world.getEntity("狼的唯一标识符")
wolf.setProperty("minecraft:sound_variant", "cute")
})
其中获得狼实体的方法仅演示用，个人不推荐用world.getEntity()方法，因为有其他方法可以直接获得实体，而实体的唯一标识符通常是要先获取实体才能得到。对于自定义属性，因为原版中没有定义这样的属性（即使你在实体行为文件中定义的新属性也不叫“DynamicProperty”，不过这样的属性在原版中也没有相应的作用），所以你需要借助SAPI来定义它的效果。比如：import { world } from "@minecraft/server"
world.afterEvents.itemUse.subscribe(event => {
event.itemStack.setDynamicProperty("tpspot", { x: 1, y: 1, z: 1 })
if (event.itemStack.typeId === "minecraft:bow") {
event.source.teleport(event.itemStack.getDynamicProperty("tpspot"))
}
})
这样你在拉弓的时候就会传送至坐标为1,1,1的位置。
总结
在这里先打一个小补丁，官方文档中的字段后面是半角冒号的，表示该字段的参数是必填项，带半角问号和半角冒号的表示该字段的参数可以不填，也就是可以留空（或设置为null）。以上的演示代码基本符合@minecraft-server-2.0.0以后的格式，如果你知道如何使用SAPI脚本就可以直接复制到.js文件中进行试验。
感谢作者分享！说实话之前还蛮看不懂DynamicProperties是什么意思。
页: [1]