feat: build template

Author: nebulaliu

.config/.vitepress/config.mts

@@ -138,6 +138,7 @@ export default defineConfig({
           { text: "后端服务指引", link: "/Design/BackendServiceStartup" },
           { text: "网络通信适配", link: "/Design/UsingNetworking" },
           { text: "使用水印保护代码包安全", link: "/Design/wasmWaterMark" },
+          { text: "配置构建模板", link: "/Design/BuildTemplate.md" }
         ],
       },
       {

Design/BuildTemplate.md

@@ -0,0 +1,103 @@
+# 配置构建模板
+
+## 简介
+团结/Unity快适配项目最终导出 `minigame` 目录即为微信小游戏代码包，使用微信开发者工具打开并上传。该部分主要由 JavaScript、JSON、WASM及图片资源构成。在实际的游戏开发中，开发者仍需要对 minigame 目录中产物做一些定制化的修改，这些修改同时也要跟随项目内容一起进行代码托管。为此微信提供配置构建模板的能力。
+
+## 结构说明
+
+- 在Package Manager导入WXSDK模式下的目录 `Packages/com.qq.weixin.minigame/Runtime/wechat-default`
+- 以及在Assets导入资源模式下的目录 `Assets/WX-WASM-SDK-V2/Runtime/wechat-default`
+
+两个目录中的 `wechat-default` 是项目的基础模板，基础模板不建议开发者进行编辑，因为随着新的SDK的更新覆盖也将失去其修改内容。
+
+开发者需要手动创建 `Assets/WX-WASM-SDK-V2/Editor/template` 目录，在 `template/minigame` 目录中的资源内容将会按照完整的层级结构覆盖到最终的 `minigame` 的导出目录中。
+
+**直观的结构：**
+
+```
+# 游戏工程目录
+Assets
+├─ WX-WASM-SDK-V2
+│  ├─ Editor
+│  │  ├─ template      # 自行创建该目录内容
+│  │  │  ├─ minigame
+│  │  │  │  └─ ...     # 需要被覆盖的资源文件
+│  │  │  └─ plugin.cs  # 可缺省创建，请阅读「构建模板前后不同时机的钩子」小节
+│  │  └─ ...
+│  └─ ...
+└─ ...
+
+# WXSDK目录
+Packages/com.qq.weixin.minigame 或 Assets/WX-WASM-SDK-V2
+├─ Runtime
+│  ├─ wechat-default   # 基础模板
+│  └─ ...
+└─ ...
+
+# 导出资源目录（转换微信小游戏产物）
+wechat
+├─ minigame      # 基础模板 + template（合并结果）
+│  └─ ...
+└─ webgl
+```
+
+值得注意的是，基础模板（wechat-default）并不是一个可以运行的标准JavaScript代码包，因为其中包含了大量的占位符将在导出时根据项目不同的实际情况作出替换，因此开发者在 `template/minigame` 创建用于覆盖的脚本时，应该以 `wechat-defalut` 中的脚本为修改基准，而不是导出的资源目录 `wechat/minigame` 中的资源作为参考。如此一来你自定义模板也将适应占位符的内容作出最终的结果变更。
+
+## 新版本SDK引起的冲突提醒
+
+随着WXSDK的更新，如果你覆盖过 `wechat-defalut` 中的关键脚本，那么在新版本WXSDK导入后可能会引起部分功能表现异常，因此WXSDK将识别到关键脚本发生更新且被开发者自定义覆盖的情况下作出警告。（只会检查 .js .json 文件冲突，图片文件不会检查）
+
+- **在WXSDK初始化时（引擎启动、或导入新的WXSDK时）作出检查**
+
+  检查异常时将在Unity控制台中给出详细的冲突信息；
+
+- **在导出微信小游戏时作出检查**
+
+  检查异常时将终止导出，并在Unity控制台中给出详细的冲突信息。
+
+### 消除冲突提醒
+
+观察到异常提醒后开发者需要根据提醒前往对比冲突的脚本内容**自行适配**，当冲突的自定义模板文件较冲突前发生变化后提醒也将自动消除。
+
+## 构建模板前后不同时机的钩子
+
+有时候简单的覆盖可能并不能满足开发者复杂的修改需要，在构建时提供的不同时机钩子允许开发者使用C#代码来替换或变更是更灵活自由的方案，我们提供了 [BuildTemplateHelper](#buildtemplatehelper介绍) 工具类来便捷的实现这一能力。
+
+### 钩子介绍
+
+在构建模板中通常需要以下几个阶段的钩子：
+
+<img src="/image/buildtemplateprocess.png" width="90%" />
+
+### 使用钩子
+
+为了统一约定，推荐开发者创建位于 `Assets/WX-WASM-SDK-V2/Editor/template/plugin.cs` 脚本来执行构建模板相关的设计。
+
+```
+# 游戏工程目录
+Assets
+├─ WX-WASM-SDK-V2
+│  ├─ Editor
+│  │  ├─ template
+│  │  │  ├─ minigame
+│  │  │  │  └─ ...
+│  │  │  └─ plugin.cs  # 请创建该文件并编写钩子逻辑
+│  │  └─ ...
+│  └─ ...
+└─ ...
+```
+
+样例：
+
+```c#
+// plugin.cs
+
+// code...
+
+```
+
+### BuildTemplateHelper介绍
+
+请使用 BuildTemplateHelper 提供的资源访问接口，搭配[钩子介绍](#钩子介绍)小节中的不同阶段，可以任意的对你的 `wechat-default（标准模板）`、`template（自定义模板）`、`wechat/minigame（导出产物）` 中进行新的脚本创建、已有脚本中局部代码的文本替换（例如使用正则替换）甚至是图片等资源的变更。
+
+BuildTemplateHelper 为你提供了一个会**自动复原的“伪沙箱”环境**，在 BuildTemplateHelper 的操作下你可以任意的修改上述三者目录中的内容，在结束导出后不会真实的影响你的游戏工程内容，也不需要你进行资源还原，这对于你托管项目代码很便捷。