打包机制文档

跳转：快速参考

注意事项

文件地址中，目录分隔符一律使用正斜杠（/）！
地址相关
- 下述说明中，完整地址永远指从仓库根目录算起的地址，例如对根目录下的CONTRIBUTING.md，应为CONTRIBUTING.md；对1.12版本资源包的pack.png，应为projects/1.12.2/pack.png。
- 下述说明中，相对地址永远指从特定命名空间的文件夹算起的地址，例如对仓库中的projects/1.18/assets/minecraft/minecraft/font/default.json，应为font/default.json。
- 下述说明中，目标地址永远指分发的资源包中，该文件应当被放置的位置，例如对上一条中提及的文件，应为assets/minecraft/font/default.json。
文件相关
- 下述说明中，语言文件永远指可以被打包器解读为映射表的文件。这包括了所有 lang/下的.lang和.json文件。
- 下述说明中，文本文件永远指含有文本内容，但不属于语言文件的文件。这包括了非语言文件的.txt、.md、.json文件。
- 下述说明中，非文本文件永远指不属于以上两类的文件，如图片或其他二进制文件。
本次打包器更新以后，对于非文本文件无需特殊处理：打包器会按照文件拓展名自动识别文件类型。

配置文件

配置文件分为两类：

放置在config/packer下的全局配置文件，用作整个打包流程的基础配置；
放置在各命名空间下的局域配置文件，用于对特定命名空间（以及模组）提供特殊的配置项。

文件格式

目前而言，所有配置文件都需要填写全部项——无关项可以填写空集合，但不能不填，更不能写null。有计划在将来优化这一行为。

全局配置文件

全局配置文件config/packer/<version>.json的格式如下：

根标签 object
- base object
  打包流程中的不变配置，不能被文件结构中的局域配置文件改写。包含的内容都是不低于命名空间层级的，因为局域配置文件就是放在命名空间一级中的。
  - version string
    该配置文件指向的版本，以projects/中的文件夹名称为准。原则上应当与文件名中的[version]一致。
  - targetLanguages list
    打包的目标语言，即最终在资源包中存在的语言。
    - string
      目标语言，即该版本使用的语言标识符。
      以在lang下的语言文件的文件名，以及其他文件的路径中，标明语言的部分为准。目前而言，使用的是zh_cn，尽管有消息称将要改用zho_Hans-CN。
  - exclusionMods list
    被打包器排除的模组文件夹。
    如果因为某些原因需要移除某个模组的翻译（如移交官方/其他团体等），但意图保留原有翻译，可能需要这一项。
    - string
      排除的模组。
  - exclusionNamespaces list
    被打包器排除的 [namespace] | (命名空间)。
    暂时闲置，以待后续需求。
    - string
      排除的命名空间。
- floating object
  打包流程中的可变配置，可能被文件结构中的局域配置文件改写。包含的内容都是低于命名空间层级的，因为局域配置文件就是放在命名空间一级中的。
  - inclusionDomains list
    强制包含的 [domain]。
    一般而言，用于通常不会包含语言标识符的domain。
    一般而言会包含font与textures，因为这两处往往不带语言标识符，且字体修复已经需要用到这两个domain；其他内容多半会出现在局域配置中。
    - string
      强制包含的domain名称。
  - exclusionDomains list
    强制排除的 [domain]。
    暂时闲置，或可用于排除一些策略相关的零散文件。
    - string
      强制排除的domain名称。
  - exclusionPaths list
    强制排除的 [相对地址]。
    - string
      强制排除的文件的相对地址。
      一般而言，在主配置中只会放置通用的忽略对象，例如packer-policy.json和local-config.json；其余条目最好放在局域配置中。
  - inclusionPaths list
    强制包含的 [相对地址]。
    暂时闲置，可以用于添加零散的无语言标记文件。
    - string
      强制包含的文件的相对地址。
  - characterReplacement object
    打包时采用的字符替换表。用于将部分字符替换至特殊位点，也可单纯用于简化输入。目前而言，包含了字体修复的有关内容。
    - <查询语句> string
      用以替换正则表达式<查询语句>匹配对象的内容，可以是一个或多个字符，甚至可以在这里用正则替换语句。
      主要用于字体修复包所需的符号替换，此时，查询语句通常是字面量，替换内容一般而言总是以四位Unicode转义码填写；对于基础多语种平面（BMP）以外的字符，最好用UTF-16代理对书写。
  - destinationReplacement object
    打包时采用的目标地址替换。
    可以用于移动文件，但暂时闲置；使用检索策略中的singleton也可以实现地址替换，但需要在每个模组下配置。
    - <查询语句> string
      用以替换正则表达式<查询语句>匹配对象的内容，可以是一个或多个字符，甚至可以在这里用正则替换语句。

局域配置文件

局域配置文件projects/<version>/assets/<mod-name>/<namespace>/local-config.json的格式与全局配置文件中，floating标签下的内容（可变配置）一致。

文件容斥顺序

介于在配置文件中出现了多种包含/排除文件的配置项，有必要说明以下这些项生效的顺序：

exclusionMods和exclusionNamespaces在进入命名空间前即会排除相应的文件夹——甚至不会加载其中的local-config.json。
当然，如果是通过检索策略访问的，则这一项不会生效。
在剩下的命名空间中，检索文件。下面的配置项可能会被当地的局域配置修改，除了targetLanguages以外。
在所有检索到的文件中，排除掉exclusionPaths指定的文件，即便是通过检索策略访问的。
在剩下的文件中，直接包含inclusionPaths和inclusionDomains指定的文件。
在剩下的文件中，排除掉exclusionDomains指定的文件。
在剩下的文件中，仅包含由targetLanguages指定的，在路径中任意位置包含有简体中文语言标记的文件，其他文件不予包含。

局域配置文件的重写规则

如果在某个命名空间内检测到存在local-config.json，打包器将会在全局配置的基础上，在其可变配置中添加该文件中的内容，并用这一修改后的配置执行该命名空间下的检索工作。
最好不要与全局配置中的内容重复。尽管理论上这样子可以运行，但是重复项保留哪一个或许不容易断定。
需要注意的是，如果通过检索策略来引用其他命名空间，打包器只会加载目标命名空间的局域配置，而不会加载原空间的局域配置；不过，在原位进行的检索工作不受影响。

检索策略

对于每个命名空间文件夹，打包器除了可以原位检索文件以外，还可以使用不同的检索方式。目前，可用的检索方式有四种：

原位检索文件。
引用给定的命名空间。
从给定的组合文件，直接生成语言文件（或部分）。
引用单个文件。

计划中，将对非语言文件的文本文件添加一个修改包策略，但是这个策略暂时还没实现，部分原因是在上一版打包器中，这个策略还没被用过。

单独看起来，这或许没什么用（打包器的上一版中，功能还要多些）；但有一点很重要：这些加载策略是可以串联、递归的！于是，通过这些策略，应该可以满足许多需求。

串联：在一个策略文件中，可以放置多条策略。策略将会从前往后执行，前者优先——和Minecraft资源包顺序差不多。不过，在文件冲突时，也提供了一些特殊的冲突解决选项。
递归：如果引用了其他命名空间文件夹，那里的策略文件也会生效。这意味着可以实现连续引用——尽管前提是不出现循环引用。

部分案例被放在了projects/packer-example/这一虚拟的“版本”下。很明显，我们并不会分发这一版本，但如果有条件，可以在本地构造打包器，并用这一版本做试验。

策略相关文件的格式

packer-policy.json

对于每个命名空间文件夹，策略文件为projects/<version>/assets/<mod-name>/<asset-domain>/packer-policy.json。若找不到该文件，默认策略内容为[{"type": "direct"}]，也就是原位加载，没有特殊配置。

根标签 list
打包器需要执行的策略，从前往后执行。如果有冲突内容，默认以前者优先——当然这是可以配置的。
- object
  单项策略。部分参数可变。
  - modifyOnly bool
    默认为false。
    对于语言文件，若本项为true，对于已有的键，若在该步中提供了新的值，则将会用新值替换旧值；不会包含本步中新出现的键。
    对于其他文件，本项无效。
  - append bool
    默认为false。
    对于文本文件，将会在已有的文本内容之后换行，然后连接本步的内容。
    对于其他文件，本项无效。
  - type string
    策略的类型。
  若type的值为direct： 不进行特殊处理，直接按照此处的文件结构打包。
  
  若type的值为indirect： 引用给定的命名空间。对于这些文件，其目标地址中的命名空间将会自动替换为本策略所在的命名空间。（示例的第二条）
  - source string
    引用命名空间所在文件夹的完整地址。
  若type的值为composition： 从给定的组合文件，直接生成语言文件（或部分）。这些组合文件可能不会被自动排除；可以考虑使用局域配置处理。
  - source string
    引用组合文件的完整地址。
  - destType string
    需要生成的语言文件的类型。可以为json或lang。
  若type的值为singleton： 引用给定的单个文件。理论上该操作可以选取任何位置的文件，只要目标位置填写正确；不过，一般建议放在合理的位置。（示例的第一条）
  - source string
    引用文件所在的完整地址。
  - relativePath
    文件需要被放置的相对地址。考虑到连续引用，这里不宜使用目标地址。

[组合文件].json

根标签 object
- target string
  生成的语言文件的目标地址。
- entries list
  需要生成的组合项。这些项将会分别执行组合以后，连接起来。
  如果存在键冲突，打包器会在此崩溃！ 有计划在后期更改这一行为；目前而言，可以使用多个组合文件绕过这个限制。
  - object
    单项策略。
    - templates object
      组合所用的模板。所有内容采用C#格式化模式填写。
      粗略地说，其中的格式符有形式{0}, {1}, {2},...，字面量花括号需要用{{和}}转义；完整的定义可见 .net文档/Composite Formatting。
      - <键模板> string
        <键模板>对应的值模板。
    - parameters list
      组合所用的参数表。参数按照模板中的索引顺序排列。不支持嵌套，必须用字面量。
      - object
        每个索引位置上可用的参数。
        
        <键参数> string
        <键参数>对应的值参数。

组合文件

组合文件用来生成“组合型”的语言文件/语言文件片段，也就是那些有大量重复文本、有明显的格式的语言文件片段。

组合文件的工作原理如下：

获取entries中的全部条目，每个条目代表一种组合模式。
每个条目中，由templates中的所有条目充当模板，parameters中的所有条目充当参数，生成若干组合后的条目。
- 在parameter中，有时会出现多于一组参数；这种情况下，每组参数都会自由组合。
- 同样的，templates也会和每一套参数自由组合。
将所有组合后的条目汇总，生成语言文件。
- 在这一过程中，如果出现了键冲突，目前而言，打包器会在此崩溃！ 不过，如果后续观察表明确实存在此种需要，也会考虑修改这一行为。

组合文件可以和其他打包策略混合使用，以修改组合中效果不好的部分，或者添加非组合的内容。

组合文件理论上可以放在任何位置，使用任何名称；因此，打包器的基础配置没有办法排除掉这些文件。不过，为了方便，最好将其汇总在一个位置，采用明确的名称，以便在局域配置中排除。

配置注解

上述配置全部采用json格式书写；这导致的一个问题就是，json格式严格意义上是不支持注释的！为了解决这一问题，在使用这些内容时，最好在对应的命名空间内附上注解文件。当然，这不是必须的，但最好这么做。同时，也可以在此写下对该目录内容和功能的特殊注释。

原则上注解文件可以采用任何形式，但建议写到命名空间目录下的README.md文件中——打包的全局配置默认会排除这一文件。同样的，注解文件的形式也没有特殊限定，但尽量统一为佳。

一些注解文件的例子为这个、这个和这个。

原则上，这些注解甚至可以自动生成。

快速参考

以下列出了一些与打包流程相关的常见文件配置。如果遇到以下情况，可以直接使用下面的方案。

版本增添

该项需要预先进行讨论，指定合适的版本支持计划！

制定版本支持计划。
这条一般是由管理层指定的。有时，支持计划会在issues界面中展示——1.19与1.20的支持计划即这么做了。
判定是否需要工具链更新。
- 无需更新：
  - 创建config/packer/[version].json，并按照本文的指导填写，或参照相近版本的配置文件。
  - 在.github/workflows/pr-packer.json与.github/workflows/packer.json中，一处形如version: [ "1.12.2", ... ]的列表中（如此处），加入需增添的版本。
  - 创建projects/[version]，并按照其他版本的格式填写pack.png，pack.mcmeta，LICENSE，README.txt等内容。
    - 注意pack.mcmeta需要把花括号转义；可以参照其他版本的文件。
    - 注意.../minecraft/minecraft下的字体修复文件，需要按该版本的字体支持情况考虑填写。通常可以引用旧版本的资源，以减少重复工作。
- 需要更新：
  - 更新工具链。这可能需要很长的时间，取决于更新操作的复杂程度。例如，我们对1.20的支持稍晚，部分原因就是工作人员我全面更新了一次打包器。
  - 按照“无需更新”的内容执行。

复用语言文件

如果你在维护多版本的模组，有可能会遇到相近或相同的多份语言文件。此时，复用语言文件，可以减轻维护负担。

完全复用

这适用于语言文件完全一致的情况，如不同平台的同一模组。

确定可用的文件来源。
在目标模组的命名空间文件夹下，创建packer-policy.json，填写如下内容，其中source字段按照前一步找到的来源填写。（示例）

[
    {
        "type": "indirect",
        "source": "projects/[version]/assets/[mod-identifier]/[namespace]"
    }
]

尽管理论上不会加载，但仍应删除已有的lang/zh_cn.json，以免误会。lang/en_us.json无需移除。
（可选）创建注解文件。

复用+修改

这适用于语言文件大部一致，小部有改动的情况。

确定可用的文件来源，以及需要做出的修改。多余的字段无需删去（也暂时无法删去；如有需要，会考虑增加此功能）；缺少或不同的字段则需要修改。
方案一：适用于有多个文件需要修改的情况。（示例）
- 在lang/zh_cn.json（或其他需更改的文件）中，保留与来源文本不一致，需要修改的文本，其余内容删去。
- 在目标模组的命名空间文件夹下，创建packer-policy.json，填写如下内容，其中source字段按照前一步找到的来源填写。

[
    {
        "type": "direct"
    },
    {
        "type": "indirect",
        "source": "projects/[version]/assets/[mod-identifier]/[namespace]"
    }
]

方案二：（示例）
- 以合适名称创造新文件（“修改文件”），仅包含与来源文本不一致，需要修改的文本，其余内容删去。
- 在目标模组的命名空间文件夹下，创建packer-policy.json，填写如下内容，其中两个source字段依次填写修改文件、来源命名空间的完整地址，destination字段填写目标文件的相对地址。

[
    {
        "type": "singleton",
        "source": "projects/[version]/assets/[mod-identifier]/[namespace]/[file-path]",
        "relativePath": "[file-path]"
    },
    {
        "type": "indirect",
        "source": "projects/[version]/assets/[mod-identifier]/[namespace]"
    }
]

（可选）创建注解文件。

选取单文件

若来源有多个文件，但只需要其中某个文件，可以将上述方案中，indirect策略替换为以下文本：

{
    "type": "singleton",
    "source": "projects/[version]/assets/[mod-identifier]/[namespace]/[file-path]",
    "relativePath": "[domain]/[file-path]"
}

其中source为完整地址，relativePath为在最终资源包中，需要放置的相对地址。

添加无语言标识的文件

无其他配置时，打包器只会打包含有简体中文语言标识的文件，以及domain为font、textures的文件。如果需要添加不满足此要求的文件，需要适当修改配置文件。

按domain集中添加文件

这适用于集中在一个或几个domain下的文件。

确定该模组需要加入的domain。
在目标模组的命名空间文件夹下，创建local-config.json，填写如下内容：（示例）

{
    "inclusionDomains": [],
    "exclusionDomains": [],
    "exclusionPaths": [],
    "inclusionPaths": [],
    "characterReplacement": {},
    "destinationReplacement": {}
}

在上述文件中，inclusionDomains处，按照Json格式填写所需的domain。

此外，若可以确定该domain在该版本普遍需要添加，可以转而在全局配置config/packer/[version].json中进行相应修改。

添加零散文件

这适用于文件没有特殊集中位置的情况。

确定该模组需要加入的文件。
在目标模组的命名空间文件夹下，创建local-config.json，填写如下内容：

{
    "inclusionDomains": [],
    "exclusionDomains": [],
    "exclusionPaths": [],
    "inclusionPaths": [],
    "characterReplacement": {},
    "destinationReplacement": {}
}

在上述文件中，inclusionPaths处，按照Json格式填写所需文件的相对路径。

通常不应将这种配置写入全局配置。

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Packer-Doc.md

Packer-Doc.md

打包机制文档

注意事项

配置文件

文件格式

全局配置文件

局域配置文件

文件容斥顺序

局域配置文件的重写规则

检索策略

策略相关文件的格式

packer-policy.json

[组合文件].json

组合文件

配置注解

快速参考

版本增添

复用语言文件

完全复用

复用+修改

选取单文件

添加无语言标识的文件

按domain集中添加文件

添加零散文件

Files

Packer-Doc.md

Latest commit

History

Packer-Doc.md

File metadata and controls

打包机制文档

注意事项

配置文件

文件格式

全局配置文件

局域配置文件

文件容斥顺序

局域配置文件的重写规则

检索策略

策略相关文件的格式

packer-policy.json

[组合文件].json

组合文件

配置注解

快速参考

版本增添

复用语言文件

完全复用

复用+修改

选取单文件

添加无语言标识的文件

按domain集中添加文件

添加零散文件