导航：文档首页 › 服主指南 › 自定义方块相关：物品源引用.md · 外部插件对接 / 方块模型作物.md · 脚本入门.md

🧱 自定义方块（CustomBlock）

QCL 提供了一套自定义方块抽象层，把不同来源（目前是 CraftEngine）的自定义方块/家具统一成一个接口，并自带降级机制——后端插件没装或放置失败时，自动退回普通方块，不会让世界里出现空洞。

⚠️ 这是进阶 / 开发能力，多数情况下由子插件或脚本驱动。纯服主层面，你主要需要理解两件事：item_sources（物品源） 与 降级机制。

🧠 概念

QCL 的自定义方块由几层组成：

CustomBlockBridge（聚合层）
   └── CustomBlockProvider（后端，可多个）
          └── CraftEngineBlockProvider  (id = craftengine，需装 CraftEngine)

层	作用
`CustomBlockBridge`	对外统一入口，聚合多个 Provider
`CustomBlockProvider`	某个后端的具体实现，可以有多个
`CraftEngineBlockProvider`	目前内置的唯一后端，`id = craftengine`，依赖 CraftEngine 插件

也就是说：自定义方块功能 = CraftEngine 提供方块/家具 + QCL 统一封装与降级。没装 CraftEngine 时，自定义部分用不了，但仍能靠降级机制放置普通方块。

🗂️ CustomBlockConfig 字段表

自定义方块从一个 ConfigurationSection（YAML 配置段）解析，字段如下：

键	类型	默认	说明
`material`	材质名	`CHEST`	降级材质：自定义放置失败时退回的普通方块
`custom-model-data`	整数	（未设）	降级 CMD：`≥ 0` 时生效，给降级物品/方块附加自定义模型数据
`displayname`	字符串	—	显示名
`item_sources`	列表	—	物品源引用列表，按优先级顺序排列

yaml

my_block:
  displayname: "&b魔力矿石"
  material: STONE              # 降级材质（CraftEngine 不可用时退回石头）
  custom-model-data: 10001     # 降级 CMD，≥0 才生效
  item_sources:                # 优先级从上到下
    - craftengine-myaddon_mana_ore
    - STONE

🔗 item_sources 与统一物品源的关系

item_sources 用的就是 QCL 的统一物品源引用（详见物品源引用.md）。列表里靠前的优先级更高。

其中 CraftEngine 源的写法是：

craftengine-命名空间_id

解析规则：craftengine- 前缀之后，第一个下划线 _ 会被转成冒号 :，从而对应 CraftEngine 的 命名空间:id。
例：craftengine-myaddon_mana_ore → CraftEngine 的 myaddon:mana_ore（注意只转第一个下划线，后面的 _ 保留）。

🎯 放置优先级与降级机制

place()（放置）的逻辑，按 item_sources 顺序逐个尝试：

对 item_sources 里的每个源（按顺序）：
   ├─ 若源以 craftengine- 开头：
   │     1) 先尝试「家具放置」
   │     2) 家具失败 → 再尝试「方块放置」
   └─ 若都失败 → 继续下一个源
全部源都失败：
   └─ 用 material（fallbackMaterial）放置一个普通方块（降级）

阶段	行为
1️⃣ 遍历 `item_sources`	按优先级逐个尝试
2️⃣ CraftEngine 源	先试家具，失败再试方块
3️⃣ 全部失败	用 `material` + （可选）`custom-model-data` 降级放普通方块

这样即使 CraftEngine 没装、或某个自定义方块 id 写错了，世界里也只会变成「降级材质」的普通方块，而不会报错或留空——这就是降级机制的意义。

🪑 家具 vs 方块

CraftEngine 里自定义内容有两种形态，QCL 放置时先家具后方块：

形态	说明	尝试顺序
家具（furniture）	实体形式的装饰/模型	先试
方块（block）	真实的方块	家具失败后试

对同一个 craftengine-xxx 源，QCL 会自动两种都试一遍，你不用关心它到底是家具还是方块。

🧰 能力概览

自定义方块对象（开发/脚本层面）提供这些能力：

能力	方法	说明
取物品	`getItem(数量)`	按 `item_sources` 优先级取出对应物品
放置	`place(位置)`	在指定位置放置（带上文的降级逻辑）
识别	`isThis(方块/实体)`	判断某个方块或实体是不是「这个」自定义方块
移除	`remove(方块/实体)`	移除该自定义方块

这四个能力（取 / 放 / 识别 / 移除）通常由子插件或脚本调用。服主一般通过子插件提供的配置间接用到它们。

📋 YAML 示例骨架

单一 CraftEngine 源 + 降级

yaml

mana_ore:
  displayname: "&b魔力矿石"
  material: STONE                       # CraftEngine 不可用时退回石头
  custom-model-data: -1                 # <0 不生效；想要降级模型就填 ≥0
  item_sources:
    - craftengine-myaddon_mana_ore      # → myaddon:mana_ore

多源降级（优先自定义，退回普通）

yaml

magic_chest:
  displayname: "&d魔力箱"
  material: CHEST                        # 最终兜底材质
  custom-model-data: 20001
  item_sources:                         # 优先级从上到下
    - craftengine-myaddon_magic_chest   # ① 首选：CraftEngine 自定义
    - craftengine-coreaddon_fancy_box   # ② 次选：另一个自定义
    - CHEST                             # ③ 退回：普通箱子

解析逻辑会从上往下试：①不行试②，②不行试③，③也不行才用 material（CHEST）降级。

📌 注意事项

🔌 依赖 CraftEngine：自定义形态（家具/方块）必须装 CraftEngine 才能正常放置；否则一律走降级。
🧪 这是进阶能力：多由子插件 / 脚本驱动，服主重点理解 item_sources 与降级即可。
🔠 下划线转冒号只转第一个：craftengine-a_b_c → a:b_c，别被多下划线误导。
🔻 custom-model-data 要 ≥ 0 才生效：填负数等于不设。

➡️ 继续阅读

物品源引用.md —— item_sources 用的统一物品源引用格式（含 craftengine- 前缀规则）
外部插件对接 / 方块模型作物.md —— CraftEngine 方块/家具/作物的对接细节
脚本入门.md —— 用脚本驱动自定义方块的取 / 放 / 识别 / 移除

🧱 自定义方块（CustomBlock） ​

🧠 概念 ​

🗂️ CustomBlockConfig 字段表 ​

🔗 item_sources 与统一物品源的关系 ​

🎯 放置优先级与降级机制 ​

🪑 家具 vs 方块 ​

🧰 能力概览 ​

📋 YAML 示例骨架 ​

单一 CraftEngine 源 + 降级 ​

多源降级（优先自定义，退回普通） ​

📌 注意事项 ​

➡️ 继续阅读 ​

🧱 自定义方块（CustomBlock）

🧠 概念

🗂️ CustomBlockConfig 字段表

🔗 item_sources 与统一物品源的关系

🎯 放置优先级与降级机制

🪑 家具 vs 方块

🧰 能力概览

📋 YAML 示例骨架

单一 CraftEngine 源 + 降级

多源降级（优先自定义，退回普通）

📌 注意事项

➡️ 继续阅读