diff --git a/Assets/Modules/ShrinkInstaller b/Assets/Modules/ShrinkInstaller index 2abf367..e97692e 160000 --- a/Assets/Modules/ShrinkInstaller +++ b/Assets/Modules/ShrinkInstaller @@ -1 +1 @@ -Subproject commit 2abf367f368b58a2bc4f3c0a49cdb97e486f4bb2 +Subproject commit e97692e7683cfaaaaa2486e49cc0b0a0bf8edc0e diff --git a/Godot/README.md b/Godot/README.md new file mode 100644 index 0000000..c50fe0b --- /dev/null +++ b/Godot/README.md @@ -0,0 +1,170 @@ +# ShrinkSDK for Godot 4.6 C# + +Godot 适配层使用共享 ShrinkSDK 运行时和 MSBuild/Cecil CodeGen。首期目标是 Godot 4.6.3 Mono、.NET 8，以及 Windows、Linux、macOS 桌面项目；不包含 Web、Android 和 iOS。 + +## 直接运行 Workspace 示例 + +使用 Godot 4.6.3 Mono 打开： + +```text +Godot/Samples/ShrinkSDK.Godot.Sample/project.godot +``` + +首次打开前可以先完成导入和编译： + +```powershell +$godot = Join-Path $env:GODOT_HOME "godot_console.exe" +& $godot --headless --editor --path .\Godot\Samples\ShrinkSDK.Godot.Sample --quit +dotnet build .\Godot\Samples\ShrinkSDK.Godot.Sample\ShrinkSDK.Godot.Sample.csproj +& $godot --headless --path .\Godot\Samples\ShrinkSDK.Godot.Sample +``` + +`GODOT_HOME` 指向 Godot Mono 安装目录。成功运行时会输出 `SHRINK_GODOT_SMOKE_PASS`。 + +## 在现有 Godot C# 项目中安装 + +项目需要： + +- Godot 4.6.3 Mono； +- .NET 8 SDK； +- `.csproj` 使用 `Godot.NET.Sdk/4.6.3`； +- 项目级 `NuGet.Config` 保留既有源并加入 ShrinkSDK feed。 + +`NuGet.Config` 的最小增量如下： + +```xml + + + + + + +``` + +安装 Godot 宿主和所需模块： + +```powershell +dotnet add package ShrinkSDK.Godot --version 0.1.0 +dotnet add package ShrinkSDK.EventBus --version 2.1.0 +dotnet add package ShrinkSDK.Command --version 0.3.0 +dotnet add package ShrinkSDK.Network --version 0.3.0 +dotnet add package ShrinkSDK.DataSaver --version 2.3.0 +dotnet restore +dotnet build +``` + +只有实际使用的模块需要安装。远端源尚未发布目标版本时，可以直接运行 Workspace 示例，或把本仓库生成的 `Godot/Artifacts` 作为临时本地 NuGet 源；不要删除命令中的固定版本号改用浮动版本。 + +## Installer 插件 + +`ShrinkSDK.Godot.Installer` 的 nupkg 内包含完整的 `addons/shrinksdk`。取得 `0.1.1` 包后，将包内： + +```text +contentFiles/any/any/addons/shrinksdk +``` + +复制到 Godot 项目的： + +```text +addons/shrinksdk +``` + +然后在 Godot 中打开 `Project > Project Settings > Plugins`，启用 **ShrinkSDK Installer**。左侧 ShrinkSDK 面板可以： + +- 查看项目直接安装的 ShrinkSDK NuGet 包及版本； +- 安装、升级或移除模块； +- 保留项目已有 NuGet 源和无关 `PackageReference`； +- 执行 `dotnet restore/build`； +- 查看 CodeGen 最后一次织入结果和生成的注册数量。 + +已安装版本高于面板目录版本时会显示 `Newer` 并禁用更新按钮，不会执行降级。 + +在 Workspace 中生成 Installer 包： + +```powershell +dotnet build .\Godot\Installer\ShrinkSDK.Godot.Installer.csproj -c Release +dotnet pack .\Godot\Installer\ShrinkSDK.Godot.Installer.csproj -c Release --no-build -o .\Godot\Artifacts --include-symbols --include-source +``` + +## 宿主节点 + +主场景根节点继承 `ShrinkGodotHost`，并在 `_Ready` 中先调用 `base._Ready()`： + +```csharp +using Cysharp.Threading.Tasks; +using ShrinkSDK.Godot; + +public partial class GameRoot : ShrinkGodotHost +{ + public override void _Ready() + { + base._Ready(); + BootAsync().Forget(); + } + + private async UniTaskVoid BootAsync() + { + RequireWoven(GetType().Assembly); + await StartAppAsync(); + } +} +``` + +宿主负责日志、主线程派发、时间、`user://` 持久化路径、截图、应用生命周期和网络 dispatch queue。使用 `ShrinkNetworkService` 时，通过 `AddNetworkService(service)` 交给宿主逐帧泵送，释放前调用 `RemoveNetworkService(service)`。 + +## CodeGen 织入 + +EventBus、Command、Network 和 App 的特性注册由 `ShrinkSDK.CodeGen` 在构建时生成。项目正常引用这些模块后，`buildTransitive` 会默认设置： + +```xml +true +``` + +执行： + +```powershell +dotnet build +``` + +日志应出现类似： + +```text +[ShrinkSDK.CodeGen] ... woven: instance=1, static=1, registry=2 +``` + +运行时可以在启动阶段验证程序集： + +```csharp +ShrinkGodotHost.RequireWoven(GetType().Assembly); +``` + +缺少织入时应修复 NuGet 引用或构建配置，不要增加运行时反射扫描兜底。只有明确采用手工注册的普通 .NET 宿主才设置 `false`。 + +## 特性声明示例 + +```csharp +using ShrinkCommand; +using ShrinkEventBus; +using ShrinkNetwork; + +public readonly struct PlayerReadyEvent : IShrinkEvent { } + +[ShrinkEventSubscriber] +public sealed class PlayerReadySubscriber +{ + [ShrinkSubscribe] + private void OnPlayerReady(PlayerReadyEvent value) { } +} + +[ShrinkCommandSubscriber] +public static class GameCommands +{ + [ShrinkCommand("game/status")] + public static void Status() { } +} + +[ShrinkNetworkMessage(41001, "game/player-ready")] +public sealed class PlayerReadyMessage : IShrinkNetworkMessage { } +``` + +实例订阅者使用 `EventBus.Attach(instance)` 绑定；静态订阅、Command、Network 和 App registry 由织入代码自动注册。 diff --git a/README.md b/README.md index 639a16a..9ff7e85 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # ShrinkSDK Workspace -ShrinkSDK 的 Workspace 用于跨包集成、场景验证、生成器验证和 SDK 文档。每个 `Assets/Modules/` 是独立公开仓库的 Git submodule；根仓库保留相邻 `.meta`，因此不要删除或重新生成这些文件。 +ShrinkSDK 是一组可独立组合的 Unity / Godot C# 运行时模块。共享内核以 `netstandard2.1` 为最低目标；Unity 侧支持 Unity 2022.3，Godot 侧首期支持 Godot 4.6.3 Mono 和桌面平台。 + +Workspace 用于跨包集成、Unity 场景验证、Godot 消费者验证和 CodeGen 织入测试。每个 `Assets/Modules/` 是独立公开仓库的 Git submodule；根仓库保留相邻 `.meta`，不要删除或重新生成这些文件。 ## 获取 Workspace @@ -10,11 +12,23 @@ cd Workspace git submodule update --init --recursive ``` -所有模块都可以独立打开其 `Development~/UnityProject`。根 Workspace 仅用于跨包组合与验收。 +所有 Unity 模块都可以独立打开其 `Development~/UnityProject`。根 Workspace 用于跨包组合与验收；Godot 综合示例位于 `Godot/Samples/ShrinkSDK.Godot.Sample`。 -## 安装 SDK +## Unity 安装与使用 -首选公开 Gitea NPM/UPM registry，在消费者项目的 `Packages/manifest.json` 中保留既有配置并加入： +### 通过 Installer 安装 + +在 Unity Package Manager 中选择 **Add package from git URL**，添加： + +```text +https://git.crash.work/ShrinkSDK/Installer.git#main +``` + +正式项目应在对应版本发布后把 `main` 换成固定 tag。安装完成后打开 `ShrinkSDK/包管理`，选择单个模块或推荐组合。Installer 会合并 ShrinkSDK scoped registry、安装精确版本依赖，并分别显示未安装、可升级、已安装和已安装较新版本；不会把较新版本降级到目录版本。 + +### 手工安装 + +也可以在消费者项目的 `Packages/manifest.json` 中保留原有内容并加入 registry： ```json { @@ -24,23 +38,82 @@ git submodule update --init --recursive "url": "https://git.crash.work/api/packages/ShrinkSDK/npm/", "scopes": ["com.cneicy"] } - ] + ], + "dependencies": { + "com.cneicy.shrink-app-starter-basic": "0.3.0" + } } ``` -然后按精确版本添加包，例如 `com.cneicy.shrink-app-starter-basic: 0.2.2`。Git 备用安装同样必须固定标签，例如： +如果项目已经有 `scopedRegistries` 或 `dependencies`，只合并对应条目，不要覆盖原有配置。Git 安装同样建议固定 tag，例如： ```text -https://git.crash.work/ShrinkSDK/ShrinkEventBus.git#v2.0.1 +https://git.crash.work/ShrinkSDK/ShrinkEventBus.git#v2.1.0 ``` -也可先通过固定标签安装 Editor 引导包： +### 快速开始 + +安装 `ShrinkApp.Starter.Basic` 后，执行 `ShrinkSDK/应用/基础起步/创建默认 Context 组合`。菜单会生成默认配置和入口场景；打开 `Assets/Scenes/ShrinkAppEntry.unity` 即可运行 Command、DataSaver、Network 和 App 的基础组合。 + +EventBus、Command、Network 和 App 的特性注册由 Unity ILPostProcessor 在编译期织入，不需要运行时反射扫描或手工维护注册表。修改带 ShrinkSDK 特性的代码后，等待 Unity 完成重新编译，再进入 Play Mode。 + +## Godot 4.6 C# 安装与使用 + +Godot 项目需要 Godot 4.6.3 Mono 和 .NET 8 SDK。使用现有 Workspace 验证时，直接用 Godot 打开： ```text -https://git.crash.work/ShrinkSDK/Installer.git#v0.2.4 +Godot/Samples/ShrinkSDK.Godot.Sample/project.godot ``` -随后在 Unity 打开 `ShrinkSDK/包管理`。UI Toolkit 窗口会显示直接与间接依赖的真实安装状态，并按 Context 组合基础、应用宿主、独立功能和模块集成组织固定版本包与推荐组合。安装器只合并 `com.cneicy` registry 和依赖数据，不写认证信息，也不复制模板到 `Assets`。 +外部 Godot C# 项目通过 NuGet 使用 ShrinkSDK。先在项目级 `NuGet.Config` 中加入软件源： + +```xml + + + + + + + +``` + +然后为 Godot 的 `.csproj` 安装宿主和需要的模块，例如： + +```powershell +dotnet add package ShrinkSDK.Godot --version 0.1.0 +dotnet add package ShrinkSDK.App.Starter.Basic --version 0.3.0 +dotnet add package ShrinkSDK.EventBus --version 2.1.0 +dotnet restore +dotnet build +``` + +需要自动注册的包会传递引入 `ShrinkSDK.CodeGen`。CodeGen 默认在 `CoreCompile` 后织入当前项目程序集；构建日志应出现 `[ShrinkSDK.CodeGen]`，无需额外添加 Source Generator、反射扫描或手工注册表。 + +主场景根节点可继承 `ShrinkGodotHost`： + +```csharp +using Cysharp.Threading.Tasks; +using ShrinkSDK.Godot; + +public partial class GameRoot : ShrinkGodotHost +{ + public override void _Ready() + { + base._Ready(); + StartAsync().Forget(); + } + + private async UniTaskVoid StartAsync() + { + RequireWoven(GetType().Assembly); + await StartAppAsync(); + } +} +``` + +`ShrinkGodotHost` 在 `_Ready` 中安装平台服务，在 `_Process` 中泵送主线程和网络队列，并转发暂停、恢复与退出生命周期。Godot Installer 插件的安装、包管理面板、CodeGen 状态和命令行验证方式见 [Godot/README.md](Godot/README.md)。 + +## 开发与发布 发布、子模块迁移和独立开发宿主生成规则位于 [Tools/RepositoryMigration/Initialize-ShrinkSdkPackageRepositories.ps1](Tools/RepositoryMigration/Initialize-ShrinkSdkPackageRepositories.ps1)。架构约束与跨包验证要求见 [DESIGN.md](DESIGN.md)。