Meta 扩展

Baikiruto 里和 “Meta” 相关的配置，其实有三条不同的路径：

metas / meta-scripts：真正的 Meta 对象扩展入口，会参与 BUILD / DROP 生命周期，并写入 meta_history
meta：内置效果快捷配置，会被翻译成运行时数据，供版本适配器和功能模块消费
components：现代原版 Data Components；像 damage_resistant、death_protection、use_remainder 这类能力已经更适合写在这里

当前页重点讲前两者，并明确它们和 components 的边界。

Meta 类型

metas / meta-scripts - 真正的 Meta 扩展入口

metas:
  trace:
    scripts:
      build: |
        return item
      drop: |
        return item

这类配置会创建真正的 Meta 实例：

未指定 type 时，默认回退为脚本型 Meta
指定 type / factory / meta_factory / meta-factory 时，会尝试走已注册的 MetaFactory

meta - 内置效果快捷配置

meta:
  durability:
    synchronous: true
    remains: "example:remainder"

  cooldown:
    ticks: 80
    by-player: true

  unique:
    enabled: true
    bind-player: true

meta 不会把这些子节注册成真正的 Meta 对象；它更像一层“内置功能配置入口”。

内置 Meta 功能

1. Durability（耐久系统）

自定义耐久系统入口是 meta.durability，最大耐久本体通常来自 data.durability。

items:
  custom_sword:
    material: "NETHERITE_SWORD"
    data:
      durability: 240

    meta:
      durability:
        synchronous: true
        remains: "example:broken_sword"
        bar-length: 12
        bar-symbol:
          - "&a|"
          - "&7|"

真实字段：

synchronous：是否把自定义耐久同步到原版耐久条；默认 false
remains：耐久耗尽后替换成的物品 ID
bar-length：耐久条长度；默认 10
bar-symbol：耐久条符号 [已填充, 未填充]；默认 ['&a|', '&7|']

真实注入的数据：

durability_current
durability_max
durability_percent
durability_bar

注意：这些显示变量是在 RELEASE 显示阶段注入的，不适合依赖它们去做首次 data-mapper 计算。

2. Cooldown（冷却系统）

items:
  magic_staff:
    meta:
      cooldown:
        ticks: 80
        by-player: true

真实字段：

ticks：冷却时长
time / value：ticks 的兼容别名
by-player：是否按玩家维度存冷却；默认 true

真实注入的数据：

cooldown_remaining
cooldown_remaining_seconds

如果你要让多个物品共享冷却组，请不要写顶层 use-cooldown-group，而是改写为：

components:
  use_cooldown:
    seconds: 4.0
    cooldown_group: "baikiruto:magic_spells"

3. Unique（唯一性 / 绑定系统）

items:
  soulbound_sword:
    meta:
      unique:
        enabled: true
        bind-player: true
        deny-message: "&cThis item belongs to another player."

真实字段：

enabled：默认 true（只要存在该 section）
bind-player：默认 false
deny-message：默认 &cThis item belongs to another player.

真实生成的数据：

unique.uuid
unique.date
unique.player

补充说明：

开启 bind-player: true 后，物品第一次带玩家上下文生成，或第一次被玩家实际触发绑定校验时，会自动写入 unique.player
一旦已经绑定到某个主人，后续重建不会再把主人覆盖成别的玩家
绑定校验现在不只影响普通使用，也会拦截 Shift 点击穿戴、直接点击装备槽穿戴，以及右键空气 / 方块自动穿戴装备
如果你希望装备类物品谁都能穿，不要开启 bind-player

注意：核心监听器当前直接走语言键提示，deny-message 更多是给兼容 API / 第三方调用保留的原始文本。

4. Async Tick（异步轮询策略）

meta.async-tick 用来控制 event.on_async_tick 的派发策略，不写这节时会回落到全局 operations.async-tick.default-interval。

items:
  mana_ring:
    meta:
      async-tick:
        enabled: true
        interval: 20
        conditions:
          sprinting: true
          on-ground: true
          worlds: "world, world_nether"
          game-mode:
            - survival
            - adventure
          permissions:
            - baikiruto.async.fire
            - baikiruto.async.admin
          slots:
            - mainhand
            - offhand

真实字段：

enabled：是否允许该物品触发 on_async_tick；也兼容 async-tick: false 这种简写
interval / ticks / period：单物品触发间隔，写 20 大约就是 1 秒一次
状态条件：sneaking / sneak、sprinting / sprint、swimming / swim、gliding / glide、flying / fly、on-ground / on_ground / onGround / ground、in-vehicle / in_vehicle / inVehicle / vehicle、burning / burn / on-fire / on_fire / fire、blocking / block
槽位条件：slot / slots
世界条件：world / worlds
游戏模式条件：game-mode / game-modes / gamemode / gamemodes
权限条件：permission / permissions / perm / perms
conditions.*：和上面的平铺字段等价，适合把条件集中收纳

写法规则：

布尔条件直接写 true / false
slot(s)、world(s)、game-mode(s)、permission(s) 都可写单个字符串、逗号分隔字符串或列表
worlds 会按世界名小写比对，比如 world、world_nether
game-modes 会自动规范成大写下划线风格，所以 survival、creative、adventure、spectator 都能直接写
permissions 写多个值时命中任意一个即可，不需要全部同时满足

常见槽位写法：

mainhand / hand
offhand
head / helmet
chest / chestplate / body
legs / leggings
feet / boots
hotbar：匹配主手和其他快捷栏格
inventory / storage：匹配主背包区
armor：匹配四件护甲
equipped：匹配主手、副手和四件护甲
all：不限制槽位

补充说明：

这节只负责“何时触发 on_async_tick”，真正的脚本文本还是写在 event.on_async_tick
如果物品根本没写 on_async_tick，这里只是预留策略，不会自己凭空跑脚本
slot 和 slot_index 会一并注入脚本上下文，方便你按背包格做分流

5. Native（原生 NBT 操作）

items:
  custom_item:
    meta:
      native:
        baikiruto:
          source: "example"
        custom:
          nested:
            value: 1

meta.native 会在版本效果应用后，作为最终一轮原生 NBT 覆写。

适合：

写插件自定义 NBT
对最终物品做深层补丁
接入外部系统需要的专用标签

6. Attribute（属性快捷写法）

meta.attribute 的真实格式不是 components.attribute_modifiers 那种 modifier 列表，而是“按槽位分组”的 map。

items:
  strength_ring:
    meta:
      attribute:
        mainhand:
          attack_damage: "6"
          attack_speed: "+10%"

规则：

槽位写在第一层，如 mainhand、offhand、head
属性名直接写 attack_damage、max_health 这类常用短名即可；源码会先做兼容规范化，并在 1.21+ 自动兼容新旧属性常量解析
纯数字会转成 ADD_NUMBER
百分比字符串会转成 MULTIPLY_SCALAR_1

如果你想控制“是保留原版装备自带属性，还是完全替换掉”，还可以补这一层：

items:
  strength_ring:
    meta:
      attribute:
        mainhand:
          attack_damage: "6"
          attack_speed: "+10%"
      attributes-replace-mode: true

补充说明：

attributes-replace-mode 和 attributes-replace 都能用
默认是 false：Baikiruto 只会替换自己加上的 attribute modifiers，保留原版装备自带的护甲、韧性等属性
设为 true：会把已有 attribute modifiers 全部清掉，再只按你当前配置重新写入
近期源码已改成确定性 modifier key，所以同一件物品重复构建、重建或更新时，不会再把同一组属性越叠越高

如果你需要完整的 modifier 列表、显式 operation 或现代组件格式，请改用 components.attribute_modifiers。

7. Potion（药水快捷写法）

items:
  potion_item:
    meta:
      potion:
        base: "speed"
        extended: false
        upgraded: true
        color: "55AAFF"
        effects:
          speed:
            duration: 200
            amplifier: 1
            icon: true

常见字段：

base / base-type / type
extended
upgraded 或 level
color
effects

这条路径是兼容层药水快捷写法；如果你想直接写现代原版药水组件，改用 components.potion_contents。

8. Skull（头颅数据）

items:
  custom_head:
    meta:
      skull:
        owner: "Notch"

除 owner 外，源码还支持：

texture
base64
url
signature
head-database
head_database
hdb

如果你要接 HeadDatabase，常见写法是：

meta:
  skull:
    hdb: "12345"

补充说明：

这个写法依赖 config.yml 里的 operations.hook.head-database.enabled: true
head-database、head_database、hdb 三个键都能用
写成 hdb: "12345" 或 hdb: "hdb:12345" 都可以，源码会自动去掉 hdb: 前缀
HeadDatabase hook 命中后，会把 HDB ID 转成真正的头颅 texture，并覆盖旧的 skull-url

9. Spawner（刷怪笼数据）

items:
  zombie_spawner:
    meta:
      spawner:
        entity: "ZOMBIE"
        delay: 40
        min-delay: 200
        max-delay: 800
        spawn-count: 2
        max-nearby-entities: 8
        required-player-range: 16
        spawn-range: 4

注意真实字段名是：

min-delay
max-delay

而不是常见猜测写法里的 min-spawn-delay / max-spawn-delay。

不再建议放在 meta 里的能力

以下能力当前更适合直接写在 components：

damage_resistant
death_protection
use_remainder
use_cooldown
equippable
potion_contents

推荐写法示例：

components:
  damage_resistant:
    enabled: true
    types:
      - "fire"
  death_protection:
    enabled: true
    health: 10.0
    consume: true
  use_remainder:
    id: "example:remainder"
    amount: 1

Meta 生命周期

真正的 `metas` 生命周期

对 metas 生成出来的真实 Meta 对象，可以这样理解：

Item.build()
  -> item scripts.build
  -> meta.build()
  -> meta scripts.build
  -> toItemStack()
  -> meta.drop() / meta scripts.drop（在销毁或 drop 流程中逆序执行）

这类 Meta 会进入 meta_history。

`meta` 内置效果的生效阶段

meta 不是一组真正的 Meta 对象。它更像是把配置翻译为运行时数据，随后在不同阶段分别生效：

unique：在 toItemStack() 前段预处理
durability / cooldown：在显示渲染前注入显示数据
attribute / potion / skull / spawner：在版本适配阶段应用到最终物品
native：最后一轮覆写最终 NBT

自定义 Meta

创建 MetaFactory

object CustomMetaFactory : MetaFactory {
    override val id: String = "custom"

    override fun create(
        metaId: String,
        source: Map<String, Any?>,
        scripts: ItemScriptHooks
    ): Meta? {
        return object : Meta {
            override val id: String = metaId
            override val scripts: ItemScriptHooks = scripts

            override fun build(stream: ItemStream) {
                stream.setRuntimeData("custom.flag", true)
            }

            override fun drop(stream: ItemStream) {
            }
        }
    }
}

注册 MetaFactory

Baikiruto.api().registerMetaFactory(CustomMetaFactory)

使用自定义 Meta

metas:
  custom_trace:
    type: "custom"
    option1: "value1"
    option2: 123
    scripts:
      build: |
        return item

关键点：

自定义工厂注册到 MetaFactory 注册表
配置入口使用 metas，不是 meta
类型字段可以写 type、factory、meta_factory、meta-factory

Meta 应用历史

Baikiruto 会把真正应用过的 Meta.id 记录到：

baikiruto:
  meta_history:
    - trace
    - custom_trace

注意：这里记录的是 metas 生成出的真实 Meta 条目，不是 meta.durability、meta.cooldown 这类内置快捷配置名。

实战示例

默认示例中的组合写法

metas:
  trace:
    scripts:
      build: |
        return item

meta:
  durability:
    synchronous: true
    remains: "example:remainder"
  cooldown:
    ticks: 80
    by-player: true
  unique:
    enabled: true
    bind-player: true
  native:
    baikiruto:
      source: "example-all-features"
  attribute:
    mainhand:
      attack_damage: "6"
      attack_speed: "+10%"

这也是 items/example.yml 当前展示的真实组合：

metas 负责真正的 Meta 生命周期
meta 负责内置快捷配置
更现代的原版组件继续放在 components

下一步

查看原版组件了解 damage_resistant、death_protection、use_remainder 等现代组件写法
查看物品配置了解 meta / metas 在完整物品配置中的位置
查看脚本系统了解脚本触发器和执行上下文 value1" option2: 123 scripts: build: | return item

关键点：
- 自定义工厂注册到 `MetaFactory` 注册表
- 配置入口使用 `metas`，不是 `meta`
- 类型字段可以写 `type`、`factory`、`meta_factory`、`meta-factory`

## Meta 应用历史

Baikiruto 会把真正应用过的 `Meta.id` 记录到：

```yaml
baikiruto:
  meta_history:
    - trace
    - custom_trace

注意：这里记录的是 metas 生成出的真实 Meta 条目，不是 meta.durability、meta.cooldown 这类内置快捷配置名。

实战示例

默认示例中的组合写法

metas:
  trace:
    scripts:
      build: |
        return item

meta:
  durability:
    synchronous: true
    remains: "example:remainder"
  cooldown:
    ticks: 80
    by-player: true
  unique:
    enabled: true
    bind-player: true
  native:
    baikiruto:
      source: "example-all-features"
  attribute:
    mainhand:
      attack_damage: "6"
      attack_speed: "+10%"

这也是 items/example.yml 当前展示的真实组合：

metas 负责真正的 Meta 生命周期
meta 负责内置快捷配置
更现代的原版组件继续放在 components

下一步

查看原版组件了解 damage_resistant、death_protection、use_remainder 等现代组件写法
查看物品配置了解 meta / metas 在完整物品配置中的位置
查看脚本系统了解脚本触发器和执行上下文

Meta 类型​

metas / meta-scripts - 真正的 Meta 扩展入口​

meta - 内置效果快捷配置​

内置 Meta 功能​

1. Durability（耐久系统）​

2. Cooldown（冷却系统）​

3. Unique（唯一性 / 绑定系统）​

4. Async Tick（异步轮询策略）​

5. Native（原生 NBT 操作）​

6. Attribute（属性快捷写法）​

7. Potion（药水快捷写法）​

8. Skull（头颅数据）​

9. Spawner（刷怪笼数据）​

不再建议放在 meta 里的能力​

Meta 生命周期​

真正的 metas 生命周期​

meta 内置效果的生效阶段​

自定义 Meta​

创建 MetaFactory​

注册 MetaFactory​

使用自定义 Meta​

Meta 应用历史​

实战示例​

默认示例中的组合写法​

下一步​

实战示例​

默认示例中的组合写法​

下一步​

Meta 类型

metas / meta-scripts - 真正的 Meta 扩展入口

meta - 内置效果快捷配置

内置 Meta 功能

1. Durability（耐久系统）

2. Cooldown（冷却系统）

3. Unique（唯一性 / 绑定系统）

4. Async Tick（异步轮询策略）

5. Native（原生 NBT 操作）

6. Attribute（属性快捷写法）

7. Potion（药水快捷写法）

8. Skull（头颅数据）

9. Spawner（刷怪笼数据）

不再建议放在 meta 里的能力

Meta 生命周期

真正的 `metas` 生命周期

`meta` 内置效果的生效阶段

自定义 Meta

创建 MetaFactory

注册 MetaFactory

使用自定义 Meta

Meta 应用历史

实战示例

默认示例中的组合写法

下一步

实战示例

默认示例中的组合写法

下一步