CraftEngine 开发工作流 · AI Skills

本页是 MiragEdge 的 CE 开发入口。实际配置优先于本文示例：服务器资源拷贝位于 F:\CraftEngine\resources，官方文档、源码和 DeepWiki 只用于确认版本差异与未覆盖能力。

先记住这 6 条

CE 配置的资源根目录是 plugins/CraftEngine/resources/；本项目按功能拆成多个 pack，而不是把所有内容塞进一个 items/ 目录。
每个 pack 有自己的 pack.yml，其中 namespace 是 CE pack 命名空间，例如 miragedge_items、miragedge_icon、miragedge_menu、customcrops。
items:、blocks:、images:、templates: 是不同注册表，不能混写；配置中的 ID 通常写成 namespace:id。
texture: 和 model: 不是一回事：前者通常指向纹理资源，后者指向模型资源；图标字体使用 images:，不应伪造一个物品来代替。
texture: minecraft:item/food/bacon 对应资源包中的 assets/minecraft/textures/item/food/bacon.png。assets/、textures/ 和 .png 不写进 CE 引用值。
改动后必须同时验证 CE 加载、资源包下载和游戏内显示；只看到 YAML 没报错不等于客户端材质正确。

适用边界

系统	CE 负责	其他系统负责
自定义物品	ID、基础材料、`data`、贴图/模型、事件	业务插件的复杂逻辑
自定义方块	方块注册、状态、模型、破坏/掉落相关配置	数据包的函数、世界生成和结构
字体图标	`images:` 注册、字体文件、字符映射	菜单/聊天插件决定何时输出字符
资源包	`assets/<namespace>/...` 下的 PNG、模型、字体	客户端实际下载和缓存
数据包联动	CE 物品 ID 作为跨系统数据	`function`、`loot_table`、`recipe`、`structure` 等

与其他工作流的入口：

MiragEdge 实际目录

text

plugins/CraftEngine/resources/
├── miragedge_items/
│   ├── pack.yml
│   ├── configuration/             # items、blocks、templates、recipes
│   └── resourcepack/assets/minecraft/
│       ├── models/
│       └── textures/
├── miragedge_icon/
│   ├── pack.yml
│   ├── configuration/icon.yml     # images: 字体图标
│   └── resourcepack/assets/minecraft/textures/font/image/
├── miragedge_menu/
├── miragedge_rank/
├── miragedge_other/
└── customcrops/

服务器拷贝中已经存在的 pack 不是理论目录：miragedge_items 的 pack.yml namespace 是 miragedge_items，customcrops 的作物配置则使用 customcrops:* ID。新增内容应先选择归属 pack，再决定路径和 ID，禁止默认套用 miragedge:。

标准五步闭环

1. 盘点依赖

先回答：这是物品、方块、字体图标、菜单模型还是作物阶段资源？确认目标 pack、基础材料、客户端版本、是否需要 Java/基岩版兼容，以及现有 ID 是否已经占用。

2. 设计 ID 与资源路径

推荐使用小写 snake_case：

text

注册 ID：miragedge_items:star_rod
纹理引用：minecraft:item/rods/star_rod
实际文件：resourcepack/assets/minecraft/textures/item/rods/star_rod.png

ID 命名空间和资源命名空间可以不同；必须以实际文件与现有配置为准。路径大小写、下划线、目录层级必须完全一致。

3. 编写最小配置

普通物品从 items: 开始，只添加本次需求需要的字段。物品显示数据放在 data: 中；材质字段放在物品根级。参考真实配置中的食物写法和模型写法。

4. 验证资源链路

text

CE YAML
  ├─ ID / material / data
  ├─ texture 或 model 引用
  └─ resourcepack/assets/... 下的 PNG / JSON / mcmeta
       ↓
客户端资源包下载
       ↓
游戏内获取物品、放置方块、打开菜单或发送字体字符

5. 重载与验收

text

/ce reload
/ce item get <namespace:id> [amount]
/reload                         # 只有同时修改原版数据包时才需要

/ce reload 的具体子命令随 CE 版本变化；不要把未经当前版本确认的 /ce reload all、/resourcepack reload 写入自动化脚本。资源包未更新时，先重新加入服务器或在客户端重新加载资源包，再判断材质是否失效。

配置模式

普通物品

yaml

items:
  miragedge_items:star_rod:
    material: fishing_rod
    data:
      item-name: "<!i><b><gradient:#00BFFF:#1E90FF>星辉钓鱼竿</gradient></b>"
      max-damage: 256
      custom-model-data: 203
    texture:
      - minecraft:item/rods/star_rod
      - minecraft:item/rods/star_rod_cast

多纹理列表用于具有不同状态/模型的物品（本服务器鱼竿就是这种实际用法），不要擅自改成虚构的 layers: 结构。

食物与事件

yaml

items:
  miragedge_items:toast:
    material: bread
    data:
      item-name: "<!i><gradient:#DEB887:#BC8F8F><b>吐司</b></gradient>"
      food:
        nutrition: 7
        saturation: 8.0
        can-always-eat: false
      lore:
        - "<!i><gray>10秒速度 I</gray>"
    texture: minecraft:item/food/toast
    events:
      - on: consume
        functions:
          - type: potion_effect
            potion_effect: minecraft:speed
            duration: 200
            amplifier: 0

业务命令、条件和函数参数必须以当前 CE 版本文档及服务器已有配置为准；不要从其他插件的事件语法照搬。

自定义食物食用时出现黑紫色碎屑粒子

以下结论已在 Minecraft Java 26.2 + CraftEngine 26.7.4 环境中验证。

现象与判断

自定义食物的物品贴图和手持模型都正常，但食用时出现黑紫色缺失材质粒子。CE 自带的可食用物（例如 hami_melon_slice、magma_fruit）以及 CustomCrops 果实正常时，可以先排除资源包整体加载、PNG 路径、texture 字段和 food 营养值问题。

根因

为了让物品不可堆叠而添加 data.components.minecraft:max_damage: 1，会在 Java 26.2 的 CE 自定义食物路径中把物品带入耐久组件处理，导致客户端解析食用碎屑粒子模型失败，最终显示为黑紫色缺失材质。

这不是缺少 particle 字段，也不需要为每种食物额外编写 item/generated 模型或粒子定义。正常食物不需要配置粒子字段。

错误与正确写法

错误：用 max-damage 实现不可堆叠。

yaml

data:
  components:
    minecraft:max_damage: 1

正确：改用最大堆叠数量限制，并保留原有 material、texture、food、events 和 consume-replacement 配置。

yaml

data:
  components:
    minecraft:max_stack_size: 1
  food:
    nutrition: 7
    saturation: 8.0

修复时删除 food.yml 中所有食物项的 max-damage: 1；只有确实需要不可堆叠的食物才添加 minecraft:max_stack_size: 1。

部署与验收

修改实际服务器目录 CraftEngine/resources/miragedge_items/configuration/food.yml。
执行 /ce reload all，让客户端重新接收或刷新服务端资源包。
至少抽测普通食物、带 on consume 事件的食物，以及带 consume-replacement 的饮料各一项，确认物品贴图和食用碎屑都正常。
如果仍然异常，先用一个不带 events 的食物做最小复现，并检查是否残留 max_damage；不要优先修改贴图或补写 particle。

模型与方块

model: 用于模型注册或物品/方块绑定，常见结构是 type、path、generation。模型引用也遵循资源定位规则，例如 customcrops:block/customcrops/crop/chinese_cabbage/stage_1 对应 assets/customcrops/models/block/customcrops/crop/chinese_cabbage/stage_1.json。

yaml

items:
  customcrops:chinese_cabbage_stage_1:
    material: sugar
    model: customcrops:block/customcrops/crop/chinese_cabbage/stage_1
    behavior:
      type: block_item

实际项目还使用 templates/models.yml、templates/block_states.yml 和 templates/block_settings.yml。复杂方块先复用模板，再写单个实例；不要在每个配置文件复制一套模型生成逻辑。

字体图标（`images:`）

yaml

images:
  miragedge_icon:money:
    height: 10
    ascent: 8
    font: minecraft:default
    file: minecraft:font/image/money.png
    chars: ""

file 对应 assets/minecraft/textures/font/image/money.png。chars 是实际字符映射，不要假设所有字符都在 U+E000–U+F8FF；服务器现有配置中同时出现了私用区字符和其他 Unicode 字符。新增字符前必须在现有 icon.yml、rank_icom.yml、菜单配置中查重。

字体图标的使用方式由菜单/聊天插件决定。CE 注册了图标，不代表玩家发送普通文字时会自动显示它。

装备与盔甲

装备涉及 items:、templates:、model:、equipments: 多个注册表。实际 miragedge_items/configuration/armor.yml 同时为 1.21.2+ 使用 type: component，为旧版本保留 type: trim 分支；这类配置不要删掉版本条件。

yaml

equipments:
  $$>=1.21.2:
    miragedge_items:winter_helmet_asset:
      type: component
      humanoid: "minecraft:entity/equipment/humanoid/winter_armor"

盔甲贴图还涉及 assets/minecraft/textures/entity/equipment/...，与背包物品图标的 textures/item/... 是两条资源链路，必须分别验收。

AI 执行清单

收到 CE 改动请求时，按以下顺序工作：

扫描目标 pack 的 pack.yml、相关 configuration 和 resourcepack/assets，确认实际 namespace 与路径。
搜索同类配置，优先复制服务器正在使用的最小模式；先不要引入模板、事件或模型高级字段。
分别列出注册 ID、基础材料、配置路径、资源文件、客户端展示场景和联动插件。
创建/修改配置与资源；YAML 中的中文保持 UTF-8 无 BOM，图片确认是真实 PNG 而非下载到的 HTML 错误页。
检查 ID、路径大小写、资源文件存在性、同名字符冲突、JSON/YAML 语法。
/ce reload 后获取对象做游戏内验收；记录服务器日志中的首个错误，而不是只看最后一行。
若涉及数据包，额外执行 /reload 并参考数据包 CE 集成章节。

故障定位

现象	优先检查
紫黑方块/材质缺失	`texture` 或 `model` 路径、大小写、PNG 是否存在、客户端是否拿到新包
只显示原版物品	ID/配置文件未加载、`material` 或 `custom-model-data` 不匹配、字段缩进错误
字体图标为空白	`images:` 是否加载、`file` 路径、`chars` 是否冲突、调用方是否指定了相同 font
物品能拿到但放置异常	物品模型与方块模型混用，或缺少 block state / behavior
自定义食物食用时出现黑紫色碎屑	先检查 `food.yml` 是否残留 `max-damage: 1` 或 `minecraft:max_damage: 1`；移除后改用 `minecraft:max_stack_size: 1`，再刷新资源包并实机复测
CE 重载报错	查看 `logs/latest.log` 中第一条 CraftEngine 配置错误，回滚最后一个改动再二分
Java 正常、基岩版异常	这是跨端转换链路问题，单独检查 Geyser/转换资源包，不要仅凭 Java 资源包结论

版本与引用原则

不在本页硬编码未经验证的 CE 版本号；当前拷贝的 pack.yml 版本字段是 pack 版本，不等于插件版本。
Minecraft pack_format 由实际服务端版本决定，不能从旧页面或网上示例复制。
官方资料优先级：当前服务器配置和日志 → CE 官方文档 → 源码 → DeepWiki。
DeepWiki 是辅助阅读材料，不是比源码和当前服务器更高的权威来源。

数据包工作流

CE材质引擎工作流

基岩材质转换工作流

附魔配置工作流

开发方式

触发器参考

Fluxon 参考

钓鱼系统工作流

插件开发归档

CraftEngine 开发工作流 · AI Skills

先记住这 6 条

适用边界

MiragEdge 实际目录

标准五步闭环

1. 盘点依赖

2. 设计 ID 与资源路径

3. 编写最小配置

4. 验证资源链路

5. 重载与验收

配置模式

普通物品

食物与事件

自定义食物食用时出现黑紫色碎屑粒子

现象与判断

根因

错误与正确写法

部署与验收

模型与方块

字体图标（`images:`）

装备与盔甲

AI 执行清单

故障定位

版本与引用原则

相关页面

开发方式

CraftEngine 开发工作流 · AI Skills ​

先记住这 6 条 ​

适用边界 ​

MiragEdge 实际目录 ​

标准五步闭环 ​

1. 盘点依赖 ​

2. 设计 ID 与资源路径 ​

3. 编写最小配置 ​

4. 验证资源链路 ​

5. 重载与验收 ​

配置模式 ​

普通物品 ​

食物与事件 ​

自定义食物食用时出现黑紫色碎屑粒子 ​

现象与判断 ​

根因 ​

错误与正确写法 ​

部署与验收 ​

模型与方块 ​

字体图标（images:） ​

装备与盔甲 ​

AI 执行清单 ​

故障定位 ​

版本与引用原则 ​

相关页面 ​

CraftEngine 开发工作流 · AI Skills

先记住这 6 条

适用边界

MiragEdge 实际目录

标准五步闭环

1. 盘点依赖

2. 设计 ID 与资源路径

3. 编写最小配置

4. 验证资源链路

5. 重载与验收

配置模式

普通物品

食物与事件

自定义食物食用时出现黑紫色碎屑粒子

现象与判断

根因

错误与正确写法

部署与验收

模型与方块

字体图标（`images:`）

装备与盔甲

AI 执行清单

故障定位

版本与引用原则

相关页面