云北知识库

外观

道旗加载与资源包制作 ​

概述 ​

道旗是挂在道路灯杆上的旗帜方块（road_pole_flag）。旗帜的图案不写死在模组里，而是由模组在启动时从资源包中读取一份清单，再按 ID 渲染对应贴图。因此只要制作一个资源包，就能为游戏添加任意数量的自定义道旗，无需改动模组本体。

这份文档分两部分：先说明模组是如何加载道旗的，再说明如何制作并安装一个道旗资源包。

一、道旗的加载机制 ​

1. 加载时机 ​

道旗清单在客户端资源重载时读取。Fabric 端注册的是一个同步资源重载监听器，Forge / NeoForge 端挂在客户端的资源重载事件上，两者行为一致。

每次重载都会先清空已有数据，再完整重新扫描一遍。所以更换资源包、调整 JSON 之后，只要触发一次资源重载，改动就会生效，不需要重启游戏。

道旗是纯客户端资源，贴图只在安装了该资源包的客户端上显示。服务器无需安装，但联机时每位玩家都需要各自装好。

2. 扫描范围 ​

加载器会遍历资源管理器中的所有命名空间，在每个命名空间的根目录下查找固定文件名的 flags_yunbeiuc.json，即：

text
assets/<命名空间>/flags_yunbeiuc.json

注意两点：

  • 文件名必须严格为 flags_yunbeiuc.json，写在命名空间的根目录，不要放进子文件夹。
  • 这与图案、字体的资源包不同（它们放在 ui_definitions/ 下）。道旗清单是独立的一套，位置在命名空间根部。

模组自身的数据就放在 assets/yunbeiuc/flags_yunbeiuc.json，可以作为参考样板。

3. 文件结构 ​

清单是一个 JSON 对象，顶层只有一个 custom_flags 字段，里面每个键就是一个旗帜 ID：

json
{
  "custom_flags": {
    "wuxi_1": {
      "name": "践行八礼四仪 争做新时代好少年",
      "image": "yunbeiuc:textures/block/flags/wuxi_1.png",
      "color": "e74095"
    },
    "wuxi_2": {
      "name": "弘扬志愿精神 凝聚文明力量",
      "image": "yunbeiuc:textures/block/flags/wuxi_2.png",
      "color": "e74095"
    }
  }
}

4. 字段说明 ​

字段位置说明
旗帜 ID对象键唯一标识，用于保存和渲染。建议只用小写字母、数字和下划线
name必填显示名称，出现在选择界面的列表与预览区
image必填贴图路径，详见下方说明
color必填列表条目的文字颜色，十六进制，带不带 # 都可以（e74095 与 #e74095 等价）

三个字段都是必填项。缺少任意一个，该文件会解析失败并被跳过，控制台会打印错误信息。

5. 贴图路径的两种写法 ​

image 的解析规则是看有没有冒号：

  • 带命名空间前缀：命名空间:路径，例如 yunbeiuc:textures/block/flags/wuxi_1.png
  • 不带冒号：直接按当前所在命名空间补全，例如 textures/block/flags/wuxi_1.png 会被当作 当前命名空间:textures/block/flags/wuxi_1.png

路径要写到 .png 为止，包含 textures/ 这一段。

6. 加载后的数据 ​

每个旗帜会被封装成一个 CustomFlag，包含 ID、名称、贴图位置和颜色四个值。所有旗帜按 JSON 中出现的先后顺序保存，选择界面里的列表也按这个顺序排列。加载完成后，控制台会按命名空间输出各自加载到的数量，方便确认资源包有没有被读到。

二、游戏内使用 ​

  1. 放置一个 road_pole_flag 方块。它会自动判断下方是普通灯杆还是路灯杆，切换到对应的杆型。
  2. 手持通用魔杖右键点击该方块，打开 选择旗帜 界面。
  3. 界面左侧是旗帜列表，右侧是预览面板，显示当前选中旗帜的图案、名称和 ID。
  4. 点击预览面板下方的保存按钮，所选旗帜的 ID 会写入方块实体并同步到服务器，随后渲染为对应贴图。

旗帜以双面方式渲染，正面与背面都会显示。渲染尺寸为宽 0.6 格、高约 1.6 格，两者比例约为 1 : 2.67。

三、制作道旗资源包 ​

1. 搭建基础框架 ​

新建一个文件夹，例如 MyFlagPack，在其中创建 pack.mcmeta：

json
{
  "pack": {
    "pack_format": 15,
    "description": "自定义道旗资源包"
  }
}

pack_format 要与游戏版本对应，上面是 1.20.1 的取值。不同版本的数字不同，按目标版本填写即可。

然后在根目录下创建 assets 文件夹，再在里面建一个命名空间文件夹（如 my_flag_pack）。命名空间只能用小写字母、数字和下划线，游戏内引用时以 my_flag_pack: 为前缀。

text
MyFlagPack/
 ├── pack.mcmeta
 └── assets/
     └── my_flag_pack/

2. 放置道旗清单 ​

在命名空间根目录下创建 flags_yunbeiuc.json：

text
MyFlagPack/
 └── assets/
     └── my_flag_pack/
         └── flags_yunbeiuc.json

内容按前面的结构编写：

json
{
  "custom_flags": {
    "demo_1": {
      "name": "示例旗帜一",
      "image": "my_flag_pack:textures/flag/demo_1.png",
      "color": "3a7bd5"
    },
    "demo_2": {
      "name": "示例旗帜二",
      "image": "my_flag_pack:textures/flag/demo_2.png",
      "color": "3a7bd5"
    }
  }
}

3. 放置贴图 ​

把 PNG 图片放到清单里写明的路径下，例如 assets/my_flag_pack/textures/flag/：

text
MyFlagPack/
 └── assets/
     └── my_flag_pack/
         ├── flags_yunbeiuc.json
         └── textures/
             └── flag/
                 ├── demo_1.png
                 └── demo_2.png

图片建议按 1 : 2.67 的宽高比制作（例如 1062 × 2834），与渲染尺寸一致，避免拉伸变形。贴图支持透明，镂空区域不会被绘制。

4. 打包与安装 ​

  1. 进入 MyFlagPack 文件夹。
  2. 同时选中 assets 文件夹和 pack.mcmeta 文件。
  3. 右键 压缩为 ZIP 文件 。
  4. 把生成的压缩包改名为 MyFlagPack.zip（后缀必须是 .zip，压缩包里不能再套一层文件夹）。

打开游戏，进入 选项 → 资源包 → 打开资源包文件夹 ，把压缩包放进去并启用，回到游戏触发一次资源重载即可。之后右键道旗方块，就能在选择界面里看到新增的旗帜。

四、常见问题 ​

资源包里加了旗帜，游戏里却没有 先确认文件名是 flags_yunbeiuc.json，且位于 assets/<命名空间>/ 根目录，不是子文件夹。再看控制台是否输出了对应命名空间的加载数量，没有输出说明文件没被扫描到。

清单文件整体失效 检查 custom_flags 是否存在，以及每个旗帜的 name、image、color 是否齐全。缺字段会导致整个文件解析失败。

贴图显示为紫黑格 路径写错了，或者图片没有放进资源包。核对 image 中的命名空间、目录和文件名是否与实际文件一致。

旗帜被拉伸 图片宽高比与 1 : 2.67 差得太多。按该比例重新导出即可。

多个资源包都定义了同一个 ID 后加载的会覆盖先加载的。给自己的旗帜加命名空间前缀（如 my_flag_pack_demo_1）可以避免和别的资源包撞名。

Copyright@ 2026 BGSDT