Packer-Doc.md

打包机制文档

注意事项

• 文件地址中，目录分隔符一律使用正斜杠！
• 地址相关
  • 下述说明中，完整地址永远指从仓库根目录算起的地址，例如对根目录下的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标签下的内容（可变配置）一致。

文件容斥顺序

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

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

局域配置文件的重写规则

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

检索策略

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

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

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

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

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

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

策略相关文件的格式

packer-policy.json

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

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

[组合文件].json

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

组合文件

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

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

1. 获取entries中的全部条目，每个条目代表一种组合模式。
2. 每个条目中，由templates中的所有条目充当模板，parameters中的所有条目充当参数，生成若干组合后的条目。

• 在parameter中，有时会出现多于一组参数；这种情况下，每组参数都会自由组合。
• 同样的，templates也会和每一套参数自由组合。

3. 将所有组合后的条目汇总，生成语言文件。

• 在这一过程中，如果出现了键冲突，目前而言，**打包器会在此崩溃！**不过，如果后续观察表明确实存在此种需要，也会考虑修改这一行为。

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

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

配置注解

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

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

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

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