跳到主要内容

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
        apply-on-cancelled-triggers:
          - on_right_click

真实字段：

  • ticks：冷却时长
  • time / value：ticks 的兼容别名
  • by-player：是否按玩家维度存冷却；默认 true
  • apply-on-cancelled-triggers：指定哪些触发器即使取消了底层事件，也仍然写入本次冷却

apply-on-cancelled-triggers 也可以写成 apply_on_cancelled_triggers、applyOnCancelledTriggers、cancelled-triggers、cancelled_triggers。列表值按脚本触发器别名解析，例如 on_right_click / right_click 都会归一化为 right_click；写错的触发器会被忽略。

这个选项只影响“触发器执行后把事件取消了”的情况。没有配置时，取消事件不会消耗冷却；配置后，命中的触发器取消事件也会进入冷却。

真实注入的数据：

  • 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。

10. Drop Display（掉落实体显示）​

meta.drop 用来控制物品掉到地上之后的实体显示名。

items:
  protected_artifact:
    meta:
      drop:
        display-name: "&6Protected Artifact"
        display-visible: true

真实字段：

  • display-name / display_name / displayName / name：掉落实体的自定义显示名
  • display-visible / display_visible / displayVisible / visible：是否让显示名常显；默认 true

兼容简写：

meta:
  drop-name: "&6Protected Artifact"
  drop-visible: true

说明：

  • 这只影响掉在地上的 Item 实体，不会改背包里物品的名称和 Lore
  • 显示名会走 & 颜色代码转换
  • 如果显示名为空，源码会直接忽略这项配置

11. Protection（保护规则）​

meta.protection 用来限制物品被合成、放进特定容器，或者作为掉落实体被环境伤害销毁。

items:
  protected_artifact:
    meta:
      protection:
        crafting:
          any: true
          stations:
            - ANVIL
            - GRINDSTONE
            - SMITHING
        containers:
          deny:
            - HOPPER
            - FURNACE
            - ARMOR_STAND
        destroy:
          enabled: true
          causes:
            - fire
            - lava
            - cactus
            - lightning

protection 也可以写成 protect 或 rules。

crafting​

crafting 控制合成和工作站操作：

  • crafting: true：直接拦截所有合成 / 工作站场景
  • vanilla / vanilla-crafting：拦截原版合成矩阵
  • any / all：拦截所有已识别的合成和工作站场景
  • stations / station / workstations：只拦截指定工作站

常用工作站写法：

  • CRAFTING / WORKBENCH / CRAFTING_TABLE
  • STONECUTTER / STONE_CUTTER
  • ENCHANTING / ENCHANT_TABLE / ENCHANTMENT_TABLE
  • ANVIL
  • GRINDSTONE
  • SMITHING / SMITHING_TABLE
  • CRAFTER

containers​

containers 控制物品能不能进入指定容器：

meta:
  protection:
    containers:
      deny:
        - HOPPER
        - FURNACE
        - ARMOR_STAND

deny 也兼容 denied、blocks、block、blacklist。当前监听会覆盖玩家点击 / 拖拽、漏斗移动、容器拾取掉落物，以及盔甲架交互。

常用容器写法：

  • DECORATED_POT / POT
  • FURNACE
  • BLAST_FURNACE
  • SMOKER
  • ARMOR_STAND
  • HOPPER
  • CRAFTER

destroy​

destroy 控制掉在地上的物品是否会被火、岩浆、仙人掌等环境伤害销毁：

meta:
  protection:
    destroy:
      enabled: true
      causes:
        - fire
        - lava
        - cactus
        - explosion
        - void

真实字段：

  • enabled / enable：是否启用掉落物销毁保护
  • causes / cause / types / type / damage-types：保护哪些伤害类型

常用伤害类型：

  • all：所有伤害类型
  • fire：包含 FIRE、FIRE_TICK、HOT_FLOOR
  • lava
  • cactus：包含 CONTACT
  • lightning
  • explosion：包含方块爆炸和实体爆炸
  • void：包含虚空 / 掉出世界

兼容简写：

  • no-craft: true：等价于开启 protection.crafting.any
  • no-destroy: true：等价于开启掉落物销毁保护，并默认保护 all

不再建议放在 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 在完整物品配置中的位置
  • 查看 脚本系统 了解脚本触发器和执行上下文