跳到主要内容

🗂️ 认识项目

上一章完成了插件安装。本章先认识 CraftEngine 的目录结构，再用一条命令创建教程所需的工作区。

插件目录结构​

打开 plugins/CraftEngine/，可以看到以下内容：

CraftEngine
generated
libs
resources
translations
commands.yml
config.yml

目前只需关注 resources/ 文件夹：所有自定义物品、方块和家具都存放在这里。

什么是“包”​

CraftEngine 以“包”为单位组织自定义内容。每个包对应 resources/ 下的一个文件夹，其中包含：

  • configuration/ —— 放 .yml 配置文件。物品怎么定义、方块什么属性，全写在这里
  • resourcepack/ —— 放模型文件（.json）、贴图文件（.png）、音效文件（.ogg）。结构和原版 Minecraft 资源包一样
  • pack.yml —— 包的基本信息，包括名称、作者和命名空间

💡 文件夹名以 . 开头（比如 .hidden_pack）会被 CraftEngine 忽略，不会被加载。

你可以创建多个包（如 tutorial、my_weapons、furniture_pack），CraftEngine 会合并加载其中的内容。本教程始终使用同一个 tutorial 包。

什么是命名空间​

命名空间就像内容 ID 的“姓氏”。Minecraft 中的物品、方块和贴图都有唯一 ID，例如 minecraft:diamond：minecraft 是命名空间，diamond 是名称。

自定义内容需要使用独立的命名空间，以免与原版内容重名。本教程使用 tutorial，因此物品 ID 会采用 tutorial:xxx 的格式。

命名空间只能用小写字母、数字、-、_、.、/。不能有大写字母、不能有空格。

💡 小测验：以下哪些 ID 合法？

  1. MyFirst:golden_sword
  2. minecraft:steel furnace
  3. abcd-efgh:1122.3344
  4. craftengine:happy$crafting
  5. test:tutorial_book
  1. ❌ 大写字母不合法
  2. ❌ 空格不合法
  3. ✅ 数字、连字符、点号都合法
  4. ❌ $ 不合法
  5. ✅ 小写字母和下划线都合法

第 1 步：用命令创建包​

无需手动创建文件夹。CraftEngine 可以通过一条命令生成完整的包结构。

在游戏里输入：

/ce resource create tutorial

这条命令会：

  • 将 tutorial 设为包名和文件夹名，并默认用作命名空间
  • 自动生成 pack.yml（写好了命名空间 tutorial、作者、版本等信息）
  • 自动创建 configuration/ 文件夹和 resourcepack/ 下的全套子目录

命令执行成功后，打开 plugins/CraftEngine/resources/tutorial/，可以看到自动创建的全部子目录：

tutorial
configuration
resourcepack
pack.yml

⚠️ 如果提示 pack already exists（包已存在），说明 resources/tutorial/ 已存在。请改用其他包名，或确认不再需要该文件夹后将其删除，再重新执行命令。

💡 pack.yml 中已经自动填好命名空间、作者和版本信息，通常无需修改。

第 2 步：创建配置文件​

包创建完成后，在 configuration/ 中新建第一个配置文件。下一章将用它来定义物品。

用什么编辑器​

请使用纯文本编辑器。推荐 VS Code：它免费且支持语法高亮，有助于减少格式错误。

方式一：文件管理器​

打开 configuration 文件夹，右键 → 新建 → 文本文档，把文件名改成 items.yml。

⚠️ 文件名必须是 items.yml，不是 items.yml.txt。 Windows 默认隐藏文件后缀——你可能以为改成了 .yml，实际是 .yml.txt。检查方法：文件管理器顶部点「查看」→ 勾选「文件扩展名」，确认后缀确实是 .yml。

方式二：命令行​

# 先进到 configuration 目录
cd plugins/CraftEngine/resources/tutorial/configuration

# Linux / Mac
touch items.yml

# Windows PowerShell
ni items.yml

创建完成后，使用 VS Code、记事本或 nano 等纯文本编辑器打开文件，即可开始编写配置。

第 3 步：了解配置文件的加载方式​

所有 .yml 和 .json 文件放在 configuration/ 下就会被加载。你可以把配置写在一个文件里，也可以拆成多个文件——CraftEngine 会把它们全读进去合并。

比如你可以按类型分：

configuration
items.yml
blocks.yml
furniture.yml

也可以按功能分：

configuration
weapons.yml
materials.yml
decorations.yml

两种分类方式都可以。本教程为便于操作，先将物品配置集中写在 items.yml 中；制作方块和家具时再创建新文件。

💡 configuration/ 下也可以建子文件夹来分类管理。比如 configuration/weapons/、configuration/blocks/——CraftEngine 会递归扫描所有子目录，里面的 .yml 和 .json 全都会被加载。

让修改后的配置生效​

每次修改配置文件（.yml 或 .json）后，都需要让 CraftEngine 重新加载。请根据改动类型选择命令：

修改内容运行命令
改了 .yml 配置（加物品、改名字、改属性）/ce reload config
改了合成配方/ce reload recipe
改了贴图文件（.png）或模型文件（.json）/ce reload all
修改工作流定义、触发条件或步骤/ce reload config
修改包 ID 或托管设置/ce reload host
不确定该用哪个/ce reload all（最稳妥）

/ce reload config 更新配置及工作流定义，但不会重新构建资源包。/ce reload all 会执行 trigger 包含 reload_pack 的工作流，默认的 default 工作流负责生成、上传和发送。如果自己的构建工作流没有设置该触发条件，请显式执行 /ce workflow [名称]。发送更新需要 send_pack 步骤，且只会发送给当前使用该包的玩家。

直接运行 /ce reload（不带参数）等同于 /ce reload config。