内容文件¶

内容文件（Content File）是附加包中用于列出包内资源路径的JSON文件，文件名通常为contents.json。它位于包根目录，与清单文件处于同级目录，用于为游戏提供一份“本包包含哪些文件”的索引。

概述¶

内容文件通过version字段区分格式版本，目前存在版本0和版本1两种格式。当version字段不存在时，默认按版本0处理。

版本0（旧版）：version字段可选，content数组也可选。路径格式限制宽松，允许任意格式的路径字符串。

版本1（当前版本）：version字段为必填项，值应为1，content数组为必填项。路径格式较严格，路径不得以分隔符开头，且只允许使用正斜线作为目录分隔符。

两种格式版本下，数组中的每一项均表示一个文件路径条目：

contents.json（版本1）

{
  "version": 1,
  "content": [
    {
      "path": "manifest.json"
    },
    {
      "path": "textures/blocks/example_block.png"
    }
  ]
}

path的值以包根目录为基准，应包含文件扩展名，并使用正斜线/分隔目录，不应指向包外文件。每一项还可以包含可选的key字段；该字段接受一个长度为32字节的字符串，作为对应文件的AES-256 CFB8 NoPadding解密密钥。

作用¶

内容文件主要用于描述包内预期会被加载的内容。它与清单文件不同：清单文件声明包的身份、模块、版本和依赖关系；内容文件则描述包中实际存在的资源文件。

在常规开发中，许多资源包和行为包即使不提供contents.json也能被游戏识别和加载。因此，内容文件不应被理解为所有附加包都必须手写的文件。相反，当包中存在内容文件时，它应当与实际目录保持一致。

保持路径准确

如果内容文件中保留了不存在的文件路径，游戏仍可能尝试读取这些路径。对于界面、声音、纹理等资源，错误的路径可能导致资源缺失、界面异常或内容日志报错。

自动生成¶

游戏可以自动生成contents.json的content数组。开发者可以在包根目录创建只包含空对象的文件：

contents.json

{}

在下一次加载并验证该包时，游戏会扫描包内文件并写入路径列表，然后将version字段设置为1，完成版本升级。升级时游戏会保留原文件中已存在的所有路径（即使对应文件已不存在），仅将新发现的文件路径追加到末尾，并同时修正路径中的畸形分隔符（如将//规范化为/，将反斜线替换为正斜线）。该过程不会删除原有的无效路径，因此自动生成后仍应检查结果。

升级触发条件

版本升级仅在游戏确认该包通过清单文件验证，且内容文件的根内容为对象且version不为1时触发。若内容文件本身不是有效的JSON对象，升级逻辑将不会运行。触发升级的操作包括：将包加入游戏时、在已加载的情况下游戏初始化或切回前台（仅资源包）时，以及在资源栈中点击包验证按钮时。

加密与密钥¶

内容文件是加密包的索引文件。若包内某些文件被加密，引擎会在读取时按照每个路径条目对应的key字段所存储的密钥，对该文件进行AES-256 CFB8 NoPadding解密后再读取。

市场包加密算法下，内容文件本身通常处于加密状态，并具有256字节的文件标头，用于标识该内容文件并确保其保密性。引擎在解析时会先验证并去除该标头，再对剩余部分进行解密以获取原始JSON内容。

与子包¶

子包会按自身目录覆盖包根目录中的同路径资源。当前开发中通常只需要在包根目录维护contents.json；不应把每个子包都视为必须单独创建内容文件的目录。维护旧包时，如果子包内已经存在内容文件，应检查其中路径是否只指向该子包实际提供或覆盖的文件。

使用建议¶

普通开发包可以优先保持目录简单，避免把未使用的原版文件复制到包中。
若创建内容文件，应只列出包中真实存在且确实需要分发的文件。
删除或移动资源文件后，应同步更新内容文件。
发布前应检查包中是否混入工程缓存、图像工程文件、压缩包副本或其他与游戏内容无关的文件。