chore: initialize standalone UPM package

2026-08-26 02:50:31 +08:00
commit 78ccae3e07
142 changed files with 6572 additions and 0 deletions
@@ -0,0 +1,102 @@
+# __PROJECT_NAME__
+
+这是由 `ShrinkModFramework` 生成器创建的外部 DLL 模组模板。
+
+## 模板内容
+
+- `src/__PROJECT_NAME__Mod.cs`
+  - 模组主入口，演示 `ShrinkModFramework + ShrinkEventBus + ShrinkCommand + ShrinkNetwork`
+- `src/__PROJECT_NAME__Contracts.cs`
+  - 示例事件、RPC 请求与响应
+- `__PROJECT_NAME__.csproj`
+  - 独立类库工程，默认引用当前 SDK 仓库里的运行时工程
+- `build.ps1`
+  - 一键构建，可选复制 DLL 到你的模组目录
+- `dev-env.ps1`
+  - 先设置 `MSBuildEnableWorkloadResolver=false`，适合有些 IDE 打开项目前先跑一遍
+- `global.json`
+  - 锁定到生成模板时检测到的 `dotnet SDK` 版本
+
+## 默认标识
+
+- `ProjectName`: `__PROJECT_NAME__`
+- `Namespace`: `__ROOT_NAMESPACE__`
+- `ModId`: `__MOD_ID__`
+- `DisplayName`: `__DISPLAY_NAME__`
+
+生成后建议你先改这几处，再开始写正式业务。
+
+## 构建
+
+```powershell
+dotnet build .\__PROJECT_NAME__.csproj -c Release /nr:false
+```
+
+或者直接运行：
+
+```powershell
+.\build.ps1
+```
+
+如果你的 IDE 打开项目时报类似：
+
+```text
+Microsoft.NET.SDK.WorkloadAutoImportPropsLocator
+```
+
+先在 PowerShell 里执行：
+
+```powershell
+.\dev-env.ps1
+```
+
+然后在**同一个 shell** 里启动 IDE，或者直接继续 `dotnet build`。
+
+默认产物输出到：
+
+```text
+artifacts\Release\
+```
+
+## 投放到游戏
+
+`ShrinkModFramework` 当前会扫描：
+
+```text
+Application.persistentDataPath/Mods
+```
+
+所以常见流程是：
+
+1. 先构建出 `__PROJECT_NAME__.dll`
+2. 把 DLL 复制到游戏实际使用的 `Mods` 目录
+3. 启动游戏，让 `ShrinkModLoader` 自动发现
+
+如果你已经知道目标 `Mods` 目录，也可以直接用：
+
+```powershell
+.\build.ps1 -ModsDir "D:\YourGameMods\Mods"
+```
+
+## 这个模板示范了什么
+
+- `[ShrinkMod]` 模组声明
+- `ShrinkModBase` 生命周期
+- `[ShrinkEventSubscriber]` / `[ShrinkSubscribe]` 生成式实例接入 Mod Bus
+- `ShrinkCommandSubscriber` 实例命令自动接入
+- `ShrinkNetworkSubscriber` 实例网络处理自动接入
+- `context.RegisterContent(...)` 使用 ModId namespace 注册内容
+- `context.OverrideContent(...)` 以显式优先级覆盖已有内容
+- `context.RegisterNetworkHandler(...)` 走模组网络抽象层
+
+## 注意
+
+- 示例里用到的 `opcode`、命令路径、`modId` 都只是模板默认值，正式模组请自己调整，避免冲突
+- 当前模板默认依赖当前仓库根目录下的：
+  - `ShrinkModFramework.Runtime.csproj`
+  - `ShrinkEventBus.Runtime.csproj`
+  - `Assets/Modules/ShrinkEventBus/Tools~/DotNet/ShrinkEventBus.Generator/ShrinkEventBus.Generator.csproj`（作为 Roslyn analyzer）
+  - `ShrinkCommand.Runtime.csproj`
+  - `ShrinkNetwork.Runtime.csproj`
+- 如果你把模板工程移到别处，需要同步修正 `__PROJECT_NAME__.csproj` 里的 `ProjectReference`
+- 某些 IDE / MSBuild 环境里，`MSBuildEnableWorkloadResolver=false` 写在项目文件内仍然太晚；这种情况要靠 `dev-env.ps1` 或系统环境变量在**打开项目之前**先设置