跳到主要内容

📄 模板系统实战

方块教程中使用过 default:loot_table/self：这是一个内置模板，可以通过一行配置展开为完整的战利品表。本章将说明模板适合解决哪些问题，以及何时使用模板。

模板解决什么问题​

大型资源包中经常出现结构相同、只有少量字段不同的配置。反复复制这些内容既难维护，也容易产生不一致。模板可以复用公共结构，只填写不同的参数。

最简示例：

# 定义模板
templates:
  tutorial:common_sounds:
    break: minecraft:${sound_type}.break
    step: minecraft:${sound_type}.step
    place: minecraft:${sound_type}.place
    hit: minecraft:${sound_type}.hit
    fall: minecraft:${sound_type}.fall
# 使用模板
settings:
  template: tutorial:common_sounds
  arguments:
    sound_type: block.stone

应用模板时，${sound_type} 会被替换为参数值，并生成五条完整的音效路径。

什么时候用模板​

可以参考以下原则：

应该用模板不必用模板
3 个以上物品共享相同结构一次性配置
后续还会添加更多物品每个字段都完全不同
想保证整个资源包的配置一致性模板参数比原配置还多

如果同一段配置需要重复使用三次或更多，通常值得将其提取为模板。

公开资源包注意事项

如果资源包需要公开发布，请勿引用内置模板（default:*）。内置模板可能随 CraftEngine 更新而变化，进而造成意外的兼容问题。

用你自己的命名空间定义模板：

# ❌ 公开资源包不要这样做
loot:
  template: default:loot_table/self

# ✅ 定义自己的模板然后引用
loot:
  template: mypack:self_loot

使用自己的命名空间后，模板内容便由资源包自身控制，不会随 CraftEngine 内置模板的更新而变化。

配置工厂​

自定义物品往往还需要配方、战利品表或方块定义。为每个变体分别编写整套配置既繁琐，也容易遗漏。

配置工厂可以一次批量生成多种配置。将物品所需的 items、recipes 等内容写入同一份蓝图，再列出各个变体，CraftEngine 就会为每个实例生成完整配置：

config_factory#sofa:
  blueprint:
    items:
      "custom:${color}_sofa":
        material: paper
        data:
          item_name: "<!i><${dye_color}>${display_name} 沙发"
        behavior:
          type: furniture_item
          furniture:
            variants:
              ground:
                elements:
                  - item: custom:${color}_sofa
                hitboxes:
                  - position: 0,0,0
                    type: shulker
                    seats:
                      - 0,0.35,0
            settings:
              hit_times: 3
            loot:
              pools:
                - rolls: 1
                  entries:
                    - type: furniture_item
    recipes:
      "custom:${color}_sofa":
        type: shaped
        pattern:
          - "WWW"
          - "WDW"
          - "SSS"
        ingredients:
          W: "minecraft:${color}_wool"
          D: "minecraft:${color}_dye"
          S: minecraft:stick
        result:
          id: ${__NAMESPACE__}:${__ID__}
  instances:
    - {color: white,      display_name: 白色,   dye_color: white}
    - {color: light_gray, display_name: 淡灰色, dye_color: gray}
    - {color: gray,       display_name: 灰色,   dye_color: dark_gray}
    - {color: black,      display_name: 黑色,   dye_color: dark_gray}
    - {color: brown,      display_name: 棕色,   dye_color: dark_gray}
    - {color: red,        display_name: 红色,   dye_color: red}
    - {color: orange,     display_name: 橙色,   dye_color: gold}
    - {color: yellow,     display_name: 黄色,   dye_color: yellow}
    - {color: lime,       display_name: 黄绿色, dye_color: green}
    - {color: green,      display_name: 绿色,   dye_color: dark_green}
    - {color: cyan,       display_name: 青色,   dye_color: dark_aqua}
    - {color: light_blue, display_name: 淡蓝色, dye_color: aqua}
    - {color: blue,       display_name: 蓝色,   dye_color: blue}
    - {color: purple,     display_name: 紫色,   dye_color: dark_purple}
    - {color: magenta,    display_name: 品红色, dye_color: light_purple}
    - {color: pink,       display_name: 粉红色, dye_color: light_purple}

${__NAMESPACE__} 和 ${__ID__} 从条目键自动推导——custom:red_sofa 解析为 __NAMESPACE__ → custom、__ID__ → red_sofa。无需重复写。

一个 config_factory 配置段即可生成全部 16 种沙发变体，每种都同时包含物品、家具定义和配方，无需循环或复制粘贴。

什么时候用配置工厂：同一组关联配置重复 5 次以上时——带配方的彩色家具、带装备和战利品表的等级盔甲、带方块和掉落的矿石变体。批量较小时，普通模板就够了。