|
2 | 2 |
|
3 | 3 | ## 注意事项 |
4 | 4 | - 文件地址中，目录分隔符**一律使用正斜杠**！ |
5 | | -- 下述说明中，**完整地址**永远指从**仓库根目录**算起的地址，例如根目录下的`CONTRIBUTING.md`即为`CONTRIBUTING.md`，1.12版本资源包的`pack.png`即为`projects/1.12.2/pack.png`。 |
6 | | -- 下述说明中，**相对地址**永远指从**特定命名空间的文件夹**算起的地址，例如仓库中的`projects/1.18/assets/minecraft/minecraft/font/default.json`即为`font/default.json`。 |
7 | | -- 下述说明中，**目标地址**永远指分发的资源包中，该文件应当被放置的位置，例如上一条中提及的文件就是`assets/minecraft/font/default.json`。 |
8 | | -- 本次打包器更新以后，对于**非文本文件**无需特殊处理；打包器会将所有*未知的*拓展名按照非文本文件处理，无需特殊配置。 |
9 | | - - 目前而言，打包器会将`lang/`下的`.lang`和`.json`作为语言文件，其余的`.txt`, `.md`, `.json`作为普通文本文件，其余文件都作为非文本文件。<br>如果出现其他格式，可以后续添加——尽管这一部分没有添加显式的配置项。 |
| 5 | +- 地址相关 |
| 6 | + - 下述说明中，**完整地址**永远指从**仓库根目录**算起的地址，例如对根目录下的`CONTRIBUTING.md`应为`CONTRIBUTING.md`，1.12版本资源包的`pack.png`应为`projects/1.12.2/pack.png`。 |
| 7 | + - 下述说明中，**相对地址**永远指从**特定命名空间的文件夹**算起的地址，例如对仓库中的`projects/1.18/assets/minecraft/minecraft/font/default.json`应为`font/default.json`。 |
| 8 | + - 下述说明中，**目标地址**永远指**分发的资源包中**，该文件应当被放置的位置，例如上一条中提及的文件应为`assets/minecraft/font/default.json`。 |
| 9 | +- 文件相关 |
| 10 | + - 下述说明中，**语言文件**永远指可以被打包器解读为**映射表**的文件。这包括了所有 **`lang/`下的`.lang`和`.json`文件**。 |
| 11 | + - 下述说明中，**文本文件**永远指含有**文本内容**，但**不属于语言文件**的文件。这包括了非语言文件的`.txt`、`.md`、`.json`文件。 |
| 12 | + - 下述说明中，**非文本文件**永远指**不属于以上两类**的文件，如图片或其他二进制文件。 |
| 13 | +- 本次打包器更新以后，对于**非文本文件**无需特殊处理：打包器会按照文件拓展名自动识别文件类型。 |
10 | 14 |
|
11 | 15 | <!-- 下面的部分内容是从我的fork处，尚未完工（短期内也不会完工）的wiki摘录+修改而来的。有些地方用XML注释格式去掉了部分内容，但是我没有完全删掉，因为还打算复制回去的。 ---> |
12 | 16 |
|
|
18 | 22 |
|
19 | 23 | ### 文件格式 |
20 | 24 |
|
| 25 | +目前而言，所有配置文件都需要填写全部项——无关项可以填写空集合，但不能不填，更不能写null。有计划在将来优化这一行为。 |
| 26 | + |
21 | 27 | **全局**配置文件`./config/packer/<version>.json`的格式如下： |
22 | 28 |
|
23 | 29 | - 根标签 object |
|
40 | 46 | - string<br>强制包含的文件的**相对地址**。 |
41 | 47 | - `characterReplacement` object<br>打包时采用的字符替换表。用于将部分字符替换至特殊位点，也可单纯用于简化输入。目前而言，包含了字体修复的有关内容。 |
42 | 48 | - `<查询语句>` string<br>用以替换**正则表达式**`<查询语句>`匹配对象的内容，可以是一个或多个字符，甚至可以在这里用**正则替换语句**。<br>主要用于*字体修复包*所需的**符号替换**，此时，查询语句通常是字面量，替换内容一般而言总是以四位*Unicode转义码*填写；对于**基础多语种平面（BMP）**以外的字符，最好用**UTF-16代理对**书写。 |
43 | | - - `destinationReplacement` object<br>打包时采用的目标地址替换。<br>可以用于移动文件，但暂时闲置。 |
| 49 | + - `destinationReplacement` object<br>打包时采用的目标地址替换。<br>可以用于移动文件，但暂时闲置；使用**检索策略**中的`singleton`也可以实现地址替换，但需要在每个模组下配置。 |
44 | 50 | - `<查询语句>` string<br>用以替换**正则表达式**`<查询语句>`匹配对象的内容，可以是一个或多个字符，甚至可以在这里用**正则替换语句**。 |
45 | 51 |
|
46 | | -**局域**配置文件`./projects/<version>/assets/<mod-name>/<namespace>/local-config.json`的格式与全局配置文件中，`floating`标签下的内容（*浮动配置*）一致。 |
| 52 | +**局域**配置文件`./projects/<version>/assets/<mod-name>/<namespace>/local-config.json`的格式与全局配置文件中，`floating`标签下的内容（*可变配置*）一致。 |
47 | 53 |
|
48 | 54 | ### 文件容斥顺序 |
49 | 55 |
|
|
59 | 65 |
|
60 | 66 | - 如果在某个命名空间内检测到存在`local-config.json`，打包器将会在全局配置的基础上，在其*可变配置*中**添加**该文件中的内容，并用这一修改后的配置执行**该命名空间下的**检索工作。 |
61 | 67 | - 最好不要与全局配置中的内容重复。尽管理论上这样子可以运行，但是重复项保留哪一个或许不容易断定。 |
62 | | -- 需要注意的是，如果通过*检索策略***引用其他命名空间**，打包器**只**会加载目标命名空间的局域配置，而**不会**加载原空间的局域配置；不过，在原位进行的检索工作不受影响。 |
| 68 | +- 需要注意的是，如果通过*检索策略*来**引用其他命名空间**，打包器**只**会加载目标命名空间的局域配置，而**不会**加载原空间的局域配置；不过，在原位进行的检索工作不受影响。 |
63 | 69 |
|
64 | 70 | ## 检索策略 |
65 | 71 |
|
66 | | -对于每个**命名空间文件夹**（注意这个概念和**命名空间**有着细微差别），打包器除了可以原位检索文件以外，还可以**使用不同的检索方式**。目前，可用的检索方式有两种： |
67 | | -1. **引用**给定的命名空间。 |
68 | | -2. 从给定的**组合**文件，直接生成语言文件（或部分）。 |
| 72 | +对于每个**命名空间文件夹**，打包器除了可以原位检索文件以外，还可以**使用不同的检索方式**。目前，可用的检索方式有四种： |
| 73 | +1. **原位**检索文件。 |
| 74 | +2. **引用**给定的命名空间。 |
| 75 | +3. 从给定的**组合**文件，直接生成语言文件（或部分）。 |
| 76 | +4. 引用**单个**文件。 |
69 | 77 |
|
70 | | -计划中，将对*非语言文件的文本文件*添加一个**修改包**策略，但是这个策略暂时还没实现，部分原因是在上一版打包器中，这个策略还没被用过。 |
| 78 | +> 计划中，将对*非语言文件的文本文件*添加一个**修改包**策略，但是这个策略暂时还没实现，部分原因是在上一版打包器中，这个策略还没被用过。 |
71 | 79 |
|
72 | | -单独看起来，这或许没什么用（Packer的上一版中，功能还要多些）；但有一点很重要： |
73 | | -这些加载策略（包括**原位**加载）是可以**串联**、**递归**的！于是，通过这三种策略，应该可以满足许多需求。 |
| 80 | +单独看起来，这或许没什么用（Packer的上一版中，功能还要多些）；但有一点很重要：这些加载策略是可以**串联**、**递归**的！于是，通过这些策略，应该可以满足许多需求。 |
74 | 81 |
|
75 | | -- **串联**：在一个策略文件中，可以放置**多条策略**。策略将会从前往后执行，**前者**优先——和*Minecraft资源包*顺序差不多。不过，如果有需要，在策略文件中也预留了一个字段，用来**覆盖**前序文件。 |
| 82 | +- **串联**：在一个策略文件中，可以放置**多条策略**。策略将会从前往后执行，**前者**优先——和*Minecraft资源包*顺序差不多。不过，在文件冲突时，也提供了一些特殊的冲突解决选项。 |
76 | 83 | - **递归**：如果**引用**了其他命名空间文件夹，那里的策略文件**也会生效**。这意味着可以实现*连续引用*——尽管前提是不出现**循环引用**。 |
77 | 84 |
|
78 | 85 | 部分案例被放在了`./projects/packer-example/`这一虚拟的“版本”下。很明显，我们**并不会**分发这一版本，但如果有条件，可以在本地构造打包器，并用这一版本做试验。 |
|
82 | 89 | #### packer-policy.json |
83 | 90 |
|
84 | 91 | 对于每个**命名空间文件夹**，策略文件为`./projects/<version>/assets/<mod-name>/<asset-domain>/packer-policy.json`。 |
85 | | -若找不到该策略，默认策略文件内容为`[{"type": "direct"}]`。 |
| 92 | +若找不到该文件，默认策略内容为`[{"type": "direct"}]`，也就是**原位**加载，没有特殊配置。 |
86 | 93 |
|
87 | 94 | - 根标签 list<br>打包器需要执行的策略，**从前往后执行**。如果有冲突内容，默认以**前者**优先——当然这是可以配置的。 |
88 | 95 | - object<br>单项策略。部分参数可变。 |
89 | | - - `overrides` bool<br>是否可以用本步的文件覆盖前序文件。如果无此项，默认为`false`。<br>关于这里的“覆盖”，对于**非语言文件**（不在`lang\`下），指的是**全文**覆盖；对于**语言文件**，则是**按条目**覆盖。 |
90 | 96 | - `type` string<br>策略的类型。可为以下选项之一： |
91 | 97 | - `direct` 默认选项。不进行特殊处理，直接按照此处的文件结构打包。 |
92 | 98 | - `indirect` 引用给定的命名空间。对于这些文件，其*目标地址*中的*命名空间*将会自动替换为本策略所在的命名空间。 |
93 | 99 | - `source` string<br>引用命名空间所在文件夹的**完整地址**。 |
94 | 100 | - `composition`<br>从给定的*组合文件*，直接生成语言文件（或部分）。<br>这些组合文件可能不会被自动排除；可以考虑使用*局域配置*处理。 |
95 | | - - `source` string<br>引用组合文件的**完整位置**。 |
| 101 | + - `source` string<br>引用组合文件的**完整地址**。 |
96 | 102 | - `destType` string<br>需要生成的语言文件的类型。可以为`json`或`lang`。 |
| 103 | + - `singleton`<br>引用给定的单个文件。<br>理论上该操作可以选取任何位置的文件，只要目标位置填写正确；不过，一般建议放在*合理的位置*。 |
| 104 | + - `source` string<br>引用文件所在的**完整地址**。 |
| 105 | + - `relativePath`<br>文件需要被放置的**相对地址**。考虑到连续引用，这里不宜使用**目标地址**。 |
| 106 | + - **通用参数** |
| 107 | + - `modifyOnly` bool<br>默认为`false`。<br>对于**语言文件**，若本项为`true`，对于已有的键，若在该步中提供了新的值，则将会用新值替换旧值；**不会**包含本步中新出现的键。<br>对于其他文件，本项无效。 |
| 108 | + - `append` bool<br>默认为`false`。<br>对于**文本文件**，将会在已有的文本内容之后**换行**，然后连接本步的内容。<br>对于其他文件，本项无效。 |
97 | 109 |
|
98 | 110 | #### [组合文件].json |
99 | 111 |
|
100 | 112 | - 根标签 object |
101 | 113 | - `target` string<br>生成的语言文件的**目标地址**。 |
102 | | - * `entries` list<br>需要生成的组合项。这些项将会分别执行组合以后，连接起来。<br>**如果存在键冲突，打包器会在此崩溃！**有计划在后期更改这一行为。 |
| 114 | + * `entries` list<br>需要生成的组合项。这些项将会分别执行组合以后，连接起来。<br>**如果存在键冲突，打包器会在此崩溃！**有计划在后期更改这一行为；目前而言，可以使用多个组合文件绕过这个限制。 |
103 | 115 | * object<br>单项策略。 |
104 | | - * `templates` object<br>组合所用的模板。所有内容采用**C#格式化模式**填写。<br>粗略地说，其中的格式符有形式`{0}, {1}, {2},...`；完整的定义可见 *.net文档*。 |
| 116 | + * `templates` object<br>组合所用的模板。所有内容采用**C#格式化模式**填写。<br>粗略地说，其中的格式符有形式`{0}, {1}, {2},...`，字面量花括号需要用`{{`和`}}`转义；完整的定义可见 *[.net文档/Composite Formatting](https://learn.microsoft.com/en-us/dotnet/standard/base-types/composite-formatting)*。 |
105 | 117 | - `<键模板>` string<br>`<键模板>`对应的值模板。 |
106 | | - * `parameters` list<br>组合所用的参数表。参数按照模板中的**索引**顺序排列。不支持嵌套，必须字面量。 |
| 118 | + * `parameters` list<br>组合所用的参数表。参数按照模板中的**索引**顺序排列。不支持嵌套，必须用字面量。 |
107 | 119 | * object<br>每个索引位置上可用的参数。 |
108 | 120 | - `<键参数>` string<br>`<键参数>`对应的值参数。 |
109 | 121 |
|
110 | 122 | ### 组合文件 |
111 | 123 |
|
112 | 124 | 组合文件用来生成“组合型”的**语言文件/语言文件片段**，也就是那些有大量重复文本、有明显的格式的语言文件片段。 |
| 125 | + |
113 | 126 | 组合文件的工作原理如下： |
114 | 127 | 1. 获取`entries`中的全部条目，每个条目代表一种组合模式。 |
115 | 128 | 2. 每个条目中，由`templates`中的所有条目充当模板，`parameters`中的所有条目充当参数，生成若干组合后的条目。 |
|
0 commit comments